@event4u/agent-config 16.4.0 → 17.0.0

package/dist/agent-src/commands/team-knowledge.md

@@ -26,7 +26,7 @@ packs:
 Top-level orchestrator for the `/team-knowledge` family — the
 consolidation gate over the typed knowledge-observation events
 captured during normal task work (see
-[`knowledge-pages`](../../agent-src/templates/contexts/knowledge-pages.md)
+[`knowledge-pages`](../templates/contexts/knowledge-pages.md)
 and the event schema in `src/scripts/_lib/knowledge_events.ts`).
 
 Not to be confused with the pre-existing [`/knowledge`](../../product-discovery/knowledge/command.md)

package/dist/agent-src/commands/threat-model.md

@@ -3,7 +3,7 @@ model_tier: high
 name: threat-model
 pack: engineering-base
 visibility: internal
-skills: [threat-modeling, authz-review, security-sensitive-stop]
+skills: [threat-modeling, authz-review]
 description: Run a pre-implementation threat model on a proposed change — enumerates abuse cases, trust boundaries, and authorization gaps before the first line of code is written
 council_depth: deep
 suggestion:

package/dist/agent-src/commands/upstream-contribute.md

@@ -18,6 +18,22 @@ packs:
 
 # /upstream-contribute
 
+This command is a **front on one outward step**, not a second way out. It
+decides *what* is worth contributing and hands the finding to
+`self-repair:release`, which owns the branch, the commit identity, the privacy
+floor over the record text and every pushed object, and the pull-request or
+issue route. It pushes one commit built on `origin/main` from the branch's net
+change, on `retro/<fingerprint>`, under the signed-in account's noreply
+identity. Over that commit the floor checks credentials and the consumer's own
+identifiers only — a name in the diff that is neither still passes, so read
+the diff in the dry run.
+
+```
+ONE WAY OUT. THIS COMMAND NEVER PUSHES, NEVER OPENS A PULL REQUEST,
+AND NEVER WRITES A SECOND COPY OF AN ARTIFACT.
+WHAT LEAVES THE MACHINE LEAVES THROUGH `self-repair:release`.
+```
+
 ## Input
 
 The user may provide:
@@ -30,13 +46,15 @@ The user may provide:
 
 ### 1. Identify what to contribute
 
-If the user provided a file path → read it.
-If not → check for recent overrides or new skills:
+If the user provided a file path, read it. If not, look for recent overrides
+or new project-local artifacts:
 
 ```bash
-ls agents/overrides/ 2>/dev/null
-find .augment/skills -name 'SKILL.md' -newer .augment/rules -maxdepth 3 2>/dev/null
-git diff --name-only HEAD~5 -- agents/overrides/ .augment/skills/ 2>/dev/null
+ls agents/overrides/
+```
+
+```bash
+git diff --name-only HEAD~5 -- agents/overrides/
 ```
 
 Ask the user to confirm what should be contributed:
@@ -53,130 +71,102 @@ Ask the user to confirm what should be contributed:
 
 ### 2. Check universality
 
-Before proceeding, verify the content is package-worthy:
+This is a **worth-contributing** judgement, not a privacy check — the privacy
+floor over the record text runs in step 4 and cannot be satisfied by a checkbox
+here.
 
-- [ ] No project-specific references (domain names, local paths, FQDNs, project-specific classes)
-- [ ] Benefits ALL consumers, not just this project
-- [ ] Learning occurred 2+ times OR is clearly generalizable
+- [ ] Benefits every consumer, not only this project
+- [ ] The learning meets the evidence threshold in `docs/contracts/retro-v1.md`
+- [ ] A named mechanism explains why the shipped default is wrong
 
-If project-specific content is found, ask:
+Below that bar, record the signal and leave the shipped default alone.
 
-```
-> ⚠️ Found project-specific references: {examples}
->
-> 1. Remove them — make it universal
-> 2. Cancel — keep as project-only override
-```
-
-### 3. Determine contribution type and target path
+### 3. Determine contribution type and source path
 
-| Type | Source target | Condensed target |
-|---|---|---|
-| **Skill** | `src/skills/{name}/SKILL.md` | `dist/agent-src/skills/{name}/SKILL.md` |
-| **Rule** | `src/rules/{name}.md` | `dist/agent-src/rules/{name}.md` |
-| **Command** | `src/domains/{domain}/{name}/command.md` | `dist/agent-src/commands/{name}.md` |
-| **Guideline** | `docs/guidelines/{cat}/{name}.md` | _(not condensed; reference-only)_ |
+`src/` is the only place an artifact is authored. The projections under
+`dist/agent-src/` are regenerated by the package's own sync step; a
+contribution never writes a second, hand-condensed copy (ADR-201 copies `.md`
+verbatim).
 
