pi-crew 0.9.18 → 0.9.20

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## [v0.9.20] — security hardening: RPC HMAC auth + per-task API key scoping + safe-bash whitelist (2026-07-06)
+
+Three defense-in-depth security upgrades distilled from cross-source research (52+ repos) and the H-1/H-2/H-6 audit findings. All three are additive (no breaking changes); two are opt-in via env vars, one is default-on.
+
+### Highlights
+
+- **RPC HMAC authentication (opt-in).** All cross-extension RPC channels (`ping`/`run`/`status`/`live-control` at extension layer; `ping`/`spawn`/`stop` at runtime layer) now support HMAC-SHA256 origin signing. When `PI_CREW_RPC_SECRET` is set, every request must carry a valid signature with timestamp + nonce (anti-replay) and channel binding (cross-channel replay guard). Timing-safe comparison prevents timing attacks. Unset = backward-compatible passthrough. Closes the H-2 authorization-bypass finding where any co-installed extension could spoof `source='pi-crew'` to spawn/kill subagents. New module `src/extension/rpc-hmac.ts`; 24 tests in `test/unit/rpc-hmac-auth.test.ts`.
+- **Per-task API key scoping (default-on).** Child workers previously inherited ALL model provider API keys via a broad allowlist. `buildChildPiSpawnOptions()` now takes an optional `model` param and calls `buildScopedAllowList()` to inject only the provider keys needed for the assigned model. When no model is given, only `BASE_ALLOWLIST` system vars pass through (zero provider keys leak). Reduces blast radius: a compromised child only gets keys for its model. Helpers `providerEnvKeys()` + `buildScopedAllowList()` in `src/utils/env-filter.ts`; per-task wiring in `src/runtime/child-pi.ts`; tests in `test/unit/api-key-scoping.test.ts`.
+- **Safe-bash whitelist mode (opt-in).** A deny-by-default whitelist as an opt-in alternative to the legacy blacklist `isDangerous()`. Enabled via `PI_CREW_SAFE_BASH_MODE=whitelist`. Only 16 read-only commands allowed (`ls cat head tail wc grep find echo pwd date whoami uname df du file stat`). Shell metacharacter regex blocks chaining/substitution before the first-token check (`ls; rm file` cannot smuggle `rm`); unmatched quotes are rejected as malformed input. Legacy blacklist path unchanged when not enabled. `src/tools/safe-bash.ts`; 21 tests in `test/unit/safe-bash-whitelist.test.ts`.
+
+### Verification
+
+| Gate | Result |
+|---|---|
+| Affected unit tests (20 files) | ✅ 187/187 pass |
+| safe-bash (blacklist + whitelist + ANSI) | ✅ 51/51 |
+| env-filter + API key scoping | ✅ 26/26 |
+| cross-extension-rpc + HMAC | ✅ 48/48 |
+| child-pi (hardening/exit/redaction/compaction) | ✅ 35/35 |
+| security (hardening/artifact/cwd/import/output) | ✅ 27/27 |
+| Live E2E (research workflow) | ✅ 3/3 tasks, end-to-end |
+| Extension load | ✅ |
+
+### Files
+
+- NEW: `src/extension/rpc-hmac.ts`, `test/unit/rpc-hmac-auth.test.ts`, `test/unit/api-key-scoping.test.ts`, `test/unit/safe-bash-whitelist.test.ts`
+- MOD: `src/extension/cross-extension-rpc.ts`, `src/runtime/cross-extension-rpc.ts`, `src/utils/env-filter.ts`, `src/runtime/child-pi.ts`, `src/tools/safe-bash.ts`, `src/tools/safe-bash-extension.ts`, `test/unit/env-filter.test.ts`, `test/unit/security-hardening.test.ts`
+
+## [v0.9.19] — plan-execute workflow + main-session→planner analysis handoff (2026-07-03)
+
+New builtin workflow for the common "I already analyzed this — just plan + execute + verify it" case, plus a generic `analysis`/`analysisPath` channel on `team action='run'` for handing caller-session context to planner child workers.
+
+### Highlights
+
+- **`plan-execute` builtin workflow.** 3-step sequential (plan → execute → verify), no explore step. Designed for callers who have already done the analysis and want the planner to build directly on it. The `plan` step declares `reads: analysis.md` so the caller's pre-analysis is injected via the standard sharedReads dependency-context pipeline. Workflow count: 8 → 9 (`test/unit/discovery.test.ts` updated).
+- **`analysis` / `analysisPath` channel on `team action='run'`.** Two new optional params (mutually exclusive):
+  - `analysis` (string, ≤100 000 chars) — inline pre-analysis from the calling session
+  - `analysisPath` (string, file path within project) — pre-analysis loaded from a markdown file
+  - Both go through `sanitizeTaskText()` (SEC-007 prompt-injection stripper from `buildTaskPacket`) before being injected, so the analysis can never smuggle a directive past the planner. The text is persisted to `artifacts/{runId}/shared/analysis.md` as an audit trail. Mutual exclusivity, path containment (`resolveContainedPath` with null-byte + symlink realpath), and file-not-found / 100 KB cap are all fail-fast, checked BEFORE `createRunManifest` so validation errors never leave orphan run state. Goal-wrapped runs emit a clear `console.warn` if `analysis` is set but ignored (chain dispatch + goal-wrap don't honor v1).
+- **`reads` injection is correctly step-scoped.** Verified live: only the `plan` step (which declares `reads: analysis.md`) receives the analysis content; `execute` and `verify` prompts contain zero unique analysis headings even though the goal text references the analysis file path. This is the intended behavior — the filter limits *dependency-injected* content, not the goal itself.
+
+### Cross-platform fix (was blocking Windows CI)
+
+`run-analysis.test.ts` failed on macOS + Windows because `writeArtifact` stores canonicalized paths via `resolveInside`, while the test compared against a path built from raw `mkdtempSync` cwd. Two fixes:
+1. `fs.realpathSync` the test cwd in `makeRunCwd` — closes the macOS symlink (`/var` → `/private/var`) case.
+2. Switched the `manifest.artifacts[]` lookup to a normalized suffix compare (`a.path.replace(/\\/g, "/").endsWith("shared/analysis.md")`) — closes the Windows drive-letter-case + separator case. Robust against both realpath drift and Windows path normalization.
+
+### Defense-in-depth
+
+- `analysisPath` file size is `statSync`-checked against the same 100 KB cap as the inline channel (prevents prompt-size blowup via the file route).
+- `sanitizeTaskText` applied to both inline AND file content before any persistence or injection.
+- Path traversal on `analysisPath` is rejected with the same `resolveContainedPath` machinery used by other path-taking params (symlink-canonicalized + null-byte guarded).
+
+### Verification
+
+| Gate | Result |
+|---|---|
+| TSC | ✅ |
+| Lint | ✅ |
+| format:check | ✅ |
+| check:conflict-markers | ✅ |
+| check:lazy-imports | ✅ |
+| check:bundle-staleness | ✅ (dist rebuilt at 3011.0 KB) |
+| test:unit (run-analysis) | ✅ 9/9 (with --test-timeout=120000) |
+| test:unit (plan-execute-workflow) | ✅ 3/3 |
+| test:unit (discovery, +1 workflow) | ✅ updated assert 8→9 |
+| Live E2E plan-execute + inline analysis | ✅ 3/3 tasks, consistency=1 |
+| Live E2E plan-execute + analysisPath (file) | ✅ planner + executor passed; verifier hit pre-existing child-Pi hang (unrelated) |
+| CI Ubuntu / Node 22 | ✅ |
+| CI macOS / Node 22 | ✅ |
+| CI Windows / Node 22 | ✅ |
+| CI fallow audit | ✅ |
+
+### Changed
+
+- `workflows/plan-execute.workflow.md` — new builtin workflow (30 lines).
+- `src/schema/team-tool-schema.ts:264-279` — new `analysis` + `analysisPath` params on `TeamToolParams` + matching interface fields.
+- `src/extension/team-tool/run.ts` — new `resolveAnalysisText()` helper (fail-fast validation + sanitize); analysis artifact write before `atomicWriteJson` of updated manifest; `reads: ["analysis.md"]` injected into direct-agent synthetic workflow when analysis is set; goal-wrap path emits a warning when analysis is provided but ignored.
+- `test/unit/discovery.test.ts:17` — workflows count 8 → 9.
+- `test/unit/plan-execute-workflow.test.ts` — new (46 lines, 3 tests).
+- `test/unit/run-analysis.test.ts` — new (242 lines, 9 tests including size cap, path traversal, mutual exclusion, file-missing).
+
+### Migration notes
+
+- Existing `team` tool callers are unaffected — both `analysis` and `analysisPath` are optional. Workflow count is `discoverWorkflows`-reflected, so `team action='list', resource='workflow'` now shows 9 builtin entries instead of 8.
+- No new dependencies. All new code uses existing `sanitizeTaskText`, `resolveContainedPath`, and `writeArtifact` machinery.
+- `plan-execute` joins the builtin workflow family alongside `default`, `fast-fix`, `research`, `review`, `implementation`, `pipeline`, `parallel-research`, and `chain`.
+
+### Known limitation (out of scope for v0.9.19)
+
+- Goal-wrapped runs and chain dispatch ignore the `analysis` param in v1 (with a `console.warn`). If callers need analysis in those modes, file an issue and we can plumb it through `goal.ts` / `chain-dispatch.ts` in a follow-up.
+
 ## [v0.9.18] — perf fix bundle-mode spawn + config cache (2026-07-02)
 
 Five commits addressing items from the v0.9.17 performance review (`docs/perf/performance-review-2026-07.md`):

package/dist/build-meta.json

@@ -12603,7 +12603,7 @@
       "format": "esm"
     },
     "src/schema/team-tool-schema.ts": {
-      "bytes": 12557,
+      "bytes": 13646,
       "imports": [
         {
           "path": "node_modules/@sinclair/typebox/build/esm/index.mjs",
@@ -15768,7 +15768,7 @@
       "format": "esm"
     },
     "src/extension/team-tool/run.ts": {
-      "bytes": 39160,
+      "bytes": 42914,
       "imports": [
         {
           "path": "src/agents/discover-agents.ts",
@@ -15785,6 +15785,11 @@
           "kind": "import-statement",
           "original": "../../runtime/pipeline-runner.ts"
         },
+        {
+          "path": "src/runtime/task-packet.ts",
+          "kind": "import-statement",
+          "original": "../../runtime/task-packet.ts"
+        },
         {
           "path": "src/state/active-run-registry.ts",
           "kind": "import-statement",
@@ -18161,7 +18166,7 @@
       "imports": [],
       "exports": [],
       "inputs": {},
-      "bytes": 6421066
+      "bytes": 6427881
     },
     "dist/index.mjs": {
       "imports": [
@@ -21202,7 +21207,7 @@
           "bytesInOutput": 6424
         },
         "src/schema/team-tool-schema.ts": {
-          "bytesInOutput": 11030
+          "bytesInOutput": 11702
         },
         "src/extension/team-tool/doctor.ts": {
           "bytesInOutput": 12349
@@ -21559,7 +21564,7 @@
           "bytesInOutput": 6259
         },
         "src/extension/team-tool/run.ts": {
-          "bytesInOutput": 31284
+          "bytesInOutput": 33569
         },
         "src/extension/team-tool.ts": {
           "bytesInOutput": 35293
@@ -21778,7 +21783,7 @@
           "bytesInOutput": 81
         }
       },
-      "bytes": 3080272
+      "bytes": 3083229
     }
   }
 }

package/dist/index.mjs

@@ -46604,6 +46604,17 @@ var init_team_tool_schema = __esm({
         // "description-only schema" strict-provider check.
         Type.Any()
       ),
+      analysis: Type.Optional(
+        Type.String({
+          maxLength: 1e5,
+          description: "Inline analysis/context notes from the calling session. Persisted to artifacts/{runId}/shared/analysis.md (audit trail) and auto-injected into any workflow step declaring reads: analysis.md (e.g. builtin 'plan-execute'). Mutually exclusive with analysisPath. Ignored by goal-wrapped runs and chain dispatch in v1."
+        })
+      ),
+      analysisPath: Type.Optional(
+        Type.String({
+          description: "Path to an existing markdown analysis file (resolved within cwd). Copied into shared/analysis.md. Mutually exclusive with analysis."
+        })
+      ),
       focus: Type.Optional(
         Type.String({
           description: "Sub-focus for the doctor action. 'zombies' runs a READ-ONLY scan for orphaned pi-crew sub-agent processes (identified by PI_CREW_KIND=subagent); it never kills and never matches the user's interactive main session."
@@ -69542,6 +69553,48 @@ ${tail}` : ""}`;
   }, 3e3);
   timer.unref();
 }
+function resolveAnalysisText(params, cwd) {
+  const hasInline = typeof params.analysis === "string" && params.analysis.length > 0;
+  const hasPath = typeof params.analysisPath === "string" && params.analysisPath.length > 0;
+  if (hasInline && hasPath) {
+    return {
+      error: "`analysis` and `analysisPath` are mutually exclusive. Set exactly one.",
+      source: "none"
+    };
+  }
+  if (!hasInline && !hasPath) return { source: "none" };
+  if (hasPath) {
+    let resolved;
+    try {
+      resolved = resolveContainedPath(cwd, params.analysisPath);
+    } catch {
+      return {
+        error: `analysisPath must be within project directory: ${params.analysisPath}`,
+        source: "none"
+      };
+    }
+    if (!fs90.existsSync(resolved)) {
+      return {
+        error: `Analysis file not found: ${resolved}`,
+        source: "none"
+      };
+    }
+    const { size } = fs90.statSync(resolved);
+    if (size > MAX_ANALYSIS_BYTES) {
+      return {
+        error: `Analysis file too large: ${size} bytes (max ${MAX_ANALYSIS_BYTES}). Trim the analysis or pass a summary inline.`,
+        source: "none"
+      };
+    }
+    const raw = fs90.readFileSync(resolved, "utf-8");
+    const sanitized2 = sanitizeTaskText(raw);
+    if (!sanitized2) return { source: "none" };
+    return { text: sanitized2, source: "path" };
+  }
+  const sanitized = sanitizeTaskText(params.analysis);
+  if (!sanitized) return { source: "none" };
+  return { text: sanitized, source: "inline" };
+}
 async function handleRun(params, ctx) {
   if (params.chain) {
     const { handleChainRun: handleChainRun2 } = await Promise.resolve().then(() => (init_chain_dispatch(), chain_dispatch_exports));
@@ -69625,11 +69678,14 @@ Commit or stash changes before using worktree mode, or use workspaceMode: 'singl
         id: "01_agent",
         role: params.role ?? "agent",
         task: "{goal}",
-        model: params.model
+        model: params.model,
+        reads: params.analysis || params.analysisPath ? ["analysis.md"] : void 0
       }
     ]
   } : workflows.find((item) => item.name === workflowName);
   if (!baseWorkflow) return result(`Workflow '${workflowName}' not found.`, { action: "run", status: "error" }, true);
+  const analysisParam = resolveAnalysisText(params, resolvedCtx.cwd);
+  if (analysisParam.error) return result(analysisParam.error, { action: "run", status: "error" }, true);
   const { expandParallelResearchWorkflow: expandParallelResearch } = await Promise.resolve().then(() => (init_parallel_research(), parallel_research_exports));
   const workflow = directAgent ? baseWorkflow : expandParallelResearch(baseWorkflow, resolvedCtx.cwd);
   if (!directAgent) {
@@ -69647,6 +69703,11 @@ Commit or stash changes before using worktree mode, or use workspaceMode: 'singl
   if (!directAgent && workflow.source === "builtin" && isGoalWrapEnabled(resolvedCtx.cwd, workflow.name)) {
     const decision2 = shouldGoalWrap(resolvedCtx.cwd, workflow);
     if (decision2.enabled) {
+      if (analysisParam.text) {
+        console.warn(
+          `[team-tool.run] analysis param is ignored by goal-wrapped run (workflow=${workflow.name}). The analysis artifact will not be written.`
+        );
+      }
       return await startGoalWrappedRun(params, ctx, workflow, goal);
     }
     if (decision2.message) {
@@ -69722,10 +69783,19 @@ Commit or stash changes before using worktree mode, or use workspaceMode: 'singl
 `,
     producer: "team-tool"
   });
+  const analysisArtifacts = analysisParam.text ? [
+    writeArtifact(paths.artifactsRoot, {
+      kind: "prompt",
+      relativePath: "shared/analysis.md",
+      content: `${analysisParam.text}
+`,
+      producer: "team-tool"
+    })
+  ] : [];
   const updatedManifest = {
     ...manifest,
     ...skillOverride !== void 0 ? { skillOverride } : {},
-    artifacts: [goalArtifact],
+    artifacts: [goalArtifact, ...analysisArtifacts],
     summary: "Run manifest created; worker execution is not implemented yet."
   };
   atomicWriteJson(paths.manifestPath, updatedManifest);
@@ -70239,13 +70309,14 @@ ${dwfResult.manifest.summary ?? ""}`,
     executed.manifest.status === "failed"
   );
 }
-var _cachedExecuteTeamRun, crewInitPromise;
+var _cachedExecuteTeamRun, crewInitPromise, MAX_ANALYSIS_BYTES;
 var init_run = __esm({
   "src/extension/team-tool/run.ts"() {
     "use strict";
     init_discover_agents();
     init_config();
     init_pipeline_runner();
+    init_task_packet();
     init_active_run_registry();
     init_artifact_store();
     init_atomic_write();
@@ -70265,6 +70336,7 @@ var init_run = __esm({
     init_config_patch();
     init_context();
     init_goal_wrap();
+    MAX_ANALYSIS_BYTES = 1e5;
   }
 });