Files
kandev/docs/specs/tasks/attach-workspace-sources.md
T

342 lines
25 KiB
Markdown

---
status: building
created: 2026-07-22
owner: kandev
---
# Attach Workspace Sources
## Why
Tasks often grow beyond the repositories selected at creation time. Users need to add another
repository or supporting folder without recreating the task, losing conversation context, or
manually moving files into the task workspace.
## What
- A repository-backed task exposes one **Workspace actions** menu in the Files panel on desktop and
mobile. The menu contains **Add Repositories to workspace** and **Open workspace folder** rather
than separate toolbar controls.
- **Add sources** uses the same repository-selection language as task creation without adding a
second mode switch. One **Add repository** menu offers **Workspace repository**, **Local Git
repository**, and **Remote repository**; **Add folder** remains a separate action when supported.
- Subject to the task executor's capabilities, one submission can add one or more mixed sources.
**Workspace repository** combines saved workspace repositories and discovered local Git
repositories in the shared repository selector, including its refresh and create-repository
actions. **Local Git repository** accepts an existing checkout, **Remote repository** reuses the
provider-backed and pasted-URL selector from task creation, and **Add folder** offers an arbitrary
local folder when supported.
- Adding another repository or folder appends a row without hiding or discarding configured rows,
so one submission can mix workspace, local, remote, and folder sources.
- Repository rows choose a base branch with the shared task-creation controls. The add-sources UI
does not expose a second checkout-branch field.
- A successful submission makes every added source visible as a named top-level entry in the Files
panel. Repository sources also appear in repository-aware Changes, branch, editor, and pull
request surfaces; folder sources remain file-only.
- Duplicate repository/branch pairs, duplicate canonical folder paths, cross-workspace repository
IDs, invalid remote URLs, and inaccessible local paths are rejected before the task changes.
- A source file rename may stay within its canonical workspace/source root; a cross-root move or
rename is rejected before either source is mutated.
- A multi-source submission is atomic from the user's perspective: either every source is attached
and materialized in the current task environment, or none of the new attachments remain. When an
attachment repointed a pre-existing Kandev-owned entry, a failed submission restores that entry to
the target it had before the attachment rather than deleting it.
- Repository attachment works for every executor that can run the task. Arbitrary folders are
available only to Local and Worktree tasks, where the selected host paths remain live. Container
and remote pickers do not offer the folder source kind, and the backend rejects a forged folder
request without changing the task.
- Kandev may re-root or restart an idle task environment when its executor cannot safely change the
agent working directory in place. The action is unavailable while a turn or tool call is active,
and the backend independently rejects that race with a conflict response.
- Before submission, the desktop dialog and phone drawer explain the executor-specific effect on
the agent working directory, provider session context, terminal and workspace processes, existing
files and Git changes, and atomic rollback. They state that **Cancel** leaves the task unchanged.
- Providers that honor a changed `session/load` working directory keep their native ACP session
after the re-root. Providers that do not are started in a fresh ACP session at the promoted task
root, and Kandev rehydrates the recorded conversation context with the next prompt.
- Worktree and Local/Local PC rebinds stop terminal shells, the task editor server, dev servers, and
other agentctl-managed workspace processes; users must reopen or restart them. Docker, SSH, and
Sprites attach repository siblings through the live workspace and rescan without restarting the
agent or those processes.
- When **Add Repositories to workspace** is unavailable, the combined Files action remains
reachable so **Open workspace folder** still works. The repository action is disabled and shows
the reason in touch-visible text rather than relying on a tooltip.
- Existing conversations, task state, plan, sessions, and repository attachments remain intact.
- Agents receive a batch `add_workspace_sources_kandev` MCP tool that uses the same validation and
materialization path.
- The existing worktree-only `add_branch_to_task_kandev` tool remains a live compatibility path
for one repository/branch source. It may run during the invoking agent turn, creates the new
worktree as a sibling under the Kandev-owned task root, promotes the persisted task workspace
path to that root, and refreshes Files and repository trackers without restarting the agent or
agentctl-managed workspace processes.
- A legacy add-branch call does not nest the new worktree inside the current repository and does
not change the running agent or terminal working directory. Its MCP result returns the exact new
worktree path, the promoted task workspace path, and that the agent CWD did not change.
Decisions: [ADR-2026-07-22-runtime-mutable-task-workspace-sources](../../decisions/2026-07-22-runtime-mutable-task-workspace-sources.md)
[ADR-2026-07-23-workspace-source-root-move-boundary](../../decisions/2026-07-23-workspace-source-root-move-boundary.md),
and [ADR-2026-07-27-legacy-add-branch-live-rescan](../../decisions/2026-07-27-legacy-add-branch-live-rescan.md).
## Data model
Repository attachments continue to use `task_repositories`; their current uniqueness contract on
`(task_id, repository_id, base_branch, checkout_branch)` is unchanged.
Arbitrary folder attachments use `task_workspace_folders`:
| Field | Contract |
| -------------------------- | ---------------------------------------------------- |
| `id` | Stable attachment identity. |
| `task_id` | Owning task; cascade-deleted with the task. |
| `local_path` | Canonical absolute path selected on the Kandev host. |
| `display_name` | Sanitized, non-empty top-level workspace entry name. |
| `position` | Stable order among folder attachments. |
| `created_at`, `updated_at` | Audit timestamps. |
`(task_id, local_path)` and `(task_id, display_name)` are unique. The effective source projection
combines ordered `task_repositories` and `task_workspace_folders`; it does not replace repository
identity or make folders participate in Git operations.
## API surface
`POST /api/v1/tasks/:id/workspace-sources`
```json
{
"sources": [
{
"kind": "repository",
"repository_id": "optional-workspace-repository-id",
"local_path": "optional-local-git-path",
"remote_url": "optional-provider-or-pasted-url",
"provider": "optional-provider",
"provider_repo_id": "optional-provider-id",
"provider_owner": "optional-provider-owner",
"provider_name": "optional-provider-name",
"base_branch": "main",
"checkout_branch": "optional-existing-branch"
},
{
"kind": "folder",
"local_path": "/absolute/path/to/folder",
"display_name": "optional-name"
}
]
}
```
The response returns the persisted source projection, the effective task workspace path, and the
affected session IDs. Validation errors return `400`, ownership/not-found errors return `404`,
duplicates or an active turn return `409`, and materialization failures return `422` after rollback.
The backend publishes `task.updated` with both `repositories` and `workspace_folders`, then emits a
session-scoped workspace-sources update after agentctl has adopted the new workspace root. Clients
refresh the Files tree and repository trackers from those events rather than assuming the POST
response is the only writer.
Full and summary task-session responses expose `workspace_path` as the effective task workspace
root. In a multi-source task this is the parent that contains every repository and folder entry;
`worktree_path` remains the flattened primary-repository path for backward compatibility. Live
workspace-source and sibling-materialization events update `workspace_path` without replacing the
primary `worktree_path`, and a later session refresh returns the same effective root.
Chat file links resolve against `workspace_path`, so an absolute path under any attached source is
converted to its task-root-relative Files path before it is opened. Clients may fall back to
`worktree_path` for legacy session payloads that do not yet include `workspace_path`. Absolute paths
outside the effective workspace remain non-actionable and are never rewritten into a workspace
file request.
`add_workspace_sources_kandev` accepts the same source union and defaults `task_id` to the current
task.
`add_branch_to_task_kandev` preserves its existing request arguments and returns:
```json
{
"id": "task-repository-id",
"task_id": "task-id",
"repository_id": "repository-id",
"base_branch": "main",
"checkout_branch": "feature/example",
"position": 1,
"worktree_path": "/absolute/task-root/repository-feature-example",
"task_workspace_path": "/absolute/task-root",
"agent_cwd_changed": false
}
```
`worktree_path` and `task_workspace_path` are omitted when a pre-launch attachment succeeds but
materialization is intentionally deferred until the task launches. `agent_cwd_changed` is always
false. A live call returns the materialized sibling path so the invoking agent can address it
without inferring a directory name.
## Permissions
The action follows Kandev's trusted-local-user model and is scoped to the task's workspace. Saved
repository IDs must belong to that workspace. Explicit local repository and folder selections grant
access only to their canonical paths, not to parent directories, sibling paths, or filesystem
volumes. Remote credentials follow the existing provider-neutral repository contract and are never
persisted in source URLs or copied into agent-visible metadata.
## Failure modes
| Condition | Observable behavior |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| A turn or tool call is active for batch attachment | The UI disables the action when known; a racing batch request returns `409` without mutation. |
| The invoking agent calls legacy add-branch during its turn | The worktree is created and trackers refresh without stopping the active agent, terminals, or workspace processes. |
| Any source is invalid or duplicated | The full batch is rejected before persistence or materialization. |
| A host materializer fails | New filesystem entries and source records are rolled back; existing task contents remain. |
| A container/remote repository clone fails | Newly created remote entries are removed best-effort, durable attachments are rolled back, and the response identifies the failed source. |
| A container/remote task submits a folder source | The request returns `422` without persistence or filesystem changes. |
| Agentctl cannot rescan the new root | The attachment fails rather than reporting success with a stale Files tree. |
| A chat message links to an absolute path outside the task root | The link is not sent to the workspace file API; normal external/unsafe-path handling remains in effect. |
| An idle agent must restart to adopt the promoted root | The intentional stop is not shown as a prior agent failure; the replacement agent uses the promoted task root. |
| A requested file move or rename crosses canonical source roots | The request is rejected before either source is mutated. |
| A persisted local folder later disappears | The current live environment keeps its existing materialization; a new/reset environment surfaces the missing source and does not silently omit it. |
| The client disconnects during materialization | Rollback runs on a detached bounded context and the eventual task event reflects durable state. |
| A Kandev-owned task-root entry already points at a different directory than the current durable spec (e.g. a stale entry left by an earlier launch) | Because the task root is Kandev-owned and the entry is a directory link, reconciliation repoints it to the current spec target and the launch/resume proceeds; it does not fail closed forever. |
| A Kandev-owned task-root entry's ownership marker names a different task than the one reconciling | Reconciliation does not repoint the entry; it fails closed with a marker-conflict error and leaves the other task's entry pointing at its existing target. |
| A multi-source attachment that repointed a pre-existing owned entry later fails during materialization | Rollback restores each repointed entry to the target it had before the attachment and deletes only entries this attachment created; no pre-existing entry is left deleted. |
| A safe replacement would overwrite a non-owned or out-of-root entry, or its recreate fails after removal | A non-owned or changed entry, or a traversal path, is rejected before any removal, and a failed recreate restores the entry to its prior target rather than leaving it missing. |
## Persistence guarantees
Repository and folder attachments survive backend restarts. Local/worktree environments continue to
resolve the exact canonical host path. New container or remote environments recreate repository
checkouts from durable repository attachments; they never persist folder attachments. Existing task
conversations and source records survive an environment restart even when runtime materialization
must be retried.
Each task that materializes a Kandev-owned task root under the tasks base directory derives its
task-root directory name from task identity. The name is collision-resistant, not injective: two
distinct tasks — including two tasks whose titles sanitize to the same slug, or a local task and a
worktree task sharing a title — are overwhelmingly unlikely to resolve to the same task root, and any
residual collision is caught by the fail-closed ownership marker, which verifies task identity before
any Kandev-owned entry under a shared root is repointed. The task-root name is computed once and
persisted; every relaunch and resume of that task reuses the persisted name.
## Scenarios
- **GIVEN** a repository-backed task with the Files tree loaded, **WHEN** the user opens the
workspace-actions control, **THEN** one menu exposes **Add Repositories to workspace** and **Open
workspace folder**.
- **GIVEN** a running worktree task with one repository and no active turn, **WHEN** the user opens
**Add sources**, chooses **Workspace repository**, and adds a saved or discovered repository and
branch with the shared task-create selector, **THEN** the new worktree appears as a top-level
Files entry and in repository-aware Changes surfaces without recreating the task.
- **GIVEN** an idle task whose runtime resumes its agent or emits a late session-resumed status while
adopting an updated workspace root, **WHEN** the user attaches another source, **THEN** lifecycle
boot/status messages do not create a phantom turn and the subsequent attachment succeeds.
- **GIVEN** an idle single-repository task whose agent started in the repository directory, **WHEN**
another source promotes the workspace to the task root, **THEN** the next agent prompt runs from
the task root without a previous-agent-error banner; compatible providers retain their native
session and incompatible providers receive a fresh session with recorded conversation context.
- **GIVEN** an idle Worktree or Local task, **WHEN** the user opens **Add sources**, **THEN** a
visible consequence summary explains that the CWD moves to the task root, the agent and
agentctl-managed workspace processes restart or stop, recorded task context remains, and
provider-private context that Kandev did not record may not carry over.
- **GIVEN** an idle Docker, SSH, or Sprites task, **WHEN** the user opens **Add sources**, **THEN**
the consequence summary says repositories are attached and rescanned under the current remote
workspace without restarting the agent or changing its CWD.
- **GIVEN** configured source rows in either add-sources surface, **WHEN** the user chooses
**Cancel** or closes the surface before submission, **THEN** no attachment request is sent and
the task workspace remains unchanged.
- **GIVEN** an Add sources batch with a local row already configured, **WHEN** the user chooses
**Remote repository** from **Add repository**, **THEN** both rows remain visible in the batch and
submit atomically.
- **GIVEN** a repository-backed local task, **WHEN** the user adds a local Git repository and an
arbitrary folder in one submission, **THEN** both live sources appear under one task workspace and
the folder does not appear in Git-only controls.
- **GIVEN** a Docker, SSH, or Sprites task, **WHEN** the user opens **Add sources**, **THEN** the
workspace, local-Git, and remote repository choices are available from **Add repository**, and
the local-folder affordance is not offered.
- **GIVEN** a Docker, SSH, or Sprites task, **WHEN** a client submits a forged folder source,
**THEN** the backend returns `422` and leaves the task and executor filesystem unchanged.
- **GIVEN** a mixed three-source submission whose second source cannot be cloned, **WHEN**
materialization fails, **THEN** none of the three new attachments remain in the database, Files
tree, or executor workspace.
- **GIVEN** an active agent turn, **WHEN** the user attempts to add sources, **THEN** no source is
attached, the **Add Repositories to workspace** menu item explains that the task must be idle
first, and **Open workspace folder** remains available.
- **GIVEN** an active worktree-executor agent whose CWD is the initial repository, **WHEN** it calls
`add_branch_to_task_kandev`, **THEN** Kandev creates the new repository/branch worktree as a
sibling under the task root, promotes the persisted workspace path, refreshes Files and
repository trackers, and does not restart the agent or change its CWD.
- **GIVEN** a live legacy add-branch materialization, **WHEN** the MCP result returns, **THEN** it
includes the absolute new `worktree_path`, the promoted `task_workspace_path`, and
`agent_cwd_changed: false`.
- **GIVEN** the original repository has no pending changes, **WHEN** a legacy add-branch call creates
a sibling worktree, **THEN** Git status in the original repository does not report the sibling as
an untracked or changed path.
- **GIVEN** a task whose workspace contains multiple repositories, **WHEN** an agent message links
to an absolute file path in either the primary or an attached repository, **THEN** clicking the
link opens the exact file through the task-root-relative Files API path without a file-not-found
notification.
- **GIVEN** that multi-repository task is reloaded after workspace promotion, **WHEN** the user
clicks the same chat file link, **THEN** the session-restored `workspace_path` resolves the same
file and `worktree_path` still identifies the primary repository.
- **GIVEN** a legacy single-repository session payload without `workspace_path`, **WHEN** a chat
file link is inside `worktree_path`, **THEN** the link continues to open as a repository-relative
path.
- **GIVEN** a live legacy add-branch materialization fails, **WHEN** the MCP call returns an error,
**THEN** the new `task_repositories` row and any newly created repository entity are rolled back
while the agent and existing processes continue running.
- **GIVEN** the same repository/branch or canonical folder is already attached, **WHEN** it is
submitted again, **THEN** the request returns a conflict naming the duplicate and leaves the task
unchanged.
- **GIVEN** a phone viewport on the Files tab, **WHEN** the user opens the 44px workspace-actions
control, **THEN** an inset bottom-sheet menu exposes both actions with touch-sized rows.
- **GIVEN** that phone action menu, **WHEN** the user selects **Add Repositories to workspace**,
chooses repository kinds from the touch-sized **Add repository** menu, adds two sources, and
submits, **THEN** a touch-usable full-height picker completes the same operation without
horizontal document overflow and returns focus to the workspace-actions control.
- **GIVEN** an agent calls `add_workspace_sources_kandev` for its current idle task, **WHEN** all
inputs materialize, **THEN** the UI receives the same task and session updates as the human flow.
- **GIVEN** two distinct tasks whose titles sanitize to the same task-root slug, **WHEN** each task
materializes a Kandev-owned task root, **THEN** their collision-resistant suffixes normally produce
different task-root directory names; if a residual suffix collision occurs, the ownership marker
rejects cross-task repointing with a marker-conflict error rather than redirecting the other task's
entries.
- **GIVEN** a local task whose persisted task root already contains a Kandev-owned directory-link
entry for a repository that points at a different directory than the current durable spec target,
**WHEN** the task launches or resumes, **THEN** reconciliation repoints the owned entry to the
current spec target and the launch/resume proceeds instead of failing with an owned-link target
mismatch on every attempt.
- **GIVEN** a Kandev-owned task-root entry that is not a directory link (a real file or directory a
reconcile did not create), **WHEN** the task launches or resumes, **THEN** reconciliation does not
delete or overwrite it and the launch surfaces an error identifying the conflicting entry.
- **GIVEN** two persisted legacy tasks whose environments share one Kandev-owned task root, **WHEN**
the second task launches or resumes and its ownership marker does not match the root's marker,
**THEN** reconciliation fails closed with a marker-conflict error and does not redirect the first
task's live entry.
- **GIVEN** a multi-source attachment that repointed a pre-existing Kandev-owned entry, **WHEN** a
later source in the same submission fails to materialize, **THEN** rollback restores the repointed
entry to its prior target and no pre-existing entry is left deleted.
- **GIVEN** a Kandev-owned entry whose recreate could fail after the old link is removed, **WHEN**
reconciliation replaces it, **THEN** a traversal or out-of-root name is rejected before any removal
and a failed recreate leaves the original entry intact rather than missing.
## Out of scope
- Removing or detaching sources after they have been attached.
- Promoting a repository-less task into a repository-backed task.
- Copying, mounting, or synchronizing arbitrary host folders into container or remote executors.
- Running batch workspace-source attachment while an agent turn or tool call is active; the legacy
worktree-only `add_branch_to_task_kandev` compatibility path is the explicit exception.
- Changing the running agent or terminal CWD during a legacy add-branch call.
- Nesting a new Git repository or worktree inside the current repository.
- Expanding or bypassing a provider-owned filesystem sandbox when it excludes the returned sibling
path.
- Reordering sources after attachment.
- Sharing task-creation state, its mode switch, or its **None**/scratch semantics with Add sources;
only the repository picker leaves are shared.
- Making the unimplemented remote Docker executor runnable; its source-materializer capability is
required when that executor becomes available.
## Implementation plan
See [Attach Workspace Sources plan](../../plans/attach-workspace-sources/plan.md) and the
[live add-branch compatibility repair plan](../../plans/restore-live-add-branch/plan.md), plus the
[multi-repository chat file-link repair plan](../../plans/multi-repo-chat-file-links/plan.md) and the
[owned link target mismatch repair plan](../../plans/owned-link-target-mismatch-repair/plan.md).