pi-crew 0.9.68 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,130 @@
 
 > **Note:** `atomic-write-v2.ts` / `AtomicWriter` mentioned in historical entries below was consolidated into `atomic-write.ts` as of v0.9.42. This changelog is preserved as historical record — the migration was completed (the v2 class was never adopted; v1 won on simplicity + symlink-safety + link+unlink atomicity). See `docs/migration/atomic-write-v2-migration.md` for the decision rationale.
 
+## [0.10.1] — subagent v2: governed delegation, plan objects, spec system, transparency (2026-08-20)
+
+The full subagent-v2 effort (design `docs/design/subagent-v2-design.md`, plan
+`docs/design/subagent-v2-implementation-plan.md`) shipped as ONE release.
+Trains T1-T5 merged as internal phases (PRs #47-#51); batteries B1-B5 in
+`docs/real-test/reports/`. ADRs: governed-nesting, plan-object,
+waiting-producer-ask, spec-system (+ round-1 errata).
+
+### T1 — waiting/ask producer + session surface
+- Ask tool (worker→leader blocking questions; parked `waiting` tasks,
+  structured events `ask.requested/answered/timedout`), follow-up
+  notifications, session-ownership map.
+
+### T2 — plan object (ADR-4)
+- PlanRecord revisions (append-only, stable item ids, carried linkage),
+  `plans approve/reject` dual-write, scheduler linkage, adaptive re-plan
+  (revision switch, dropped-item soft-cancel advisory).
+
+### T3 — governed nesting (ADR-5)
+- delegate tool for executor-class roles at depth 1 (dormant flag;
+  `nesting.enabled` USER-only sensitive), nested-slot budget (fail-fast,
+  max(1,⌊sem/2⌋)), depth-capped broker credentials (grandchild tokens
+  subId-scoped + shadow task records — unbounded chains terminate),
+  read-only grandchild roles, usage roll-up, fenced results via mailbox.
+
+### T4 — spec system (ADR-6 + erratum §11)
+- SpecRecord store: workspace `state/specs/` (generated-only) + USER store
+  `~/.pi/agent/specs/` with DIGEST-BOUND trust sidecar — workers can never
+  mint re-executable specs (provenance v2; content-swap + TOCTOU closed).
+- SPEC-EVIDENCE footer contract + mechanical coverage gate (default:
+  `unverified` badge on gaps, never blocks); strict mode = coverage AND
+  machine-check in a hardened sandbox (`unshare -rn`, ulimit, env scrub,
+  digest-only outcomes, fail-closed everywhere); verifier-role reject-start.
+- Freeze at dispatch: snapshots immutable; later spec edits never rewrite
+  what a running task was held to. Mint CLI: `scripts/spec-import.mjs`.
+
+### T5 — P2 transparency + hygiene
+- R7 Plan UI (`PI_CREW_PLAN_UI=1`): plans snapshot slice, dashboard pane 7
+  (tree, progress, depth badges, approval keys, revision diff), powerbar
+  plan phases.
+- R8 model-routing transparency: pre-run budget summary (chain +
+  worst-case spawns/task), deduped unvalidated-passthrough warnings,
+  per-attempt models in the output pane.
+- R9 worker self-reporting channel: bounded `worker.*` append channel
+  (schema tag, sliding-window rate limit, FIFO cap, partial-line
+  quarantine); `PI_CREW_EVENTS_PATH` unconditional (read-only roles too).
+- R10 docs hygiene (phantom commands removed, real ones documented,
+  widget TTL corrected).
+
+### Fixes surfaced by the batteries
+- bug-029: symlinked-TMPDIR repo-root escape (macOS `/var`↔`/private/var`)
+  — deterministic `getCacheStats` CI failures; canonicalized boundaries.
+- dwf-setresult determinism (ambient `PI_CREW_TRUST_PROJECT_DWF` leak).
+- B2/B3 live catches: hang-class timeout group-kill gaps, delegate
+  deadline precedence, double-save clobber on plan revision switch.
+
+**Full suites at release tree: 6977 unit + 188 integration, 0 fail; CI 3-OS green on every train PR.**
+
+## [0.10.0] — maintainability refactor: full remediation + reliability (2026-08-16)
+
+Branch `refactor/maintainability`: 16-round audit → 5-phase refactor →
+finding-by-finding sweep → full remediation of every open finding (Waves
+1A/1B/2A/2B/B/C). Full execution log with commit map:
+`docs/refactor-plan.md`. Audit inventory: `docs/refactor-plan.review.md`.
+
+### Security (config tiering)
+- Schema-driven project-config sanitize: `sensitive:true` drop-list +
+  CONDITIONAL drops — project config may only TIGHTEN (guards `off`/
+  loosening dropped). goalWrap subtree + magicKeywords user-only.
+  ADR: `docs/decisions/2026-08-15-schema-driven-sanitize.md`.
+- P1 fix: project-tier `.pi/crew-settings.json` no longer bypasses sanitize
+  (tiers API; legacy flat fns JSDoc'd user-tier-only).
+- scheduledJobs user-tier opt-in gate (both `schedulingEnabled:true` AND
+  `allowProjectScheduledJobs:true` required for project jobs).
+
+### Performance
+- R10-1 O(B²) batch closeout → per-run `ResultArtifactReadCache`
+  (bench b10: −50% fs reads, byte-identical outputs; b11 extends to
+  dependency-context path).
+- R10-2 path-scoped flush; R10-3 broker mtime-gated manifest parse cache
+  (N waiters ≤2 parses); R10-4 sync/async snapshot parity; R10-5
+  child-executor fs batching (≤250ms documented window).
+
+### Hygiene / dead code
+- FIFO caps on all unbounded collections (10 sites); named+removed abort
+  listeners; dead GroupJoinManager + 7 dead fns removed; security telemetry
+  wired into doctor; parser/schema bounds aligned (schema wins).
+
+### Runner reliability (bug-026)
+- Sub-A: stderr-only result artifacts now FAIL the task
+  (`empty-or-stderr-only-result`) instead of persisting noise as completed.
+- Sub-B: fatal-fs errno classifier — ENOSPC/EDQUOT/EMFILE surfaced as
+  `failed (disk full)`-style failureCause in task/run/status/doctor.
+- Sub-C: terminal runs evicted from in-memory preloaded manifests +
+  heartbeat aggregator terminal-task defense (kills phantom dead-worker
+  alerts on long-lived sessions).
+
+### Runner reliability (bug-027 / bug-028 — post-Wave-D, found via real-test + CI)
+- bug-027 (`f6e605ef`): `finalizeRun` heals stale non-terminal in-memory
+  snapshots from disk (in-flight guard) — a run whose disk manifest is
+  terminal but whose preloaded snapshot says "running" no longer blocks
+  finalize with a misleading in-flight error.
+- bug-028 (`e9586aca`): fan-out stale-fallback resurrection —
+  `persistSingleTaskUpdate` previously wrote the dispatch-time
+  `fallbackTasks` array (the O(1) "F4" shortcut), which could resurrect
+  disk-terminal sibling tasks back to "running". It now always re-reads
+  the latest manifest from disk inside the run lock. Deterministic
+  regression test:
+  `test/unit/runtime/task-runner/state-helpers-bug028-stale-fallback.test.ts`
+  (verified fail-before-fix via git stash).
+
+### Verification (real-test 9-tier, v0.10.0 premerge)
+- Full 9-tier real-test battery incl. the live mid-run battery: steer into
+  a running task, live cancel (cross-session ownership guard + force),
+  plan-approval waiting flow, and respond handler — run via a second pi
+  session in tmux. Report:
+  `docs/real-test/reports/real-test-2026-08-16-v0.10.0-premerge.md`.
+- macOS CI teardown hardening (`8197f054`): retry recursive rmSync against
+  the worker-write/rmdir ENOTEMPTY race in `resume-cancel.test.ts`.
+
+### Repo hygiene
+- bench suite b1–b11 tracked; per-run perf reports + bench results
+  gitignored; package.json-referenced scripts committed (fresh-clone fix).
+
 ## [0.9.68] — RLM fixes after deep-review verification (2026-08-12)
 
 Fixes from `docs/rlm-deep-review-2026-08-12.md` (verified) +

package/agents/analyst.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find, ls
+tools: read, grep, find, ls, ask
 ---
 
 You are a requirements analyst. Identify what is known, unknown, risky, ambiguous, or underspecified. Produce clarifying assumptions and acceptance criteria.

package/agents/cold-verifier.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find, ls, bash
+tools: read, grep, find, ls, bash, ask
 maxTurns: 12
 ---
 
@@ -64,3 +64,5 @@ EVIDENCE: file:line references + your own test output
 ```
 
 If you cannot refute a claim after honest effort, that is itself evidence the claim is solid — say so explicitly rather than inventing doubt.
+
+Intentionally unreferenced by builtin teams (CLI/custom use).

package/agents/critic.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find, ls, glob
+tools: read, grep, find, ls, glob, ask
 ---
 
 You are a critical reviewer. Find flaws, missing steps, unsafe assumptions, overengineering, underengineering, and verification gaps. Return concrete fixes to the plan.

package/agents/executor.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find, ls, bash, edit, write, scratchpad
+tools: read, grep, find, ls, bash, edit, write, scratchpad, ask
 ---
 
 You are an implementation specialist. Follow the provided plan, make targeted changes, keep edits minimal, and report changed files plus validation status. Do not broaden scope without explaining why.

package/agents/explorer.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find, ls, glob, bash
+tools: read, grep, find, ls, glob, bash, ask
 ---
 
 You are a fast codebase explorer. Map relevant files, symbols, data flow, and constraints. Do not modify files. Return concise findings with paths and evidence.

package/agents/planner.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find, ls, glob
+tools: read, grep, find, ls, glob, ask
 ---
 
 You are a planning specialist. Convert the goal and discovery notes into a concrete, ordered plan. Identify dependencies, risks, validation steps, and handoff instructions for implementers.

package/agents/reviewer.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find, ls, glob, bash
+tools: read, grep, find, ls, glob, bash, ask
 ---
 
 You are a code reviewer. Review the implementation for bugs, regressions, maintainability issues, missing tests, and project-rule violations. Return prioritized findings with evidence.

package/agents/security-reviewer.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find
+tools: read, grep, find, ask
 ---
 
 You are a security reviewer. Look for injection, authn/authz flaws, insecure defaults, secret exposure, unsafe filesystem/network behavior, and dependency risks. Return severity and remediation.

package/agents/test-engineer.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, edit, write, bash, ls, scratchpad
+tools: read, edit, write, bash, ls, scratchpad, ask
 ---
 
 You are a test engineer. Identify the right test level, add or adjust tests when asked, detect flaky assumptions, and report exact validation commands and results.

package/agents/verifier.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, grep, find, ls, bash, scratchpad
+tools: read, grep, find, ls, bash, scratchpad, ask
 maxTurns: 15
 ---
 

package/agents/writer.md

@@ -5,7 +5,7 @@ model: false
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-tools: read, edit, write, ls
+tools: read, edit, write, ls, ask
 ---
 
 You are a documentation specialist. Produce clear, concise, maintainable docs and summaries. Preserve technical accuracy and avoid marketing fluff.