Workspace and worktree lifecycle
Orca turns a registered repository or folder into a host-owned workspace for coding work. It keeps the checkout, user session, agent surfaces, Git state, product metadata, and cleanup state connected so a workspace can be created, resumed, retired, or recovered without crossing host or path boundaries. This page is a child of Agent workspaces and sessions. Related flows are described in Agent integrations and hooks, Agent protocol client sessions, AI vault sessions, Native agent conversations, and Automation services.
Repository registration
Repository registration gives Orca a lasting project record and an execution target. Later workspace actions use that record to choose the owning host, Git view, workspace location, and saved product state.
Repository identity
The repository record identifies a project by stable ID and canonical path. It also carries host context because the same project can appear on local, SSH, and runtime hosts. Git repositories expose a main checkout and linked worktrees. Folder projects use the folder as a shared root and create session records instead of Git worktrees.
Folder projects can change to Git projects only after Orca proves that the project folder itself is the Git root. It preserves the folder locator when Git reports an equivalent path with different separators or drive-letter case. This keeps existing folder session metadata and terminal state attached to the same visible workspace after conversion.
References: src/…/repo-worktrees.ts• L17-45 src/…/folder-repo-git-conversion.ts• L22-153 src/…/repo-worktree-row-resolution.ts• L171-205
Host ownership
An execution host is the machine or runtime that owns workspace files and processes. Orca resolves this owner before it lists, creates, opens, removes, or probes a workspace. An unknown or ambiguous owner stops the action instead of falling back to a local path with the same spelling.
The same host decision controls file access, visible rows, terminals, metadata, and cleanup. This keeps a remote or runtime workspace from being opened or removed through a local checkout by mistake.
References: src/…/worktree-create-execution-host-route.ts• L21-51 src/…/repo-worktree-row-resolution.ts• L82-115 src/…/host-qualified-identity.ts• L27-101
Folder workspace records
A folder workspace is a session record for an existing directory. Several sessions can use one folder. Retiring one session removes only its record and leaves the shared directory in place. A project-root session remains protected because the folder project owns the directory.
Folder workspaces can belong to project groups. Group setup runs in the group root while each session keeps its own workspace key and runner lifetime. This lets sessions share setup context without sharing terminal or metadata identity.
References: src/…/runtime-folder-worktree-create.ts• L59-153 src/…/runtime-group-folder-setup.ts• L52-160 src/…/workspace-registration-removal.ts• L84-108
Workspace locations
Orca selects a workspace location from repository and global path settings. A repository-specific base is resolved on the repository's owning host. The same host path view is then used for creation, visibility, authorization, and cleanup.
Windows and WSL use their own path rules. A controller path is not treated as proof of a path inside a WSL distribution.
References: src/…/configured-worktree-base-path.ts• L1-80 src/…/runtime-worktree-filesystem.ts• L24-48 src/…/local-worktree-filesystem.ts• L58-168
Worktree visibility
The catalog separates Orca-managed worktrees from external checkouts and agent scratch worktrees. Repository policy can expose selected external paths and can define built-in or custom visibility sources. Visibility is evaluated after host ownership is resolved, so a path that looks like a workspace is not enough to make it managed.
References: src/…/runtime-worktree-visibility.ts• L13-41 src/…/workspace-process-listing.ts• L157-189 src/…/visibility-sources.test.ts• L27-145
Workspace session ownership
A workspace session is the user-facing state that returns when a workspace opens again. Its owner is the host-qualified workspace instance rather than only a path or repository ID. This keeps terminals, files, browser state, agents, focus, and review context with the correct checkout.
Workspace identity
The usual worktree ID combines the repository ID and path. Because paths can change and folder sessions can share a directory, durable state also records an instance identity and execution host. A new checkout at a reused path must not inherit the old session or lineage.
Path spelling is folded only for comparison. The stored ID keeps its original path. Comparison accounts for platform differences such as separators, drive-letter case, and equivalent WSL roots. Folder session IDs preserve their per-session suffix when they share one directory.
References: src/…/id.ts• L15-97 src/…/path-equal-worktree-rows.ts• L1-120 src/…/runtime-worktree-path-identity.ts• L1-80
Host-qualified sessions
The same locator can exist on more than one host. Session and metadata operations therefore select the host-owned partition before they update or purge state. An unqualified row stays in an unknown bucket and is never assumed to be local.
The rule also applies to saved sort order, activity, terminals, and metadata discovery. An ID-only write is allowed only when one host owns the row. A host-named write is allowed only when repository registration confirms that host.
References: src/…/get-runtime-id.ts• L26-110 src/…/host-qualified-worktree-meta.ts• L24-124 src/…/runtime-worktree-ps-activity.ts• L203-312
Session restoration
Restoration rebuilds the workspace surface from durable ownership records. It reconnects terminal and agent surfaces only when the saved binding still belongs to the workspace on the expected host. Duplicate or damaged bindings remain unresolved instead of attaching to the first matching row.
A failed or timed-out repository scan does not prove that a saved workspace was deleted. A persisted terminal is accepted only when its host, workspace, pane, process handle, and process incarnation agree. A saved sleeping agent is recovery state, not proof of a running agent. A live status or a fresh process check must prove current activity.
References: src/…/session-worktree-ownership.ts• L21-119 src/…/worktree-ps-saved-sleep.test.ts• L37-192 src/…/runtime-hook-agent-row-selection.ts• L35-96
Workspace activation
Activation selects one workspace surface for the client and routes work to that workspace's host. Desktop activation can notify the host and clients. Mobile activation rebuilds session tabs and reports whether sleeping agents can be woken by an authoritative host.
Creation can also run while the renderer is reloading or unavailable. The owning host retains creation and terminal work, then reports the result when a client can consume it.
References: src/…/workspace-activation.ts• L59-140 src/…/runtime-folder-worktree-create.ts• L142-152 src/…/orca-runtime-worktree-provisioning-availability.test.ts• L36-110
Lifecycle serialization
Workspace lifecycle commands are serialized per host and workspace. This prevents sleep, wake, create, and delete from overtaking one another. Creation remains visible only after a fresh catalog result confirms its membership.
An operation that fails with an unknown host outcome pauses later work. A confirmed operation failure is reported as a failure. A force delete can explicitly break a paused wait, but it does not silently convert lost contact into proof that the host stopped its processes.
References: src/…/workspace-lifecycle-queue.ts• L58-113 src/…/workspace-lifecycle-command.ts• L5-47 src/…/workspace-lifecycle-creations.ts• L35-87
Worktree creation
Creation turns a workspace request into a Git checkout or a folder session on the selected host. It resolves the repository and base, chooses a safe branch and path, creates or adopts the workspace, records ownership, and then starts setup or an agent surface when requested.
The main lifecycle is:
flowchart LR
A[Workspace request] --> B[Resolve repository and host]
B --> C[Resolve base and candidate]
C --> D[Create or adopt workspace]
D --> E[Persist identity and metadata]
E --> F[Record lineage]
F --> G[Run setup and provision surfaces]
G --> H[Publish catalog and activate]
Creation routing
Desktop IPC and runtime calls share the creation contract. A local Git request creates a worktree on the local project runtime. A folder request registers a session. A provisioned-root request adopts a checkout that already exists. A route that this process cannot serve fails before it touches a path.
Creation is made visible after the project is known. A retry can reuse its client mutation identity for a short period. This prevents a connection change from creating a duplicate workspace.
References: src/…/workspace-creation.ts• L33-79 src/…/runtime-provisioned-workspace-adoption.ts• L10-29 src/…/folder-workspace.ts• L11-64
Base selection
The requested base has priority when Git can resolve it. Otherwise Orca uses the repository or detected default. A remote-tracking base can be refreshed when safe, while a usable local base remains available when the network is not.
When a new branch has the same name as its remote base, Orca restores the upstream link. Other new branches remain untracked until their first push. Existing branches are reused only when the request and current Git state agree; a busy or divergent branch is not silently replaced.
References: src/…/runtime-local-worktree-create.ts• L1080-1179 src/…/worktree-add.ts• L34-185 src/…/runtime-branch-reuse-real-git.test.ts• L115-287
Branch and path selection
Orca derives a Git-safe branch and a workspace path from the request and repository settings. It validates branch prefixes and keeps path rules separate for Windows, POSIX, and WSL hosts. It refuses a candidate that leaves the allowed workspace area or conflicts with a pending removal.
Generated names have a retirement record so later suggestions do not reuse a retired generated name. User-entered names remain reusable because generated-name retirement is not a ban on arbitrary branch names.
References: src/…/worktree-branch-name.ts• L19-61 src/…/runtime-local-worktree-create.ts• L1202-1303 src/…/runtime-branch-reuse-real-git.test.ts• L290-326
Folder setup and startup
Setup policy is checked before Git creates a checkout when a repository needs a user choice. This keeps a missing decision free of side effects. After creation, setup and startup run on the selected host and can return warnings without changing the fact that the workspace exists.
The host decides which terminals and default tabs to provision. A setup wrapper can hold agent startup until setup ends. Readiness checks wait for a safe agent prompt and reject shell output, failed setup, stale panes, or an uncertain host. A failed startup remains visible as a warning or surface state rather than turning a valid checkout into a failed create.
References: src/…/runtime-group-folder-setup.ts• L52-160 src/…/runtime-local-worktree-terminal-startup.ts• L63-257 src/…/runtime-worktree-startup-readiness.ts• L44-117
Creation metadata
Creation metadata records product choices that Git does not know. It includes the workspace instance and host, display choices, links, sparse settings, creator and automation context, selected agent, base information, push-target ownership, startup state, and lineage.
The create result can report setup state, startup surfaces, warnings, progress, and base fallback while still reporting a valid checkout. Auxiliary writes are best effort, but stale base data is removed when it cannot be replaced.
References: src/…/runtime-local-worktree-materialization.ts• L68-147 src/…/runtime-managed-worktree-metadata.ts• L61-194 src/…/meta-types.ts• L18-103
Creation publication
Publication sends the host's result to clients and refreshes the catalog before the new row is consumed. The result can contain warnings and partial startup state. Activation callbacks route the initial surface to the correct host or client without forcing an unrelated desktop window to navigate.
References: src/…/workspace-creation.ts• L186-260 src/…/workspace-catalog.ts• L112-155 src/…/orca-runtime-worktree-provisioning-availability.test.ts• L91-110
Worktree retirement
Retirement removes a workspace from active use and releases resources that belong to it. A Git retirement checks the selected host and checkout state, stops owned sessions, removes the checkout, updates branch and remote state, purges metadata, and publishes the result. A folder workspace retires only its session record.
Removal ownership
Removal resolves one host and keeps it through listing, process teardown, Git work, metadata purge, and publication. The target carries the confirmed workspace ID and host claim. If two hosts own the same locator, an unqualified request fails closed.
Requests for the same workspace and cleanup policy can join one in-flight removal. This prevents competing deletes from using different ownership decisions.
References: src/…/workspace-removal.ts• L69-156 src/…/runtime-worktree-removal-target.ts• L9-45 src/…/workspace-removal-target.ts• L55-119
Removal sequence
The normal Git sequence keeps an accepted removal recoverable:
- Resolve the repository, host, and canonical checkout.
- Check locks, dirty state, nested worktrees, and archive policy.
- Stop terminals and structured agent sessions, then close file-watcher access.
- Remove shared links and the Git checkout.
- Retire branch and push-target state according to saved policy.
- Purge workspace metadata and transient state, then publish the change.
Slow deletion can continue in the background. The workspace remains marked as removing until the host reports completion. A second request joins the existing removal instead of starting a competing delete.
References: src/…/runtime-registered-local-worktree-removal.ts• L94-225 src/…/runtime-registered-local-worktree-removal.ts• L241-312 src/…/workspace-removal-target.ts• L147-235
Archive hook gate
The archive hook is the last save step before destructive cleanup. A failed or unverifiable hook stops removal before processes or files change. Only an explicit failed-hook waiver allows cleanup to continue after a failed archive.
References: src/…/worktree-archive-hook-gate.ts• L9-33 src/…/runtime-registered-local-worktree-removal.ts• L98-120
Branch and push-target retirement
Orca normally removes a branch created for the workspace. Metadata can preserve an existing branch. A later force delete still checks the saved branch and expected head so cleanup cannot remove a different ref after the branch moves.
An Orca-created review remote is retired only when no known workspace in the repository still owns or references it. Cleanup checks branch remote configuration, the current URL, and the Git-side Orca provenance marker. It does not remove common user remotes or a remote still needed by a live branch.
References: src/…/worktree-branch-removal.ts• L17-195 src/…/worktree-push-target-cleanup.ts• L44-246 src/…/worktree-remote.ts• L717-927
Folder retirement
Folder retirement stops sessions on the owning host and removes session metadata. It does not remove the shared folder. The project-root session is protected and can be removed only with the folder project.
References: src/…/folder-workspace.ts• L47-64 src/…/workspace-registration-removal.ts• L84-108
Removal recovery
An interrupted or failed removal keeps a durable record of the accepted path, branch, head, host, and delete policy. The host can resume an interrupted delete at the next start. A failed delete stays visible for an explicit retry rather than running unseen in the background.
If Git has already dropped the registration but files remain, recovery removes only a proven leftover. It keeps the branch and push target until the folder is gone. A different checkout, nested registered checkout, symlink, or ordinary user folder blocks recovery.
References: src/…/worktree-background-removal.ts• L54-186 src/…/runtime-interrupted-local-worktree-removal.ts• L130-277 src/…/worktree-removal-leftover.ts• L67-177
Workspace cleanup
Workspace cleanup is a host-owned policy service that finds inactive or otherwise eligible workspaces and removes or archives them. It separates a preview from a run, uses the same evidence model for both, records a run report, and never treats missing evidence as permission to delete.
Cleanup evidence
Cleanup evaluates worktree state together with activity and user intent. Its evidence includes Git status, merge state, saved activity, live agents, active workspaces, terminal liveness, unsaved editor buffers, pins, and folder membership. Main worktrees and protected rows are kept without expensive Git checks.
Each host cleans only repositories and checkouts that it owns. A remote or paired host contributes evidence only through an explicit host route. A failed scan, truncated listing, or unavailable paired server keeps the affected workspace or folder group.
References: src/…/workspace-cleanup-run-evidence.ts• L59-184 src/…/workspace-cleanup-run-evidence.ts• L187-281 src/…/workspace-cleanup-paired-folder-children.ts• L49-101
Cleanup scheduling
The cleanup runner starts after workspace sessions have time to restore. It responds to enabled policy changes and runs at most one cleanup at a time. Preview requests with the same rules share one evaluation, while a run re-checks each candidate immediately before removal.
The command line exposes preview, run, and report operations. A request timeout does not imply that the host stopped the run; the report command is the source for the final run state.
References: src/…/workspace-cleanup-runner.ts• L43-145 src/…/workspace-cleanup-runner.ts• L182-235 src/…/workspace-cleanup.ts• L17-88
Folder cleanup groups
A folder workspace can span several repositories and hosts. Cleanup treats its related worktrees as one safety group so it does not remove one member while another member is active, dirty, or unknown. Bot homes and orchestration hand-offs are separate work because they are not ordinary members of the user's folder work.
The group is re-read before each removal. A sibling created during a long run can therefore hold the group. An incomplete paired-host read also holds the group because the missing host may contain another member.
References: src/…/workspace-cleanup-folder-membership.ts• L31-161 src/…/workspace-cleanup-removal-step.ts• L67-149 src/…/workspace-cleanup-folder-group.test.ts• L179-345
Cleanup reports
Every run records its trigger, time range, per-workspace outcome, reason, error, branch result, and optional space data. Kept rows explain the blocker. Failed rows remain visible for a later action. A run with no enabled rule does no workspace scan and reports that cleanup is off.
References: src/…/workspace-cleanup-runner.ts• L239-339 src/…/workspace-cleanup-runner-methods.ts• L56-103 src/…/workspace-cleanup.test.ts• L33-50
Worktree observation
Observation keeps the catalog and Source Control view aligned with Git actions outside Orca. Local hosts use native change signals with bounded reconciliation. Remote hosts use their host route and stored rows when the local process cannot read the remote Git area.
Catalog authority
An authoritative listing proves that the selected host answered and that omitted worktrees are safe to treat as absent. A failed, disconnected, stale, or overtaken report is retained as non-authoritative evidence and cannot prune live rows.
The resolved catalog combines repository scans with folder sessions, metadata, visibility, and lineage. It can keep a persisted row when a scan has not reached a safe verdict. A repository with no completed scan is marked unscanned rather than treated as a repository with no worktrees.
References: src/…/workspace-catalog.ts• L107-155 src/…/repo-worktree-row-resolution.ts• L82-157 src/…/resolved-worktree-scan-join.ts• L91-150
Catalog assembly
The catalog scans Git repositories by host-qualified repository key and joins each scan with current metadata. It then projects folder sessions and lineage. A row projection memo reuses unchanged rows while rebuilding rows whose Git facts or identity metadata changed. This keeps clients stable while a metadata write updates one workspace.
The catalog cache uses a short resolved-row lifetime and a longer scan lifetime. Its runtime key changes when the project runtime or SSH route changes. This keeps cached rows tied to the host that produced them.
References: src/…/repo-worktree-row-resolution.ts• L160-263 src/…/worktree-row-projection-memo.ts• L37-99 src/…/runtime-worktree-scan-cache.ts• L13-42
Visibility projection
Listing applies hidden repository and host rules, resolves the worktree's host, and then applies configured visibility sources. Scoped listings still name known hosts even when a row limit prevents every row from being shown. This lets clients distinguish a truncated result from an unlisted host.
References: src/…/workspace-process-listing.ts• L157-189 src/…/runtime-managed-worktree-queries.ts• L71-113 src/…/worktree-listing-host-scope.ts• L1-100
Scan freshness
Each scan has a generation, runtime key, expiry, and Git administration fingerprint. A mutation that overtakes an in-flight scan makes that scan stale. Its rows and pruning effects cannot be published as current.
When the fingerprint is unknown or a probe stalls, Orca keeps known rows and uses a bounded fallback. A slow mount therefore causes limited staleness instead of a false empty catalog.
References: src/…/runtime-worktree-scan-state.ts• L1-24 src/…/runtime-worktree-scan-cache.ts• L13-42 src/…/worktree-scan-admin-fingerprint-gate.test.ts• L181-245
Filesystem observation
Filesystem observation separates structural changes from status-only changes. Structural changes refresh the worktree catalog. Index changes refresh Source Control. Head changes use a narrower identity signal so background worktrees can update without a full graph rebuild.
The watcher path is supported by bounded polling. Polling avoids overlapping scans and keeps periodic full checks for filesystems that hide child changes or lose native events.
References: src/…/worktree-git-common-entry-snapshot.ts• L31-148 src/…/worktree-git-common-polling.ts• L22-249 src/…/worktree-git-common-watch-reconciliation.ts• L10-125
Cleanup safety
Cleanup is fail-closed when Orca cannot prove that a path, Git registration, process, or metadata record belongs to the selected workspace. The system prefers a visible stale row and a retry over deletion of a repository, nested worktree, or another host's live session.
Path and registration proof
Orca refuses dangerous paths such as repository roots, home directories, file-system roots, and paths that contain registered child worktrees. A missing Git row alone does not authorize directory deletion. An unregistered directory needs matching Orca ownership evidence and an explicit recovery choice.
References: src/…/worktree-removal-safety.ts• L1-180 src/…/worktree-removal-leftover.ts• L119-151 src/…/runtime-interrupted-local-worktree-removal.ts• L206-267
Process proof
Before a checkout is deleted, Orca checks runtime, provider, registry, and structured-session ownership. Normal removal requires proof that owned processes stopped. Force Delete can waive that proof only through an explicit option. Dirty-file force is not the same as permission to delete a live PTY or agent session.
An unreachable host reports terminal liveness as unverifiable rather than inactive. This protects cleanup and activity views from turning lost relay contact into a safe-to-delete result.
References: src/…/worktree-teardown.ts• L76-308 src/…/worktree-ps-unverifiable-terminals.test.ts• L77-116 src/…/removal.ts• L4-69
Nested worktree proof
When a target contains registered child worktrees, Orca does not infer that all children should be deleted. It shows a removal plan and requires approval for the exact children. A partial failure keeps preserved branches and remaining work visible for later cleanup.
References: src/…/nested-worktree-removal.ts• L18-81 src/…/worktree-prune-guard.ts• L1-120 src/…/worktree-removal-leftover.ts• L77-85
Platform path proof
File checks and deletion run through the selected host's path view. Windows uses native and delayed-directory handling. WSL uses the distribution's Linux path view. A move, timeout, permission error, or unavailable host remains blocked or unverifiable instead of looking absent.
References: src/…/local-worktree-filesystem.ts• L58-168 src/…/runtime-worktree-filesystem.ts• L24-48 src/…/worktree-removal.ts• L185-205
Cleanup evidence
Cleanup views distinguish clean inactive workspaces from protected or uncertain rows. Main worktrees, folder roots, active sessions, disconnected hosts, incomplete evidence, and unsaved editor buffers are not ordinary reclaimable workspaces. Unavailable space measurements remain unavailable rather than becoming zero.
References: src/…/workspace-cleanup-run-evidence.ts• L109-184 src/…/managed-workspace-operations.ts• L64-87 src/…/workspace-catalog.ts• L148-190
Metadata and lineage
Metadata joins live Git facts with product state that Git does not know. Lineage records the parent context of a workspace so an agent-created checkout remains traceable when its path changes or is reused.
Git and product state
Git supplies checkout path, branch, head, lock, sparse, main-worktree, and removal-state facts. Orca metadata supplies ownership, instance and host identity, display choices, links, activity, creator context, branch policy, creation provenance, and startup state. The catalog joins both while keeping host authority visible.
References: src/…/repo-worktree-row-resolution.ts• L192-235 src/…/runtime-local-worktree-materialization.ts• L68-147 src/…/meta-types.ts• L18-103
Metadata ownership
Metadata updates resolve the workspace before writing and use the workspace's host identity. A late update from a terminal bound to a removed folder session is ignored. Discovery can repair missing host and project ownership without replacing a conflicting host stamp.
Conditional lineage writes can require that the parent is still the one seen by the caller. This prevents a delayed unlink or move from overwriting a newer hand-off.
References: src/…/runtime-managed-worktree-metadata.ts• L61-194 src/…/runtime-managed-worktree-metadata-conditional-parent.test.ts• L68-95 src/…/worktree-discovery-metadata.ts• L12-69
Workspace lineage
Lineage connects a child workspace to a parent workspace or folder session. Explicit parent context is stronger than inferred context. Inferred context can come from an environment, terminal, current directory, task, or orchestration run. Conflicting candidates produce no link instead of a guessed link.
Bot-created work follows the bot's home as an orchestration parent even when the agent request says no parent. A user-selected parent still wins. Bot homes and bot hand-offs remain separate from ordinary folder cleanup groups.
References: src/…/runtime-worktree-lineage-resolution.ts• L75-305 src/…/runtime-bot-created-lineage.test.ts• L61-103 src/…/lineage-types.ts• L1-103
Lineage host boundary
A parent and child must share an execution host when Orca can prove both values. An explicit cross-host parent fails before creation. An inferred cross-host parent is dropped with a warning so creation can succeed without a false relationship.
Cross-store lineage uses an installation identity and instance identity. It is a reference to another store, not permission to treat that store's files as local.
References: src/…/runtime-managed-worktree-metadata.ts• L119-175 src/…/runtime-worktree-lineage-controller.ts• L99-220 src/…/lineage-types.ts• L72-92
Lineage instance safety
Lineage stores workspace IDs and instance IDs. If a path is reused by a new checkout, the instance mismatch prevents the old parent-child relationship from validating. This keeps path reuse from reviving stale agent context.
References: src/…/runtime-managed-worktree-metadata.ts• L241-285 src/…/lineage-types.ts• L38-64 src/…/runtime-worktree-lineage-controller.ts• L205-220
Recovery across hosts and platforms
Recovery reconciles durable metadata with the current report from the execution host. It handles external deletion, stale registration, path reuse, reconnects, host changes, WSL path differences, and incomplete session data without allowing one host to inspect or mutate another host's files.
Selector resolution
Selectors can name a full worktree ID, identity, path, branch, name, linked issue, or folder workspace. A selector with more than one host-qualified match is ambiguous and must be narrowed. Full IDs retain repository and path scope, while comparison can account for platform spelling without changing the stored ID.
Folder selectors can resolve a project-group session. A duplicated folder ID is rejected because no selector can safely choose one host's copy. A path or name can match folders only when the caller opts into folder matching.
References: src/…/workspace-selectors.ts• L53-180 src/…/workspace-selector-candidates.ts• L57-243 src/…/id.ts• L30-55
Missing worktrees
An authoritative host scan can show that a checkout disappeared outside Orca. Orca then forgets or retires only the exact known target and removes related metadata after process and watcher checks. A failed or timed-out scan preserves saved session IDs instead of treating them as deleted.
Headless hosts also sweep metadata that no longer matches an authoritative local scan. Non-authoritative scans do not perform that sweep.
References: src/…/repo-worktree-row-resolution.ts• L82-157 src/…/runtime-managed-worktree-metadata-sweep.test.ts• L58-92 src/…/workspace-removal.ts• L176-249
Disconnected hosts
When SSH or another external host is unavailable, Orca retains host-qualified metadata rows with a non-authoritative reason. It does not treat a missing response as an empty catalog or prune that host's sessions and lineage. When the host returns, Orca rebuilds host-owned surfaces and rechecks terminal authority before publishing recovery.
References: src/…/detected-provider-listing.ts• L89-107 src/…/ssh-worktree-fallback.ts• L78-136 src/…/worktree-ps-unverifiable-terminals.test.ts• L77-116
Path changes
A moved checkout keeps its occupant identity even when its path-based locator changes. Recovery moves workspace-owned state together, including terminal bindings, editor and browser state, focus records, lineage, and close intents. Prior path IDs remain as aliases long enough for session hydration and cleanup to recognize the same workspace.
Identity migration also repoints workspace IDs inside pane, tab, and environment records. This prevents a closed surface from returning under the old path or attaching to a new occupant.
References: src/…/id.ts• L57-75 src/…/worktree-identity-migration.ts• L19-235 src/…/meta-types.ts• L94-99
Host changes
Host changes are ownership changes, not simple path changes. Destructive actions carry the confirmed host from resolution through cleanup. File and Git targets use the same host resolver, so an SSH or runtime workspace cannot silently route through a local repository row.
References: src/…/worktree-create-execution-host-route.ts• L26-51 src/…/workspace-file-session-targets.ts• L202-261 src/…/workspace-removal-target.ts• L55-119
Windows and WSL recovery
The owning host controls path comparison, Git invocation, existence checks, and deletion. WSL repositories use Linux paths inside the selected distribution. Windows worktrees use Windows-safe deletion rules. A move fence, timeout, permission error, or missing host answer keeps ownership uncertain instead of making the path look gone.
References: src/…/local-worktree-filesystem.ts• L76-168 src/…/runtime-worktree-filesystem.ts• L24-48 src/…/runtime-interrupted-local-worktree-removal.ts• L177-267
State purge
After confirmed retirement or an authoritative omission, Orca removes state owned by the retired workspace. This includes metadata, terminals, agent bindings, browser and editor state, status caches, focus and launch intents, cleanup snapshots, and Orca-created agent trust. The purge is host-scoped and protects a surviving same-ID owner.
References: src/…/workspace-removal-target.ts• L147-235 src/…/worktree-removal-agent-trust-cleanup.test.ts• L33-83 src/…/host-qualified-worktree-meta.ts• L109-124
Change checklist
When these files or sections are changed, remember to consider these:
- Keep repository resolution, execution-host routing, Git access, PTY ownership, cleanup evidence, and metadata purge on the same host-qualified target.
- Keep worktree ID comparison, folder-session instance identity, path aliases, and lineage checks aligned so path reuse cannot inherit state.
- Keep authoritative, non-authoritative, stale, rejected, canceled, and timed-out listings distinct from an empty catalog.
- Keep scan generations, runtime cache keys, catalog versions, row projection memo keys, and mutation invalidation aligned so an old scan cannot undo a create, retirement, or metadata purge.
- Keep folder cleanup membership tied to current lineage, folder instances, paired-host answers, bot-home rules, and exact host identity.
- Keep cleanup preview and removal re-checks based on the same evidence model. A sibling or live terminal found during re-check must hold the group.
- Keep setup refusal before checkout creation. Keep setup, startup, terminal provisioning, and agent readiness warnings separate from checkout success.
- Keep lifecycle queue keys host-qualified and preserve ordering across unresolved lookups, create settling, sleep, wake, and delete.
- Keep archive-hook refusal before PTY stop and file mutation. Record an explicit waiver when cleanup proceeds after a failure.
- Keep stale-registration and leftover recovery behind Git lock checks, current registration checks, safe-root proof, nested-worktree proof, and path ownership evidence.
- Keep branch force-delete fenced by the expected head and aware of active Git operations.
- Keep remote provenance, branch configuration, URL checks, sibling adoption, and host-scoped ownership aligned.
- Keep Windows and WSL probes and deletion on the host that owns the path. An unavailable path must remain unverifiable.
- Keep process-listing visibility aligned with the catalog. Saved sleep records and restored agent rows must not become proof of live work without host evidence.
- Keep lineage edges tied to execution host and instance identity. Uncertain inferred parents must degrade without creating a false link.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A same-ID workspace is removed without a confirmed host. | Cleanup can stop processes or purge state for another host. | Resolve one host and reject ambiguous ownership. |
| A failed host scan returns an authoritative empty catalog. | Live workspaces can disappear and metadata can be pruned. | Retain rows as non-authoritative until the host gives a safe verdict. |
| A folder project or folder group is resolved without a unique host and session identity. | A command can open or remove the wrong shared directory. | Reject ambiguous folder IDs and require host-qualified selection. |
| A create reuses a branch or path held by a pending removal. | Create and delete can race and leave invalid state. | Reject the create until the matching removal settles. |
| Setup or startup is treated as part of checkout success. | A valid checkout can be hidden by a terminal or hook failure. | Return warnings and surface state separately from the created workspace. |
| A cleanup run removes a folder member without re-reading its siblings. | A newer or active sibling can be removed with the group. | Recollect folder membership and evidence immediately before removal. |
| A paired host does not answer during folder cleanup. | A workspace group can be split and a remote member can be removed unexpectedly. | Keep the group when the paired read is incomplete. |
| A PTY or structured session cannot be proved stopped. | Deletion can leave a running process tied to a removed path. | Require stop proof or an explicit Force Delete waiver. |
| An unregistered path is classified by path shape alone. | A user directory can be deleted as an Orca worktree. | Require ownership evidence, safe-root proof, and explicit recovery choice. |
| A nested worktree is deleted without exact approval. | Child checkouts or branches can be removed unexpectedly. | Require a current plan and matching approval. |
| A Git delete fails after registration is gone. | Files, branch, and push-target state can remain out of sync. | Keep a visible leftover record and retry only after current path and Git proof. |
| A different checkout replaces a failed-removal path. | Recovery can delete another user's work. | Compare registration, branch, head, path, and nested checkout state before deletion. |
| A branch moves while stale cleanup waits to force-delete it. | Cleanup can delete a newer branch tip or user work. | Delete only when the ref still matches the recorded head. |
| A path moves without its instance and session state. | Closed terminals, drafts, or agent state can return on the wrong checkout. | Re-key workspace-owned state and validate instance identity. |
| A port or file action uses a client-supplied path or host. | Orca can act on the wrong workspace or machine. | Resolve the workspace through the host-owned catalog. |
| A restored sleep or agent row is treated as a live process. | Cleanup or status can report activity that no longer exists. | Require fresh PTY, host, structured-session, or pane evidence. |
| Lineage crosses hosts or reuses an old instance. | Agent nesting can point to an unrelated workspace after reconnect or path reuse. | Enforce host and instance checks and drop uncertain inferred edges. |
Key files
| File | Why to read it |
|---|---|
| src/…/repo-worktrees.ts | Shows how registered repositories become Git or folder workspace sources. |
| src/…/folder-repo-git-conversion.ts | Shows how a folder project is safely proven and stamped as a Git project. |
| src/…/worktree-create-execution-host-route.ts | Defines which host owns creation and when a route must fail closed. |
| src/…/workspace-catalog.ts | Combines scans, metadata, folder sessions, and lineage into resolved rows. |
| src/…/repo-worktree-row-resolution.ts | Shows degraded scan fallback, host ownership, metadata stamping, and row projection. |
| src/…/workspace-selector-candidates.ts | Defines folder and worktree selection and ambiguity behavior. |
| src/…/workspace-creation.ts | Shows creation routing, setup, lineage, publication, and activation. |
| src/…/runtime-local-worktree-create.ts | Shows base, branch, path, and Git creation decisions. |
| src/…/runtime-folder-worktree-create.ts | Shows folder session identity, metadata, and startup behavior. |
| src/…/runtime-local-worktree-terminal-startup.ts | Shows host-owned terminal and setup provisioning. |
| src/…/runtime-worktree-startup-readiness.ts | Defines safe readiness checks before startup input is delivered. |
| src/…/workspace-lifecycle-queue.ts | Defines ordering, settling, cancellation, and recovery pauses. |
| src/…/runtime-registered-local-worktree-removal.ts | Defines archive checks, teardown, Git deletion, and publication. |
| src/…/runtime-interrupted-local-worktree-removal.ts | Shows how interrupted removals finish from current Git and filesystem evidence. |
| src/…/worktree-background-removal.ts | Defines durable background removal, restart recovery, and visible failure records. |
| src/…/workspace-cleanup-runner.ts | Defines cleanup scheduling, shared preview evaluation, run reports, and re-checks. |
| src/…/workspace-cleanup-run-evidence.ts | Defines the evidence and host ownership used by cleanup policy. |
| src/…/workspace-cleanup-folder-membership.ts | Defines folder-wide cleanup grouping across lineage and hosts. |
| src/…/runtime-managed-worktree-metadata.ts | Defines host-aware metadata and conditional lineage updates. |
| src/…/workspace-process-listing.ts | Defines host-scoped workspace activity and agent status summaries. |
| src/…/workspace-removal-target.ts | Defines state purge, same-ID protection, and interrupted-removal resumption. |
| src/…/local-worktree-filesystem.ts | Defines platform-owned path proof and WSL filesystem deletion. |
| src/…/id.ts | Defines stored worktree IDs, comparison folding, and folder-session paths. |
| src/…/lineage-types.ts | Defines instance-aware same-store and cross-store lineage. |