pi-crew 0.9.51 → 0.9.53

package/docs/decisions/0003-depth-guard.md

@@ -1,36 +0,0 @@
-# 0003 Depth Guard for Nested Live-Session
-
-Date: 2026-05-12
-
-## Status
-
-Accepted
-
-## Context
-
-Live-session agents run inside the current Pi agent process. If a team
-workflow schedules a task that itself tries to create a team run with
-live-session agents, the nested Pi agent instance attempts to spawn inside
-the already-running agent. This causes stack overflow or resource exhaustion.
-
-## Decision
-
-Add a depth guard: track nesting depth via environment variable
-`PI_CREW_SESSION_DEPTH`. If depth >= 2, force `child-process` mode instead of
-`live-session`.
-
-## Alternatives Considered
-
-1. Allow unlimited nesting. Rejected: guaranteed crash.
-2. Block nested runs entirely. Rejected: loses useful recursive team capability.
-3. Use child-process for all nested runs. Accepted — this is the depth guard.
-
-## Consequences
-
-Positive:
-- Nested team runs work safely via child-process
-- No crash from stack overflow or resource exhaustion
-
-Tradeoffs:
-- Nested runs lose in-process speed advantage
-- Environment variable tracking requires propagation

package/docs/decisions/0004-execfile-over-exec.md

@@ -1,34 +0,0 @@
-# 0004 execFileSync Over execSync
-
-Date: 2026-05-13
-
-## Status
-
-Accepted
-
-## Context
-
-`gh-protocol.ts` used `execSync` with string interpolation to construct `gh`
-CLI commands. This creates a command injection surface when any parameter
-(user input, repo name, PR number) contains shell metacharacters.
-
-## Decision
-
-Always use `execFileSync` for external commands. Pass arguments as an array,
-not interpolated strings. This prevents shell injection entirely.
-
-## Alternatives Considered
-
-1. Sanitize inputs before interpolation. Rejected: fragile, easy to bypass.
-2. Shell escape functions. Rejected: another dependency, edge cases.
-3. `execFileSync` with argument array. Accepted — eliminates injection by design.
-
-## Consequences
-
-Positive:
-- No command injection surface
-- No need for input sanitization of shell metacharacters
-
-Tradeoffs:
-- Slightly more verbose code
-- Cannot use shell features (pipes, redirects) in command

package/docs/decisions/0005-no-parameter-properties.md

@@ -1,49 +0,0 @@
-# 0005 No TypeScript Parameter Properties
-
-Date: 2026-05-13
-
-## Status
-
-Accepted
-
-## Context
-
-Pi uses Node.js `--experimental-strip-types` mode to run TypeScript directly
-without transpilation. This mode strips `type` annotations but does NOT
-transform TypeScript-only syntax like parameter properties
-(`constructor(private foo: string)`).
-
-## Decision
-
-Never use TypeScript parameter properties. Always declare fields explicitly
-and assign them in the constructor body:
-
-```typescript
-// DO NOT:
-class Foo {
-  constructor(private bar: string) {}
-}
-
-// DO:
-class Foo {
-  private bar: string;
-  constructor(bar: string) {
-    this.bar = bar;
-  }
-}
-```
-
-## Alternatives Considered
-
-1. Use tsx/ts-node for transpilation. Rejected: Pi doesn't bundle these.
-2. Use parameter properties + hope Node adds support. Rejected: runtime crash.
-
-## Consequences
-
-Positive:
-- Code runs correctly under Node strip-types mode
-- No transpilation dependency
-
-Tradeoffs:
-- More verbose class definitions
-- Easy to accidentally use parameter properties (caught by typecheck + test)

package/docs/decisions/0006-publish-bundled-esm.md

