mustard-claude 3.1.1 → 3.1.2

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "mustard-claude",
-  "version": "3.1.1",
-  "description": "Framework-agnostic CLI for Claude Code project setup",
-  "type": "module",
-  "bin": {
-    "mustard": "./bin/mustard.js"
-  },
-  "main": "dist/cli.js",
-  "types": "dist/cli.d.ts",
-  "files": [
-    "bin/",
-    "dist/",
-    "templates/"
-  ],
-  "keywords": [
-    "claude",
-    "claude-code",
-    "ai",
-    "cli",
-    "scaffold"
-  ],
-  "author": "rubensrpj",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rubensrpj/mustard.git"
-  },
-  "homepage": "https://github.com/rubensrpj/mustard#readme",
-  "bugs": {
-    "url": "https://github.com/rubensrpj/mustard/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "inquirer": "^9.2.15",
-    "ora": "^8.0.1"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "devDependencies": {
-    "@types/inquirer": "^9.0.9",
-    "@types/node": "^25.2.1",
-    "rimraf": "^6.1.2",
-    "typescript": "^5.9.3"
-  },
-  "scripts": {
-    "start": "node bin/mustard.js",
-    "build": "tsc",
-    "clean": "rimraf dist",
-    "typecheck": "tsc --noEmit",
-    "test": "node --test",
-    "release": "npm version patch && npm run build && npm publish"
-  }
-}
+{
+  "name": "mustard-claude",
+  "version": "3.1.2",
+  "description": "Framework-agnostic CLI for Claude Code project setup",
+  "type": "module",
+  "bin": {
+    "mustard": "./bin/mustard.js"
+  },
+  "main": "dist/cli.js",
+  "types": "dist/cli.d.ts",
+  "files": [
+    "bin/",
+    "dist/",
+    "templates/"
+  ],
+  "scripts": {
+    "start": "node bin/mustard.js",
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "release": "npm version patch && npm run build && npm publish"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "cli",
+    "scaffold"
+  ],
+  "author": "rubensrpj",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rubensrpj/mustard.git"
+  },
+  "homepage": "https://github.com/rubensrpj/mustard#readme",
+  "bugs": {
+    "url": "https://github.com/rubensrpj/mustard/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "inquirer": "^9.2.15",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^25.2.1",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/CLAUDE.md

@@ -55,6 +55,7 @@ node scripts/sync-registry.js --force
 - PreToolUse hooks use `permissionDecision` response format
 - PostToolUse hooks use `decision` response format
 - Every new hook must be registered in `settings.json` with a timeout
+- Task dispatch failures (API overload) are logged to `pipeline-state.lastDispatchFailure`; `/resume` auto-recovers within 10 min
 - Generated files must start with `<!-- mustard:generated -->` header
 - Skills must have YAML frontmatter BEFORE the `<!-- mustard:generated -->` line
 

package/templates/commands/mustard/feature/SKILL.md

@@ -155,7 +155,7 @@ When user chooses "Approve and implement now":
 6. Dispatch agents (wave rules: DB+Backend parallel, Frontend after Backend UNLESS spec marks task as `(parallel-safe)` — see `pipeline-config.md` Parallel Rules). Agent prompt includes `{recommended_skills}` as skill hints — agents read SKILL.md of relevant skills before implementing
 7. Wave transitions between waves (from `pipeline-config.md`)
 8. On return: validate (build/type-check), update spec `[ ]` → `[x]` (line-by-line edits, NEVER copy entire spec blocks as old_string)
-8b. **Agent Memory:** After agents return and spec is updated, write agent memory: `echo '{"agent_type":"{type}","wave":{N},"pipeline":"{spec-name}","summary":"{what agent did}","details":{...}}' | node .claude/scripts/memory-write.js` — one per agent. Skip if single-wave pipeline (no downstream agents to benefit).
+8b. **Agent Memory:** After agents return and spec is updated, write agent memory: `node .claude/scripts/memory-write.js --json '{"agent_type":"{type}","wave":{N},"pipeline":"{spec-name}","summary":"{what agent did}","details":{...}}'` — one per agent. Skip if single-wave pipeline (no downstream agents to benefit).
 
 #### Escalation Status Handling
 

package/templates/commands/mustard/resume/SKILL.md

@@ -12,6 +12,25 @@ Resumes an interrupted pipeline. The main context BECOMES the Pipeline Runner
 
 ## Action
 
+### Step 0: Dispatch Failure Pre-Check
+
+Before the normal detect-and-confirm flow, scan the newest pipeline state for a recent dispatch failure flagged by `subagent-tracker` (PostToolUse on Task).
+
+1. Glob `.claude/.pipeline-states/*.json` (exclude `*.metrics.json`) and pick the file with the newest mtime.
+2. Read it and inspect the `lastDispatchFailure` field.
+3. If present:
+   - Compute `ageMs = Date.now() - new Date(lastDispatchFailure.at).getTime()`.
+   - **If ageMs <= 10 * 60 * 1000** (≤10 min, fresh):
+     1. Inform the user: `Detected failed dispatch ({agentType}) due to {reason} at {at}. Re-dispatching with same prompt.`
+     2. Re-invoke the Task tool with:
+        - `subagent_type`: `lastDispatchFailure.agentType` (fallback: `general-purpose`)
+        - `description`: `lastDispatchFailure.description`
+        - `prompt`: `lastDispatchFailure.prompt`
+     3. After the re-dispatch returns, clear the flag: remove `lastDispatchFailure` from the state object and rewrite the pipeline-state JSON.
+     4. Fall through to Step 1 (normal resume flow continues from the updated state).
+   - **If ageMs > 10 * 60 * 1000** (stale): silently remove `lastDispatchFailure` from the state and rewrite the file, then continue to Step 1.
+4. If `lastDispatchFailure` is absent, skip Step 0 entirely and proceed to Step 1.
+
 ### Step 1: Detect & Confirm
 
 1. Glob `.claude/spec/active/*/spec.md` — if 0 specs → inform user and stop
@@ -103,7 +122,7 @@ Run `node .claude/scripts/diff-context.js` to capture the current git state. Inc
 
 17b. **Agent Memory:** After each wave completes and spec checkboxes are updated, write agent memories for downstream waves:
     ```bash
-    echo '{"agent_type":"{agent_type}","wave":{N},"pipeline":"{spec-name}","summary":"{1-line summary of what agent did}","details":{"files_modified":[...],"decisions":[...]}}' | node .claude/scripts/memory-write.js
+    node .claude/scripts/memory-write.js --json '{"agent_type":"{agent_type}","wave":{N},"pipeline":"{spec-name}","summary":"{1-line summary of what agent did}","details":{"files_modified":[...],"decisions":[...]}}'
     ```
     One call per agent in the completed wave. Summary ≤300 chars (key facts: files created, patterns used, endpoints added). Skip if no downstream waves remain.
 
@@ -167,7 +186,7 @@ When a pipeline is paused (user leaves session or requests pause):
    - Set `nextAction` to the specific next step (ONE sentence)
 2. Write agent memory for carry-over:
    ```bash
-   echo '{"agent_type":"orchestrator","wave":0,"pipeline":"{spec-name}","summary":"Paused at {phase}. Next: {nextAction}"}' | node .claude/scripts/memory-write.js
+   node .claude/scripts/memory-write.js --json '{"agent_type":"orchestrator","wave":0,"pipeline":"{spec-name}","summary":"Paused at {phase}. Next: {nextAction}"}'
    ```
 3. Confirm to user: "Pipeline paused. Next action saved: {nextAction}"
 

package/templates/commands/mustard/templates/agent-prompt/SKILL.md

@@ -2,16 +2,21 @@
 
 Orchestrator fills `{placeholders}` before dispatch. Agent receives the rendered version.
 
----
+Single unified template for all dispatches:
+- When `.claude/agents/{subproject}-impl.md` **exists**: orchestrator leaves `{role_block}` empty (role/boundary/validate/return already defined in the custom agent).
+- When it **does NOT exist**: orchestrator fills `{role_block}` with `ROLE: {role} — {boundary}` / `Validate: {validate_command}` / `Return: {return_sections}`.
+
+`{context_extras}` is optional (e.g. extra line to read `notes.md`); leave empty when unused.
 
-## Compact Template (custom agent — role already defined in agent)
+---
 
-Use when `.claude/agents/{subproject}-impl.md` exists. Role, boundary, return format, and validation are already in the agent definition — prompt only needs references + entity + task.
+## Dispatch Template
 
 ```
 ## CONTEXT
-1. Read `{subproject}/CLAUDE.md` — guards, stack, key paths
+1. Read `{subproject}/CLAUDE.md` — guards, stack, paths
 2. Read `{subproject}/.claude/commands/guards.md` — mandatory rules
+{context_extras}
 
 ## REFERENCE
 {reference_files}
@@ -20,67 +25,26 @@ Use when `.claude/agents/{subproject}-impl.md` exists. Role, boundary, return fo
 {entity_info}
 
 ## SKILLS
-Your available skills are listed in the system. Before implementing, check if any skill matches your task — read its SKILL.md for patterns and examples.
-Key skills for this task: {recommended_skills}
-If a skill has `references/` files, read them only when you need concrete code examples.
+Available skills listed in system. Read SKILL.md only if task matches. Key: {recommended_skills}
+Load references/ only for concrete examples.
 
 ## WEB VALIDATION
-When in doubt about API usage, library version, or implementation pattern: search the web for the latest documentation before implementing. Only proceed when 100% confident.
+In doubt about API/version/pattern → search web for latest docs before implementing.
+
+## ROLE
+{role_block}
 
 ## EFFICIENCY
-- Absolute paths — NEVER cd
-- Chain kill+build in single Bash
-- Max 3 build attempts → STOP + report
+- Absolute paths, no cd
+- Read each file once
+- Max 3 build attempts, then STOP + report
 
 {retry_context}
 
 ## TASK
 {task_steps}
-```
-
----
-
-## Full Template (fallback — general-purpose agent, no custom agent)
-
-Use when `.claude/agents/{subproject}-impl.md` does NOT exist.
-
-```
-## STEP 0: READ CONTEXT
-1. `{subproject}/CLAUDE.md` — guards, stack, key paths
-2. `{subproject}/.claude/commands/guards.md` — mandatory rules
-3. `{subproject}/.claude/commands/notes.md` — project-specific notes
-
-## REFERENCE MODULE
-{reference_files}
 
-## GUARDS (verify in return)
-{guards_summary}
-
-## ENTITY REGISTRY
-{entity_info}
-
-## SKILLS
-Your available skills are listed in the system. Before implementing, check if any skill matches your task — read its SKILL.md for patterns and examples.
-Key skills for this task: {recommended_skills}
-If a skill has `references/` files, read them only when you need concrete code examples.
-
-## WEB VALIDATION
-When in doubt about API usage, library version, or implementation pattern: search the web for the latest documentation before implementing. Only proceed when 100% confident.
-
-## ROLE: {role} — {boundary}
-Validate: {validate_command}
-Return: {return_sections}
-
-## EFFICIENCY RULES
-- Shell state does NOT persist between Bash calls — ALWAYS use absolute paths, NEVER cd
-- Build: {build_command}
-- Read each file ONCE — trust your edit
-- Max 3 build attempts/step. After 3rd: STOP and report error.
-
-{retry_context}
-
-## TASK — Execute in order
-{task_steps}
+Guards carregados via CLAUDE.md acima — respeite sem exceção.
 ```
 
 ---

package/templates/hooks/__tests__/hooks.test.js

@@ -265,6 +265,25 @@ describe("memory-write.js", () => {
     });
   }
 