-### 4. Get access to the package repo
+| Type | Source path |
+|---|---|
+| **Skill** | `src/skills/{name}/SKILL.md` |
+| **Rule** | `src/rules/{name}.md` |
+| **Command** | `src/domains/{domain}/{name}/command.md` |
+| **Guideline** | `docs/guidelines/{category}/{name}.md` |
 
-```
-> I need to create files in the agent-config package repo.
->
-> 1. I have it cloned locally — I'll give you the path
-> 2. Clone it for me into /tmp/agent-config-upstream
-> 3. Just output the files — I'll handle it manually
-```
+### 4. Hand the finding to the ladder
 
-**Option 1:** User provides path → verify it's the right repo:
+Show the user what would leave the machine, before anything leaves it:
 
 ```bash
-cd {path} && git remote get-url origin
-# Must contain event4u-app/agent-config
+./agent-config self-repair:release <fingerprint> --dry-run
 ```
 
-**Option 2:**
-
-```bash
-git clone git@github.com:event4u-app/agent-config.git /tmp/agent-config-upstream
-cd /tmp/agent-config-upstream
-```
+The dry run prints where the send goes — repository, account, route and its
+fallback rungs, push remote, base commit — and what it carries — branch name,
+commit identity and message, diff, title, body, and the issue the ladder falls
+back to — then the digest of all of it. The one byte outside the digest is the
+commit date, set at send time in UTC. A blob that is not UTF-8 text is refused,
+not scanned. It reads GitHub and the local repository and writes to neither. Read it with the user; a refusal from
+the privacy floor is final and the finding stays local.
 
-**Option 3:** Skip to Step 7 (output files only).
-
-### 5. Create branch and write files
+**No record yet?** Then there is nothing to release, and no command here
+makes one. `self-repair:status` LISTS records, and it plus `self-repair:release`
+are the only two verbs `./agent-config` routes. A record is opened by the
+self-repair hook when it observes the defect, so a learning that no record
+covers cannot ride this ladder today — that gap is real, it is named here
+rather than papered over, and it is the consumer-project case
+`road-to-one-upstream-that-checks-what-leaves` Phase 4 still owes a route.
 
 ```bash
-cd {package-repo}
-git checkout main && git pull
-git checkout -b {type}/{name}  # e.g. feat/skills/php-container-discovery
+./agent-config self-repair:status
 ```
 
-Write the **uncondensed version** (full, verbose, human-readable).
-Write the **condensed version** (token-efficient, 40-60% shorter for skills; 1:1 for rules/commands).
-
-Condensed version MUST preserve:
+### 5. Quality gates (only in a checkout of this package)
 
-- All code blocks (byte-for-byte)
-- YAML frontmatter (verbatim)
-- All headings
-- Validation rules, gotchas, "Do NOT" sections
+Run the package's full CI pipeline and confirm it is green. This is numbered
+before the send because it runs before the send. The `package-ci-checks` rule
+owns the entry point and names it; a consumer project has no such runner,
+which is why the command is not repeated here. Outside such a checkout there
+is nothing to run first, and the package CI runs these after the issue or
+pull request exists.
 
-Frontmatter must have `source: package`.
-
-### 6. Run quality gates
+### 6. Send, once, with the user's word in that turn
 
 ```bash
-./scripts-run src/scripts/skill_linter --all           # 0 FAIL required
-./scripts-run src/scripts/check_condensation            # No 🔴 errors for this file
-./scripts-run src/scripts/condense --generate-tools    # Regenerate symlinks
-bash scripts/condense.sh --check                # dist/agent-src/ in sync with source
+./agent-config self-repair:release <fingerprint> --approve <digest>
 ```
 
-Fix any issues before continuing.
+The user runs that command; the agent prints it and never runs the `--approve`
+form itself. The digest names the bytes it covers — anything changed since the
+dry run voids it — but it is not consent: the agent can read it as easily as
+the user. It is a Hard-Floor action under
+`non-destructive-by-default`, so no standing instruction, autonomy setting or
+earlier approval substitutes for it.
 
-### 7. Present result
+The ladder chooses the vehicle: a pull request only when the release runs
+from a checkout of this package — `AGENT_CONFIG_SOURCE` names that checkout
+when the command runs inside it by another path, and set in a consumer project
+it widens nothing — an issue otherwise, and a local record when nothing may
+leave. Degrading never widens what leaves the machine, only the vehicle.
 
