maestro/docs/issues/2026-06-30-workspace-file-provenance.md

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:

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:

GetFileProvenance({ path: string })

Returns a compact provenance record for one file.

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:

## 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.