+  function runScriptArg(inputObj, opts = {}) {
+    return new Promise((resolve, reject) => {
+      const cwd = opts.cwd || PROJECT_DIR;
+      const child = spawn(
+        process.execPath,
+        [path.join(SCRIPTS_DIR, "memory-write.js"), "--json", JSON.stringify(inputObj)],
+        { cwd, stdio: ["ignore", "pipe", "pipe"] }
+      );
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (d) => (stdout += d));
+      child.stderr.on("data", (d) => (stderr += d));
+      child.on("error", reject);
+      child.on("close", (code) => {
+        resolve({ code, stdout: stdout.trim(), stderr: stderr.trim() });
+      });
+    });
+  }
+
   it("should create memory entry and index", async () => {
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem-test-"));
     const memDir = path.join(tmpDir, ".claude", ".agent-memory");
@@ -317,6 +336,32 @@ describe("memory-write.js", () => {
     const result = await runScript("not valid json");
     assert.equal(result.code, 0, "Should exit 0 even on bad input");
   });
+
+  it("should accept input via --json arg (Windows-friendly mode)", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem-test-arg-"));
+    const memDir = path.join(tmpDir, ".claude", ".agent-memory");
+    try {
+      const result = await runScriptArg({
+        cwd: tmpDir,
+        agent_type: "arg-impl",
+        wave: 2,
+        pipeline: "arg-pipeline",
+        summary: "Wrote via --json arg mode.",
+        details: { mode: "arg" },
+      });
+      assert.equal(result.code, 0, `Exit code should be 0, stderr: ${result.stderr}`);
+      assert.ok(fs.existsSync(memDir), "Memory dir should exist");
+      const indexPath = path.join(memDir, "_index.json");
+      assert.ok(fs.existsSync(indexPath), "Index file should exist");
+      const index = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+      assert.equal(index.length, 1, "Index should have 1 entry");
+      assert.equal(index[0].agent_type, "arg-impl");
+      assert.equal(index[0].wave, 2);
+      assert.ok(index[0].summary.includes("arg mode"), "Summary should round-trip");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
 });
 
 // ─── subagent-tracker.js (memory injection) ─────────────────────────────────
@@ -384,3 +429,168 @@ describe("subagent-tracker.js memory injection", () => {
     }
   });
 });