-**If Option 1 or 2** (working in package repo):
+### 7. Remind about local override cleanup
 
 ```
-> ✅ Files created in {package-repo}:
->
-> - `src/{type}/{name}` (source)
-> - `dist/agent-src/{type}/{name}` (condensed)
+> After the contribution is merged and you update the package here:
 >
-> Quality gates: {pass/fail summary}
+> 1. rm agents/overrides/{type}/{name}.md
+> 2. ./agent-config update   (moves the version pin; your package manager fetches it)
 >
-> 1. Commit and push — I'll create the PR
-> 2. Commit only — I'll push later
-> 3. Review the files first
-```
-
-**If Option 3** (manual):
-
-Show both file contents in copyable fenced blocks with full paths as headers.
-
-### 8. Create PR (if user chose Option 1 in Step 7)
-
-```bash
-git add .
-git commit -m "{type}({scope}): add {name}
-
-{brief description of what it does and why it's universal}"
-git push -u origin {branch}
+> The shared version then replaces your local override.
 ```
 
-Create PR via GitHub API with the package's PR template.
-Fill in all gates (Promotion, Quality, Universality, Completeness).
-
-### 9. Remind about local override cleanup
+## Do NOT
 
-```
-> 📝 After the PR is merged and you update the package in this project:
->
-> ```bash
-> rm agents/overrides/{type}/{name}.md
-> composer update event4u/agent-config  # or: npm update
-> ```
->
-> The shared version will then replace your local override.
-```
+- Do NOT push, open a pull request, or open an issue by hand — that is the
+  ladder's job, and the floor it does carry runs there.
+- Do NOT write a hand-condensed second copy of an artifact.
+- Do NOT edit any generated projection; `src/` is the source of truth.
+- Do NOT stage with a bare `git add .` — name the paths.
+- Do NOT assume consent from an earlier contribution; the word is per turn.

package/dist/agent-src/commands/worktree/cleanup.md

@@ -34,18 +34,25 @@ For a whole-checkout sweep, get the classified set in one pass instead of
 running the per-worktree gate by hand:
 
 ```bash
-./scripts-run src/scripts/worktree_cleanup_check inventory        # counts + review reasons
-./scripts-run src/scripts/worktree_cleanup_check inventory --plan # commands for the safe set
+agent-config worktree:cleanup inventory          # counts + review reasons
+agent-config worktree:cleanup inventory --plan   # commands for the safe set
+agent-config worktree:cleanup apply              # remove the safe set (`--apply`)
 ```
 
-`safe` = on a branch, merged into the trunk, clean, in a conventional
-worktree root, and no git activity for 48 h. `review` carries its
-disqualifying reason; `live` means another session may hold it. The mode
-reports only — running the plan is a bulk deletion needing the user's
-explicit this-turn approval per
-[`non-destructive-by-default`](../../../rules/non-destructive-by-default.md).
-Present the safe set as a list and wait; a bulk sweep never inherits a
-single earlier approval.
+`safe` = on a branch whose work is on the trunk — merged by merge commit or
+rebase (`merged-ancestor`), squash-merged with the branch tip equal to the PR's
+head (`merged-pr`, read once through your `gh` login), or offline by tree
+equivalence (`merged-equivalent`) — clean, holding no ignored file a rebuild
+would not restore, not locked, with no live session and no git activity for
+48 h, inside a conventional root or registered by this package. `review` names
+its disqualifier; `live` means a session may hold it.
+
+**`/worktree cleanup --apply`** runs `apply`: it removes exactly the safe set,
+re-checks every candidate immediately before removing it, never passes force,
+never deletes a branch, and writes one journal line per candidate. Removing the
+proven set is housekeeping (ADR-295), so the explicit command is the user's ask
+and needs no second confirmation. Anything outside the safe set is listed, never
+removed here — removing it stays a decision per candidate, below.
 
 ### 2. Per candidate, run the gates IN ORDER
 
@@ -54,7 +61,7 @@ branch without remote, tag-only reachability, deleted remote branch,
 untracked files, paths with spaces — `tests/scripts/worktree_cleanup_check.test.ts`):
 
 ```bash
-./scripts-run src/scripts/worktree_cleanup_check check <worktree-path>
+agent-config worktree:cleanup check <worktree-path>
 ```
 
 Exit `0` → removal allowed. Exit `1` → **refuse** that candidate; the

package/dist/agent-src/contexts/contracts/consumer-agents-md-guide.md

