## Why

Code running inside a Planner session couldn't tell which document the session belongs to. An Atomic extension that writes to the room's document over MCP needs the document id or URL for `read_document` / `update_document`, and nothing in the session gave it either. `read_plan` and `edit_plan` results had no identity, the session id is a random UUID, and the working directory names the room only when there is no checkout. The only workaround was matching documents by source and revision, which is a guess. Writing to the wrong document is the worst outcome here.

Closes #366

## What changed

Planner tools (`apps/server/src/agent/tools.ts`)

- `read_plan` returns `document: { id, url }`. The id is the channel id and the URL is the one MCP `read_document` returns. - `edit_plan` returns the same `document` field on success and on the locked, stale and invalid refusals. The tool reads the identity from the plan's own channel record once, before the room lock. It follows a rename and never names another document. - The value doesn't depend on the Planner's working directory, so rooms with and without a checkout report the same identity.

Shared URL helper

- New `apps/server/src/channels/document-url.ts`. `read_document` and `invoke_planner` in `apps/server/src/mcp/hosted.ts` use it now instead of building the path themselves. `documentIdentity()` in `apps/server/src/plan/service.ts` looks up the channel record and returns `{ id, url }` for the tools. - For a child document the helper looks up the parent and returns the nested canonical path, `/documents/:owner/:repository/:parentSlug/children/:childSlug`. Before this, `read_document` gave children a top-level path. - `read_document` and the other MCP tools now accept that nested URL as a locator. One whose parent slug doesn't resolve to the child's actual parent is refused.

Docs

- `docs/hosted-agent.md` describes the new result shape. It limits the guarantee to structured `edit_plan` results; argument and storage errors still return plain error text.

Session-start metadata (option 2 in the issue) is left out. The Planner already calls `read_plan` before relying on the document.

## Verification

- `bun run fix`: 0 errors, 10 existing warnings, no diff changes. - `bun test` in the default environment: 4015 pass, 3 skip, 29 fail. Every failure is a `scripts/pr-maintenance` temp-repo commit refused by the global SSH commit-signing setting. Not caused by this change. - `bun test` with `commit.gpgsign=false` for that command only: 4046 pass, 3 skip, 0 fail. - `bun test` with the `tools.ts` change reverted: 2 `tools.test.ts` tests fail, so the new tests catch the bug. The child-document tool test fails against the old helper. The nested-locator test in `hosted.test.ts` fails with the child path handling disabled. Run alone, `tools.test.ts` needs `--preload harness/agents.ts` because of an existing import cycle. - `bun run types`: clean. - `bun run ci`: 0 errors, 10 existing warnings.

Not run: `bun run e2e`. The instructions for this run excluded it. Relying on CI's browser-integration job.

Review: GPT-6.1 Sol approved round 1. GPT-6 Luna raised the child URL and refusal-identity gaps, both fixed here. A follow-up GPT-6 Luna pass found that `read_document` couldn't resolve the nested URL, which is fixed and tested.

Assistant-model: Claude Opus 5.5 (fast) Assistant-workflow: issue-to-pr (run 1f82dfe5-bb8e-4329-9c56-fe8f74828f87), review findings finished inline Assistant-duration: 49m converged, estimated 40m Assistant-verification: bun run fix passed: 0 errors, 10 warnings that were already there, no diff changes Assistant-verification: bun test failed: in the default environment 4015 pass, 3 skip, 29 fail. Every failure is a scripts/pr-maintenance temp-repo commit that the global SSH commit-signing setting refused. The failures are environmental, not caused by this change Assistant-verification: bun test passed: with commit.gpgsign=false set for that command only, 4046 pass, 3 skip, 0 fail Assistant-verification: bun test (fix reverted) failed: 2 tools.test.ts tests fail without the tools.ts change, as expected. This shows the new tests catch the bug Assistant-verification: bun run types passed: type check clean Assistant-verification: bun run ci passed: 0 errors, 10 warnings that were already there Assistant-verification: bun run e2e unavailable: not run because the instructions excluded it User-preference: Use claude-opus-5-5-fast, gpt-6.1-sol-fast and gpt-6-luna-fast (-fast variants) for agent work Assistant-verification: gpt-6-luna-fast review passed: found the nested-URL locator gap in read_document, now fixed and tested User-preference: One sibling git worktree and one PR per assigned issue Co-authored-by: Alex Lavaee <lavaman131@github.com>

Rebased onto current main (248 commits) with no conflicts. All three commits are still signed; the change itself is unchanged.

- GitHub CI run 37849331132 on a62601b2: format, lint, types, and tests; e2e; and container all pass. - `bun run types` and `bun run ci`: pass. - `bun test` with `commit.gpgsign=false` for that command only: 4338 pass, 3 skip, 0 fail.

Assistant-model: Claude Opus 5.5 (fast) Assistant-workflow: inline Assistant-duration: 5m converged, estimated unmeasured Assistant-verification: GitHub CI passed: run 37849331132 on a62601b2, all three jobs Assistant-verification: bun test passed: 4338 pass, 3 skip, 0 fail with commit.gpgsign=false for the command only Assistant-verification: bun run types and bun run ci passed: 0 errors, no new Impeccable findings Co-authored-by: lavaman131