# Add workspace file provenance so agents can identify which task created or owns files

## Summary

Persistent workspaces make it harder to tell which task created, uploaded, or
modified a file. This is especially confusing when multiple tasks share the same
workspace tree. The agent may see a file and assume it belongs to the current
task, even though it was an input or output from a different task.

Add a file provenance ledger so both users and agents can answer:

- Which task created this file?
- Was this uploaded by the user or generated by an agent?
- Which task last modified it?
- Is it safe for the current task to edit, or should it be treated as read-only
  context?

## Problem

In persistent workspace mode, files can outlive a single task. That is useful,
but it creates ambiguity:

- old input files remain visible to later tasks
- previous task outputs look like current task artifacts
- generated files and uploaded files are not clearly distinguished
- agents may edit or rely on files that belong to unrelated tasks
- users cannot easily audit why a file exists

Current workspace/runtime separation helps logs:

- `workspace_path` points to the shared files tree
- `runtime_dir` separates per-task logs/checklists/raw outputs

But shared workspace files themselves do not have provenance metadata.

## Proposed Design

Add a sidecar provenance ledger for files in persistent workspaces.

Prefer a DB-backed table for queryability, with optional JSONL export for
debugging. Do not write task tags into file contents.

### Schema

Suggested table:

```sql
CREATE TABLE workspace_file_provenance (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  space_id TEXT,
  workspace_path TEXT NOT NULL,
  rel_path TEXT NOT NULL,
  created_by_task_id INTEGER,
  created_by_job_id TEXT,
  created_by_piece TEXT,
  created_by_movement TEXT,
  source_kind TEXT NOT NULL,
  first_seen_at TEXT NOT NULL,
  last_modified_by_task_id INTEGER,
  last_modified_by_job_id TEXT,
  last_modified_at TEXT,
  checksum TEXT,
  note TEXT,
  UNIQUE(workspace_path, rel_path)
);
```

Suggested `source_kind` values:

- `user_input`
- `agent_output`
- `agent_edit`
- `bash_generated`
- `subtask_output`
- `imported_existing`
- `unknown`

### Recording Rules

Record provenance at these boundaries:

- UI upload to `input/`
  - `source_kind=user_input`
  - `created_by_task_id=current task`

- `Write`
  - new file: `source_kind=agent_output`
  - existing file: update `last_modified_by_task_id`

- `Edit`
  - update `last_modified_by_task_id`
  - keep original `created_by_task_id`

- `Bash`
  - compare workspace file snapshot before/after command
  - new files: `source_kind=bash_generated`
  - changed files: update `last_modified_by_task_id`

- subtask outputs copied/visible to parent
  - `source_kind=subtask_output`
  - include parent task and subtask job id

- existing files in a persistent space before this feature ships
  - backfill as `source_kind=imported_existing` or `unknown`

### Agent-Facing Tools

Add META tools:

```ts
GetFileProvenance({ path: string })
```

Returns a compact provenance record for one file.

```ts
ListWorkspaceFiles({
  path?: string;
  sourceKind?: string;
  createdByTaskId?: number;
  lastModifiedByTaskId?: number;
  includeUnknown?: boolean;
})
```

Returns bounded file listings with provenance summaries.

### Prompt Guidance

Update the system prompt / workspace guidance so the agent uses provenance
before editing ambiguous files.

Candidate prompt copy:

```md
## Workspace file provenance
Persistent workspaces may contain files from older tasks. Before editing a file
whose provenance shows `source_kind=user_input` or `created_by_task_id` differs
from the current task, verify that it is relevant. Prefer creating a new output
file when unsure. Use GetFileProvenance / ListWorkspaceFiles to inspect file
origin.
```

### UI

Show provenance in the file browser / preview:

- created by task id/title
- source kind
- last modified by task id/title
- timestamp

This can be a small metadata row or tooltip; avoid cluttering the file list.

## Files Likely Involved

- `src/db/schema.sql`
  - add provenance table

- `src/db/migrate.ts`
  - migration for existing installations

- `src/db/repository.ts`
  - read/write/query provenance records
  - optional backfill helpers

- `src/engine/tools/core.ts`
  - hook `Write`, `Edit`, and `Bash` file changes
  - expose task/job/piece/movement context needed for provenance

- `src/engine/piece-runner.ts`
  - thread task id, job id, piece, movement into `ToolContext`

- `src/engine/tools/index.ts`
  - register provenance tools as META tools

- `src/engine/tools/file-provenance.ts`
  - implement `GetFileProvenance`
  - implement `ListWorkspaceFiles`

- `src/bridge/local-tasks-api.ts` / file APIs
  - record UI uploads
  - return provenance metadata with file listing/detail responses

- `ui/src/components/files/*`
  - display provenance metadata

- `src/engine/agent-loop/prompt.ts`
  - add concise workspace provenance guidance

- `ui/src/content/help/*.md`
  - document how provenance labels work

- `ui/src/content/help/00-changelog.md`
  - add user-facing changelog entry

## Acceptance Criteria

- New files created by `Write` record current task provenance.
- Files changed by `Edit` preserve original creator and update last modifier.
- Files created or changed by `Bash` are detected and recorded.
- User-uploaded input files are recorded as `user_input`.
- File listing or preview can show provenance metadata.
- Agent can call `GetFileProvenance` for a file.
- Agent can list files filtered by provenance.
- Prompt guidance tells the agent to avoid editing unrelated/user-input files
  without checking relevance.
- Existing persistent workspace files remain usable after migration.
- Provenance output is bounded and does not dump large file contents.

## Non-goals

- Do not embed task tags into file contents.
- Do not make files from other tasks globally read-only; the agent may still
  need to use shared workspace artifacts.
- Do not block all edits to `user_input` files immediately. Start with warnings
  and guidance to avoid breaking existing workflows.
- Do not use `UpdateUserMemory` for per-file task metadata.

## Suggested Implementation Order

1. Add DB schema and repository helpers.
2. Record UI uploads and `Write`/`Edit` provenance.
3. Add `Bash` before/after file change detection.
4. Implement `GetFileProvenance`.
5. Implement `ListWorkspaceFiles` with filters and caps.
6. Add prompt guidance.
7. Surface metadata in the file browser/preview.
8. Update help docs and changelog.