@@ -21,6 +21,60 @@ the sections below into AGENTS.md only when the project actually needs
 the content there (e.g. an unusual stack note that no `agents/` doc
 covers). Default: leave AGENTS.md thin and put detail under `agents/`.
 
+## Goal section (optional copy-in)
+
+```markdown
+## Goal
+
+{{one_to_three_sentences}}    # What this project is for, in terms a plan can
+                              # be checked against. Not a mission statement:
+                              # "every booking reaches the organiser within a
+                              # minute, and no booking is lost" is checkable,
+                              # "delight our users" is not.
+```
+
+## No-gos section (optional copy-in)
+
+```markdown
+## No-gos
+
+- Never {{forbidden_thing}}   # One per bullet. Name a PATH, a COMMAND, a
+                              # DEPENDENCY or a BEHAVIOR — "never edit
+                              # `migrations/` by hand", "never run `php
+                              # artisan migrate:fresh` outside a throwaway
+                              # database", "never add a runtime dependency
+                              # without an ADR".
+```
+
+**These two are the exception to "leave AGENTS.md thin".** The default above
+is right for detail: a stack note or a test convention is read when the agent
+reaches the thing it describes, so `agents/` is the better home. A goal and a
+no-go are different in kind — they bind **every** turn, including the ones
+that never open the file where they would otherwise live. What is not written
+in the always-loaded file does not exist for the agent at the moment it
+decides, and a no-go the agent reads after the edit is a no-go it has already
+broken.
+
+Keep both short for the same reason the root file is capped: a goal nobody
+finishes reading constrains nothing.
+
+### Removing a deny row your no-gos produced
+
+`/agents:init` can turn a no-go that names a path or a command into a rule the
+host refuses on, and a rule that blocks work you later need has to be
+removable without reading this package's source. It is:
+
+1. Open the settings file the rows were written to — `.claude/settings.json`
+   unless you chose another — and delete the line from the `permissions.deny`
+   array. Nothing else in the file is touched by removing one entry.
+2. Edit or delete the bullet in your `## No-gos` section, or the next run will
+   offer the same row again.
+
+Nothing re-adds a row you removed on its own: every write is behind an
+explicit question, and declining it writes nothing. There is no command that
+removes a row for you — a package-written entry and one you typed yourself are
+the same text in the same array, so a remover could not tell them apart.
+
 ## Tech-stack section (optional copy-in)
 
 ```markdown

package/dist/agent-src/contexts/execution/analysis-loop.md

@@ -0,0 +1,137 @@
+# Analysis loop
+
+The shared vocabulary of the four analysis doors — `analyze:reference`,
+`analyze:and-optimize`, `analyze:pr` and `analyze:inbox` — loaded on demand by
+each of them. The decision behind the family and every default named here is
+[`ADR-288`](../../../../docs/decisions/ADR-288-analysis-family-one-engine-four-doors.md);
+the mechanics are code under `src/scripts/analysis_*.ts`. This file is the
+lookup surface, not a contract: ADR-118 forbids a loop-design contract, so the
+caps live in each door's `limits:` block.
+
+## Vocabulary
+
+| Word | Means | Never means |
+|---|---|---|
+| **pass** | one extraction read of an inbox source set (inbox Phases 3–5) | a deepening iteration |
+| **loop** | one deepening iteration by one analyst over its own analysis **and** its own roadmap | a re-read of the same draft |
+| **round** | one exchange: every analyst reads the others' finals and reconciles | a loop |
+| **run** | one invocation of a door, from scope resolution to its end state | a round |
+
+## The brief
+
+Every analyst of a run receives the **same brief**, digested; a brief digest
+that differs between two analysts is a defect, not a variation. The brief is
+frozen after scope resolution and at most one blocking scope question. A
+mid-run owner message opens a **new brief revision**, recorded in the run with
+its reason — it never edits the frozen one in place.
+
+## The scope line
+
+Every door prints, before any read:
+
+```
+Scope: <repo|module|subdir> <name> at <path> (anchor: <…>)
+```
+
+Resolved by `src/scripts/analysis_target.ts`. Inside a module the scope names
+the module and `project_root` stays the outer project, with or without a marker
+in the module's own `agents/`.
+
+## The loop shape
+
+Each loop is declared before it runs, in one line:
+
+```
+Loop N/M — <lens> — <falsifiable goal> — inputs: <…> — must produce: <…> — stop-if: <…>
+```
+
+### Deepening lenses (seed + three loops, all three always run)
+
+1. **coverage** — what is there. Read code, not the README. What is wrongly
+   marked missing.
+2. **adversary** — every retained item tested against named
+   counter-hypotheses: already present, contradicts a recorded decision, only
+   different, cost, license. Killing nothing is legal when every test is
+   recorded.
+3. **overbuild-sequencing** — the smallest rung, duplicates folded, order.
+
+Loops 4–5 (`--loops`, cap 5) run only while the previous loop added a top-tier
+item. The summary prints the real loop count.
+
+### Exchange loops (one round)
+
+Each analyst receives the others' final analysis and roadmap, relabelled
+A / B / C, and runs:
+
+1. **inventory** — every foreign claim checked at the pin:
+   `still-true / never-true / unverifiable`, with its tier.
+2. **cross-exam** — the disputed claims, picked by `selectCrossExamTarget`; the
+   prompt quotes each claim verbatim.
+3. **converge** — the own roadmap revised, with a disagreement ledger.
+
+Facts are settled by the tree, never by majority. A minority finding is
+accepted or rejected with a reason, never dropped (`auditMinorityRetention`).
+
+**After every exchange the run prints the gate's numbers** — `reason`,
+`settleable`, `band` and `estimate`, the four fields `analysis_gate.ts`
+returns. A gate whose numbers stay inside the process cannot be audited
+afterwards: the run reads as *"it ran one more round"* with no trace of why.
+
+**An offer is not a decision.** `offer: true` says a further round is
+affordable and plannable, never that it happens. A further round runs only on
+a **recorded council** verdict or a **recorded owner** answer, written where
+the run's reader finds it; the estimate is an input to that decision and never
+a substitute for it.
+
+## Stages a door runs from the shell
+
+```bash
+./scripts-run src/scripts/analysis_target                 # the scope line
+./scripts-run src/scripts/analysis_validate --run <run-dir> --root <project-root> <emitted file>…
+./scripts-run src/scripts/analysis_run_record --run <run-dir>   # checks run.json
+```
+
+`analysis_validate` moves an `emitted` run to `validated` or names each failure;
+`--content-only` skips the five tree gates and says so, for a run on a project
+whose tree those gates do not read.
+
+## Evidence tiers
+
+| Tier | Means | Counts for stopping or "verified" |
+|---|---|---|
+| `executed` | a command or test was run and its output read | yes |
+| `read` | the file or line was opened at the pin | yes |
+| `claimed` | a source or an analyst says so | no |
+| `inferred` | reasoned, not observed | no |
+
+A loop with no `executed` or `read` evidence tied to a changed conclusion is
+`no-external-signal` and does not count as a loop.
+
+## Council roles
+
+- **seat** — answers a question; never edits, runs or fetches.
+- **synthesizer** — folds the seats' answers, names dissent.
+- **gate judge** — decides the one-more-round offer (`src/scripts/analysis_gate.ts`).
+
+Quorum is two seats from two providers; anything less is `single-voice`, said
+in the run and never counted as a clearance. On safety or data-integrity
+questions a critical dissent outweighs a majority.
+
+## The `handoff-v1` shape for external analysts
+
+An analyst outside this host returns one Markdown file:
+
+```yaml
+---
+handoff: v1
+phase: seed | deepen | exchange
+loop: <N>
+pin: <commit sha the analysis was made against>
+consolidates: [<files this one folds, for lint_consolidation_lineage>]
+---
+```
+
+Sections, in order: **Findings vs tree** · **Kills** · **Decisions** · **Steps
+with `verify:`** · **Loop log**. Source names appear only in a sibling
+`*.annex.md`, never in the handoff itself. The owner drops the file into
+`agents/tmp/<round-id>/`; the engine never writes there.

package/dist/agent-src/contexts/execution/auto-dispatch-classification.md

@@ -198,9 +198,9 @@ NEVER "ALWAYS FORK" — THE BENEFIT CANNOT BE PREDICTED BEFORE THE FORK HAPPENS.
 | Needs isolation, a different tool set, or nested dispatch | `subagent` — a fork cannot nest and cannot change tools |
 | Ambiguous / host has no fork primitive | `subagent` — the only primitive this suite's `Agent`-tool dispatch uses today |
 
-A fork forces background mode, which changes the tool set and therefore
-invalidates the very prefix that motivated the fork — so a slice that would
-need a different tool set mid-flight is a `subagent` candidate even when it
+A fork keeps the parent's prefix and tools where the host row says
+`fork_shares_cache: true`, but it cannot change its tools — so a slice that
+would need a different tool set mid-flight is a `subagent` candidate even when it
 started as a fork candidate. This output never downgrades the form or tier
 decisions above; it only picks the primitive once a `parallel` / `steps` /
 `judge` form has already been selected. See

package/dist/agent-src/contexts/execution/decision-closure-execution.md

@@ -76,7 +76,7 @@ expanding the mission. Both lists, closed:
 
 ## What `blocked-by:` may point at, after the retirement
 
-The marker itself is unchanged — `run-continuation` reads blockedness from it
+The marker itself is unchanged — the withdrawn `run-continuation` read blockedness from it
 and from nothing else. What narrows is its contents.
 
 A `## Blockers` entry is the record of a decision the agent **correctly did not