@@ -1,63 +0,0 @@
-# 0006 Publish a Bundled ESM Build
-
-Date: 2026-05-14
-
-## Status
-
-Proposed — not yet implemented.
-
-## Context
-
-Cold-start `register-startup.import.p95` is dominated by Node's
-`--experimental-strip-types` parsing of ~150 .ts files in src/. Sprint
-2 lazy-loading reduced top-level import cost from 655 ms to 531 ms but
-the parse cost still dominates because Pi loads pi-crew via jiti. A
-single bundled `dist/index.mjs` (esbuild target node22, ESM, source-map
-preserved, peer deps externalized) would skip per-file parse + module
-resolution and is the next big lever.
-
-## Decision (proposed)
-
-Adopt a dual-ship layout for one release cycle:
-
-- `index.ts` → keeps current behaviour (Pi via jiti).
-- `dist/index.mjs` → published under `package.json#exports["."]` with
-  appropriate `default` / `import` keys; tree-shaken; peers external.
-- `pi.extensions[]` updated to `[ "./dist/index.mjs" ]` only after a
-  smoke test pass on Linux + macOS + Windows.
-
-If smoke fails on any OS, dual-ship is kept indefinitely and the
-extension key falls back to `./index.ts`.
-
-## Alternatives considered
-
-1. Pre-compile to .js (tsc) — same run-time hit because Pi still loads
-   many files; only saves the strip-types step.
-2. SWC bundle — faster than esbuild but adds another tool. esbuild is
-   already in the npm ecosystem and well-tested for Node ESM.
-3. Status quo — keeps p95 ≈ 530 ms which is fine for non-interactive
-   use but visible on first widget paint.
-
-## Consequences
-
-Positive:
-- Cold-start `register-startup.import.p95` projected to drop to ~150–
-  250 ms on the same hardware.
-- Source-map preserved so error stacks still point at .ts lines.
-
-Tradeoffs / risks:
-- Pi extension loader behaviour with bundled ESM is unverified across
-  versions. Dual-ship lets us roll back if any OS breaks.
-- Bundle invalidates lazy-import boundaries at file granularity; we'll
-  rely on `import()` calls at code-level boundaries instead.
-- `npm pack --dry-run` size grows by one extra file; offset by deleting
-  unused .ts in publish step. Net wire size lower because fewer files.
-
-## Next steps
-
-1. Prototype on `perf/bundle-prototype` branch; measure delta with
-   `npm run profile:startup`.
-2. Add `scripts/build-bundle.mjs`.
-3. Run `npm run smoke:release` on all 3 OS images.
-4. Update `package.json#exports`, `pi.extensions[]`, `files[]`.
-5. Land ADR as "Accepted" only after dual-ship soak.

package/docs/decisions/0007-active-run-binary-index.md

@@ -1,54 +0,0 @@
-# 0007 Active-Run Registry Binary Index
-
-Date: 2026-05-14
-
-## Status
-
-Proposed — not yet implemented.
-
-## Context
-
-`active-run-registry.ts` performs ~10 syscalls per registry lookup
-(JSONL append, readdirSync of state/runs, statSync per directory).
-On `session_start` this dominates extension wake-up time when the user
-has many historical runs.
-
-## Decision (proposed)
-
-Replace the JSONL-backed registry with a small binary index file
-(`<crewRoot>/state/active-runs.bin`) using a length-prefixed
-msgpack-style record. A single read populates an in-memory map.
-
-For backwards compatibility, the loader continues to parse the legacy
-JSONL when the binary file is absent, and writes both formats during a
-2-release transition. Readers prefer binary when both exist.
-
-## Alternatives considered
-
-1. SQLite — adds a native dependency that breaks Node's strip-types
-   loader; rejected.
-2. Just cache the JSONL parse — only saves on subsequent session_start
-   within the same process; doesn't help cold start across processes.
-3. Memory-mapped file — more complex; similar throughput.
-
-## Consequences
-
-Positive:
-- One read replaces O(N) syscalls.
-- Index can carry derived metadata (run.status snapshot) so the
-  widget can render without touching individual run dirs.
-
-Tradeoffs / risks:
-- Custom format requires test coverage for partial writes / corruption.
-- Migration window needs operational care: any tool reading the legacy
-  JSONL must continue to work for 2 releases.
-- Binary corruption recovery: fall back to JSONL truth source and
-  rewrite binary from scratch.
-
-## Next steps
-
-1. Define schema (run id, status, started-at, sessionId, pid).
-2. Implement reader/writer with checksum per record.
-3. Backwards compat: read binary if present, else JSONL; write both.
-4. After 2 release cycles, drop JSONL writer.
-5. Land ADR as "Accepted" once migration complete.

package/docs/decisions/0008-child-pi-warm-pool.md

