pi-crew 0.11.24 → 0.11.26

package/{workflows/chain.workflow.md → docs/chain-workflow.md}

@@ -6,6 +6,14 @@ topology: dynamic
 
 # Chain Workflow - Sequential execution with context passing
 
+> **This file is DOCUMENTATION, not a runnable workflow (R28-M1 / wave-6 M3-24).**
+> It lives in `docs/` because the framework discovers every
+> `workflows/*.workflow.md` as a workflow resource; as a doc it parsed to 10
+> phantom steps (its prose headings) and the advertised `chain` workflow could
+> never run. Chain execution is implemented by the chain runner
+> (`src/runtime/chain-runner.ts` + `src/extension/team-tool/chain-dispatch.ts`);
+> there is no `chain` workflow resource.
+
 **Source:** pi-boomerang integration plan  
 **Syntax:** `step1 -> step2 -> step3`  
 **Version:** 1.0.0

package/docs/dynamic-workflows.md

@@ -275,6 +275,29 @@ script can reach `process`/`require` directly or via constructor walking. The
   (e.g. `require('child'+'_process')`, `globalThis.process.mainModule.require`).
   The real boundary is commit-review + the path-allowlist, not the content check.
 
+### Project-sourced workflows are DEFAULT-DENY (F-01)
+
+`.dwf.ts` files that resolve to a **project** source (`.crew/workflows/`,
+`<proj>/.pi/teams/workflows/`) are refused at run time unless you explicitly opt
+in with the env var `PI_CREW_TRUST_PROJECT_DWF=1`
+(`src/runtime/goal-workflow/dynamic-workflow-runner.ts:189`). The rejected run
+emits a `dwf.trust_denied` event and throws before the script is loaded:
+
+```text
+Project dynamic workflow requires explicit trust. Set PI_CREW_TRUST_PROJECT_DWF=1
+```
+
+The gate compares against the literal string `"1"` — `true`, `yes`, or `on` all
+FAIL closed. Cloning a repo and running its workflow is otherwise arbitrary code
+execution, hence the opt-in.
+
+**Scope of the gate (honest):** only `source === "project"` is gated. **Builtin**
+workflows and **user-scope** workflows (`~/.pi/agent/extensions/pi-crew/workflows/`)
+proceed with **no** trust prompt — they run as ordinary trusted local code. The
+`PI_CREW_TRUST_PROJECT_DWF` gate is therefore not a blanket guarantee that every
+`.dwf.ts` you execute was reviewed: it protects against *repo-supplied* authoring,
+not against user-scope authoring.
+
 ## Determinism (round-13 P0-2)
 
 Dynamic workflow scripts must be **deterministic** — the runner rejects

package/docs/publishing.md

@@ -24,8 +24,8 @@ Before publishing to npm:
 npm run check
 ```
 
-For a fast pre-publish smoke (97 broker/UI/config tests in ~20s, instead
-of the full ~6,500-test `npm run check` which takes minutes):
+For a fast pre-publish smoke (124 broker/UI/config tests in ~15s, instead
+of the full `npm run check` unit+integration suite, which takes minutes):
 
 ```bash
 npm run test:critical && npm run typecheck && npm run build:bundle
@@ -94,7 +94,7 @@ lockfile drift):
 - **push to `refs/heads/main`** — `check:conflict-markers` + `typecheck`,
   then the **FULL unit suite** (`npm run test:unit`, the same gate CI
   runs). Any failure blocks the push. This closes the 2026-10 gap where
-  local pushes ran only `test:critical` (~120 tests) while CI ran the full
+  local pushes ran only `test:critical` (124 tests) while CI ran the full
   suite — three waves shipped red that way.
 - **push to any other ref** — fast gates only (`check:conflict-markers` +
   `typecheck`).
@@ -128,8 +128,37 @@ The package exports:
 ./schema.json
 ```
 
-Use this for editor validation of:
+Use this for editor validation of the **current** config path
+(`src/config/config.ts:208`; the `~/.pi/agent/extensions/pi-crew/config.json`
+path is legacy/read-only-for-migration — see `docs/usage.md`):
 
 ```text