package/dist/agent-src/contexts/execution/host-capability-manifest.md

@@ -18,6 +18,8 @@ A single JSON object, `schema_version: 1`:
   "separate_quota_pool": false,
   "agent_teams": false,
   "worker_respawn": false,
+  "worker_resume": false,
+  "fork_shares_cache": false,
   "structured_ask": false,
   "reads_project_mcp_config": false,
   "mcp_needs_manual_activation": true
@@ -70,6 +72,8 @@ to in-session execution rather than attempting an unsupported primitive.
 | `agent_teams` | bool | Claude Code's experimental multi-instance Agent Teams primitive (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`). `false` → the [judgment ladder](auto-dispatch-classification.md#judgment-ladder-phase-2--road-to-always-on-orchestration)'s rung 3 (team) degrades to parallel subagents, recorded as `degraded_from: 3`. |
 | `worker_respawn` | bool | The host can kill a running worker and spawn a fresh one that continues the SAME task mid-flight. `false` on every host today, deliberately — set `true` only once OBSERVED, never by inference from spawning and killing existing separately. `false` → degrade to stop-loss behaviour, loudly. |
 | `structured_ask` | bool | The host exposes its own structured-ask tool — a native question picker the agent can call instead of rendering a numbered-options block as prose. The per-host SHAPE (tool name, question and option ceilings, free-text availability) lives in `_lib/structured_ask.ts`, never here: every field of this manifest is a strict boolean and a nested object would normalize silently to `false`. `false` → the ask degrades to text, and no call is fired into a host that has no such tool. |