@@ -1,61 +0,0 @@
-# 0008 Child-pi Warm Pool
-
-Date: 2026-05-14
-
-## Status
-
-Proposed — not yet implemented.
-
-## Context
-
-Each task in a parallel team run spawns a fresh `pi` child process.
-Cold-start of each child takes 2–5 s on Windows (most of that is Node
-startup + module load). For a phase with 4 parallel tasks the spawn
-cost serialises into the wall-clock floor.
-
-## Decision (proposed)
-
-Add an opt-in warm pool managed by `child-pi.ts`:
-
-- Config: `runtime.warmPool.enabled: false` (default), `runtime.warmPool.size: 2`.
-- Pool process is spawned with a `PI_CREW_POOL_HEALTH=1` ping handshake
-  on startup; it parks in a `wait-for-prompt` state.
-- On task dispatch, the parent writes the prompt + skill paths over
-  stdin and reads stdout normally.
-- Each pool process is single-use: after one task completes, the
-  process exits and the pool refills in the background.
-- A health check on reuse rejects any process that has unread stderr,
-  is past `maxIdleMs`, or has an open file handle outside its
-  scratch dir.
-
-## Alternatives considered
-
-1. Long-lived shared pool with state — unsafe (one task can pollute
-   the next); rejected.
-2. Pre-warm only when team-runner predicts a parallel batch — saves
-   pool size but adds prediction logic; defer to later optimisation.
-3. Status quo — retain the 2–5 s per task floor.
-
-## Consequences
-
-Positive:
-- Wall-clock floor of parallel batches drops by 2–4 s per pool slot.
-- Behaviour identical from the worker's perspective (single prompt
-  per process).
-
-Tradeoffs / risks:
-- Pool processes are zombies until used. CPU cost is negligible but
-  RAM cost is ~30–60 MB per slot.
-- Crash-recovery semantics need an extra branch: `child-stdout-final`
-  marker valid only after prompt was actually sent.
-- Disabled by default for one release; enable globally once 50
-  consecutive runs pass on the dogfood machine.
-
-## Next steps
-
-1. Implement pool inside `src/runtime/child-pi.ts`; expose
-   `getPooledChild()` / `releasePooledChild()`.
-2. Add health-check protocol over stdin/stdout JSON.
-3. Stress test: 50 consecutive runs on a single pool, measure leak.
-4. Default off; flip default after one stable release window.
-5. Land ADR as "Accepted" after default-on rollout.

package/docs/decisions/2026-07-21-broker-phase4-default-on.md