-~/.pi/agent/extensions/pi-crew/config.json
+~/.pi/agent/pi-crew.json
 ```
+
+## Known tarball / consumer-side notes (R26/R29 census, 2026-10-19)
+
+Verified with `npm pack --dry-run`. These are **declared defects**, not hidden:
+
+- **`skills/research/scripts/__pycache__/safe_io.cpython-312.pyc` ships** in the
+  tarball (11.5 kB): the `files` entry `"skills/**"` plus the missing
+  `.npmignore` rule means compiled Python bytecode is published and it embeds
+  build-machine paths. Fix = add `__pycache__` to a `.npmignore` / tighten
+  `files`.
+- **Dev tooling ships to consumers:** `scripts/analyze-run.mjs` (64.5 kB),
+  `scripts/resource-sampler.mjs`, `scripts/watch-agent-transcript.mjs`. Harmless
+  bulk; consider moving them behind a dev-only entry.
+- **Consumer-side git hooks reference scripts that are NOT published:**
+  `scripts/install-hooks.mjs` (published) sets `core.hooksPath=.githooks`, and
+  `.githooks/pre-commit` runs `node scripts/check-lockfile-sync.mjs` — but
+  `files[]` ships neither `scripts/check-lockfile-sync.mjs` nor
+  `scripts/test-runner.mjs`, so an installed-from-npm consumer's hook fails.
+- **Peer range on `pi-coding-agent` is unbounded** (`>=1.0.4`, no ceiling) while
+  the `pi-tui` peer IS bounded (`<2.0.0`); pi-crew consumes pi-tui symbols
+  re-exported through `pi-coding-agent`, so a future 2.x installs clean and fails
+  at load (R49-F2 — bounding it is prospective work).
+- **Committed `dist/` must match the tag:** the `--committed-hash` gate reads the
+  committed blob (`dist/index.mjs` — the ONLY tracked dist artifact) from the git
+  object DB, so every commit that touches `src/` needs
+  `npm run build:bundle && git add -f dist/index.mjs` rerun and committed
+  (`dist/` is `.gitignore`d, hence `-f`).

package/docs/troubleshooting.md

@@ -18,8 +18,11 @@ run/process status. Start here.
 **Symptom:** `team action='run'` returns a `blocked` status with a message like
 "Child worker execution is disabled".
 
-**Cause:** Worker execution is off. pi-crew refuses to create no-op scaffold
-subagents by default until you opt in.
+**Cause:** Worker execution is off. When `executeWorkers` is **explicitly**
+`false` (or `PI_CREW_EXECUTE_WORKERS=0`), pi-crew refuses to create no-op
+scaffold subagents and returns `blocked`. Note the default is the **opposite**:
+child-worker execution is enabled by default
+(`src/extension/team-tool/run.ts:205`).
 
 **Fix — pick one:**
 - Set in your config (`~/.pi/agent/pi-crew.json`): `"executeWorkers": true`
@@ -149,6 +152,51 @@ code + a help hint inline. Common ones:
 | E012 | RunStale | run reconciled as stale | see "Stale async process" above |
 | E013 | ModelOutOfScope | requested model not in pi's `enabledModels` allowlist | pick a model listed in `enabledModels` (settings.json) or disable `reliability.scopeModels` |
 
+## Doctor says OK but the run is dead (doctor blind spots, R48)
+
+`team action='doctor'` is a **liveness sanity check, not a watchdog**. The
+deep-review health/status/doctor census (round 48) found these classes are
+**NOT** detected — status/health can print `running` for a dead host:
+
+| Class | Why it is missed | What to do |
+|---|---|---|
+| Host process dead, manifest frozen `running` | orphan detection keys on updatedAt/magic-string heuristics (`src/runtime/process-status.ts`) | check the host pid yourself; `team action='cancel'` then re-run |
+| Disk full (`ENOSPC`) | no free-space probe in doctor | `df -h` the state root / TMPDIR |
+| Bad state-file permissions (`EACCES`) | reads may classify as unreadable, not as a doctor failure | `ls -l <crewRoot>/state/runs/*` |
+| Orphaned worker processes (reparented to PID 1) | only reaped when a run is reconciled | `ps -ef \| grep ' pi '`, then `team action='cleanup'` |
+| Broken `node_modules` / missing `pi` resolve | spawn succeeds, worker dies instantly | run `pi --version` in the run cwd |
+
+Only two classes are reliably caught: stale broker socket and orphan mux pane.
+Treat a green `doctor` as "no *known* problem", not as "the run is alive".
+
+## Debug logging: `PI_CREW_DEBUG` / `PI_TEAMS_DEBUG` are TRUTHY, not "=1" (R45-F4)
+
+Internal debug logging (`logInternalError(..., "debug")`, `src/utils/internal-error.ts:10`)
+is gated on a raw truthiness check, so **any non-empty value enables it** —
+including `PI_CREW_DEBUG=0`, `PI_TEAMS_DEBUG=false`, and `PI_TEAMS_DEBUG=off`.
+To actually silence debug output, **unset** the variable (do not set it to `0`).
+
+## Mux surfaces (tmux / herdr) — known sharp edges (R42)
+
+`runtime.surface.mode: 'tmux' | 'herdr'` (default `auto`) runs tier-1 workers in
+real mux panes. Live-probed known limits:
+
+- **Panic characters in commands:** tmux `send-keys -l` swallows a trailing `\n`,
+while herdr `pane.send_text` treats `\n` as Enter — a boot line containing a
+newline would be split/executed early. pi-crew's own callers pass
+shell-escaped single-line paths, so this is latent, not live.
+- **Pane/tab ids are not regex-validated before `-t`:** a malformed id in a
+manifest (`kill-pane -t "-x"`) can act on the *wrong* pane (today every path is
+liveness-gated, so it is defence-in-depth, not an open hole).
+- **`capture-pane -p` trims trailing spaces** (cosmetic; only feeds doctor
+liveness).
+- **No tmux minimum-version gate:** old tmux silently falls back to a two-strike
+headless degrade.
+- **herdr is an external socket daemon** — pi-crew never spawns it, and the
+server-wide subscription (no pane filter) amplifies traffic.
+- Pane ids are unique only within one mux server lifetime; a stale manifest can
+name an id now owned by an unrelated pane.
+
 ## Still stuck
 
 - `team action='explain' runId=…` — structured per-task analysis (why, files,

package/docs/usage.md

@@ -42,7 +42,7 @@ Supported fields:
     "requirePlanApproval": false
   },
   "ui": {
-    "widgetPlacement": "aboveEditor",
+    "widgetPlacement": "bottom",
     "widgetMaxLines": 8,
     "powerbar": true,
     "dashboardPlacement": "right",
@@ -239,6 +239,12 @@ Dirty worktrees are preserved unless `force: true` is provided.
 
 ## Slash commands
 
+> **`/team-cleanup <runId>` does not exist** (R27-D1). The registered commands
+> are `/team-manager` (and its alias `/team-cleanup-menu`) — runId-targeted
+> cleanup is the `cleanup` action on the `team` tool (`team action='cleanup'
+> runId=…`). Only `team-cleanup-menu` is registered
+> (`src/extension/registration/commands/manage.ts:99-107`).
+
 ```text
 /teams
 /team-run default "Implement login with tests"
@@ -251,7 +257,6 @@ Dirty worktrees are preserved unless `force: true` is provided.
 /team-events team_...
 /team-artifacts team_...
 /team-worktrees team_...
-/team-cleanup team_...
 /team-forget team_... --confirm
 /team-export team_...
 /team-import .crew/artifacts/team_.../export/run-export.json   # or .pi/teams/artifacts/... on legacy layout

package/install.mjs

@@ -13,7 +13,8 @@ const legacyConfigPath = path.join(agentDir, "extensions", "pi-crew", "config.js
  * Default config written to `~/.pi/agent/pi-crew.json` on fresh installs.
  *
  * WI-1b.2 (G17): this object is intentionally an embedded literal — install.mjs
- * runs under bare `node` as the `pi-crew` bin (engines floor is >=22.0.0; .ts
+ * runs under bare `node` as the `pi-crew` bin (engines floor is >=22.19.0 — the
+ * pre-R29-F3 comment said >=22.0.0; .ts
  * imports would require >=22.18 or `--experimental-strip-types`, which the npm
  * bin shim cannot pass). Runtime jiti/esbuild loading was rejected as a
  * postinstall failure surface; build-time codegen would need package.json /

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.24",
+	"version": "0.11.26",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",
@@ -57,6 +57,7 @@
 		"docs/troubleshooting.md",
 		"docs/usage.md",
 		"docs/architecture.md",
+		"docs/chain-workflow.md",
 		"docs/dynamic-workflows.md",
 		"docs/resource-formats.md",
 		"docs/publishing.md",
@@ -116,6 +117,7 @@
 		"smoke:pi": "pi install .",
 		"smoke:release": "node scripts/release-smoke.mjs",
 		"prepack": "node scripts/clean-strip-types.mjs",
+		"prepublishOnly": "npm run ci",
 		"test:fast": "npm run test:critical && npm run test:bundle",
 		"check:wc-gate": "node scripts/wc-gate.mjs"
 	},
@@ -136,7 +138,7 @@
 	"peerDependencies": {
 		"@earendil-works/pi-agent-core": ">=1.0.4",
 		"@earendil-works/pi-ai": ">=1.0.4",
-		"@earendil-works/pi-coding-agent": ">=1.0.4",
+		"@earendil-works/pi-coding-agent": ">=1.0.4 <2.0.0",
 		"@earendil-works/pi-tui": ">=1.0.4 <2.0.0",
 		"@sinclair/typebox": "*"
 	},

package/skills/read-only-explorer/SKILL.md

@@ -17,11 +17,21 @@ triggers:
 
 Use this skill for explorer, analyst, reviewer, and source-audit roles. These roles must inspect code without modifying it.
 
+> **Tool availability (enforced — R27-D6).** `explorer` (and `librarian`) ship
+> **without a `bash` tool**: `src/config/role-tools.ts:25-29` sets
+> `tools: ["read", "grep", "find", "ls", "glob", "ask"]` +
+> `excludeTools: ["edit", "write", "bash", "web"]`. The shell syntax below
+> (`rg …`, `find …`, `git status`) is therefore **reference syntax for the
+> intent**, not runnable in an explorer session. Map each example to the tool you
+> actually have: `rg` → `grep`, `find`/shell globbing → `find`/`glob`,
+> `ls` → `ls`, `cat`/`sed -n` → `read` (with offset/limit). `analyst`/`reviewer`
+> roles keep `bash` (`role-tools.ts:33-35`, `:64-68`) — the restriction is per-role.
+
 ## Core Contract
 
 1. **Do not edit files** — no write, no edit, no delete
 2. **Do not write generated artifacts** outside the run artifact directory
-3. **Prefer read-only commands**: `read`, `rg`, `find`, `ls`, `git status`
+3. **Prefer read-only tools**: `read`, `grep`, `find`, `ls`, `glob` (explorer has no shell — see the note above)
 4. **Record exact files inspected** — include path and relevant line numbers
 5. **Distinguish direct evidence from inference** — don't guess
 6. **If implementation is needed, recommend** — don't modify code
@@ -242,10 +252,10 @@ If ANY answer is NO → Stop. Adhere to read-only contract.
 
 ## Source patterns
 
-- `src/runtime/task-runner.ts` — task execution pipeline
-- `src/runtime/child-pi.ts` — worker spawning
-- `src/runtime/live-agent-manager.ts` — live agent lifecycle
-- `src/state/event-log.ts` — event logging system
+- `src/runtime/task-runner.ts` + `src/runtime/task-runner/` — task execution pipeline
+- `src/runtime/child-pi/` — worker spawning
+- `src/runtime/live-session/live-agent-manager.ts` — live agent lifecycle
+- `src/state/event-log/` — event logging system
 - `src/extension/team-tool/` — API and tool handling
 - `src/ui/` — widget and TUI rendering
 

package/skills/real-test-pi-crew/SKILL.md

@@ -275,7 +275,7 @@ To add Tier 1 to CI as a fast-feedback gate (under 30s):
 
 ---
 
-## Tier 1 — Critical unit tests (~19s, 120 tests, the only suite you need for broker/UI changes)
+## Tier 1 — Critical unit tests (~13s, 124 tests, the only suite you need for broker/UI changes)
 
 **What**: run the curated 15-file fast subset.
 
@@ -287,7 +287,7 @@ To add Tier 1 to CI as a fast-feedback gate (under 30s):
 time npm run test:critical
 ```
 
-Expected output: `# tests 120 # pass 120 # fail 0 # cancelled 0 # duration_ms ~19965`. (Count was 97 at v0.9.46, 101 at v0.9.66, 102 at the waitMethodsEnabled flip, 116 since 2026-09-20, **120 @ 2026-10-07** (+`child-executor-heartbeat-pulse.test.ts` → 15 files) — verify with the actual run; the skill's hard-coded numbers drift between releases.) **Since RR-021 round-2 the runner itself fails loudly on `# cancelled N>0`** (dual-reporter TAP scrape — the round-1 unref incident shipped green with 2 cancelled tests), and **round-3 added the missing-file pre-check**: an explicitly-listed file that does not exist now exits 1 naming the path instead of being silently skipped by node:test.
+Expected output: `# tests 124 # pass 124 # fail 0 # cancelled 0 # duration_ms ~12800`. (Count was 97 at v0.9.46, 101 at v0.9.66, 102 at the waitMethodsEnabled flip, 116 since 2026-09-20, 120 @ 2026-10-07, **124 @ 2026-10-18** (+`child-executor-heartbeat-pulse.test.ts` → 15 files) — verify with the actual run; the skill's hard-coded numbers drift between releases.) **Since RR-021 round-2 the runner itself fails loudly on `# cancelled N>0`** (dual-reporter TAP scrape — the round-1 unref incident shipped green with 2 cancelled tests), and **round-3 added the missing-file pre-check**: an explicitly-listed file that does not exist now exits 1 naming the path instead of being silently skipped by node:test.
 
 **References**:
 
@@ -327,7 +327,7 @@ PI_CREW_BROKER=0 npm run test:critical
 PI_CREW_BROKER=1 npm run test:critical
 ```
 
-All three must show `# pass 120 # fail 0`. Measured times in this session (2026-08-11): ~26s for default, ~26s for `PI_CREW_BROKER=0`, ~26s for `PI_CREW_BROKER=1` (varies ±1-2s run-to-run).
+All three must show `# pass 124 # fail 0`. Measured times in this session (2026-08-11): ~26s for default, ~26s for `PI_CREW_BROKER=0`, ~26s for `PI_CREW_BROKER=1` (varies ±1-2s run-to-run).
 
 **References**:
 
@@ -609,7 +609,7 @@ If the two md5s match → session is on the latest code. If not → user must `/
 
 **What**: drive the team tool + subagent tools through a spread of actions from the parent Pi session to prove the full surface works end-to-end, not just one smoke run.
 
-**Why this exists**: Tier 7 proves one team run completes. But pi-crew has **55 `team` actions across 5 domain dispatchers** (`RUN` 10: run/parallel/plan/plans/orchestrate/resume/retry/wait/steer/goal · `STATUS` 16: status/list/get/events/artifacts/summary/graph/search/health/worktrees/checkpoint/cache/explain/onboard/recommend/help · `CONTROL` 7 · `MANAGE` 16 · `AUTOMATE` 6 — `src/schema/team-tool-schema.ts:391-437`) plus the subagent tools (`Agent`, `crew_agent`, `get_subagent_result`, `steer_subagent` — with `crew_agent_result`/`crew_agent_steer` aliases), the worker-side tools (`ask`, `delegate`, `message`), and the `team-settings` config surface, dispatched through several code paths (sync run, async run, chain, parallel, direct subagent). A schema or registration regression can break *some* paths while others still pass. The battery catches path-specific breakage.
+**Why this exists**: Tier 7 proves one team run completes. But pi-crew has **57 `team` actions across 5 domain dispatchers** (`RUN` 10: run/parallel/plan/plans/orchestrate/resume/retry/wait/steer/goal · `STATUS` 17: status/list/get/events/artifacts/breakdown/summary/graph/search/health/worktrees/checkpoint/cache/explain/onboard/recommend/help · `CONTROL` 7 · `MANAGE` 17 · `AUTOMATE` 6 — `src/schema/team-tool-schema.ts:437-489`) plus the subagent tools (`Agent`, `crew_agent`, `get_subagent_result`, `steer_subagent` — with `crew_agent_result`/`crew_agent_steer` aliases), the worker-side tools (`ask`, `delegate`, `message`), and the `team-settings` config surface, dispatched through several code paths (sync run, async run, chain, parallel, direct subagent). A schema or registration regression can break *some* paths while others still pass. The battery catches path-specific breakage.
 
 **When required**: any change to `src/schema/team-tool-schema.ts`, `src/extension/registration/team-tool.ts`, `src/extension/team-tool/*.ts` (handler dispatch), or the subagent-tool registration. Optional but cheap for any change — the read-only actions are free.
 
@@ -1383,7 +1383,7 @@ Use this to answer "đủ full tính năng chưa?" without re-deriving. Every us
 
 | Feature | Code entry | Verify via |
 |---|---|---|
-| Team tool — 56 actions / 5 domains | `src/schema/team-tool-schema.ts:391-437`, dispatch in `src/extension/team-tool/` | 9a (read-only) + 9b/9c/9d/9e/9f theo domain |
+| Team tool — 57 actions / 5 domains | `src/schema/team-tool-schema.ts:437-489`, dispatch in `src/extension/team-tool/` | 9a (read-only) + 9b/9c/9d/9e/9f theo domain |
 | Runtime mode `child-process` (default) | `src/runtime/child-pi/` | 9b sync run + T7 |
 | Runtime mode `scaffold` (dry-run) | `src/runtime/task-runner/pre-execution.ts:176` | 9b `action='plan'`/`'plans'` (preview không spawn) hoặc run với `runtime.mode='scaffold'` |
 | Runtime mode `live-session` (experimental) | `src/runtime/live-session/` | Run với `runtime.mode='live-session'` + irc tool xuất hiện trong worker (`src/runtime/custom-tools/irc-tool.ts`) |
@@ -1464,7 +1464,7 @@ The skill does NOT need to be updated for every commit — only when the cited l
 ## Quick reference — exact commands
 
 ```bash
-# Tier 1 (critical unit, ~19s, 120 tests)
+# Tier 1 (critical unit, ~13s, 124 tests)
 npm run test:critical
 # Tier 2 (3-path proof, broker changes only)
 PI_CREW_BROKER=0 npm run test:critical
@@ -1548,7 +1548,7 @@ PY
 
 Before claiming "tested":
 
-- [ ] Tier 1: `test:critical` fresh-run, all pass (<25s). Count varies by release — was 97 at v0.9.46, 101 at v0.9.66, 102 at the waitMethodsEnabled flip, 116 @ 2026-09-20, **120 @ 2026-10-07**; record the actual count in the report.
+- [ ] Tier 1: `test:critical` fresh-run, all pass (<25s). Count varies by release — was 97 at v0.9.46, 101 at v0.9.66, 102 at the waitMethodsEnabled flip, 116 @ 2026-09-20, 120 @ 2026-10-07, **124 @ 2026-10-18**; record the actual count in the report.
 - [ ] Tier 2: 3-path proof all pass — **required if you touched `src/config/defaults.ts` or `src/extension/registration/lifecycle-handlers.ts`**
 - [ ] Tier 3: `npm run typecheck` exit 0, `npm run build:bundle` exit 0
 - [ ] Tier 4: bundle md5 matches what the session loaded (or user has `/quit`-ed + reopened)

package/src/config/config-validation.ts

@@ -110,6 +110,64 @@ export const DANGEROUS_OBJECT_KEYS = new Set([
 	"__lookupSetter__",
 ]);
 
+/**
+ * Case-normalized view of DANGEROUS_OBJECT_KEYS. The canonical set keeps the
+ * real member spellings (toString, valueOf, …), but key matching must be
+ * lowercase on BOTH sides — `"valueOf".toLowerCase()` is `"valueof"`, which
+ * would never match a camelCase entry.
+ */
+const DANGEROUS_KEYS_LOWER = new Set([...DANGEROUS_OBJECT_KEYS].map((key) => key.toLowerCase()));
+
+/**
+ * True when `key` collides with a reserved Object.prototype member.
+ * Case-insensitive to catch `__Proto__`, `CONSTRUCTOR`, `TOSTRING`, etc.
+ */
+export function isDangerousKey(key: string): boolean {
+	return DANGEROUS_KEYS_LOWER.has(key.toLowerCase());
+}
+
+/**
+ * True when ANY dot-separated segment of a dotted config path collides with a
+ * reserved Object.prototype member. This is the guard for dotted-path walkers
+ * (setNested/unsetPath): it catches the NESTED pollution vectors
+ * `__proto__.polluted` and `constructor.prototype.x` that single-key checks
+ * miss, because the walk hits `obj["__proto__"]` (the [[Prototype]] getter)
+ * long before the final segment is written.
+ */
+export function isDangerousPath(dottedPath: string): boolean {
+	return dottedPath.split(".").some((segment) => segment.length > 0 && isDangerousKey(segment));
+}
+
+/**
+ * Deeply strip dangerous prototype-pollution keys from an arbitrary value
+ * (objects, arrays, primitives pass through). Returns a fresh plain-object
+ * tree that is safe to merge/assign at a parse boundary.
+ *
+ * M1-1 shared boundary contract: every boundary that accepts a user-supplied
+ * config patch, dotted key, or translation registration (team-settings
+ * set/unset, updateConfig unsetPaths, config/autonomy patch parsing, i18n
+ * addTranslations) routes through isDangerousPath/isDangerousKey/
+ * stripDangerousKeysDeep here — ONE canonical drop rule. This is
+ * BOUNDARY-LEVEL defense only; it must not grow handler-specific predicates:
+ * carrier keys of tool payloads (`args`, `scope`, `unset`, …) are
+ * intentionally NOT dangerous keys — never add them (RT24-F1 lesson: mirrored
+ * handler predicates drifted and over-blocked reads).
+ *
+ * Case-insensitive superset of the retired per-module strippers (which covered
+ * only `__proto__`/`constructor`/`prototype` case-sensitively): this drops the
+ * full DANGEROUS_OBJECT_KEYS set at every level.
+ */
+export function stripDangerousKeysDeep<T>(value: T): T {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map((item) => stripDangerousKeysDeep(item)) as T;
+	const safe: Record<string, unknown> = {};
+	for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+		if (isDangerousKey(key)) continue;
+		safe[key] = stripDangerousKeysDeep(child);
+	}
+	return safe as T;
+}
+
 /**
  * Strips dangerous Object.prototype keys from an object.
  * Returns a new object built with Object.create(null) to prevent

package/src/config/config.ts

@@ -6,7 +6,7 @@ import { withFileLockSync } from "../state/coordination/locks.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { isJunkPathLiteral, projectCrewRoot, projectPiRoot } from "../utils/paths.ts";
 import { mergeConfig } from "./config-merge.ts";
-import { parseConfig, parseConfigWithWarnings } from "./config-validation.ts";
+import { isDangerousKey, isDangerousPath, parseConfig, parseConfigWithWarnings } from "./config-validation.ts";
 import { DEFAULT_BROKER, DEFAULT_NESTING, DEFAULT_PERSISTENCE, resolveBrokerEnvOverride } from "./defaults.ts";
 import { getCrewEnv, getCrewEnvBool } from "./env-vars.ts";
 import { sanitizeProjectConfig } from "./sanitize-project-config.ts";
@@ -258,6 +258,13 @@ function resolvePersistenceEnvOverrideAndDefaults(parsed: PersistenceConfig | un
 }
 
 function unsetPath(record: Record<string, unknown>, dottedPath: string): void {
+	// R24-H2 (M1-1): walking a raw dotted key through `target["__proto__"]`
+	// resolves to Object.prototype via the [[Prototype]] getter, so a key like
+	// `__proto__.toString` DELETES Object.prototype members. Refuse dangerous
+	// segments at the walker itself (shared proto-safe helpers in
+	// config-validation.ts) — this covers
+	// every unsetPaths consumer (team-settings unset, team `config` action).
+	if (isDangerousPath(dottedPath)) return;
 	const parts = dottedPath.split(".").filter(Boolean);
 	if (parts.length === 0) return;
 	let target: Record<string, unknown> = record;
@@ -305,6 +312,66 @@ function measureJsonDepth(root: unknown): number {
 	return maxDepth;
 }
 
+/**
+ * M3-13 (R45-F1): `parseConfig` is a strict WHITELIST builder (see
+ * config-validation.ts) — it returns an object literal of known keys only, so
+ * merging a patch into `parseConfig(current)` and writing the result back
+ * silently DELETES every unknown on-disk key (typos, forward-compat keys
+ * written by a newer version, keys owned by another tool). updateConfig used
+ * to do exactly that on every write.
+ *
+ * This helper re-attaches the raw on-disk shape underneath the normalized
+ * merge result: `parsed` wins for every key/value it defines (so mergeConfig's
+ * per-key semantics and its sanitizers keep applying to known keys), while raw
+ * keys that the whitelist dropped are carried through untouched.
+ *
+ * Dangerous prototype keys are NEVER carried through (M1-1/R24-H1: the parse
+ * boundary drops `__proto__`/`constructor`/`prototype` at every depth).
+ *
+ * @param parsed  normalized merge result (what the whitelist understands)
+ * @param raw     raw on-disk record, already with `unsetPaths` applied
+ * @returns a new record shaped like the on-disk file, preserving key order
+ */
+function preserveUnknownKeys(parsed: Record<string, unknown>, raw: Record<string, unknown>): Record<string, unknown> {
+	const target = cloneRawRecord(raw, 0);
+	return overlayKnownKeys(target, parsed, 0);
+}
+
+const MAX_PRESERVED_DEPTH = 100;
+
+function isPlainRecordObject(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Depth-bounded clone that keeps raw key order and skips dangerous keys. */
+function cloneRawRecord(source: Record<string, unknown>, depth: number): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	if (depth > MAX_PRESERVED_DEPTH) return out;
+	for (const [key, value] of Object.entries(source)) {
+		if (isDangerousKey(key)) continue;
+		out[key] = isPlainRecordObject(value) ? cloneRawRecord(value, depth + 1) : value;
+	}
+	return out;
+}
+
+/** Overlay `source` (normalized) onto `target` (raw clone), recursing into shared objects. */
+function overlayKnownKeys(target: Record<string, unknown>, source: Record<string, unknown>, depth: number): Record<string, unknown> {
+	if (depth > MAX_PRESERVED_DEPTH) return target;
+	for (const [key, value] of Object.entries(source)) {
+		// `undefined` means "not set in this layer" (mergeConfig's withoutUndefined
+		// contract) — never write it over a preserved raw value.
+		if (value === undefined) continue;
+		if (isDangerousKey(key)) continue;
+		const existing = target[key];
+		if (isPlainRecordObject(value) && isPlainRecordObject(existing)) {
+			overlayKnownKeys(existing, value, depth + 1);
+			continue;
+		}
+		target[key] = value;
+	}
+	return target;
+}
+
 function readConfigRecord(filePath: string): Record<string, unknown> {
 	if (!fs.existsSync(filePath)) return {};
 	// Defense-in-depth: reject config files larger than 10 MB before parsing.
@@ -462,7 +529,11 @@ export function updateConfig(patch: PiTeamsConfig, options: UpdateConfigOptions
 			const message = error instanceof Error ? error.message : String(error);
 			throw new Error(`Could not update pi-crew config: ${message}`);
 		}
-		let merged = mergeConfig(parseConfig(current), patch);
+		const normalizedCurrent = parseConfig(current);
+		// Known-key semantics (per-key merge + otlp header sanitization) stay in
+		// mergeConfig — see M3-13 below for why the WRITE target is rebuilt from
+		// the raw record instead of from this whitelist-normalized result.
+		let merged = mergeConfig(normalizedCurrent, patch);
 		if (options.unsetPaths?.length) {
 			const raw = JSON.parse(JSON.stringify(merged)) as Record<string, unknown>;
 			for (const unset of options.unsetPaths) unsetPath(raw, unset);
@@ -472,12 +543,26 @@ export function updateConfig(patch: PiTeamsConfig, options: UpdateConfigOptions
 		// (e.g. `team action='config'` with an empty patch — read-only path).
 		// Both sides are parseConfig-normalized, so JSON.stringify key order is
 		// deterministic (same construction path); no key sorting needed.
-		const normalizedCurrent = parseConfig(current);
-		if (JSON.stringify(merged) === JSON.stringify(normalizedCurrent)) {
+		const normalizedUnchanged = JSON.stringify(merged) === JSON.stringify(normalizedCurrent);
+		// M3-13 (R45-F1): parseConfig is a whitelist, so writing `merged` erased
+		// every unknown on-disk key (typos, forward-compat keys). Rebuild the
+		// written shape from the RAW record: known keys take the merged value,
+		// unknown keys survive untouched. `unsetPaths` are applied to the raw
+		// base too, so an explicit unset of an unknown key still removes it.
+		const rawBase = cloneRawRecord(current, 0);
+		for (const unset of options.unsetPaths ?? []) unsetPath(rawBase, unset);
+		const toWrite = preserveUnknownKeys(merged as unknown as Record<string, unknown>, rawBase);
+		// An unsetPaths entry may name a key the whitelist cannot see (an unknown
+		// key), in which case the normalized comparison above reports "unchanged"
+		// even though the raw record must change. Only that case overrides the
+		// skip: if applying the unsets left the raw base byte-identical, nothing
+		// outside the whitelist moved and the legacy skip stands.
+		const unsetsChangedRaw = JSON.stringify(rawBase) !== JSON.stringify(current);
+		if (normalizedUnchanged && !unsetsChangedRaw) {
 			return { path: filePath, config: merged, written: false }; // unchanged — skip write
 		}
 		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		atomicWriteFile(filePath, `${JSON.stringify(merged, null, 2)}\n`);
+		atomicWriteFile(filePath, `${JSON.stringify(toWrite, null, 2)}\n`);
 		// (F16) Invalidate the loadConfig cache after a write — the next
 		// caller must see the new value, not a 0-2s stale snapshot.
 		invalidateConfigCache();

package/src/config/env-vars.ts

@@ -277,7 +277,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	},
 	PI_CREW_DEBUG: {
 		name: "PI_CREW_DEBUG",
-		doc: "truthiness enables background debug logging (background-runner.ts:63)",
+		doc: "truthiness enables background debug logging (background-runner.ts:63); RAW truthiness — '0'/'false' still ENABLE, unset to disable (R45-F4)",
 	},
 	PI_CREW_DEBUG_BUDGET: {
 		name: "PI_CREW_DEBUG_BUDGET",
@@ -371,7 +371,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	},
 	PI_CREW_TRUST_PROJECT_DWF: {
 		name: "PI_CREW_TRUST_PROJECT_DWF",
-		doc: "'1' allows project-sourced .dwf.ts workflows (dynamic-workflow-runner.ts:154)",
+		doc: "'1' allows project-sourced .dwf.ts workflows (dynamic-workflow-runner.ts:189)",
 	},
 	PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS: {
 		name: "PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS",
@@ -380,7 +380,7 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 	},
 	PI_TEAMS_DEBUG: {
 		name: "PI_TEAMS_DEBUG",
-		doc: "truthiness gates debug-severity internal-error logging (internal-error.ts:4)",
+		doc: "truthiness gates debug-severity internal-error logging (internal-error.ts:10); RAW truthiness — '0'/'false' still ENABLE, unset to disable (R45-F4)",
 	},
 	PI_TEAMS_MOCK_CHILD_PI: {
 		name: "PI_TEAMS_MOCK_CHILD_PI",
@@ -766,18 +766,25 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
  * Raw crew-env lookup. Returns the raw string (undefined when unset) with
  * mirror-alias fallback applied per the entry's `mirrorPrecedence`. This is
  * the behavior-preserving replacement for `process.env.PI_CREW_X` reads.
+ *
+ * R26-F1 (deep-review round 26): `env` is an OPTIONAL source override. Reads
+ * that receive an env object as a parameter (`isRootSession(env)`,
+ * `currentCrewDepth(env)`, …) must still route through the registry — passing
+ * the object here keeps the registry invariant intact for those sites instead
+ * of leaving them as gate-blind `env.PI_CREW_X` dot reads. Defaults to
+ * `process.env`, so existing call sites are unchanged.
  */
-export function getCrewEnv(name: string): string | undefined {
+export function getCrewEnv(name: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
 	const spec = CREW_ENV_VARS[name];
 	if (!spec?.mirror || spec.mirrorPrecedence === "or") {
-		return process.env[name];
+		return env[name];
 	}
 	const crewName = name.startsWith("PI_TEAMS_") ? spec.mirror : name;
 	const teamsName = name.startsWith("PI_TEAMS_") ? name : spec.mirror;
 	if (spec.mirrorPrecedence === "teams") {
-		return process.env[teamsName] ?? process.env[crewName];
+		return env[teamsName] ?? env[crewName];
 	}
-	return process.env[crewName] ?? process.env[teamsName];
+	return env[crewName] ?? env[teamsName];
 }
 
 /**

package/src/config/role-tools.ts

@@ -27,9 +27,11 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
-	// Analyst - Read and analyze, limited execution
+	// Analyst - Read and analyze, limited execution. (ask_question removed
+	// 2026-10-18: the host tool is `ask` — excluding a nonexistent name was a
+	// dead entry; the live `ask` tool stays allowed for analyst.)
 	analyst: {
-		excludeTools: ["edit", "write", "ask_question"],
+		excludeTools: ["edit", "write"],
 	},
 
 	// Planner - Read-only planning; emits plans as TEXT (runner persists result).
@@ -41,7 +43,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// default/implementation workflows.
 	planner: {
 		tools: ["read", "grep", "find", "ls", "glob", "ask"],
-		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
+		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
 	// Critic - Read-only plan/design critique (F2: was missing from the map,
@@ -67,7 +69,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// Writer - Documentation focused
 	writer: {
 		tools: ["read", "edit", "write", "ls", "ask"],
-		excludeTools: ["bash", "web", "ask_question"],
+		excludeTools: ["bash", "web"],
 	},
 
 	// Security Reviewer - Strict restrictions
@@ -76,7 +78,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// resolved at runtime (returned {}), silently dropping enforcement.
 	"security-reviewer": {
 		tools: ["read", "grep", "find", "ask"],
-		excludeTools: ["edit", "write", "bash", "web", "ask_question"],
+		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
 	// Verifier - Runs tests (needs bash) but must NOT edit source (F4: moved