+| `worker_resume` | bool | A finished worker can be re-tasked by name and its next run starts warm. Independent of `worker_respawn` (mid-task kill-and-respawn); neither derives the other. `false` → every dispatch is a fresh spawn, as today. |
+| `fork_shares_cache` | bool | A forked worker's first call reads the parent prefix from cache and keeps the parent tool pool. `false` → the fork guidance keeps its current premise. |
 | `reads_project_mcp_config` | bool | Whether the installer writes an MCP entry into this host's config. `false` → no entry is written for it. Set `true` only once OBSERVED — a host may read a USER-scope MCP config and ignore a project one, and an inference from "supports MCP" erases exactly that distinction. |
 | `mcp_needs_manual_activation` | bool | Whether a human step remains after install — an approval dialog, a restart, a manual enable. **Defaults to `true`, inverted against every other field here**, and only an explicit `false` clears it: the others answer "can the host do X", where an unknown must not read as a capability; this one answers "is there a step left for the user", where an unknown must not read as "nothing to do". |
 
@@ -132,6 +136,8 @@ A prober that decides for itself what counts as evidence is the inference
 | `status_polling` | a **completed poll returning a state the parent did not already hold**. A poll that returns what the parent knew is not an observation of polling |
 | `separate_quota_pool` | a **child leg continuing across a parent quota condition** — the parent constrained, the child proceeding |
 | `worker_respawn` | **one task continuing across a killed and re-spawned worker, same task id.** Never inferred from the fact that spawning and killing both exist separately |
+| `worker_resume` | **a finished leg re-tasked by name whose next `SubagentStart` carries the same ledger `ref`, and whose first call in that run reads more than half its input from cache.** Never inferred from the host documenting a resume or message tool |
+| `fork_shares_cache` | **a fork whose first call reads more than half its input from cache and whose tool list equals the parent's.** Never inferred from documentation |
 | `structured_ask` | **the host's delivered tool surface, in a real session, carrying (or not carrying) a question-picker tool.** The delivered surface is the observation — never the vendor's documentation, and never another host by analogy. A `false` written from an observed surface is "checked, absent"; omitting the field is "never looked" |
 | `reads_project_mcp_config` | **a server named only in the project-scope config appearing in that host's own tool list.** Never inferred from the host documenting MCP support, which does not say which scope it reads |
 | `mcp_needs_manual_activation` | **a session in which the server is live with no human step after install.** The absence of an observation leaves the field `true` — the residual stays reported until somebody watches it not happen |