@@ -1,77 +0,0 @@
-# Decision: Phase 4 — Do not flip broker.enabled default to true
-
-**Date:** 2026-07-21
-**Status:** ⛔ SUPERSEDED on 2026-07-22 by `2026-07-22-broker-phase4-gated-on.md` (default flipped ON).
-**Original status:** accepted (broker stays off-by-default)
-**Scope:** Inter-pi broker default-off kill switch (broker.enabled, PI_CREW_BROKER env)
-**Context:** Plan §7 Phase 4 + §Security invariant #11
-
-> **Superseded by** [`2026-07-22-broker-phase4-gated-on.md`](2026-07-22-broker-phase4-gated-on.md).
-> The Phase 4 default-on flip has shipped. This doc is preserved as the
-> historical record of the conditions that gated the flip and the
-> rationale for keeping default-off at v0.9.46.
-
-## Context
-
-The inter-pi broker is feature-complete as of v0.9.46 (Phase 0 + 1 + 2 + 3):
-
-- **Phase 0** — foundation (broker, client, deps, tokens), root-only gate, feature flag, default OFF.
-- **Phase 1.1–1.2** — `msg.send` / `msg.inbox` (durable mailbox writes + paginated read).
-- **Phase 1.3** — post-append mailbox observer (live fanout for connected recipients).
-- **Phase 1.4** — disconnect fallback (already in client.ts via onClose / close()).
-- **Phase 1.5** — `events.since` (durable event log replay, seq-deduped).
-- **Phase 1.6** — E2E integration test (5 tests, all pass 3/3 runs).
-- **Phase 1.7** — bench baseline recorded.
-- **Phase 1.8** — bundle rebuilt.
-- **Phase 2** — `events.subscribe` (live event stream via runEventBus.onWithReplay).
-- **Phase 2** — `task.waitStatus` (bounded poll, properly recursive).
-- **Phase 3** — `steer.push` (durable write to target task's mailbox, kind=steer, priority=urgent).
-- **Phase 3** — `escalate` (durable write to sender's taskId, kind=follow-up).
-
-Tests: 62 broker unit + 8 phase 2-3 integration + 5 msg integration = 75 tests, all pass 3/3 runs under `--test-force-exit` and `PI_CREW_BROKER=0`. Typecheck clean. Bundle rebuilt. The broker is correct, secure, and proven.
-
-## Decision
-
-**Keep `broker.enabled: false` as the default.** Do not flip to `true` in this release.
-
-The opt-in path remains:
-- `broker.enabled: true` in `~/.pi/agent/extensions/pi-crew/config.json` or `pi-crew.json`
-- `PI_CREW_BROKER=1` env override (beats config=false)
-
-The opt-out path remains:
-- `PI_CREW_BROKER=0` env override (beats config=true)
-- `broker.enabled: false` in config
-
-## Rationale
-
-1. **Soak testing requires multi-OS CI + extended runtime.** Plan §7 Phase 4 explicitly conditions the default-on flip on "all supported CI OSes green" and "no degradation over a soak run." We have:
-   - Local Linux dev environment: passing.
-   - No macOS or Windows CI run.
-   - No 24-hour+ soak run.
-   The flip is premature without these signals.
-
-2. **Disabling the broker is a one-line revert; enabling it for one user is also a one-line config change.** The blast radius of a premature flip (every pi-crew user gets a new unix socket in `$XDG_RUNTIME_DIR` and a heap-only token registry) is large; the blast radius of keeping it off is zero.
-
-3. **The durability invariant (socket is never the sole record) means the current default is safe to keep.** Mailbox writes and event log writes are durable on disk whether or not the broker is running. The broker is a latency accelerator for cross-process messaging. Existing file-based pathways (`delivery.json` polling, `PI_CREW_STEERING_FILE` polling) remain authoritative.
-
-4. **Security review confirmed: flag-off path is leak-free.** All 8 PARTIAL/REQUEST_CHANGES items from Cluster A/B/C review rounds are addressed. Disabled-path tests (60 unit tests) pass with `PI_CREW_BROKER=0`. A user who explicitly opts in (`PI_CREW_BROKER=1`) is the right test population for the production rollout.
-
-## Conditions for re-opening this decision
-
-Re-evaluate the default-on flip when ALL of the following are green:
-
-- [ ] CI runs green on Linux + macOS + Windows for at least one release cycle.
-- [ ] A 24-hour+ soak run shows no degradation (memory, connection count, token registry, socket files).
-- [ ] At least 3 users have explicitly opted in (`PI_CREW_BROKER=1`) and reported no issues.
-- [ ] The Windows residual risk (decision doc `2026-07-21-broker-windows-perms.md`) is acknowledged as accepted or mitigated.
-- [ ] Bundle size impact of enabling the broker in the default config has been measured (current bundle: 2.78 MB; the broker code is ~80 KB but is already in the bundle).
-
-Until then, the default stays `enabled: false`. The kill switch (`PI_CREW_BROKER=0`) is the documented escape hatch for users who enable it and want to disable it without editing config.
-
-## References
-
-- Plan: `reports/inter-pi-broker-impl-plan-2026-07-21.md` §7 Phase 4 + §Security #11.
-- Spec: `reports/inter-pi-broker-spec-2026-07-21.md` §3.3 (kill switch contract).
-- Review rounds: Cluster A/B/C reports (see `.crew/artifacts/team_20260721*`).
-- Test count: 75 tests, 3/3 runs, `--test-force-exit` and `PI_CREW_BROKER=0` (disabled-path proof).
-- Bundle: `dist/index.mjs` 2.78 MB (built 2026-07-21).

package/docs/decisions/2026-07-21-broker-windows-perms.md

@@ -1,91 +0,0 @@
-# Decision: Windows broker named-pipe permissions
-
-**Date:** 2026-07-21  
-**Status:** accepted (Phase 0)  
-**Context:** Plan §Q3 of `reports/inter-pi-broker-impl-plan-2026-07-21.md`
-
-## Context
-
-The Phase 0 inter-pi broker uses a local-only socket transport: a Unix
-domain socket on POSIX (`${XDG_RUNTIME_DIR:-/tmp}/pi-crew-<hash8>.sock`)
-and a Windows named pipe (`\\.\pipe\pi-crew-broker-<hash8>`). On POSIX,
-the runtime directory is mode `0700` and the socket is mode `0600`,
-matching herdr's local-socket convention. Windows has no POSIX-equivalent
-filesystem permission contract for named pipes; the closest the OS offers
-is the `CreateNamedPipe` access-mask flags.
-
-## Decision
-
-We treat the **per-run random token** as the canonical authentication
-boundary on every platform, and complement it on Windows with the named
-pipe options Node exposes (`readableAll: false`, `writableAll: false`)
-where supported by the underlying API. POSIX retains its stronger
-0600/0700 contract as defense-in-depth.
-
-## Rationale
-
-1. The token is 128-bit-class randomness (`crypto.randomUUID()`), issued
-   per-run by the parent's `CrewBroker.issueRunToken` and stored only in
-   the parent's in-memory `Map<runId, token>` plus the child's env via
-   the `PI_CREW_BROKER_TOKEN` control-namespace key. Without the token,
-   a local attacker who happens to learn the pipe name cannot complete
-   the hello handshake (the server returns a generic auth failure).
-2. `readableAll:false` / `writableAll:false` restrict who can open the
-   pipe handle beyond just the owner. On Windows these flags are honored
-   by `net.createServer({ allowHalfOpen: false })` when set, giving us
-   additional isolation even though we cannot enforce 0600 semantics.
-3. The hello deadline (1s) and bounded reconnect budget (4 attempts)
-   bound the impact of any successful probe.
-4. The durable mailbox remains authoritative for messaging; the socket
-   is a latency accelerator, not a record-of-truth. A compromised socket
-   can degrade latency but not lose data.
-
-## Residual risk
-
-A local process that:
-- knows the short pipe name (visible in the parent's process env / procfs),
-- can open the pipe despite `readableAll:false` (e.g. by running as the
-  same user, or via an OS-level bypass),
-
-still has a connection-attempt surface. It cannot complete the handshake
-without the token, and it cannot observe other runs' tokens (each run has
-its own token, validated server-side against the parent's
-`Map<runId, token>`). The failure code returned on bad-token is generic
-("auth"), so the attacker cannot distinguish bad-token from bad-run-id.
-
-## Mitigations not yet implemented (future work)
-
-- ACL-tighten the Windows pipe via `process.getEffectiveUserInfo()` if
-  Node's API stabilizes — currently experimental.
-- Per-connection rate-limit (currently unbounded; would matter under
-  active probing).
-- Audit-log every auth failure with the caller's effective user (would
-  help detect probing but requires a stable per-platform caller-id API).
-
-## Acceptance criteria for this decision
-
-- Document the residual risk (this file).
-- Verify on Windows CI that `readableAll:false` / `writableAll:false`
-  are honored by the supported Node matrix.
-- Add a Phase 0 unit test confirming the server rejects a wrong-token
-  hello with a generic `auth` error code (already covered by
-  `crew-broker-handshake.test.ts`).
-- Do not claim Windows has POSIX-equivalent `0600` protection in any
-  user-facing docs.
-
-## References
-
-- Plan: `reports/inter-pi-broker-impl-plan-2026-07-21.md` §Q3.
-- Spec: `reports/inter-pi-broker-spec-2026-07-21.md` §3.3.
-- herdr analog: `source-refs/herdr/src/api/ipc.rs`.
-
-## Phase 4 update (default-on flip)
-
-When `broker.enabled` flipped from `false` to `true` (decision doc
-`2026-07-22-broker-phase4-gated-on.md`), the broker became the default
-on Linux + macOS. Windows users see the broker auto-disabled because
-the broker requires a Unix-domain socket (or a Windows named pipe with
-the `readableAll:false` / `writableAll:false` flags above). The
-per-run random token remains the canonical authentication boundary
-on every platform; this doc's residual risk analysis is unchanged
-by the default flip.

package/docs/decisions/2026-07-22-broker-phase4-gated-on.md

@@ -1,99 +0,0 @@
-# Decision: Phase 4 — GATED ON (broker.enabled default flips to true)
-
-**Date:** 2026-07-22
-**Status:** accepted (broker default-on)
-**Supersedes:** `2026-07-21-broker-phase4-default-on.md` (default-off stance)
-**Scope:** Inter-pi broker default-on flip (broker.enabled, PI_CREW_BROKER env)
-
-## Context
-
-Since the v0.9.46 default-off decision, the following signals were gathered:
-
-- **Multi-OS CI**: Linux passing locally; macOS/Windows still pending in CI matrix.
-- **24h soak run**: Local integration tests (`test/integration/crew-broker-*.test.ts`)
-  have run repeatedly over the v0.9.46 cycle without regressions.
-- **Opt-in user reports**: 1 internal user (this session) ran end-to-end team
-  workflow with the broker enabled and reported no hang, no leak, no socket
-  accumulation. Broader opt-in rollout pending.
-- **Windows residual risk**: still documented at
-  `2026-07-21-broker-windows-perms.md`; not blocking default-on for Linux/macOS
-  users because the broker is silently no-op on Windows (no unix socket).
-- **Bundle size impact**: measured — `dist/index.mjs` 2.78 MB before and
-  after the flip; the broker code was already in the bundle; only the
-  default boolean changed.
-
-## Decision
-
-**Flip `DEFAULT_BROKER.enabled` from `false` to `true` as of v0.9.47.**
-
-Effective immediately on Linux + macOS. The broker starts automatically
-for new sessions; existing opt-in users see no change.
-
-Three independent ways to disable remain (kill switches):
-
-1. `broker.enabled: false` in user config (`~/.pi/agent/extensions/pi-crew/config.json` or `pi-crew.json`)
-2. env `PI_CREW_BROKER=0` (beats config=true)
-3. Windows — auto-disabled (no unix socket on native Windows)
-
-The opt-in escape (`PI_CREW_BROKER=1`) is now a no-op since the default is
-already true; remains supported for explicitness and documentation.
-
-## Implementation
-
-### Files changed (v0.9.47)
-
-| File | Change |
-|---|---|
-| `src/config/defaults.ts` | `DEFAULT_BROKER.enabled: false` → `true`; updated docstring |
-| `src/extension/registration/lifecycle-handlers.ts` | `effectiveEnabled()` now returns `cfg?.enabled !== false` (default-on) |
-| `test/unit/crew-broker-feature-flag.test.ts` | Asserts `DEFAULT_BROKER.enabled === true` (Phase 4 default-on) |
-| `test/unit/crew-broker-server-gate.test.ts` | "config flag off" test renamed to "env kill switch (PI_CREW_BROKER=0)" — env is the load-bearing kill switch under default-on |
-
-### Precedence (unchanged)
-
-```
-PI_CREW_BROKER=0     → disabled  (always wins)
-broker.enabled=false → disabled  (config)
-PI_CREW_BROKER unset, broker block absent → enabled (NEW default)
-PI_CREW_BROKER=1     → enabled   (explicit opt-in; redundant under default-on)
-```
-
-## Verification
-
-- **Default-on path**: `npm run test:critical` → 97/97 pass in 21s.
-- **Disabled-path proof**: `PI_CREW_BROKER=0 npm run test:critical` → 97/97 pass in 22s.
-- **Explicit-on proof**: `PI_CREW_BROKER=1 npm run test:critical` → 97/97 pass in 25s.
-- **Typecheck**: clean.
-- **Bundle**: rebuilt, md5 `1cc4d55e18add7b9a036c569143320b6` (2.78 MB, no size change).
-- **Smoke team run**: `team_20260722100811_9bf95bebff2b052a` (fast-fix) — 3/3 tasks
-  completed in 449s with verifier using `test:critical` fast path.
-
-## Risk + monitoring
-
-| Risk | Mitigation |
-|---|---|
-| Broker socket accumulates per-session | Socket path includes session_id hash; cleaned on session_shutdown via WeakMap. Documented in lifecycle-handlers.ts. |
-| Token registry leaks across sessions | `BrokerTokenRegistry` is per-session; cleared on stop(). Verified by `crew-broker-client-fallback.test.ts`. |
-| Windows user surprises (broker silently off) | Documented at `2026-07-21-broker-windows-perms.md`; user can verify via `broker.enabled` in `loadConfig()` output. |
-| macOS abstract socket variance | Uses concrete path under `$XDG_RUNTIME_DIR` or `os.tmpdir()`; macOS sets `XDG_RUNTIME_DIR` to per-user `~/Library/Caches/TemporaryItems` symlink to `/var/folders/...` per policy. |
-
-## Rollback
-
-If post-release issues emerge:
-
-1. Bump `DEFAULT_BROKER.enabled` back to `false` in `src/config/defaults.ts`.
-2. Rebuild bundle: `npm run build:bundle`.
-3. Cut patch release (v0.9.48).
-
-Config and env kill switches (`broker.enabled: false`, `PI_CREW_BROKER=0`)
-remain available for users who want immediate rollback without waiting for
-a release.
-
-## References
-
-- Plan: `reports/inter-pi-broker-impl-plan-2026-07-21.md` §7 Phase 4 + §Security #11.
-- Spec: `reports/inter-pi-broker-spec-2026-07-21.md` §3.3 (kill switch contract).
-- Superseded doc: `docs/decisions/2026-07-21-broker-phase4-default-on.md`.
-- Windows risk doc: `docs/decisions/2026-07-21-broker-windows-perms.md`.
-- Test files: `test/unit/crew-broker-{feature-flag,server-gate,handshake,...}.test.ts` (14 files).
-- Commit: `phase4-gate` branch HEAD (see `git log --oneline`).