@mmerterden/multi-agent-pipeline 20.30.0 → 20.34.0

package/CHANGELOG.md

@@ -16,6 +16,129 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [20.34.0] - 2026-10-26
+
+### Added
+
+- Plans carry `reviewFocus[]` (at most five inputs the spec implies but no task's tests exercise, each owned by a task whose tests add it) and `globalConstraints[]` (project-wide values every task brief quotes). `validate-planning.mjs` checks both and, with `--spec`, warns when a plan runs more than four times the length of its spec. Planning schema 1.1.0.
+- The plan critic has two more lenses: `unstated-input`, an input the spec implies (empty, boundary, expired, concurrent) that no task's tests exercise, and `underspecified`, a decision a task leaves to its implementer that the analysis or the user should make.
+- `rework-rulings.mjs`: at the rework cap every accepted finding still open gets a recorded ruling. Blocking and security findings (a `SEC-*` rule, a security criteria source, or the security auditor's `security` object) escalate to the user; the rest are parked as follow-ups and the run continues to Phase 4 instead of stopping.
+- Phase 4 Step 0b lists deferred and parked findings before the commit and asks once whether to ship with them as follow-ups.
+- Code graph: `graph-query.mjs --path <from> <to>` finds the shortest path between two symbols or files; an ambiguous name is refused with candidate ids and an unknown one gets its nearest names. External modules end a path but are never walked through.
+- `GRAPH_REPORT.md` gains import cycles, clusters of files with a cohesion score (label propagation over imports and references) and questions worth asking before a change; `graph-report.mjs --diff <older graph>` lists what changed between two builds. All deterministic (`_graph-analysis.mjs`).
+- `graph-links.mjs`: which files of one repository import another, by matching each graph's unresolved imports against what the others export (package name, Python packages, Swift targets, Go module, Kotlin types). A Kotlin link holds only files whose import names the exporting file's package, and a repository name counts only when the stack names no export. Graphs stay separate (ADR-0018).
+- Kotlin graphs index a capitalised `fun` as its own `composable` kind and make it a reference target, so a change to a Compose UI function reaches its callers; an extension function is named after the function, not its receiver.
+- `debt-ledger.mjs`: one list per repository of the limits accepted on purpose (`shortcut: <limit>, <when to replace>` markers a diff adds in a comment outside any string, deferred findings, parked rulings), fed by `capture-flush.sh`, secret-scanned, closable with `resolve`.
+- `file-context.sh`, a PostToolUse hook on Read: once per file per session it hands the model what the repo's memory says about the file just read (ledger facts whose scope covers it and that feedback has not suppressed, its latest review findings, its open known limits) as untrusted context, after the secret scan. On inside a pipeline run, everywhere with `prefs.global.fileContext.enabled: true`, never with `false`.
+- `scope-check-gate.mjs --patch` (or `--repo <dir> --patch-range <a>...<b>`, which reads the diff itself) lists hunks that only change layout (`formatOnly[]`): whitespace outside string literals and comments, never a space that keeps two operators apart, a line break after `return` or before a leading operator in Kotlin and Swift, a leading indent in Python, YAML or a Makefile, or the space around brackets and colons outside C-family languages and Python. A pure addition or deletion is never layout-only. Reported to reviewers and never fatal; the code reviewer gains a fit lens (follow the surrounding code, leave untouched lines alone) and reads `shortcut:` markers as known limits.
+- `pipeline/eval/ab/write-lean.json` measures a candidate write-time rule for the GREEN step against none. It is not shipped: its run scored below the baseline.
+- Ledger entries earn or lose weight: `learnings-ledger.mjs feedback --id <L:id> --outcome useful|dead_end|corrected` (Phase 5 records it for injected entries). A corrected entry, or one judged a dead end at least twice and more often than useful, leaves `brief` and `profile`; one useful at least twice ranks by a strength that fades with age. A new entry that repeats an existing one in other words (TF-IDF cosine 0.9 or more, same numbers and negations) is not added (`_memory-policy.mjs`).
+- When `check-read-size.sh` turns a whole-file read away it also prints what the repo's memory says about that file (`file-context.mjs --lines`), so the delegated read starts from what is already known.
+- `knowledge.md` documents progressive recall over a large ledger or triage corpus through the toolkit's existing full-text index (`context_index`, `context_search`, `context_get`).
+- `npm run audit:refs` (`ref-filler-audit.mjs`): filler phrases and sentences copied verbatim across the instruction docs, with the tokens a rewrite would win back. Advisory; it rewrites nothing.
+- The explorer returns its JSON with nothing around it, in short phrases, keeping negations, numbers and paths exactly as found.
+- `prefs.global.memory.excludeProjects`: repos whose ledger, triage corpus and debt list are never written.
+- Reviewers return `cannotVerify[]` for requirements that live in code the diff does not touch; triage settles each as verified (citing the file:line read), a finding (citing the file:line of the accepted or deferred finding) or out of scope, and `validate-triage.mjs --reviewers` or `--reviewers-dir` fails one left unsettled or settled without that evidence. Reviewer output 1.6.0, triage output 3.6.0.
+- `smoke-skill-size.sh`: no `pipeline/commands/**/SKILL.md` may reach 20,000 bytes, and a file between 18,000 and 19,999 bytes is reported as a warning. After context compaction Claude Code re-attaches each invoked skill truncated at about 20k characters, so anything past that point would silently stop applying mid-run. Runs through `run-smokes.mjs` and the CI lite workflow.
+
+### Changed
+
+- The five command skills over that limit now keep their step skeleton, stop conditions and hard rules, with explicit "Read <ref> before Step N" pointers to the long reference sections, moved without changing their meaning: `channels` (33,925 to 17,749 bytes; `multi-agent-refs/channels/menu.md`, `generator.md`, `preview.md`, `reference.md`, plus the Step 1 target resolution in `multi-repo.md`), `setup` (26,000 to 17,452; `setup/language.md`, `multi-repo-group.md`, `summaries.md`, `accounts.md`, `hooks-and-plugins.md`, and sections appended to `token-save-flow.md`, `app-store-connect.md`, `firebase.md`, `google-play.md`), the `/multi-agent` dispatcher (24,130 to 17,548; `orchestrator/dispatcher.md`), `review` (24,033 to 17,838; `review/inputs.md`, `module-guides.md`, `valven.md`) and `resume` (20,102 to 17,586; `resume/details.md`). `setup` and `channels` leave the token-budget grace list, now under the hard cap.
+- Token ceilings: phase-3 17200 to 17260, phase-4 6600 to 6650, phase-5 5700 to 5710, total 63550 to 63710, after the review-settled contracts above (triage settles `cannotVerify`, the PR body carries deferred, parked and marked limits, Phase 5 records ledger outcomes). Existing prose in phases 1 to 5 was compressed first and absorbed every earlier addition of this release.
+- The reply-shape rule keeps negations, numbers, units and paths when it shortens a list.
+
+### Fixed
+
+- Office: the autopilot window could open empty with "busy" when the panel's own status poll was still running, because `GET /v1/autopilot` refused a second caller. It, `GET /v1/prs` and the maturity read now answer every concurrent caller from the one run in flight; at most two maturity reads for different issues run at once. A window that reloads after a request now redraws only if it is still the open one, so a late answer for Skills no longer replaces the autopilot window.
+- `eval-ab-judge.mjs` showed the judge `blocker` as the string "true|false", so judges answered with a string and the judgement was dropped; the example is a boolean now and a quoted "true"/"false" is read as one. `MULTI_AGENT_EVAL_USER_SETTINGS=1` lets a live eval log in on a host that keeps its CLI login in user settings.
+
+### Security
+
+- The learnings ledger (`add`, `from-triage`) and the triage corpus (`ingest`) run every row through the secret scan before writing it, through one shared helper (`scripts/_secret-scan.mjs`) that the transcript miner uses too. A refused row is counted in `droppedBySecretScan`; a missing scanner refuses the row instead of writing it unchecked. `<private>...</private>` spans are removed before anything is stored. Control bytes are removed from the scanned copy, so a NUL cannot make the scanner treat the text as binary and skip it. The triage corpus scans every stored field, task id, title, stack and reviewer included.
+- A token hard-wrapped by a space or a line break is still refused: a run that starts with a known token prefix is scanned a second time with its whitespace removed.
+- Every memory store refuses a repository slug that could leave the memory folder (a path separator, NUL, `.` or `..`); spaces and non-ASCII letters stay valid, and slugs compare in Unicode NFC, so `excludeProjects` matches either normal form. The transcript miner honours `memory.excludeProjects` for the ledger and the `CLAUDE.local.md` block alike.
+- `file-context.mjs --lines`, used when a whole-file read is turned away, prints inside the same untrusted-data block as the hook and stays silent when `fileContext.enabled` is false.
+
+## [20.33.0] - 2026-10-25
+
+### Added
+
+- Office: pipelines run step by step. Agents wait at the open office and walk over to take their seat in a run's room. The table sign counts phases from 1 over the run's own phases, fills the current phase as its tasks finish and names the task in progress; the run window shows each phase's checklist and a seat shows its own tasks and recent MCP calls. A finished run stays two minutes.
+- `task-mirror.sh`, a PostToolUse hook on `TaskCreate` / `TaskUpdate`: the native task list of the session driving a run lands in that run's tracker under the phase in progress, so the office and the terminal show the same list. Phase tiles are skipped, nothing is written outside a run bound to the session, and the hook never prints.
+- The analysis mode has its own phase names in `schemas/phases.json` (Intake, Evidence, Synthesis, Review, Publish, Report); `/multi-agent:test-gen` and a standalone `/multi-agent:review` register tracker runs with their own steps, on Claude Code and Copilot CLI alike.
+- Office rooms per repository are typed: Development rooms (`/multi-agent`) and Analysis rooms (`/multi-agent:analysis`), each floor keeping a free Analysis room; a run that touches more repositories opens an annex desk on theirs. Labels go through one layout pass and never overlap; a thought cloud over a working agent says what it is doing and opens its detail.
+- Office reception has two new-run desks (development and analysis) that list Jira and GitHub issues and take free text.
+- Office mail room: pull requests on every GitHub account `gh` is logged in to, each asked with its own token, and on the configured Bitbucket Server.
+- Office server room: the key cabinet (`GET /v1/credentials`, names and probe verdicts from `credential-inventory.sh`, never a value, local-only) and the system panel (`GET /v1/system`: CPU, memory, disk and the pipeline's own processes, numbers only). The library holds per-repository memory (`GET /v1/memory`: code graph age, learnings, findings and session notes, redacted). The restroom previews and prunes old run logs through `prune-logs.sh` (`POST /v1/prune-logs`, two steps, 7, 30 or 90 days, local-only).
+- Office orientation room: a trainer next to reception opens a guide built from the floor that is drawn, listing every room with the windows it opens, how both pipelines run, what is a job, a window or terminal-only, the security model and the signs. Each visit points at it in the feed; the page keeps nothing in browser storage.
+- Five read-only office jobs: doctor, route status, scan, scenario audit and analysis review (19 jobs in all). Commands that stay in the terminal say why instead of offering a copy button.
+- Office tables seat a run's whole crew from the start, one seat per role each phase uses (planner and plan critic, developer and dev critic, three reviewers, committer, reporter; an analysis run its own): whoever's phase runs works, later ones wait for their turn, finished ones stay seated.
+- The table sign names where the work came from (the Jira key, the GitHub issue as `repo#N`, both when an issue got a Jira, or free text), what a waiting run waits for (a local test, the report channels, an answer here, or a question in the terminal) and, once finished, the pull request it opened. `runs-index` carries `source`, `prNumber`, `mode`, `channels` and the local-only `channelUrls` (runs surface 1.3.0). The client contract is 1.6.0: the six new routes, and the activity and pull-request surfaces at 1.1.0. A run with no tracker still lists every phase of its mode.
+- A question a session asks in its own terminal counts as waiting for you: the table glows, the HUD counts it, the feed says so and the tab title shows the number; the drawer says to answer it in the terminal. The HUD reads agents working, runs and sessions.
+- Office settings screen in the manager's office (`GET/POST /v1/settings`, local-only, two steps, one change at a time): output language, the fable rung and model routing, each through the script its terminal command runs (`office-settings.mjs`). Route on keeps the saved strategy and scope; rules, free providers and prompt language stay in the terminal.
+- Phase 5 records each report channel's outcome in `state.channelResults`; the run window lists where the report went, with the addresses (https only) from the run record, which drops them from a redacted answer.
+- The memory shelf offers a code graph build or refresh for each repository, through the graph job.
+- Office characters come in twelve looks: six sheets and a recoloured second set, so every role at a run's table looks different. The team window shows every character with its portrait, the office staff and the agent pool apart, and the chat drawer shows the character actually at the seat.
+- README and README.tr gain an office section with screenshots; README.tr gains the hooks-per-host table README has.
+- Office rooms carry more of a real office: pictures, a clock and hanging plants on free wall, and a plant in each free corner, never behind a tall piece, under a room's sign or in anyone's way.
+- The autopilot window is one switch that says the state and flips it, the three numbers that matter, and the repository selection; stop buttons appear only while it runs, and with no repository it says how one is added.
+
+### Changed
+
+- Office roles on the floor and in the feed are translated, and phase events count from 1 like the table sign.
+- `/multi-agent:office-on` describes the panel as it is; the help catalog says the server runs until `office-off`.
+- `prune-logs.sh` spares a run that can still be resumed (an `agent-state.json` status that is not finished, abandoned or cancelled) unless `--task` names it; `--only-from=FILE` limits a prune to a confirmed list. The office prunes only the folders its preview listed, passing them through `--only-from`, and refuses with `changed` when the set moved.
+- `phase-tracker.sh task <N> <id> deleted` takes a mirrored task off the list, as a native `TaskUpdate` with status `deleted` does. A task id used again in a later phase updates that phase's task.
+- Text cut to fit a field (`transcript-index` excerpts) counts its ` ...` ending toward the limit.
+- An MCP call a turn left without a result is closed as failed, so no desk stands at the server rack forever. A task created between two phases is mirrored under the phase about to start.
+- The key cabinet shows every verdict `credential-inventory.sh --probe` gives (malformed, no credential, probe error, server error, tier ready, needs a grant) and calls one it does not know unknown instead of not checked.
+- The Bitbucket pull request list authenticates the way the credential inventory does: Basic with a stored `bitbucket_user`, else the token as a bearer. On a `gh` without `auth token --user`, the active account answers alone.
+- The system panel counts only a node, npx or npm process as the toolkit server, and on macOS reports used memory from `vm_stat` (reclaimable pages count as free).
+- A memory store line that is not a JSON object is skipped, a shelf that cannot be read is left out instead of failing the answer, and a graph dated in the future reads as zero days old.
+- The room sign names only commands that exist; an autopilot job reads `/multi-agent autopilot` as its run does. Prunes run one at a time. A language change the preferences file could not take, or whose command descriptions were not switched, is reported as failed.
+- The office translates numbered roles in the run window and chat drawer, the HUD counts sessions apart from solo jobs, the job form names the scenario audit's CSV field, and a run's head and crew stay at the table until it leaves.
+- A run that just finished keeps only the session that ran it, so a session that starts the next run within two minutes sits at the new table.
+- Office wall-station labels sit inside their room instead of above the top wall, and `smoke-office-runtime.sh` checks that no two labels overlap at any zoom step. A floor station's label sits above its tallest piece, hotbar labels fit under their icons, and room signs never cover a picture or board; the runtime smoke checks all three.
+- `schemas/phases.schema.json` allows a mode's own phase `names`.
+
+### Security
+
+- `GET /v1/system` measures with child processes off the event loop; requests that arrive while one measures share its answer, and the log folder size is reused for a minute. `GET /v1/memory` reads its stores asynchronously, parses only their last megabyte, and skips a store that is a FIFO, a symlink or anything but a regular file.
+- Turning routing on from the office names, in its confirmation, the saved free provider chain it brings back and whether that chain allows training.
+- `/multi-agent:scenario-audit` writes its verdicts in a folder of the run's own instead of a fixed name under `/tmp`.
+- The Bitbucket token is read from the credential store with a deadline and sent only over https (a loopback host excepted); redirects are not followed. A redacted pull request list carries no URL or login.
+- `resolveToken` gives the credential store a deadline. A GitHub Enterprise Server account's token reaches `gh` as `GH_ENTERPRISE_TOKEN` as well.
+- Office threat model rows T19 to T24 cover the new routes, the PR listing, the task mirror hook, the settings screen and report links.
+
+## [20.32.0] - 2026-10-25
+
+### Added
+
+- Office: a repository can be added from any window that picks one. Checkouts earlier runs worked in are suggested, a path can be typed, and a registered entry whose folder is gone can be taken off the list; each is a two-step write (`POST /v1/repos`, `DELETE /v1/repos/{id}`), and only a git checkout is accepted. `GET /v1/repos?all=1` (`launch-request.mjs repos --all`) lists the suggested and the missing entries by id, never by path to a page.
+- Office keeps itself current: the open page shows a reload banner when a newer page is installed and reloads onto it through a fresh one-time code (`GET /office/version`, `POST /office/reload`); `office-on` replaces a running server whose code changed on disk. A server that has stopped is said so on the page.
+- The office ships the toolkit version the release was checked against (`office/toolkit.json`, written by `office-build.mjs` from `docs/facts.json` and held by `--check`), so the Tools window starts an exact version with no manual step and every pipeline update moves it forward. `MA_TOOLKIT_VERSION` and `prefs.global.office.toolkitVersion` still override it. The Tools window shows the version; nothing writes the preferences file.
+- Office: hand a job to someone. Clicking a person or a station opens the jobs that role does (`schemas/office-jobs.json`: 14 jobs, each parameter typed by kind, no free text); the confirmation names the exact prompt, the repository and what the job writes outside this machine, and the second step starts `claude --bg` with the unattended profile and no shell (`GET/POST /v1/jobs`, two steps). A team job meets in its repository's room and is refused while another run is live there (`room-busy`); a solo job sits at a desk under its role. Every start is recorded under `logs/multi-agent/office/jobs/` (0600). The autopilot runner and the office start sessions through one launcher, `pipeline/lib/bg-launch.mjs`.
+- Office is a company building: a hall with the lobby, the open office and the kitchen on top, then the manager's office, library, server room, test lab, analysis room, archive, mail room and restroom, with each repository's meeting rooms below. Thirteen staff work in their rooms; the hotbar moves the camera to a room, and each room's window holds its commands (the cleanup in the restroom previews `/v1/gc` before it runs). Copy buttons are gone: the New run flow, PR review and the command cards start real jobs.
+- Office furniture drawn for this project: 16 sprites kept as pixel grids in `pipeline/office-art` and rendered into PNGs by `office-build.mjs` with a dependency-free encoder; `--check` holds the PNGs to their sources.
+- `smoke-office-ui.sh`: the signed-in panel driven by Playwright (adding a repository, the refusal of a folder that is not a checkout, command cards, the reload banner, a stopped server).
+
+### Security
+
+- The unattended profile denies reading `~/.claude/logs/multi-agent/contract-server/` (a `Read` deny, a sandbox `denyRead`, and in `MCP_TOOLKIT_INDEX_DENY` together with the office state directory), where the local server keeps its bearer token, so a session the office or the autopilot starts cannot pick it up. Every install adds the deny rules and index-deny directories a newer release ships to an existing `multi-agent-unattended.settings.json` without changing what it allows (`tightenUnattendedProfile`), so the autopilot's profile check keeps passing after an update.
+- `POST /v1/jobs` starts nothing unless agent-guard.sh is registered for every tool (`guard-missing`), re-checks at the confirmation that the repository is still allowed, and keeps claude's own error output off the page.
+
+### Changed
+
+- Office: the panel's server runs until `/multi-agent:office-off`; it no longer stops after an idle time or after 8 hours. `contract-server.mjs` takes `--idle-minutes 0` and `--max-hours 0` for that, and keeps its 15 minute and 8 hour defaults when started on its own. The open page checks in once a minute, also in a background tab, and says so when the server has stopped.
+- Office: command cards keep their button on the title row; long names are cut with the full name on hover.
+- `/multi-agent:sync` checks the office instead of copying it: the committed page matches its sources, the installed copies match the page, and the recorded toolkit version is reported (Step 3e).
+
+## [20.31.0] - 2026-10-25
+
+### Changed
+
+- Office: every run meets in its own walled room inside its repository's room. The orchestrator sits at the head of a long table with a computer, the agents face each other along it, and the table grows with the team from two to six chairs a side. Agent labels sit above the near row and below the far one; on a narrow floor the chairs are packed and labels show on hover. Free meeting rooms finish the row, a hall on the left leads in, and the floor reaches the bottom of the stage. The corridor label of a run over several repositories now sits beside the room name.
+
 ## [20.30.0] - 2026-10-25
 
 ### Added

package/README.md

@@ -297,7 +297,7 @@ the pipeline merges.
 - **Operations around a run.** A second launchd agent keeps the Mac awake while the mode is on (`caffeinate -s -i`, plus `-d` if you answer yes to the display question at `autopilot-on`), and each run holds a sleep lock until its tick ends. Every credential a configured repo needs is probed before the schedule is offered and again on every tick, so a locked keychain refuses with the key and the fix. A circuit breaker stops launching after consecutive attempts that produced nothing, `costCeilingUsd` caps spend over a rolling 24 hours, `maxParallelAgents` caps sessions working at once, and once a day the runner writes a cleanup report and, when enabled, a digest. [Autopilot operations](./pipeline/multi-agent-refs/features/autopilot-operations.md)
 - **A fail-closed guard.** Under the variable, the Bash guard judges a command only when it reduces to simple commands joined by `;`, `&&`, `||` and plain pipes, and refuses anything else unparsed. On what it can parse: no push, PR, issue or tracker write, no Keychain read, no fetch outside the network allowlist, no package install or manifest edit, no write into a protected path. Ticket, page and PR text reaches the model inside untrusted-data delimiters. The permission profile (`install --unattended`) is a second line; the boundary is a separate non-admin macOS user and GitHub rulesets on the default and release branches, which the operator applies. [Unattended security](./pipeline/multi-agent-refs/features/unattended-security.md)
 - **Claims are checked, not trusted.** With the quality gates active, a run's claims about the repository are checked before it commits: a localization key or endpoint the change references exists, open analysis questions are answered or park the run, a triage citation quotes the line it cites, a "pre-existing" finding points at a line the diff did not touch, the plan's steps are covered, and a test pass shows a positive executed count read with the stack's own markers (8 stacks: `ios`, `android`, `web`, `backend-node`, `python`, `go`, `rust`, `jvm`) along with a new test that fails without the change. Every verdict goes to a gate ledger, and the commit hook refuses a commit whose mandatory gates did not pass for HEAD. [Unattended gates](./pipeline/multi-agent-refs/features/unattended-gates.md), [stack adapters](./pipeline/multi-agent-refs/features/stack-adapters.md)
-- **Spec, plan and review discipline.** `/multi-agent:analysis` writes a project constitution (security, accessibility, architecture and licensing rules, each tied to a source), and a spec-consistency gate checks by id that every requirement has a task and a test and that nothing waives a binding rule. Phase 1 ends with one plan-critic round under four lenses (scope, feasibility, security, a cheaper alternative), answered once and judged by a script. In review, a `blocking` finding stops the run only when two independent reviewers carry it or a failing test shows it; otherwise it is lowered to `important`, never dropped. [Constitution](./pipeline/multi-agent-refs/features/constitution.md), [plan critic](./pipeline/multi-agent-refs/features/plan-critic.md), [review decision](./pipeline/multi-agent-refs/features/review-decision.md)
+- **Spec, plan and review discipline.** `/multi-agent:analysis` writes a project constitution (security, accessibility, architecture and licensing rules, each tied to a source), and a spec-consistency gate checks by id that every requirement has a task and a test and that nothing waives a binding rule. Phase 1 ends with one plan-critic round under six lenses (scope, feasibility, security, a cheaper alternative, an unstated input, a decision left to the implementer), answered once and judged by a script. In review, a `blocking` finding stops the run only when two independent reviewers carry it or a failing test shows it; otherwise it is lowered to `important`, never dropped. [Constitution](./pipeline/multi-agent-refs/features/constitution.md), [plan critic](./pipeline/multi-agent-refs/features/plan-critic.md), [review decision](./pipeline/multi-agent-refs/features/review-decision.md)
 - **A client contract.** Commands and run questions are declared as data. `/multi-agent:serve` starts a localhost HTTP server over the same JSON the CLI prints, and `pipeline/contract/` ships the manifest, TypeScript types and fixtures a client builds against. Four phone routes read redacted runs, answer a parked question with one of its offered options, and, only when switched on, queue a launch; every request carries an Ed25519 signature from an enrolled device. The phone app is a separate project. [Client kit](./pipeline/contract/README.md), [phone API](./pipeline/multi-agent-refs/features/phone-api.md)
 
 **Attended use is unchanged.** Every behaviour above keys on
@@ -353,6 +353,50 @@ Continuous mode therefore needs the `claude` binary on `PATH` everywhere. The
 queue and the repo selection live in `~/.claude/autopilot/` on every host, on
 purpose - two CLIs on one machine must read one queue, not two.
 
+## The office
+
+A local web page that shows the pipeline as a pixel office and lets you drive
+it. `/multi-agent:office-on` starts the contract server on 127.0.0.1 and opens
+the page with a one-time code; the server runs until `/multi-agent:office-off`.
+
+![The company floor: reception, orientation, the open office, kitchen, accounting and the restroom](.github/office/floor.png)
+
+- **Runs come alive.** Agents wait at their desks in the open office and walk
+  to a run's room when the run calls their role. Each repository has its own
+  floor of Development rooms (`/multi-agent`) and Analysis rooms
+  (`/multi-agent:analysis`); a run that touches more repositories opens an
+  annex desk on theirs.
+- **The native task widget, on the table.** The table sign shows the phase
+  (`Phase 3/6 Dev`), a bar that fills as that phase's tasks finish and the
+  task in progress. A PostToolUse hook copies `TaskCreate` / `TaskUpdate` into
+  the run's tracker, so the office and the terminal show the same list. A
+  thought cloud over a working agent says what it is doing.
+- **The rest of the ecosystem has a room.** Reception starts a run from a Jira
+  or GitHub issue or free text. The mail room lists pull requests on every
+  GitHub account `gh` is logged in to and on Bitbucket Server. The server room
+  holds the toolkit MCP tools, the services, the key cabinet (names and probe
+  verdicts, never a value) and the machine's CPU, memory and disk. The library
+  holds stacks, commands and what the pipeline learned per repository. The
+  restroom clears worktrees, abandoned runs and old run logs after a preview.
+  Accounting shows tokens and cost, the manager's office holds autopilot,
+  routines and the settings (output language, the fable rung, model routing),
+  and the orientation room explains the building.
+- **People take jobs.** Click one, pick a job, confirm. Writes that change the
+  machine are local-only and take two requests. Work that is interactive or
+  changes the installation stays in the terminal, and the commands window says
+  why for each command.
+
+![Repository floors with Development and Analysis rooms, a live analysis and an annex desk](.github/office/rooms.png)
+
+| Command                      | What it does                                                    |
+| ---------------------------- | --------------------------------------------------------------- |
+| `/multi-agent:office-on`     | Start or reuse the server and open the page                     |
+| `/multi-agent:office-status` | Whether it runs, its URL (never the token) and its last actions |
+| `/multi-agent:office-off`    | Stop the server; it runs until you do                           |
+
+Security model: [office threat model](pipeline/multi-agent-refs/features/office-threat-model.md).
+Phone access is not part of this installation.
+
 ## Which model answers
 
 The ladder is `fable -> opus -> sonnet -> haiku`, and a run walks it on failure.
@@ -458,6 +502,8 @@ The **secret scan** runs as a `PreToolUse` hook on Claude Code (hard-blocks a co
 | `agent-guard.sh` (attribution, force-push, skipped git hooks, argv secrets, closure confirmations, read-only repos, unattended policy) | PreToolUse `Bash`, file edits, fetch and toolkit tools | none | none |
 | `run-scope-guard.sh` (Figma phase rule, worktree boundary warning) | PreToolUse Figma tools, file edits | none: the phase records its own MCP calls | none |
 | `run-stop-guard.sh` (no silent stop mid-run) | Stop | none: halts stay the phase's own write | none |
+| `task-mirror.sh` (native task list into the run tracker, so the office shows it) | PostToolUse `TaskCreate`/`TaskUpdate` | none: the phase calls `phase-tracker.sh task` itself | none: the phase calls `phase-tracker.sh task` itself |
+| `file-context.sh` (what the repo's memory says about a file, after it is read) | PostToolUse `Read` | none | none |
 | `edit-syntax-gate.sh` | PostToolUse file edits | PostToolUse `apply_patch` | none: Copilot discards postToolUse output |
 | `check-read-size.sh`, capture hooks | registered | none | none |
 

package/README.tr.md

@@ -297,7 +297,7 @@ pipeline'daki hiçbir şey merge etmez.
 - **Koşunun etrafındaki operasyonlar.** Mod açıkken ikinci bir launchd ajanı Mac'i uyanık tutar (`caffeinate -s -i`; `autopilot-on`'daki ekran sorusuna evet dersen `-d` de eklenir), her koşu da tick'i bitene kadar bir uyku kilidi tutar. Yapılandırılmış bir reponun ihtiyaç duyduğu her credential zamanlama önerilmeden önce ve her tick'te yeniden yoklanır; kilitlenmiş bir keychain, anahtarın adı ve çözümüyle reddedilir. Üst üste hiçbir şey üretmeyen denemelerden sonra bir devre kesici yeni başlatmayı durdurur, `costCeilingUsd` harcamayı 24 saatlik yuvarlanan pencerede sınırlar, `maxParallelAgents` aynı anda çalışan oturum sayısını sınırlar, koşucu günde bir kez bir temizlik raporu ve açıksa bir özet (digest) yazar. [Autopilot operasyonları](./pipeline/multi-agent-refs/features/autopilot-operations.md)
 - **Kapalı başarısız olan (fail-closed) bir guard.** Değişken açıkken Bash guard bir komutu yalnızca `;`, `&&`, `||` ve düz pipe'larla birleşen basit komutlara indirgeyebildiğinde değerlendirir, gerisini ayrıştırmadan reddeder. Ayrıştırabildiklerinde: push, PR, issue ya da tracker yazımı yok, Keychain okuması yok, ağ izin listesi dışına istek yok, paket kurulumu ya da manifest düzenlemesi yok, korunan bir yola yazma yok. Ticket, sayfa ve PR metni modele güvenilmeyen-veri sınırlayıcıları içinde ulaşır. İzin profili (`install --unattended`) ikinci hattır; sınırın kendisi ayrı, admin olmayan bir macOS kullanıcısı ve varsayılan ile release branch'lerindeki GitHub ruleset'leridir, bunları operatör uygular. [Gözetimsiz güvenlik](./pipeline/multi-agent-refs/features/unattended-security.md)
 - **İddialar güvenilmez, kontrol edilir.** Kalite kapıları açıkken koşunun repo hakkındaki iddiaları commit'ten önce kontrol edilir: değişikliğin referans verdiği lokalizasyon anahtarı ya da endpoint gerçekten var, açık analiz soruları cevaplanmış ya da koşuyu park ediyor, bir triyaj alıntısı andığı satırı birebir alıntılıyor, "önceden vardı" denen bulgu diff'in dokunmadığı bir satırı gösteriyor, planın adımları karşılanmış, ve bir test başarısı stack'in kendi işaretleriyle okunan pozitif bir çalıştırılmış test sayısı gösteriyor (8 stack: `ios`, `android`, `web`, `backend-node`, `python`, `go`, `rust`, `jvm`), yanında da değişiklik olmadan kırmızıya dönen yeni bir test. Her karar bir gate ledger'a yazılır ve commit hook'u, zorunlu kapıları HEAD için geçmemiş bir commit'i reddeder. [Gözetimsiz kapılar](./pipeline/multi-agent-refs/features/unattended-gates.md), [stack adaptörleri](./pipeline/multi-agent-refs/features/stack-adapters.md)
-- **Spec, plan ve review disiplini.** `/multi-agent:analysis` bir proje anayasası yazar (güvenlik, erişilebilirlik, mimari ve lisans kuralları, her biri bir kaynağa bağlı); spec-consistency kapısı id üzerinden her gereksinimin bir görevi ve bir testi olduğunu, hiçbir şeyin bağlayıcı bir kuralı askıya almadığını kontrol eder. Faz 1 dört mercekle (kapsam, uygulanabilirlik, güvenlik, daha ucuz bir alternatif) tek bir plan-critic turuyla biter; itirazlar bir kez cevaplanır ve bir script karar verir. Review'da `blocking` bir bulgu koşuyu ancak iki bağımsız reviewer aynı bulguyu taşıdığında ya da başarısız bir test onu gösterdiğinde durdurur; aksi halde `important`'a düşürülür, asla silinmez. [Anayasa](./pipeline/multi-agent-refs/features/constitution.md), [plan critic](./pipeline/multi-agent-refs/features/plan-critic.md), [review kararı](./pipeline/multi-agent-refs/features/review-decision.md)
+- **Spec, plan ve review disiplini.** `/multi-agent:analysis` bir proje anayasası yazar (güvenlik, erişilebilirlik, mimari ve lisans kuralları, her biri bir kaynağa bağlı); spec-consistency kapısı id üzerinden her gereksinimin bir görevi ve bir testi olduğunu, hiçbir şeyin bağlayıcı bir kuralı askıya almadığını kontrol eder. Faz 1 altı mercekle (kapsam, uygulanabilirlik, güvenlik, daha ucuz bir alternatif, spec'in ima ettiği ama test edilmeyen girdi, uygulayıcıya bırakılmış karar) tek bir plan-critic turuyla biter; itirazlar bir kez cevaplanır ve bir script karar verir. Review'da `blocking` bir bulgu koşuyu ancak iki bağımsız reviewer aynı bulguyu taşıdığında ya da başarısız bir test onu gösterdiğinde durdurur; aksi halde `important`'a düşürülür, asla silinmez. [Anayasa](./pipeline/multi-agent-refs/features/constitution.md), [plan critic](./pipeline/multi-agent-refs/features/plan-critic.md), [review kararı](./pipeline/multi-agent-refs/features/review-decision.md)
 - **Bir istemci sözleşmesi.** Komutlar ve koşu soruları veri olarak beyan edilir. `/multi-agent:serve`, CLI'ın bastığı aynı JSON üzerinde localhost'ta bir HTTP sunucusu başlatır; `pipeline/contract/` bir istemcinin üzerine kurulacağı manifest'i, TypeScript tiplerini ve fixture'ları taşır. Dört telefon route'u redakte edilmiş koşuları okur, park etmiş bir soruyu sunulan seçeneklerden biriyle cevaplar ve yalnızca açıldığında bir başlatmayı kuyruğa alır; her istek kayıtlı bir cihazın Ed25519 imzasını taşır. Telefon uygulaması ayrı bir proje. [İstemci kiti](./pipeline/contract/README.md), [telefon API'si](./pipeline/multi-agent-refs/features/phone-api.md)
 
 **Elle kullanım değişmedi.** Yukarıdaki her davranış `MULTI_AGENT_UNATTENDED=1`
@@ -352,6 +352,51 @@ Dolayısıyla sürekli mod her hostta `claude` binary'sinin `PATH`'te olmasını
 istiyor. Kuyruk ve repo seçimi her hostta `~/.claude/autopilot/` altında durur;
 bu bilinçli - bir makinedeki iki CLI tek kuyruk okumalı, iki değil.
 
+## Ofis
+
+Pipeline'ı piksel bir ofis olarak gösteren ve oradan yönetmeni sağlayan yerel
+bir web sayfası. `/multi-agent:office-on` sözleşme sunucusunu 127.0.0.1'de
+başlatır ve sayfayı tek kullanımlık bir kodla açar; sunucu
+`/multi-agent:office-off` ile durdurulana kadar çalışır.
+
+![Şirket katı: resepsiyon, oryantasyon, açık ofis, mutfak, muhasebe ve tuvalet](.github/office/floor-tr.png)
+
+- **Koşular canlanır.** Ajanlar açık ofiste masalarında bekler. Bir koşu
+  rollerini çağırınca koşunun odasına yürürler. Her reponun kendi katı var:
+  Geliştirme odaları (`/multi-agent`) ve Analiz odaları
+  (`/multi-agent:analysis`). Birden fazla repoya dokunan koşu, diğer repoların
+  katında şube masası açar.
+- **Terminaldeki görev listesi masada.** Masa tabelası fazı (`Faz 3/6 Dev`),
+  fazın görevleri bittikçe dolan çubuğu ve sürmekte olan görevi gösterir. Bir
+  PostToolUse hook'u `TaskCreate` / `TaskUpdate` çağrılarını koşunun
+  takipçisine yazar; ofis ile terminal aynı listeyi gösterir. Çalışan ajanın
+  üstündeki bulut ne yaptığını söyler.
+- **Ekosistemin geri kalanının da odası var.** Resepsiyon, Jira ya da GitHub
+  issue'sundan veya serbest metinden koşu başlatır. Posta odası, `gh`'nin
+  oturum açtığı tüm GitHub hesaplarındaki ve Bitbucket Server'daki PR'ları
+  listeler. Sunucu odasında toolkit MCP araçları, servisler, anahtar dolabı
+  (ad ve canlı kontrol sonucu, asla değer) ve makinenin CPU, bellek ve disk durumu
+  var. Kütüphane stack'leri, komutları ve pipeline'ın repo başına öğrendiklerini
+  tutar. Tuvalet, önizleme gösterdikten sonra worktree'leri, yarım kalan
+  koşuları ve eski koşu loglarını temizler. Muhasebe token ve maliyeti
+  gösterir. Yönetici odasında otopilot, rutinler ve ayarlar (çıktı dili,
+  Fable basamağı, model yönlendirmesi) var. Oryantasyon odası binayı anlatır.
+- **Kişiler iş alır.** Birine tıkla, iş seç, onayla. Makineyi değiştiren
+  yazmalar yalnızca yereldir ve iki istek ister. Etkileşimli ya da kurulumu
+  değiştiren işler terminalde kalır; komutlar penceresi her komut için sebebini
+  yazar.
+
+![Geliştirme ve Analiz odalarıyla repo katları, süren bir analiz ve bir şube masası](.github/office/rooms-tr.png)
+
+| Komut                        | Ne yapar                                                 |
+| ---------------------------- | -------------------------------------------------------- |
+| `/multi-agent:office-on`     | Sunucuyu başlatır ya da var olanı kullanır, sayfayı açar |
+| `/multi-agent:office-status` | Çalışıyor mu, adresi (token asla) ve son işlemleri       |
+| `/multi-agent:office-off`    | Sunucuyu durdurur; sen durdurana kadar çalışır           |
+
+Güvenlik modeli: [ofis tehdit modeli](pipeline/multi-agent-refs/features/office-threat-model.md).
+Telefondan erişim bu kurulumun parçası değil.
+
 ## Hangi model cevaplıyor
 
 Merdiven `fable -> opus -> sonnet -> haiku`; koşu başarısızlıkta merdiveni iner.
@@ -450,6 +495,21 @@ triage notu bunu belirtir.
 
 **Secret scan**, Claude Code'da bir `PreToolUse` hook'u olarak (bulgu halinde commit'i sert-engeller) ve diğer yerlerde bir pre-push kontrolü olarak çalışır.
 
+**Host başına hook'lar.** Zorlayan hook'lar Claude Code'a ait; `install` bunları kaydeder, `/multi-agent:doctor` (`hook-reachability`) ayarlarında hangisinin eksik olduğunu söyler.
+
+| Hook | Claude Code | Codex CLI | Copilot CLI |
+| --- | --- | --- | --- |
+| `pre-commit-check.sh` (secret taraması, sahipli yollar, attended build/test kanıtı, unattended defteri) | PreToolUse `Bash` | yok: pre-push kontrolü | yok: pre-push kontrolü |
+| `agent-guard.sh` (atıf, force-push, atlanan git hook'ları, argv'de secret, kapanış onayları, salt okunur repolar, unattended politikası) | PreToolUse `Bash`, dosya düzenlemeleri, fetch ve toolkit araçları | yok | yok |
+| `run-scope-guard.sh` (Figma faz kuralı, worktree sınırı uyarısı) | PreToolUse Figma araçları, dosya düzenlemeleri | yok: faz kendi MCP çağrılarını kaydeder | yok |
+| `run-stop-guard.sh` (koşu ortasında sessizce durmaz) | Stop | yok: duraklama fazın kendi yazımı olarak kalır | yok |
+| `task-mirror.sh` (terminaldeki görev listesini koşunun takipçisine yazar, ofis de onu gösterir) | PostToolUse `TaskCreate`/`TaskUpdate` | yok: faz `phase-tracker.sh task`'ı kendisi çağırır | yok: faz `phase-tracker.sh task`'ı kendisi çağırır |
+| `file-context.sh` (okunan dosya hakkında repo hafızasının söylediklerini verir) | PostToolUse `Read` | yok | yok |
+| `edit-syntax-gate.sh` | PostToolUse dosya düzenlemeleri | PostToolUse `apply_patch` | yok: Copilot postToolUse çıktısını atar |
+| `check-read-size.sh`, capture hook'ları | kayıtlı | yok | yok |
+
+Bir host'ta eşdeğer hook yoksa kural yine faz dokümanlarında durur; orada zorlama değil, bir istektir.
+
 ## Pipeline koşusu dışında
 
 Pipeline'ı kurmak yalnız onu çalıştırdığında işe yaramıyor. Sıradan bir oturum açtığında aynı üç şey elinin altında; her sohbette yüklenen `rules/outside-the-pipeline.md` bunları duyuruyor:

package/docs/adr/0018-cross-repo-links-not-a-global-graph.md

@@ -0,0 +1,43 @@
+# 18. Cross-repository links, not a global graph
+
+**Status:** Accepted · 2026-10-26 · extends [ADR-0010](./0010-own-code-graph.md)
+
+## Context
+
+A run can touch a main repository and the libraries it depends on (the
+dev-context picker adds submodules and extra repositories). Each has its own
+code graph under `~/.claude/knowledge/<project>/`, and a change in a library is
+only half understood until the files that import it in the main repository are
+known.
+
+`Graphify-Labs/graphify` (Apache-2.0) answers this with one global graph
+across repositories, linking calls and types between them. That merges every
+repository into one store that must be rebuilt as a whole, carries names from
+unrelated repositories into each other's queries, and makes a per-project
+graph no longer the single answer for its project.
+
+## Decision
+
+Graphs stay separate. `graph-links.mjs build --projects <a,b,...>` joins them
+by one fact each graph already has: an import of a name the repository does
+not declare (a `module:` node). Each such name is matched against what the
+other repositories export (package name, Python packages, Swift targets, the
+Go module path, Kotlin top-level types) and every match is one row in
+`~/.claude/knowledge/_links.json`: importing repository, files, imported name,
+exporting repository. `graph-links.mjs affected --project <b>` lists the files
+elsewhere that import b. The link file is rebuilt in a second, so it has no
+incremental state.
+
+## Consequences
+
+- A per-project graph keeps meaning what it meant; nothing is merged into it.
+- Links are as good as the import patterns: a dynamic import or a name built
+  at run time is not linked, the same limit the per-project graph states.
+- A Kotlin import keeps only its class name in the graph, so a link is kept
+  only for the importing files whose `import <package>.<Name>` names the
+  package the exporting file declares. That check reads both repositories
+  from disk; a repository that moved since its graph was built links nothing.
+- The repository directory name counts as an export only when the stack
+  names none, so a library called `core` does not catch every `core.*` import.
+- The link file holds file paths of every listed repository; it is written
+  0600 beside the graphs and never leaves the machine.

package/docs/adr/README.md

@@ -25,8 +25,9 @@ Format: lightly adapted from [Michael Nygard's ADR template](https://cognitect.c
 | [0013](./0013-lsp-code-intelligence.md)                            | A language server for the answers regex cannot give                 | Accepted                                                                 |
 | [0014](./0014-six-phase-consolidation.md)                          | Six phases, because two of the eight were doing the same work twice | Accepted (amended by 0015: the depth answer is removed)                  |
 | [0015](./0015-one-pipeline-no-depth-answer.md)                     | One pipeline: the depth question is removed                         | Accepted (extended by 0016: the workspace and resume names go too)       |
-| [0016](./0016-the-run-shape-is-asked-not-typed.md)                  | The shape of a run is asked, not typed into its name                | Accepted                                                                 |
+| [0016](./0016-the-run-shape-is-asked-not-typed.md)                 | The shape of a run is asked, not typed into its name                | Accepted                                                                 |
 | [0017](./0017-change-impact-from-the-graph.md)                     | Change impact from the graph: spans, a transitive walk, freshness   | Accepted                                                                 |
+| [0018](./0018-cross-repo-links-not-a-global-graph.md)              | Cross-repository links, not a global graph                          | Accepted                                                                 |
 
 ## Writing a New ADR
 

package/docs/facts.json

@@ -1,7 +1,7 @@
 {
   "$comment": "Generated by pipeline/scripts/gen-facts.mjs. Do not hand-edit: the site reads this, and a number edited here instead of at its source is the drift this file removes.",
-  "generatedAt": "2026-10-24",
-  "version": "20.30.0",
+  "generatedAt": "2026-10-26",
+  "version": "20.34.0",
   "phaseSchema": 2,
   "phases": [
     {
@@ -33,14 +33,14 @@
   "modes": {
     "full": [0, 1, 2, 3, 4, 5],
     "autopilot": [0, 1, 2, 3, 4, 5],
-    "analysis": [0, 1, 3, 4, 5]
+    "analysis": [0, 1, 2, 3, 4, 5]
   },
   "commandCount": 69,
   "skillCount": 165,
   "skillCountAll": 237,
   "agentCount": 11,
   "hosts": ["Claude Code", "Codex CLI", "Copilot CLI"],
-  "toolCount": 208,
+  "toolCount": 213,
   "toolCategories": {
     "ios": 42,
     "web": 38,
@@ -51,6 +51,7 @@
     "design": 7,
     "repo": 6,
     "voice": 6,
+    "graph": 5,
     "ui": 5,
     "context": 4,
     "pass": 4,
@@ -64,5 +65,5 @@
     "test": 1
   },
   "pluginSkillCount": 261,
-  "toolkitVersion": "3.26.0"
+  "toolkitVersion": "3.27.0"
 }

package/docs/features.md

@@ -340,7 +340,7 @@ Stack adapters cover 8 stacks: `ios`, `android`, `web`, `backend-node`, `python`
 
 ### Plan Critic
 
-With the gates active, Phase 1 ends with one adversarial critic (`agents/plan-critic.md`) under four lenses: scope, feasibility, security and a cheaper alternative. Each objection carries evidence anchors; the planner answers each once, accepting and revising or rebutting with evidence, and `plan-critique-gate.mjs` judges with no model call. An objection citing a binding constitution rule blocks unless its reply resolves it with an anchor that holds; the rest is advisory and appears in the plan render and the PR summary. One round, because further rounds move agents toward each other rather than toward the right answer. The critic follows the fable switch. Detail: [`plan-critic.md`](../pipeline/multi-agent-refs/features/plan-critic.md).
+With the gates active, Phase 1 ends with one adversarial critic (`agents/plan-critic.md`) under six lenses: scope, feasibility, security, a cheaper alternative, an input the spec implies that no test exercises, and a decision left to the implementer. Each objection carries evidence anchors; the planner answers each once, accepting and revising or rebutting with evidence, and `plan-critique-gate.mjs` judges with no model call. An objection citing a binding constitution rule blocks unless its reply resolves it with an anchor that holds; the rest is advisory and appears in the plan render and the PR summary. One round, because further rounds move agents toward each other rather than toward the right answer. The critic follows the fable switch. Detail: [`plan-critic.md`](../pipeline/multi-agent-refs/features/plan-critic.md).
 
 ### Review Decision Rule
 

package/install/_dev-only-files.mjs

@@ -69,6 +69,7 @@ const DEV_ONLY_TOOLING = Object.freeze([
   "check-rewrite-overlap.mjs", // compares a rewrite against a source only a maintainer has
   "gen-catalog-history.mjs", // reads the repo's git history; an install has none
   "gen-ref-toc.mjs", // regenerates the repo's own reference tree; an install has no pipeline/
+  "ref-filler-audit.mjs", // audits the repo's own instruction docs; an install has no pipeline/
   "validate-schemas.mjs", // validates the repo's own schema files, needs ajv
   "permission-baseline.mjs", // reads the repo's own command, skill and agent tree; an install has none
   "sync-parity-check.sh",

package/install/_unattended-profile.mjs

@@ -316,6 +316,67 @@ export function buildUnattendedProfile(current = {}, opts = {}) {
   return next;
 }
 
+/**
+ * Bring an existing profile up to the shipped deny rules without touching
+ * anything else: only permissions.deny and the sandbox's denyRead and
+ * denyWrite grow, so a release that adds a deny reaches every installed
+ * profile on the next install, and nothing it allows changes. No profile file,
+ * or one that does not parse, is left alone.
+ *
+ * @param {{home:string, dryRun?:boolean}} opts
+ * @returns {{path:string, added:string[], written:boolean}}
+ */
+export function tightenUnattendedProfile({ home, dryRun = false }) {
+  const path = unattendedSettingsPath(home);
+  if (!existsSync(path)) return { path, added: [], written: false };
+  let current;
+  try {
+    current = JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return { path, added: [], written: false };
+  }
+  if (!current || typeof current !== "object" || Array.isArray(current))
+    return { path, added: [], written: false };
+  const added = [];
+  const perms = { ...(current.permissions || {}) };
+  const deny = Array.isArray(perms.deny) ? [...perms.deny] : [];
+  for (const [rule] of PROFILE.deny) {
+    if (hasRule(deny, rule)) continue;
+    deny.push(rule);
+    added.push(`deny:${rule}`);
+  }
+  const next = { ...current, permissions: { ...perms, deny } };
+  // Directories the toolkit's index refuses: a list, so it only grows too.
+  for (const [key, value] of PROFILE.env) {
+    if (key !== "MCP_TOOLKIT_INDEX_DENY") continue;
+    const env = current.env && typeof current.env === "object" ? current.env : {};
+    const have = String(env[key] ?? "")
+      .split(",")
+      .map((x) => x.trim())
+      .filter(Boolean);
+    const missing = value.split(",").filter((x) => !have.includes(x));
+    if (!missing.length) continue;
+    next.env = { ...env, [key]: [...have, ...missing].join(",") };
+    added.push(...missing.map((x) => `env.${key}:${x}`));
+  }
+  const sb = current.sandbox;
+  if (sb && typeof sb === "object" && !Array.isArray(sb)) {
+    const fs = sb.filesystem && typeof sb.filesystem === "object" ? sb.filesystem : {};
+    const nextFs = { ...fs };
+    for (const key of ["denyRead", "denyWrite"]) {
+      const have = Array.isArray(fs[key]) ? fs[key].map(String) : [];
+      const missing = PROFILE.sandbox.filesystem[key].filter((p) => !have.includes(p));
+      if (!missing.length) continue;
+      nextFs[key] = [...have, ...missing];
+      added.push(...missing.map((p) => `sandbox.${key}:${p}`));
+    }
+    next.sandbox = { ...sb, filesystem: nextFs };
+  }
+  if (!added.length || dryRun) return { path, added, written: false };
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  return { path, added, written: true };
+}
+
 /**
  * Write the profile into its own settings file. Idempotent: running it twice
  * changes nothing the second time.