package/dist/agent-src/contexts/execution/orchestration-telemetry.md

@@ -49,12 +49,12 @@ v1 forward-compat rule on unknown fields).
 | `verdict_changed_outcome` | bool \| null | **A3 extension (ADR-109 Track A).** For a review/verdict subagent (e.g. `production-validator`): did the subagent's verdict actually change the outcome versus the in-session baseline? `true` = it caught a real issue the baseline missed or flipped a false `READY`→`NOT READY`; `false` = same outcome as baseline (no lift); `null` = not a verdict dispatch / not measured. **Negative-control tasks (a clean single-file task) MUST record `false`** — a subagent that reports `true` on a control is producing spurious findings and fails Gate A. This is an additive field on THIS object, not a second schema. Counts/boolean only, no bodies. |
 | `dispatch_mode` | enum \| null | **Form-gate extension (road-to-opt-subagent-harvest P2).** Which orchestration mode the deterministic form gate selected for this dispatch (`do-and-judge`, `do-and-judge-two-stage`, `do-in-steps`, `do-in-parallel`, `do-competitively`, `judge-with-debate`, `do-in-worktrees`, `do-with-live-app-judge`) or `none` (gate declined dispatch). Mode id only. `null` = pre-extension line. Makes the form-gate's value measurable inside the ADR-117 prove-or-drop window. |
 | `task_class` | string \| null | **Routing extension (road-to-cost-aware-model-routing Phase 0).** Category id of the dispatched slice (e.g. `read-only-fanout`, `mechanical-edit`, `implementation`, `review-synthesis`). Enum-style id only, never free-form task text. `null` = pre-extension line / unclassified. |
-| `tier_chosen` | string \| null | Tier the slice was dispatched on (`lite` \| `medium` \| `high`). `null` = pre-extension line. |
+| `tier_chosen` | string \| null | Tier the slice was dispatched on (`lite` \| `medium` \| `high`). `null` = pre-extension line, or a dispatch that carried no model argument. A line with `tier_chosen` and no `model_requested` fails validation: a tier the dispatch did not carry cannot be checked. The capture hook derives it from the dispatch's per-call `model` argument through `TIER_TO_CLAUDE_MODEL`. |
 | `tier_source` | enum \| null | Where `tier_chosen` came from: `static` (frontmatter/category pin) · `inferred` (deterministic per-slice inference) · `inherit` (session tier — no downshift decision). Lets the evidence gate score inferred routing separately from static pinning. |
 | `escalated_from` | string \| null | When the slice was re-dispatched after a verification failure: the tier of the FAILED attempt (e.g. `lite` when a lite return failed verify and the slice re-ran on `medium`). `null` = no escalation. |
 | `verify_result_by_tier` | object \| null | Map of tier → verification result for every attempt of this slice (e.g. `{"lite":"fail","medium":"pass"}`). Values: `pass` \| `fail` \| `skipped`. Feeds the per-tier verify-pass-rate tripwire. Enums only, no verdict bodies. |
 | `dispatch_tokens` | int \| null | **Cost-% extension.** Absolute tokens the dispatched slice consumed (measured subagent usage). Feeds the MODELED cost-% in `orchestration_savings_report`, which needs an absolute base the token-count delta lacks. `null` = not recorded. Counts only. |
-| `session_tier` | string \| null | **Cost-% extension.** The orchestrator's OWN tier — the baseline the downshift cost-% measures `tier_chosen` against (a `high`→`lite` downshift is a rate win the token count can't see). `null` = not recorded. |
+| `session_tier` | string \| null | **Cost-% extension.** The orchestrator's OWN tier — the baseline the downshift cost-% measures `tier_chosen` against (a `high`→`lite` downshift is a rate win the token count can't see). The capture hook reads it off the model of the head's latest assistant call in its own transcript tail. `null` = not recorded. |
 | `first_pass_success` | bool \| null | **QUALITY extension (council verdict: quality × cost paired).** `true` = the subagent return was adopted without parent rework; `false` = the parent had to rework the return before adopting. Precise rework definition: § Operationalization below. `null` = pre-extension line / not measured. Boolean only, no bodies. |
 | `escalated` | bool \| null | **QUALITY extension (council verdict: quality × cost paired).** `true` = the slice was retried on a higher tier after a verification failure; `false` = no escalation. Semantics: § Operationalization below. `null` = pre-extension line / not measured. Boolean only, no bodies. |
 | `init_tokens` | int \| null | **Lean-init extension (road-to-lean-agent-init Phase 3).** Spawn-payload tokens at worker init — the payload-truth measurement feeding the Phase-5 baseline gate (p95 < ~1,500 tokens/worker drops the L2/L3 bets). `null` = not measured. Counts only. |
