prd.json is reachable from the worker (invariant 2 leak)

[samkeen]

Related: real enforcement of invariant 2 (worker physically can’t reach harness state, even with bash) is opt-in process isolation, planned in #13. This issue is the default-mode drift surface; complementary, both worth doing.

What

CLAUDE.md invariant 2 says:

The agent doesn't see harness mechanics. No prd.json structure, no events.jsonl, no summary.json, no token counts, no judge, no checkpoints.

prd.json lives in the workspace (it has to — that's where loop._load_prd reads it from), so the worker can read_file it freely. In the 5/1 demo session the worker did exactly that on T-002 iter 2:

$ jq -c 'select(.payload.task_id=="T-002" and .payload.iter==2 and .type=="tool_call")' events.jsonl
{...,"tool":"read_file","args":{"path":"tests/test_t002_package.py"}}
{...,"tool":"read_file","args":{"path":"prd.json"}}

No scope-creep happened in this run, but reading prd.json exposes every future task to the worker — and the model could legitimately decide to pre-implement T-003 while "doing" T-002. The harness has no defense.

Why memory.py doesn't already fix this

memory.build_user_prompt() correctly never injects prd into the user prompt — only the current task is rendered. The leak is purely via tool access to the file on disk.

Proposed directions (pick one)

1. Block reads to prd.json in pre_tool. Simplest. Cost: an explicit error message in the agent's view, which is itself a small leak of "there's a prd.json you can't see."
2. Move prd.json out of the worktree. Store it under sessions/<id>/prd.json (or <source>/.tilth/prd.json), and have _load_prd read from there. Worker has no way to see it. Cost: breaks the demo's "prd is a seed file in your repo" affordance; the demo workspace's PRD becomes a setup step rather than just git clone.
3. Make prd a .tilth/ directory inside the workspace and have pre_tool block .tilth/. Middle ground.

Option 2 feels closest to the invariant's intent — it's the same separation that already keeps events.jsonl / summary.json / checkpoint.json outside the worktree.

Related

• tilth/loop.py:_load_prd, tilth/loop.py:_save_prd
• tilth/tools/files.py:read
• tilth/hooks/pre_tool.py
• CLAUDE.md (invariant 2)

[samkeen]

Direction (settled, paired with #13)

Going with Option 2 (move prd.json out of the worktree) in the variant that preserves the seed-file UX:

• User still commits prd.json to their workspace as the seed (no UX change).
• At session start, the harness reads <worktree>/prd.json, copies the contents to sessions/<id>/prd.json, then git rms it from the worktree and commits it as the session branch's first commit: (tilth) move prd.json out of worktree.
• _load_prd / _save_prd switch to reading/writing sessions/<id>/prd.json from that point on.
• --resume works for free (already reads from sessions/<id>/).
• --reset works for free (already deletes sessions/<id>/).

Reframe of what this fix promises

Important context from the #13 research: _resolve is a tool-correctness boundary, not a security boundary. The worker has bash and could still cat ../prd.json from sessions/<id>/workspace/ if it decided to look. So this fix is honestly framed as drift reduction, not enforcement:

• Before: prd.json sits in ls next to the files the agent is editing. Casual exploration via read_file / glob / grep surfaces the full task queue.
• After: prd.json is two directories up and not visible to any normal file-tool inspection. The agent has no reason to look there.

That matches the Brain/Hands/Session research framing — the failure modes the invariant exists to prevent (skip-ahead, queue rewriting, self-marking-done) are drift failures, not exploit failures. Removing the temptation is the correct intervention.

Real enforcement (worker physically can't reach harness state, even with bash) is opt-in process isolation via #13. This issue closes the default-mode drift surface; #13 closes the enforcement gap. Complementary, both ship.

Scope of the change

• tilth/workspace.py: new relocate_prd_seed(worktree, dest_path) — copy + git rm + commit.
• tilth/loop.py: _load_prd / _save_prd take a direct prd_path; session-start hook invokes the relocation; all call sites pass session.root / "prd.json".
• Tests: relocation moves the file + creates the commit; post-relocation glob / file tools can't see prd.json from within the worktree.
• Docs: CLAUDE.md invariant 2 reframed as drift-reduction (with #13 referenced for enforcement); docs/architecture/memory-channels.md and docs/deep-dives/agent-visibility.md updated to reflect prd's new location; docs/getting-started/your-own-project.md adds a brief note that tilth relocates the seed at session start; docs/deep-dives/resume-mechanics.md and docs/deep-dives/session-layout.md touched where they mention prd location.

[samkeen]

Rollback — direction in the previous comment is withdrawn

Tried the relocate-on-session-start approach locally and didn't like it. Reverting the implementation; this issue stays open, further review needed.

What's left of that work in the tree:

• Code: all reverted (no relocate_prd_seed, no _load_prd signature change, no session-start hook). git diff is empty on tilth/ and tests/.
• Docs about prd's location: all reverted to pre-attempt wording.
• Kept: a short honest-scope caveat on invariant 2 in CLAUDE.md and docs/architecture/overview.md. It points readers at this issue as the open question and at Research: Docker Sandboxes (sbx) as opt-in process isolation #13 as the planned enforcement path — useful framing regardless of how this gets resolved.

What's still worth thinking about (so the next pass doesn't restart cold):

• The premise of the invariant is sound (see prior discussion + Brain/Hands/Session research) — drift failures from a worker seeing its own queue are real.
• _resolve is not a security boundary; bash makes most "block reads to prd.json" approaches half-measures (the original Option 1).
• Option 2 (relocate prd.json out of the worktree at session start) closes the file-tool drift surface but introduces a (tilth) move prd.json out of worktree commit on the session branch, which on reflection felt like the wrong shape — pollutes review diffs with harness mechanics and adds a load-bearing git step at every fresh session start.
• A determined model can still reach harness state via bash + relative paths regardless of where in the tree we put prd.json. Real enforcement lives in Research: Docker Sandboxes (sbx) as opt-in process isolation #13 (opt-in process isolation).

Open question for the next pass: is there a shape that closes the drift surface without a session-start commit on the user's branch? Options worth considering:

• Store prd seed at a sidecar path (<source>/.tilth/prd.json gitignored), no worktree presence at all — breaks git clone && tilth ./project ergonomics.
• Pass prd via a CLI flag (--prd path/to/prd.json) — explicit, no magic, but a UX cost.
• Accept the current state and rely on Research: Docker Sandboxes (sbx) as opt-in process isolation #13 for the real fix. The invariant doc already reads as "design goal" now, not a guarantee.