+
+// ─── metrics-tracker.js (sidecar + no-recursion) ────────────────────────────
+
+describe("metrics-tracker.js", () => {
+  const hook = "metrics-tracker.js";
+
+  function setupPipelineState(tmpDir) {
+    const statesDir = path.join(tmpDir, ".claude", ".pipeline-states");
+    fs.mkdirSync(statesDir, { recursive: true });
+    const pipelinePath = path.join(statesDir, "test-pipeline.json");
+    fs.writeFileSync(pipelinePath, JSON.stringify({
+      v: 1,
+      name: "test-pipeline",
+      phase: "EXECUTE",
+      phaseName: "EXECUTE",
+      status: "approved",
+      startedAt: "2026-04-05T10:00:00.000Z",
+    }), "utf8");
+    return { statesDir, pipelinePath };
+  }
+
+  it("should write metrics to sidecar and leave pipeline-state untouched", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "metrics-test-"));
+    const { statesDir, pipelinePath } = setupPipelineState(tmpDir);
+    const sidecarPath = path.join(statesDir, "test-pipeline.metrics.json");
+    try {
+      const mtimeBefore = fs.statSync(pipelinePath).mtimeMs;
+      // Wait a beat so any write would produce a different mtime
+      await new Promise((r) => setTimeout(r, 50));
+
+      const result = await runHook(hook, {
+        tool_name: "Edit",
+        tool_input: { file_path: path.join(tmpDir, "src/foo.ts") },
+        cwd: tmpDir,
+      }, { cwd: tmpDir, projectDir: tmpDir });
+
+      assert.equal(result.code, 0);
+      const mtimeAfter = fs.statSync(pipelinePath).mtimeMs;
+      assert.equal(mtimeAfter, mtimeBefore, "pipeline-state.json must NOT be modified");
+      assert.ok(fs.existsSync(sidecarPath), "sidecar must be created");
+      const sidecar = JSON.parse(fs.readFileSync(sidecarPath, "utf8"));
+      assert.equal(sidecar.metrics.apiCalls, 1);
+      assert.equal(sidecar.metrics.toolBreakdown.Edit, 1);
+      assert.equal(sidecar.previousPhase, "EXECUTE");
+      assert.equal(sidecar.metrics.startedAt, "2026-04-05T10:00:00.000Z", "startedAt inherited from pipeline-state");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("should not create recursive .metrics.metrics.json sidecars across multiple calls", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "metrics-recursion-"));
+    const { statesDir } = setupPipelineState(tmpDir);
+    try {
+      // Fire 5 PostToolUse events in sequence
+      for (let i = 0; i < 5; i++) {
+        const r = await runHook(hook, {
+          tool_name: "Write",
+          tool_input: { file_path: path.join(tmpDir, `src/file${i}.ts`) },
+          cwd: tmpDir,
+        }, { cwd: tmpDir, projectDir: tmpDir });
+        assert.equal(r.code, 0);
+      }
+
+      const files = fs.readdirSync(statesDir).sort();
+      assert.deepEqual(
+        files,
+        ["test-pipeline.json", "test-pipeline.metrics.json"],
+        `Only 2 files expected, got: ${files.join(", ")}`
+      );
+
+      const sidecar = JSON.parse(
+        fs.readFileSync(path.join(statesDir, "test-pipeline.metrics.json"), "utf8")
+      );
+      assert.equal(sidecar.metrics.apiCalls, 5, "All 5 calls must aggregate into the same sidecar");
+      assert.equal(sidecar.metrics.toolBreakdown.Write, 5);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── subagent-tracker.js (overload detection) ───────────────────────────────
+
+describe("subagent-tracker.js overload detection", () => {
+  const hook = "subagent-tracker.js";
+
+  function setupPipelineState(tmpDir) {
+    const statesDir = path.join(tmpDir, ".claude", ".pipeline-states");
+    fs.mkdirSync(statesDir, { recursive: true });
+    const pipelinePath = path.join(statesDir, "p.json");
+    fs.writeFileSync(pipelinePath, JSON.stringify({
+      v: 1,
+      phase: "EXECUTE",
+      startedAt: "2026-04-05T10:00:00.000Z",
+    }), "utf8");
+    fs.mkdirSync(path.join(tmpDir, ".claude", ".agent-state"), { recursive: true });
+    return pipelinePath;
+  }
+
+  async function dispatchTaskResult(tmpDir, toolResponse) {
+    return runHook(hook, {
+      hook_event_name: "PostToolUse",
+      tool_name: "Task",
+      tool_input: {
+        subagent_type: "general-purpose",
+        description: "test dispatch",
+        prompt: "Do something",
+      },
+      tool_response: toolResponse,
+      cwd: tmpDir,
+    }, { cwd: tmpDir, projectDir: tmpDir });
+  }
+
+  it("should flag lastDispatchFailure on real overload (is_error=true + 529)", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "overload-real-"));
+    const pipelinePath = setupPipelineState(tmpDir);
+    try {
+      const r = await dispatchTaskResult(tmpDir, {
+        is_error: true,
+        content: "Error: 529 overloaded",
+      });
+      assert.equal(r.code, 0);
+      const state = JSON.parse(fs.readFileSync(pipelinePath, "utf8"));
+      assert.ok(state.lastDispatchFailure, "flag must be set");
+      assert.equal(state.lastDispatchFailure.reason, "api_overload");
+      assert.equal(state.lastDispatchFailure.agentType, "general-purpose");
+      assert.equal(state.lastDispatchFailure.description, "test dispatch");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("should NOT flag on happy-path agent that merely documents rate limiting", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "overload-docs-"));
+    const pipelinePath = setupPipelineState(tmpDir);
+    try {
+      const r = await dispatchTaskResult(tmpDir, {
+        is_error: false,
+        content: "Documented rate limiting, 429 and 529 handling, api error recovery.",
+      });
+      assert.equal(r.code, 0);
+      const state = JSON.parse(fs.readFileSync(pipelinePath, "utf8"));
+      assert.equal(state.lastDispatchFailure, undefined, "flag must NOT be set (false positive guard)");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("should NOT flag on unrelated error (is_error=true without overload keywords)", async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "overload-unrelated-"));
+    const pipelinePath = setupPipelineState(tmpDir);
+    try {
+      const r = await dispatchTaskResult(tmpDir, {
+        is_error: true,
+        content: "SyntaxError in src/foo.ts line 42",
+      });
+      assert.equal(r.code, 0);
+      const state = JSON.parse(fs.readFileSync(pipelinePath, "utf8"));
+      assert.equal(state.lastDispatchFailure, undefined, "unrelated failure must not be flagged as overload");
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

package/templates/hooks/metrics-tracker.js

@@ -31,7 +31,7 @@ process.stdin.on('end', () => {
     const statesDir = path.join(cwd, '.claude', '.pipeline-states');
     if (!fs.existsSync(statesDir)) { process.exit(0); }
 
-    const files = fs.readdirSync(statesDir).filter(f => f.endsWith('.json'));
+    const files = fs.readdirSync(statesDir).filter(f => f.endsWith('.json') && !f.endsWith('.metrics.json'));
     if (files.length === 0) { process.exit(0); }
 
     // Update the most recently modified pipeline state
@@ -50,34 +50,64 @@ process.stdin.on('end', () => {
 
     if (!newest) { process.exit(0); }
 
-    const state = JSON.parse(fs.readFileSync(newest, 'utf8'));
-
-    // Initialize metrics if not present
-    if (!state.metrics) {
-      state.metrics = {
+    // Read pipeline-state.json READ-ONLY (to derive currentPhase, status, startedAt).
+    // Never write to it — metrics live in a sidecar to avoid "file modified since
+    // read" races with Edit/Write on the pipeline-state file.
+    let pipelineState = {};
+    try {
+      pipelineState = JSON.parse(fs.readFileSync(newest, 'utf8'));
+    } catch {}
+
+    const sidecarPath = newest.replace(/\.json$/, '.metrics.json');
+    let sidecar;
+    if (fs.existsSync(sidecarPath)) {
+      try {
+        sidecar = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+      } catch {
+        sidecar = null;
+      }
+    }
+    if (!sidecar || typeof sidecar !== 'object') {
+      sidecar = {
+        v: 1,
+        metrics: {
+          apiCalls: 0,
+          toolBreakdown: {},
+          retries: 0,
+          startedAt: pipelineState.startedAt || new Date().toISOString(),
+        },
+        previousPhase: '',
+      };
+    }
+    if (!sidecar.metrics) {
+      sidecar.metrics = {
         apiCalls: 0,
         toolBreakdown: {},
         retries: 0,
-        startedAt: state.startedAt || new Date().toISOString(),
+        startedAt: pipelineState.startedAt || new Date().toISOString(),
       };
     }
+    if (!sidecar.metrics.toolBreakdown) sidecar.metrics.toolBreakdown = {};
+
+    // Alias for minimal churn below — all mutations go to the sidecar.
+    const state = sidecar;
 
     // ── wave_reentry: track EXECUTE → PLAN transitions ──────────────────────
     // previousPhase is updated on every write so we can detect phase changes.
-    const currentPhase = state.phaseName || state.phase || '';
-    const previousPhase = state.previousPhase || '';
+    const currentPhase = pipelineState.phaseName || pipelineState.phase || '';
+    const previousPhase = sidecar.previousPhase || '';
     if (currentPhase === 'PLAN' && previousPhase === 'EXECUTE') {
       state.metrics.wave_reentry = (state.metrics.wave_reentry || 0) + 1;
     }
     // Always update previousPhase to the current phase so the NEXT write can
     // detect a transition.
-    state.previousPhase = currentPhase;
+    sidecar.previousPhase = currentPhase;
 
     // ── gate_saves: spec edits in PLAN phase after first /approve ────────────
-    // Proxy for "first approve recorded": state.status === 'approved' (set by
-    // /approve command).  A spec file is any .md in .claude/spec/ or matching
-    // *spec*.md anywhere in the pipeline-states dir.
-    if ((toolName === 'Edit' || toolName === 'Write') && currentPhase === 'PLAN' && state.status === 'approved') {
+    // Proxy for "first approve recorded": pipelineState.status === 'approved'
+    // (set by /approve command).  A spec file is any .md in .claude/spec/ or
+    // matching *spec*.md anywhere in the pipeline-states dir.
+    if ((toolName === 'Edit' || toolName === 'Write') && currentPhase === 'PLAN' && pipelineState.status === 'approved') {
       const toolFilePath = (data.tool_input || {}).file_path || (data.tool_input || {}).path || '';
       const isSpecFile =
         /[/\\]\.claude[/\\]spec[/\\]/.test(toolFilePath) ||
@@ -151,7 +181,8 @@ process.stdin.on('end', () => {
 
     state.metrics.updatedAt = new Date().toISOString();
 
-    fs.writeFileSync(newest, JSON.stringify(state, null, 2), 'utf8');
+    // Write ONLY the sidecar — never touch pipeline-state.json from this hook.
+    fs.writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2), 'utf8');
 
     process.exit(0);
   } catch (err) {

package/templates/hooks/subagent-tracker.js

@@ -2,11 +2,12 @@
 /**
  * SUBAGENT TRACKER: Tracks active subagents for statusline display
  *
- * Handles 4 events:
- * - PreToolUse(Task): queues description + type before agent starts
- * - SubagentStart:    writes agent state file (consumes from queue)
- * - SubagentStop:     removes agent state file + prunes stale queue
- * - SessionStart:     cleans up stale state from previous sessions
+ * Handles 5 events:
+ * - PreToolUse(Task):  queues description + type before agent starts
+ * - PostToolUse(Task): detects API overload / dispatch failures and flags pipeline state
+ * - SubagentStart:     writes agent state file (consumes from queue)
+ * - SubagentStop:      removes agent state file + prunes stale queue
+ * - SessionStart:      cleans up stale state from previous sessions
  *
  * State dir: .claude/.agent-state/{agent_id}.json
  * Queue:     .claude/.agent-state/_queue.json
@@ -42,6 +43,8 @@ process.stdin.on('end', () => {
 
     if (event === 'PreToolUse' && data.tool_name === 'Task') {
       handlePreToolUse(data, stateDir);
+    } else if (event === 'PostToolUse' && data.tool_name === 'Task') {
+      handlePostToolUse(data, stateDir);
     } else if (event === 'SubagentStart') {
       handleStart(data, stateDir);
     } else if (event === 'SubagentStop') {
@@ -177,6 +180,65 @@ function parseRecommendedSkills(prompt) {
   return skills;
 }
 
+/**
+ * PostToolUse(Task): Detect API overload / dispatch failures in tool_response
+ * and flag the active pipeline state with `lastDispatchFailure` so /resume can
+ * auto-recover.
+ *
+ * We write to pipeline-state ONLY when a failure is detected — happy-path
+ * dispatches never touch the state file from here.
+ */
+function handlePostToolUse(data, stateDir) {
+  try {
+    if (isSelfDelegation(data)) { return; }
+
+    const toolResponse = data.tool_response || {};
+    const responseText = JSON.stringify(toolResponse).toLowerCase();
+    // Detect overload conservatively: require is_error=true (Claude Code sets
+    // this on Task tool failures) AND at least one overload keyword. This
+    // avoids false positives on agents that merely *document* rate limiting
+    // or error handling in their returned content.
+    const isOverload =
+      toolResponse.is_error === true &&
+      /overload|rate.?limit|\b429\b|\b529\b|throttl|too many requests/.test(responseText);
+
+    if (!isOverload) return;
+
+    const projectDir = path.resolve(stateDir, '..', '..');
+    const statesDir = path.join(projectDir, '.claude', '.pipeline-states');
+    if (!fs.existsSync(statesDir)) return;
+
+    const files = fs.readdirSync(statesDir)
+      .filter(f => f.endsWith('.json') && !f.endsWith('.metrics.json'));
+    if (files.length === 0) return;
+
+    let newest = null;
+    let newestMtime = 0;
+    for (const f of files) {
+      try {
+        const fp = path.join(statesDir, f);
+        const stat = fs.statSync(fp);
+        if (stat.mtimeMs > newestMtime) {
+          newestMtime = stat.mtimeMs;
+          newest = fp;
+        }
+      } catch {}
+    }
+    if (!newest) return;
+
+    const toolInput = data.tool_input || {};
+    const state = JSON.parse(fs.readFileSync(newest, 'utf8'));
+    state.lastDispatchFailure = {
+      at: new Date().toISOString(),
+      reason: 'api_overload',
+      agentType: toolInput.subagent_type || 'unknown',
+      description: toolInput.description || '',
+      prompt: (toolInput.prompt || '').slice(0, 2000),
+    };
+    fs.writeFileSync(newest, JSON.stringify(state, null, 2), 'utf8');
+  } catch {} // fail-open: failure detection is advisory
+}
+
 function handleStart(data, stateDir) {
   const agentId = data.agent_id || `unknown-${Date.now()}`;
   const agentType = data.agent_type || 'unknown';

package/templates/scripts/memory-write.js

@@ -3,10 +3,14 @@
 /**
  * memory-write.js
  *
- * Receives a JSON memory entry from stdin and persists it to
+ * Receives a JSON memory entry and persists it to
  * {projectDir}/.claude/.agent-memory/.
  *
- * Input schema (stdin):
+ * Input (two modes):
+ *   1. --json '<JSON>' CLI arg (Windows-friendly, avoids shell echo pipe issues)
+ *   2. stdin piped JSON (POSIX)
+ *
+ * Input schema:
  *   {
  *     "agent_type": "templates-impl",
  *     "wave": 1,
@@ -110,17 +114,24 @@ function resolveSessionPrefix(projectDir) {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  // Collect stdin.
   let raw = "";
-  for await (const chunk of process.stdin) {
-    raw += chunk;
+
+  // --json arg mode (Windows-friendly: avoids shell echo pipe issues)
+  const jsonArgIdx = process.argv.indexOf("--json");
+  if (jsonArgIdx !== -1 && process.argv[jsonArgIdx + 1]) {
+    raw = process.argv[jsonArgIdx + 1];
+  } else {
+    // stdin fallback (POSIX)
+    for await (const chunk of process.stdin) {
+      raw += chunk;
+    }
   }
 
   let input;
   try {
     input = JSON.parse(raw);
   } catch (err) {
-    process.stderr.write(`[memory-write] Failed to parse stdin JSON: ${err.message}\n`);
+    process.stderr.write(`[memory-write] Failed to parse input JSON: ${err.message}\n`);
     process.exit(0);
   }
 

package/templates/settings.json

@@ -146,6 +146,11 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-knowledge-inc.js",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/subagent-tracker.js",
+            "timeout": 3
           }
         ]
       }