@@ -71,8 +71,14 @@ v1 forward-compat rule on unknown fields).
 | `floor_provenance` | enum \| null | **Dispatch-economy extension.** Provenance of the `init_tokens`/`work_tokens` pair: `measured` (transcript ledger) · `estimated`. Auto-defaults to `estimated` when either field is present untagged — mirrors `token_delta_provenance`. `null` = neither field present. |
 | `model_requested` | string \| null | **Served-model-truth extension (`inbox-harvest-2026-08-b-ledger-truth` Phase 1).** The model id that was ASKED for — the id `tier_chosen`, `tier_source`, `session_tier` and the downshift cost-% are all derived from. `null` = not recorded. Id only, never free-form. |
 | `model_served` | string \| null | **Served-model-truth extension.** The model id the provider reported ANSWERING with. `''`/`null` when the transport reports none (every CLI client) — absent is the honest value, not a defect. Attribution only: never route or tier on it. |
-| `model_divergent` | bool \| null | **Served-model-truth extension.** DERIVED, never supplied: `true` when both ids are present and differ (an alias or provider substitution — every tier-derived figure on this line attributes to a model that never ran), `false` when both are present and match. `null` when either is absent, because a comparison that never happened must not read as "checked, and they matched". |
+| `model_divergent` | bool \| null | **Served-model-truth extension.** DERIVED, never supplied: a requested family alias (`haiku`, `sonnet`, `opus`, `fable`) matches any served id of that family; otherwise `true` when both ids are present and differ (an alias or provider substitution — every tier-derived figure on this line attributes to a model that never ran), `false` when both are present and match. `null` when either is absent, because a comparison that never happened must not read as "checked, and they matched". |
 | `return_channel_chars` | int \| null | **Dispatch-economy extension (Phase 6.3).** Serialized chars of the tool result returned into the orchestrator context (sync completions, hook-derived count — content never enters the record). Detector for "isolation win refunded through the return channel"; committed cap: `MAX_ENVELOPE_CHARS` (12,000) via `return_channel` in `dispatch-economy-metrics.json`. `null` = async ack. |
+| `hand_kind` | enum \| null | **Free-hands extension.** The typed kind a rung-0.5 hand was asked to do: `classify` · `extract` · `summarise-given-text` · `draft-candidate` · `test-candidates` · `finding-proposal`. `null` = an untyped ask or a spawn. |
+| `schema_valid` | bool \| null | **Free-hands extension.** Whether the hand's return matched its kind's JSON schema. `false` is a failed call (`ask_transport` exits 3), never a partial answer. `null` = untyped. |
+| `route_billing` | enum \| null | **Free-hands extension.** How the route that served the call is paid for: `free-quota` · `self-hosted` · `per-token` · `subscription`. `null` = not a routed ask. |
+| `verified` | enum \| null | **Free-hands extension.** The head's verdict on the hand's return: `pass` · `fail` · `skipped`. REQUIRED when `route_billing` is `free-quota` or `self-hosted` — such a line without it fails validation. `ask_transport` writes `skipped` (or `fail` for a schema mismatch); the head records its own verdict as a second line under the same `work_id` with `--phase verify`. |
+| `verify_tokens` | int \| null | **Free-hands extension.** Tokens the head itself spent verifying the return — the quantity paid-limit relief is measured net of. Counts only. |
+| `counts_as_escalation` | bool \| null | **Free-hands extension.** DERIVED, never supplied: `true` when an unpaid route's return was recorded `skipped`, so not checking can never look cheaper than checking. `null` = no `route_billing`. |
 
 These routing + cost fields are additive and optional — a line without them is
 still a valid orchestration line; readers ignore unknown fields per the v1
@@ -152,7 +158,8 @@ conformant audit-log-v1 line from the counts you already have:
 ```bash
 ./scripts-run src/scripts/orchestration_record --spawn-count <n> \
   --token-delta <±n> --provenance measured|estimated \
-  [--tier-chosen lite|medium|high] [--tier-source static|inferred|inherit] \
+  [--tier-chosen lite|medium|high --model-requested <id|alias>] [--model-served <id>] \
+  [--tier-source static|inferred|inherit] [--session-tier <tier>] \
   [--task-class <id>] [--tiers a,b] [--dispatch-outcome DONE|BLOCKED|…] \
   [--first-pass-success true|false] [--escalated true|false]
 ```