# How to Complete a Task Space and Dismiss or Close the Overlay Using ego-lite

> Learn to close ego-lite overlays and complete task spaces. Use the completeTaskSpace helper with keep: false to destroy or keep: true to hide UI elements.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-21

---

**To complete a task space and dismiss its overlay in the citrolabs/ego-lite runtime, invoke the `completeTaskSpace` helper with the option `{ keep: false }` to permanently destroy the space and remove the UI, or `{ keep: true }` to hide the overlay while keeping the space active for debugging.**

A **task space** in ego-lite represents an isolated browsing context that agents create, claim, and manage during automated workflows. When you need to finish work within a specific context, you must properly signal completion to the host runtime and control whether the associated UI overlay remains visible or is dismissed entirely.

## Using the `completeTaskSpace` Helper

The primary mechanism to finish a task space and manage its overlay is the async function `completeTaskSpace`, exported from [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (beginning at line 274). This helper abstracts the runtime calls required to either persist the space for later inspection or tear it down completely.

### Function Signature

```typescript
export async function completeTaskSpace(
  ego: EgoRuntime,
  nameOrId: string | number,
  opts: { keep: boolean }
): Promise<{ done: boolean; skipped?: string }>

```

The function accepts three arguments:
- **`ego`** – The active `EgoRuntime` instance.
- **`nameOrId`** – either the string name or numeric ID of the target task space.
- **`opts.keep`** – A boolean flag determining whether the space survives after the overlay closes.

## How to Close a Task Space and Remove the Overlay Permanently

To finish a task and completely destroy its associated browsing context, set the `keep` option to `false`. This workflow first claims the space to ensure ownership, then terminates the session and dismisses the overlay from the screen.

Under the hood, the helper executes:

1. `selectTaskSpace` to locate the target by name or ID.
2. `claimResolvedTaskSpace` to assert ownership.
3. `ego.closeTaskSpace()` to destroy the space and dismiss the overlay permanently.

```typescript
// Complete the task and destroy the space
await completeTaskSpace(ego, "my-task-space", { keep: false });
// Returns: { done: true }

```

Use this mode when you have extracted all necessary data and no longer need the browsing context.

## How to Dismiss the Overlay While Preserving the Space

For debugging or multi-step workflows, you may want to hide the overlay without destroying the underlying task space. Setting `keep: true` dismisses the UI but leaves the space intact, marked as user-owned.

Internally, this path calls `ego.completeTaskSpace()` (without claiming or closing), which signals the host to hide the overlay while preserving the isolated context.

```typescript
// Dismiss overlay but keep space alive for inspection
await completeTaskSpace(ego, 42, { keep: true });
// Returns: { done: false, skipped: "user-owned" }

```

This approach is useful when you need to temporarily clear the UI to reveal the underlying page or return to the space later in the session.

## CLI and Integration Usage

The helper is registered as a CLI command in [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) at line 130 under the name `"completeTaskSpace"`. You can invoke it directly from the command line:

```bash
ego-browser <<'JS'
  await completeTaskSpace("demo-run", { keep: false });
JS

```

Integration tests demonstrating these flows live in `package/ego-browser/src/taskspace-e2e.test.mjs`, which validates both the preservation and destruction paths against a live runtime.

## Summary

- **Task spaces** in ego-lite are isolated browsing contexts identified by name or numeric ID.
- **`completeTaskSpace`** in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (line 274+) provides the unified interface to finish tasks and control overlays.
- **`{ keep: false }`** claims the space via `claimResolvedTaskSpace`, then calls `ego.closeTaskSpace()` to permanently destroy the space and remove the overlay.
- **`{ keep: true }`** invokes `ego.completeTaskSpace()` to hide the overlay while leaving the space active, returning `{ done: false, skipped: "user-owned" }`.
- The function is exposed to CLI tools via registration in [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts).

## Frequently Asked Questions

### What is the difference between dismissing and closing a task space overlay?

**Dismiss** refers to hiding the UI overlay while keeping the underlying browsing context alive (using `{ keep: true }`), whereas **close** means both hiding the overlay and destroying the task space entirely (using `{ keep: false }`). The former preserves state for debugging, while the latter frees resources.

### How do I keep a task space alive after completing the task?

Pass `{ keep: true }` as the options argument to `completeTaskSpace`. This triggers the runtime's `ego.completeTaskSpace()` method without claiming or closing the space, returning a result object with `done: false` and `skipped: "user-owned"`.

### Where is the `completeTaskSpace` function defined in the ego-lite repository?

The implementation resides in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) starting at line 274. The function is also registered for CLI access in [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) around line 130. Additional usage examples appear in `package/ego-browser/src/taskspace-e2e.test.mjs`.

### What does the `completeTaskSpace` helper return?

The function returns a Promise resolving to an object with `done: boolean` and an optional `skipped?: string` property. When `keep` is `false`, `done` is `true`. When `keep` is `true`, `done` is `false` and `skipped` contains the string `"user-owned"` to indicate the space was preserved.