pi-crew 0.9.40 → 0.9.41

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.9.41] — communication-layer optimization (2026-07-16)
+
+### Performance
+
+- **Eliminated double `JSON.parse` in `child-pi.ts` `emitLine` hot path** — `src/runtime/child-pi.ts`. The observer previously parsed each stdout line twice (once for raw assistant-text extraction, once inside `compactChildPiLine`). Now parses once and passes the result to both paths via a `preParsed` parameter. Benchmark: **2.0 → 1.0 JSON.parse/line** (~25% faster at 1000 events). Extracted shared `nonJsonLineResult` helper for the non-JSON fallback.
+- **Batched transcript writes** — `src/runtime/child-pi.ts`. Replaced per-line `open/write/close` (3 syscalls × N lines) with a module-scoped batch buffer that flushes all accumulated lines per path in a single `open/write/close` every 50ms or on lifecycle boundaries. Added `resetTranscriptBatchState()` for test isolation.
+- **Migrated non-terminal event writes to fire-and-forget** — `src/runtime/adaptive-plan.ts`. 4 diagnostic `adaptive.plan_*` events migrated to `appendEventFireAndForget`; 1 audit-critical event (`plan_injected`) upgraded to `await appendEventAsync` to prevent ordering inversion with subsequent task events.
+
+### Cleanup
+
+- **Removed dead code in `live-agent-manager.ts`** — deleted `drainIrcMessages`, `removeLiveAgentHandle`, and `listActiveLiveAgentsByWorkspace`, three internal functions with zero callers (verified via repo-wide grep; `removeLiveAgentHandle` logic was already inlined into `terminateLiveAgent`). Updated stale test comments.
+- **Stale-comment cleanup in `child-pi.ts`** — 3 comments still referenced the removed `pendingTranscriptWrites` Set after the Phase 3 batching change; updated to describe the new batch-buffer mechanism.
+
+### Documentation
+
+- **Added `docs/optimization-plan-2026-07.md`** — detailed 8-phase communication-layer optimization plan with verification gates, risk assessments, and rollback procedures.
+- **Added `docs/phase4-triage.md`** — documents the sync/async event-log migration triage, including the ordering risk between sync (filesystem lock) and async (in-process promise chain) write paths.
+- **Added `bench/child-pi-parse.bench.ts`** + baseline/final/session-verify measurement files — reproducible benchmark for the parse-count optimization.
+
+### Notes
+
+- Phase 5 (`pollRunToTerminal` → fs.watch) was attempted but reverted before review rounds. The async watcher coordination is too risky for a small win. Documented as a follow-up in `docs/optimization-plan-2026-07.md`.
+- Phases 6 (steer+control poll coalesce) and 7 (redaction trust-boundary) were skipped per the plan — Phase 6 is optional, Phase 7 was explicitly DEFER until a benchmark proves redaction is a bottleneck.
+
+### Tests
+
+- 6072 unit tests pass (was 6038 before)
+- 15+ integration tests pass
+- Lint + format:check clean (CI green on ubuntu + windows + macos)
+- New regression tests:
+  - `test/unit/child-pi-single-parse.test.ts` — 6 tests verifying single-parse invariant and preParsed path equivalence
+  - `test/unit/transcript-batch.test.ts` — 5 tests verifying batched write correctness, ordering, and timer-path flush
+- Updated `test/unit/live-agent-manager-cov.test.ts` — stale comments removed
+
 ## [0.9.40] — stale-reconciler fix + async dispatch + gitignore cleanup (2026-07-16)
 
 ### Fixes

package/dist/build-meta.json

@@ -6751,7 +6751,7 @@
       "format": "esm"
     },
     "src/runtime/live-agent-manager.ts": {
-      "bytes": 24685,
+      "bytes": 23837,
       "imports": [
         {
           "path": "src/utils/internal-error.ts",
@@ -7387,7 +7387,7 @@
       "format": "esm"
     },
     "src/runtime/child-pi.ts": {
-      "bytes": 71886,
+      "bytes": 73980,
       "imports": [
         {
           "path": "node:child_process",
@@ -15133,7 +15133,7 @@
       "format": "esm"
     },
     "src/runtime/adaptive-plan.ts": {
-      "bytes": 18288,
+      "bytes": 18395,
       "imports": [
         {
           "path": "node:fs",
@@ -17643,7 +17643,7 @@
       "format": "esm"
     },
     "src/runtime/heartbeat-watcher.ts": {
-      "bytes": 8071,
+      "bytes": 8429,
       "imports": [
         {
           "path": "node:fs",
@@ -18425,7 +18425,7 @@
       "imports": [],
       "exports": [],
       "inputs": {},
-      "bytes": 6709812
+      "bytes": 6712404
     },
     "dist/index.mjs": {
       "imports": [
@@ -20815,7 +20815,7 @@
           "bytesInOutput": 1801
         },
         "src/runtime/child-pi.ts": {
-          "bytesInOutput": 47895
+          "bytesInOutput": 48865
         },
         "src/runtime/heartbeat-gradient.ts": {
           "bytesInOutput": 953
@@ -21472,7 +21472,7 @@
           "bytesInOutput": 4743
         },
         "src/runtime/live-session-runtime.ts": {
-          "bytesInOutput": 30989
+          "bytesInOutput": 30987
         },
         "src/subagents/live/session-runtime.ts": {
           "bytesInOutput": 140
@@ -21820,7 +21820,7 @@
           "bytesInOutput": 3799
         },
         "src/runtime/adaptive-plan.ts": {
-          "bytesInOutput": 15447
+          "bytesInOutput": 15523
         },
         "src/workflows/topology-analyzer.ts": {
           "bytesInOutput": 4262
@@ -22009,7 +22009,7 @@
           "bytesInOutput": 2463
         },
         "src/runtime/heartbeat-watcher.ts": {
-          "bytesInOutput": 5931
+          "bytesInOutput": 5993
         },
         "src/extension/registration/observability.ts": {
           "bytesInOutput": 7512
@@ -22135,7 +22135,7 @@
           "bytesInOutput": 81
         }
       },
-      "bytes": 3177730
+      "bytes": 3178836
     }
   }
 }

package/dist/index.mjs

@@ -18699,34 +18699,56 @@ function appendTranscript(input, line4) {
   }
   trackTranscriptWrite(safePath, line4);
 }
-async function appendTranscriptAsync(safePath, line4) {
+function scheduleTranscriptFlush() {
+  if (transcriptFlushTimer) return;
+  transcriptFlushTimer = setTimeout(() => {
+    transcriptFlushTimer = void 0;
+    void flushTranscriptBatches();
+  }, TRANSCRIPT_FLUSH_MS);
+  transcriptFlushTimer.unref?.();
+}
+async function flushTranscriptBatches() {
+  const entries = [...transcriptBatches.entries()];
+  transcriptBatches.clear();
+  await Promise.allSettled(
+    entries.map(async ([safePath, lines]) => {
+      if (lines.length === 0) return;
+      const content = lines.join("");
+      try {
+        const fd = await fs28.promises.open(
+          safePath,
+          fs28.constants.O_WRONLY | fs28.constants.O_NOFOLLOW | fs28.constants.O_CREAT | fs28.constants.O_APPEND,
+          384
+        );
+        try {
+          await fd.write(content, void 0, "utf-8");
+        } finally {
+          await fd.close();
+        }
+      } catch (error) {
+        logInternalError("child-pi.transcript-write-failed", error, `path=${safePath}`);
+      }
+    })
+  );
+}
+function trackTranscriptWrite(safePath, line4) {
   const content = `${redactJsonLine(line4)}
 `;
-  try {
-    const fd = await fs28.promises.open(
-      safePath,
-      fs28.constants.O_WRONLY | fs28.constants.O_NOFOLLOW | fs28.constants.O_CREAT | fs28.constants.O_APPEND,
-      384
-    );
-    try {
-      await fd.write(content, void 0, "utf-8");
-    } finally {
-      await fd.close();
-    }
-  } catch (error) {
-    logInternalError("child-pi.transcript-write-failed", error, `path=${safePath}`);
+  let batch = transcriptBatches.get(safePath);
+  if (!batch) {
+    batch = [];
+    transcriptBatches.set(safePath, batch);
   }
-}
-function trackTranscriptWrite(safePath, line4) {
-  const p = appendTranscriptAsync(safePath, line4).finally(() => {
-    pendingTranscriptWrites.delete(p);
-  });
-  pendingTranscriptWrites.add(p);
+  batch.push(content);
+  scheduleTranscriptFlush();
 }
 async function flushPendingTranscriptWrites() {
-  while (pendingTranscriptWrites.size > 0) {
-    const drained = [...pendingTranscriptWrites];
-    await Promise.allSettled(drained);
+  if (transcriptFlushTimer) {
+    clearTimeout(transcriptFlushTimer);
+    transcriptFlushTimer = void 0;
+  }
+  while (transcriptBatches.size > 0) {
+    await flushTranscriptBatches();
   }
 }
 function compactString(value, maxChars = MAX_COMPACT_CONTENT_CHARS, opts = {}) {
@@ -18832,19 +18854,27 @@ function displayTextFromCompactEvent(event) {
   }).join("\n").trim();
   return text || (typeof record.text === "string" ? record.text : void 0);
 }
-function compactChildPiLine(line4) {
-  try {
-    const parsed = JSON.parse(line4);
-    const compact = compactChildPiEvent(parsed);
-    return {
-      json: true,
-      event: compact,
-      persistedLine: compact ? JSON.stringify(compact) : "",
-      displayLine: displayTextFromCompactEvent(compact)
-    };
-  } catch {
-    return { json: false, persistedLine: line4, displayLine: line4 };
+function nonJsonLineResult(line4) {
+  return { json: false, persistedLine: line4, displayLine: line4 };
+}
+function compactChildPiLine(line4, preParsed) {
+  let parsed;
+  if (preParsed !== void 0) {
+    parsed = preParsed;
+  } else {
+    try {
+      parsed = JSON.parse(line4);
+    } catch {
+      return nonJsonLineResult(line4);
+    }
   }
+  const compact = compactChildPiEvent(parsed);
+  return {
+    json: true,
+    event: compact,
+    persistedLine: compact ? JSON.stringify(compact) : "",
+    displayLine: displayTextFromCompactEvent(compact)
+  };
 }
 async function observeStdoutChunk(input, text) {
   const observer = new ChildPiLineObserver(input);
@@ -19611,7 +19641,7 @@ ${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 1e-
     }
   }
 }
-var POST_EXIT_STDIO_GUARD_MS, FINAL_DRAIN_MS, HARD_KILL_MS, RESPONSE_TIMEOUT_MS, MAX_CAPTURE_BYTES, MAX_ASSISTANT_TEXT_CHARS, MAX_TOOL_RESULT_CHARS, MAX_TOOL_INPUT_CHARS, MAX_COMPACT_CONTENT_CHARS, activeChildProcesses, childHardKillTimers, BASE_ALLOWLIST, pendingTranscriptWrites, ChildPiLineObserver;
+var POST_EXIT_STDIO_GUARD_MS, FINAL_DRAIN_MS, HARD_KILL_MS, RESPONSE_TIMEOUT_MS, MAX_CAPTURE_BYTES, MAX_ASSISTANT_TEXT_CHARS, MAX_TOOL_RESULT_CHARS, MAX_TOOL_INPUT_CHARS, MAX_COMPACT_CONTENT_CHARS, activeChildProcesses, childHardKillTimers, BASE_ALLOWLIST, transcriptBatches, transcriptFlushTimer, TRANSCRIPT_FLUSH_MS, ChildPiLineObserver;
 var init_child_pi = __esm({
   "src/runtime/child-pi.ts"() {
     "use strict";
@@ -19693,7 +19723,8 @@ var init_child_pi = __esm({
       "PI_CREW_MAX_OUTPUT",
       "PI_CREW_STEERING_FILE"
     ];
-    pendingTranscriptWrites = /* @__PURE__ */ new Set();
+    transcriptBatches = /* @__PURE__ */ new Map();
+    TRANSCRIPT_FLUSH_MS = 50;
     ChildPiLineObserver = class _ChildPiLineObserver {
       buffer = "";
       input;
@@ -19753,9 +19784,14 @@ var init_child_pi = __esm({
       }
       emitLine(line4) {
         if (!line4.trim()) return;
+        let parsed;
         try {
-          const rawParsed = JSON.parse(line4);
-          const rawTexts = extractText(rawParsed);
+          parsed = JSON.parse(line4);
+        } catch {
+          parsed = void 0;
+        }
+        if (parsed !== void 0) {
+          const rawTexts = extractText(parsed);
           if (rawTexts.length > 0) {
             this.rawTextEvents.push(...rawTexts);
             const rawOverflow = this.rawTextEvents.length - _ChildPiLineObserver.MAX_RAW_TEXT_EVENTS;
@@ -19767,9 +19803,8 @@ var init_child_pi = __esm({
               if (findingsOverflow > 0) this.intermediateFindings.splice(0, findingsOverflow);
             }
           }
-        } catch {
         }
-        const compact = compactChildPiLine(line4);
+        const compact = parsed !== void 0 ? compactChildPiLine(line4, parsed) : nonJsonLineResult(line4);
         if (compact.event !== void 0) {
           try {
             this.input.onJsonEvent?.(compact.event);
@@ -42511,9 +42546,9 @@ function loadLiveSessionModule() {
 }
 function appendTranscript2(filePath, event) {
   if (!filePath) return;
-  void appendTranscriptAsync2(filePath, event);
+  void appendTranscriptAsync(filePath, event);
 }
-async function appendTranscriptAsync2(filePath, event) {
+async function appendTranscriptAsync(filePath, event) {
   try {
     await fs49.promises.mkdir(path42.dirname(filePath), { recursive: true });
     const content = `${JSON.stringify(redactSecrets(event))}
@@ -60054,7 +60089,7 @@ async function injectAdaptivePlanIfReady(input) {
       missingPlan: false
     };
   if (!completedAssess.resultArtifact?.path) {
-    appendEvent(input.manifest.eventsPath, {
+    appendEventFireAndForget(input.manifest.eventsPath, {
       type: "adaptive.plan_missing",
       runId: input.manifest.runId,
       taskId: completedAssess.id,
@@ -60073,7 +60108,7 @@ async function injectAdaptivePlanIfReady(input) {
   try {
     text = fs85.readFileSync(resultPath, "utf-8");
   } catch {
-    appendEvent(input.manifest.eventsPath, {
+    appendEventFireAndForget(input.manifest.eventsPath, {
       type: "adaptive.plan_missing",
       runId: input.manifest.runId,
       taskId: assessTask.id,
@@ -60104,7 +60139,7 @@ async function injectAdaptivePlanIfReady(input) {
         updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
         artifacts: [...input.manifest.artifacts, repairArtifact]
       });
-      appendEvent(input.manifest.eventsPath, {
+      appendEventFireAndForget(input.manifest.eventsPath, {
         type: "adaptive.plan_repaired",
         runId: input.manifest.runId,
         taskId: assessTask.id,
@@ -60112,14 +60147,14 @@ async function injectAdaptivePlanIfReady(input) {
         data: { reason: repair.reason }
       });
     } else {
-      appendEvent(input.manifest.eventsPath, {
+      appendEventFireAndForget(input.manifest.eventsPath, {
         type: "adaptive.plan_repair_failed",
         runId: input.manifest.runId,
         taskId: assessTask.id,
         message: "Adaptive planner output could not be repaired.",
         data: { reason: repair.reason }
       });
-      appendEvent(input.manifest.eventsPath, {
+      appendEventFireAndForget(input.manifest.eventsPath, {
         type: "adaptive.plan_missing",
         runId: input.manifest.runId,
         taskId: assessTask.id,
@@ -60186,7 +60221,7 @@ async function injectAdaptivePlanIfReady(input) {
     } : task.graph
   }));
   const allTasks = refreshTaskGraphQueues([...input.tasks, ...withGraph]);
-  appendEvent(input.manifest.eventsPath, {
+  await appendEventAsync(input.manifest.eventsPath, {
     type: "adaptive.plan_injected",
     runId: input.manifest.runId,
     taskId: assessTask.id,
@@ -79032,6 +79067,7 @@ var init_heartbeat_watcher = __esm({
           if (!fs99.existsSync(run.stateRoot)) continue;
           const loaded = loadRunManifestById(this.opts.cwd, run.runId);
           if (!loaded) continue;
+          if (loaded.manifest.status !== "running") continue;
           for (const task of loaded.tasks) {
             if (task.status !== "running") continue;
             const key = `${run.runId}:${task.id}`;