@chorus-aidlc/chorus 0.19.0 → 0.20.0

package/cli/upgrade.mjs

@@ -0,0 +1,125 @@
+import * as fs from "node:fs";
+import { dirname, posix, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runUpgradeCommand, runUpgradeInstall, sanitizeUpgradeOutput, upgradeFailure } from "./upgrade-process.mjs";
+// Eagerly load every collaborator before npm can replace this package.
+import { upgradePlugins } from "./upgrade-plugins.mjs";
+
+export const PACKAGE = "@chorus-aidlc/chorus";
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export const upgradeHelp = `Usage: chorus upgrade [--plugins]
+       chorus update [--plugins]
+
+Upgrade the active npm global Chorus installation to the latest stable release.
+  --plugins   Also refresh Chorus plugins for configured daemon agents.
+  -h, --help  Show help without checking or changing anything.
+
+Exit 0: all requested work completed. Exit 1: failed or incomplete.
+Source checkouts, linked installations and other package managers are unsupported.
+`;
+
+function newer(a, b) {
+  const aa = a.split("+")[0].split(".").map(BigInt), bb = b.split("+")[0].split(".").map(BigInt);
+  for (let i = 0; i < 3; i++) if (aa[i] !== bb[i]) return aa[i] > bb[i];
+  return false;
+}
+
+export async function upgradeCli(deps = {}) {
+  const io = deps.fs ?? fs;
+  const platform = deps.platform ?? process.platform;
+  const p = platform === "win32" ? win32 : posix;
+  const env = deps.env ?? process.env;
+  const run = deps.run ?? runUpgradeCommand;
+  const root = deps.packageRoot ?? PACKAGE_ROOT;
+  const same = (a, b) => platform === "win32"
+    ? p.normalize(a).toLowerCase() === p.normalize(b).toLowerCase()
+    : p.normalize(a) === p.normalize(b);
+  const read = (path) => JSON.parse(io.readFileSync(path, "utf8"));
+  const command = (args, timeoutMs = 30_000) => {
+    const r = run("npm", args, { env, platform, timeoutMs });
+    if (!r.ok) throw new Error(`npm ${args[0]} ${upgradeFailure(r, { env })}`);
+    return String(r.stdout).trim();
+  };
+  const explain = (error) => sanitizeUpgradeOutput(error?.message, { env });
+  let prefix, installed, current, latest;
+  try {
+    prefix = command(["prefix", "-g"]);
+    const globalRoot = command(["root", "-g"]);
+    const expectedRoot = platform === "win32" ? p.join(prefix, "node_modules") : p.join(prefix, "lib", "node_modules");
+    installed = p.join(globalRoot, "@chorus-aidlc", "chorus");
+    if (!p.isAbsolute(prefix) || !p.isAbsolute(globalRoot) ||
+        !same(io.realpathSync(globalRoot), io.realpathSync(expectedRoot)) ||
+        io.lstatSync(installed).isSymbolicLink() || io.existsSync(p.join(installed, ".git")) ||
+        !same(io.realpathSync(root), io.realpathSync(installed))) throw new Error();
+    const pkg = read(p.join(root, "package.json"));
+    const listing = JSON.parse(command(["ls", "-g", PACKAGE, "--depth=0", "--json", "--long"]));
+    const entry = listing.dependencies?.[PACKAGE];
+    if (pkg.name !== PACKAGE || !STABLE.test(pkg.version) || !entry ||
+        entry.name !== PACKAGE || entry.version !== pkg.version || !entry.path ||
+        !same(io.realpathSync(entry.path), io.realpathSync(installed)) ||
+        entry.link || entry.isLink || entry.invalid || entry.extraneous || entry.problems?.length) throw new Error();
+    // npm versions differ in which provenance fields they retain. When present,
+    // refuse file/git/link sources; repository metadata is NOT install provenance.
+    for (const meta of [pkg, entry]) {
+      const source = meta.resolved ?? meta._resolved;
+      if (source && !/^https?:\/\/[^?#]+\.tgz(?:\?.*)?$/.test(source)) throw new Error();
+      if (meta._from && !/^@chorus-aidlc\/chorus@[\w.*~^<>= |+-]+$/.test(meta._from)) throw new Error();
+    }
+    current = pkg.version;
+  } catch (error) {
+    return { complete: false, changed: false, detail: `Cannot verify this npm global installation. ${explain(error)}\nUse npm install -g @chorus-aidlc/chorus@latest with the intended npm prefix; source/link/other-manager installs are unsupported.` };
+  }
+  try {
+    latest = JSON.parse(command(["view", `${PACKAGE}@latest`, "version", "--json"]));
+    if (typeof latest !== "string" || !STABLE.test(latest)) throw new Error();
+  } catch (error) {
+    return { complete: false, changed: false, detail: `Latest stable version discovery failed (npm registry/network/timeout or invalid version). ${explain(error)}` };
+  }
+  if (!newer(latest, current)) {
+    return { complete: true, changed: false, detail: `CLI ${current} is current${current !== latest ? ` (latest stable ${latest}; no downgrade)` : ""}.` };
+  }
+  try {
+    deps.log?.(`Installing CLI ${current} → ${latest}; npm progress follows (no installation timeout).`);
+    const result = await (deps.runInstall ?? deps.run ?? runUpgradeInstall)(
+      "npm", ["install", "-g", `${PACKAGE}@${latest}`, "--prefix", prefix, "--no-audit", "--no-fund", "--yes"],
+      { env, platform, onOutput: (line) => deps.log?.(sanitizeUpgradeOutput(line, { env })) },
+    );
+    if (!result.ok) throw new Error(upgradeFailure(result, { env }));
+  } catch (error) {
+    const reason = explain(error);
+    const permission = /\bEACCES\b|\bEPERM\b|permission denied/i.test(reason)
+      ? " Permission denied: use a user-owned Node installation (for example nvm), or ask the administrator to update the system npm prefix; no automatic elevation is attempted."
+      : "";
+    return { complete: false, changed: true, detail: `CLI install failed (${current} → ${latest}): ${reason}.${permission} Inspect the npm installation before retrying.` };
+  }
+  try {
+    const pkg = read(p.join(installed, "package.json"));
+    if (pkg.name !== PACKAGE || pkg.version !== latest) throw new Error();
+  } catch {
+    return { complete: false, changed: true, detail: `CLI version verification failed; expected ${latest}.` };
+  }
+  return { complete: true, changed: true, detail: `CLI upgraded ${current} → ${latest} (installed version verified).` };
+}
+
+export async function runUpgrade(argv = [], deps = {}) {
+  const log = deps.log ?? console.log;
+  if (argv.some((a) => !["--plugins", "--help", "-h"].includes(a))) {
+    log("Invalid upgrade arguments. Use chorus upgrade --help.");
+    return 1;
+  }
+  if (argv.includes("--help") || argv.includes("-h")) { log(upgradeHelp); return 0; }
+  const cli = await upgradeCli({ ...deps, log });
+  log(cli.detail);
+  let complete = cli.complete, changed = cli.changed;
+  if (complete && argv.includes("--plugins")) {
+    const results = await (deps.upgradePlugins ?? upgradePlugins)(deps);
+    for (const r of results) {
+      log(`${r.target}: ${r.complete ? "OK" : "INCOMPLETE"} — ${r.detail}`);
+      complete &&= r.complete;
+      changed ||= r.changed;
+    }
+  }
+  if (changed) log("Start new agent sessions to load updated plugins; restart the Chorus daemon when convenient. Active sessions were not restarted.");
+  return complete ? 0 : 1;
+}

package/cli/upload-hooks.mjs

@@ -409,7 +409,7 @@ function stripSystemReminders(s) {
  *    does NOT echo the user prompt (the chat UI renders that from the turn's
  *    promptText), and `reasoning` / `command_execution` / lifecycle envelopes are
  *    not conversation text — all dropped.
- *  - pi (@earendil-works/pi-coding-agent) `pi --mode json`: AgentSessionEvents whose
+ *  - pi (@earendil-works/pi-coding-agent) `pi --mode rpc`: AgentSessionEvents (same as `--mode json`) whose
  *    authoritative final text is a `message_end` carrying a full AgentMessage
  *    (`{ role, content }`). We keep ONLY the assistant message: pi UNCONDITIONALLY
  *    re-emits the wake prompt as a `message_end` with role "user" (agent-loop.ts),
@@ -449,7 +449,7 @@ export function extractTranscriptText(obj) {
     return { role: "assistant", text: itemText };
   }
 
-  // ── pi `pi --mode json` dialect ──
+  // ── pi `pi --mode rpc` event dialect ──
   // pi's authoritative final text of each step is a `message_end` carrying a full
   // AgentMessage `{ role, content }`. Keep ONLY the assistant message: pi re-emits the
   // wake prompt as a role:"user" message_end (already stored as the turn's promptText),

package/cli/wake-queue.mjs

@@ -144,7 +144,11 @@ export class WakeQueue {
     }
     // Coalesce: take everything pending for this key right now as one batch.
     // Items that arrive after this splice accumulate for the NEXT batch.
-    const items = queue.splice(0);
+    // An isolated instruction (Research) keeps the same serial lane but cannot
+    // merge with lifecycle wakes before or after it.
+    const boundary = queue.findIndex((item) => item?.isolated === true);
+    const count = boundary === 0 ? 1 : boundary > 0 ? boundary : queue.length;
+    const items = queue.splice(0, count);
     this.running.add(key);
     this.activeCount++;
 

package/cli/waker.mjs

@@ -19,6 +19,7 @@
 // wake. A failure is logged and swallowed — it must never crash the daemon
 // (no-silent-errors: visible log, no throw).
 
+import { OPERATION_ACTIONS, isExactOperation, validateOperation } from "./operation.mjs";
 import { buildBatchPrompt } from "./prompts.mjs";
 import { writeMcpConfig } from "./mcp-config.mjs";
 import { isNewSession, SESSION_CONFLICT_FAILURE } from "./claude-spawner.mjs";
@@ -108,6 +109,9 @@ export class Waker {
     // (including daemon restart) starts with an empty guard.
     /** @type {Set<string>} */
     this.deterministicConflictGuards = new Set();
+    // Retry exact launch-abort reports after a network outage. These timers carry
+    // delivery cleanup only; the existing server turn remains the lifecycle authority.
+    this.operationRecoveryTimers = new Set();
     // Daemon graceful-shutdown flag (fix-daemon-exit-orphan-running-turn). Set once
     // by interruptAll() and never cleared — a shutting-down Waker is on its way out.
     // The wake exit path reads it to report the TURN as interrupted(shutdown), and to
@@ -188,6 +192,8 @@ export class Waker {
    */
   interruptAll() {
     this.shuttingDown = true;
+    for (const timer of this.operationRecoveryTimers) clearTimeout(timer);
+    this.operationRecoveryTimers.clear();
     for (const [key, entry] of this.executions) {
       if (entry.status !== "running" || !entry.child) continue;
       try {
@@ -366,9 +372,27 @@ export class Waker {
    */
   async wakeBatch(notifications, key, attribution) {
     let cfg;
+    let operationTurnUuid = null;
     const receivedList = Array.isArray(notifications) ? notifications : [];
+    // Defense in depth for callers bypassing the router: malformed operations
+    // never clear a conflict guard, request admission or settle a pending turn.
+    try {
+      for (const n of receivedList.filter((n) => OPERATION_ACTIONS.has(n?.action))) {
+        validateOperation(n.action, n.operationPayload, {
+          sessionId: n.sessionId, directIdeaUuid: attribution?.directIdeaUuid,
+          projectUuid: n.projectUuid,
+        });
+        if (n.entityUuid !== n.directIdeaUuid || n.entityType !== "idea" ||
+            n.directIdeaUuid !== attribution?.directIdeaUuid) {
+          throw new Error("Operation protocol error: execution identity mismatch");
+        }
+      }
+    } catch (err) {
+      this.logger.warn(`[Chorus] operation remains pending and retryable: ${err}`);
+      return;
+    }
     const hasFreshHumanInstruction = receivedList.some(
-      (n) => n?.action === "human_instruction",
+      (n) => n?.action === "human_instruction" || OPERATION_ACTIONS.has(n?.action),
     );
     if (hasFreshHumanInstruction && this.deterministicConflictGuards.delete(key)) {
       this.logger.info(
@@ -437,6 +461,8 @@ export class Waker {
     const startMs = Date.now();
     const target = entity ? `${entity.entityType}:${entity.entityUuid}` : key;
     const sessionId = directIdeaUuid ?? first?.entityUuid ?? null;
+    const operations = list.filter(isExactOperation);
+    const operationRequestUuid = batchSize === 1 && operations.length ? first.turnUuid : null;
     const requestedRuntimeCwd =
       typeof first?.runtimeCwd === "string" && first.runtimeCwd
         ? first.runtimeCwd
@@ -447,6 +473,10 @@ export class Waker {
     const arrivalAction =
       batchSize > 1 ? `coalesced batch of ${batchSize}` : first?.action;
     try {
+      if (operations.length && (!operationRequestUuid || !sessionId || batchSize !== 1)) {
+        this.logger.warn(`[Chorus] Operation requires an isolated, exact pending turn — skipping ${key}`);
+        return;
+      }
       const prompt = buildBatchPrompt(list);
       if (!prompt) {
         this.logger.info(`[Chorus] no wake prompt for ${arrivalAction} on ${key} — skipping`);
@@ -475,6 +505,7 @@ export class Waker {
           status: "running",
           startedAt: new Date().toISOString(),
           child: null,
+          ...(operationRequestUuid ? { operationTurnUuid: operationRequestUuid } : {}),
         });
         this.#emitExecutionChange();
       }
@@ -523,6 +554,39 @@ export class Waker {
         this.logger.info(`[Chorus]   cwd=${cwd} action=${arrivalAction} root=${rootIdeaUuid ?? "(none)"}`);
       }
 
+      // The server's atomic pending->running edge rechecks Research eligibility
+      // under the same lock as development acceptance. Await admission BEFORE any
+      // backend can spawn; an offline/rejected/missing reporter must fail closed.
+      if (operations.length) {
+        if (execKey && this.interrupting.has(execKey)) {
+          await this.#retireUnstartedOperation({
+            sessionId, turnUuid: operationRequestUuid, status: "interrupted",
+            interruptedReason: "user",
+          });
+          return;
+        }
+        const admission = await this.advanceTurn({
+          sessionId, turnUuid: first.turnUuid, status: "running", coalescedCount: 1,
+          entityType: entity?.entityType ?? null,
+          entityUuid: entity?.entityUuid ?? null,
+        });
+        if (!admission?.ok || admission.data?.turnUuid !== first.turnUuid) {
+          this.logger.warn(`[Chorus] Operation admission rejected or unavailable for ${key} — no subprocess started`);
+          // A conflict may belong to an already-running consumer; never abort it.
+          // Otherwise the response may have been lost AFTER admission committed.
+          // Retire this exact unstarted request whether it is pending or running.
+          if ((execKey && this.interrupting.has(execKey)) || ![404, 409].includes(admission?.status)) {
+            await this.#retireUnstartedOperation({
+              sessionId, turnUuid: operationRequestUuid, status: "interrupted",
+              interruptedReason: execKey && this.interrupting.has(execKey) ? "user" : "crash",
+              transcriptRelayError: "Operation launch admission unavailable; no subprocess started",
+            });
+          }
+          return;
+        }
+        operationTurnUuid = first.turnUuid;
+      }
+
       cfg = this.writeMcpConfigFn(this.creds);
 
       await this.hooks?.onSessionStart?.({ rootIdeaKey: key, sessionId: sessionId ?? "", isNew });
@@ -536,16 +600,29 @@ export class Waker {
       // a spawn that never started (onChild never fired) does not attempt an illegal
       // pending→ended transition. There is no separate turn registry — the turn is
       // identified server-side by `sessionId`, which the waker already has here.
-      let turnAdvancedToRunning = false;
-      let runningTurnUuidPromise = Promise.resolve(null);
+      let turnAdvancedToRunning = operationTurnUuid !== null;
+      let runningTurnUuidPromise = Promise.resolve(operationTurnUuid);
+      let childStarted = false;
 
       // Track the session id the stream reports so the transcript hook can use
       // it even before spawner.wake() returns. (Do NOT reference the awaited
       // `result` inside onMessage — it's in the temporal dead zone there.)
       let observedSessionId = sessionId ?? "";
       const onChild = (child) => {
+        childStarted = true;
         const entry = execKey ? this.executions.get(execKey) : null;
         if (entry && entry.status === "running") entry.child = child;
+        if (operationTurnUuid && (this.shuttingDown || (execKey && this.interrupting.has(execKey)))) {
+          // Some backends await binary discovery before onChild. A stop during
+          // that interval must still terminate the child as soon as it exists.
+          try {
+            Promise.resolve(this.killer(child, {
+              sigintTimeoutMs: this.sigintTimeoutMs, logger: this.logger,
+            })).catch((err) => this.logger.warn(`[Chorus] cancelled operation child kill failed: ${err}`));
+          } catch (err) {
+            this.logger.warn(`[Chorus] cancelled operation child kill failed: ${err}`);
+          }
+        }
         if (sessionId && !turnAdvancedToRunning) {
           turnAdvancedToRunning = true;
           // Fire-and-forget; #advanceTurn swallows + logs its own failures so a
@@ -589,6 +666,14 @@ export class Waker {
         onChild,
         onMessage,
       };
+      if (operationTurnUuid && (this.shuttingDown || (execKey && this.interrupting.has(execKey)))) {
+        await this.#retireUnstartedOperation({
+          sessionId, turnUuid: operationTurnUuid, status: "interrupted",
+          interruptedReason: execKey && this.interrupting.has(execKey) ? "user" : "shutdown",
+          transcriptRelayError: "Operation cancelled before subprocess launch",
+        });
+        return;
+      }
       let result = await this.spawner.wake(wakeParams);
 
       // Claude can still reject a new-session launch when its durable session exists
@@ -597,6 +682,7 @@ export class Waker {
       // child for interrupt handling; onChild's gate keeps pending→running exactly once.
       if (
         isNew &&
+        !(operationTurnUuid && (this.shuttingDown || (execKey && this.interrupting.has(execKey)))) &&
         result?.failureClassification === SESSION_CONFLICT_FAILURE
       ) {
         this.logger.warn(
@@ -611,6 +697,15 @@ export class Waker {
         }
       }
 
+      if (operationTurnUuid && !childStarted) {
+        await this.#retireUnstartedOperation({
+          sessionId, turnUuid: operationTurnUuid, status: "interrupted",
+          interruptedReason: execKey && this.interrupting.has(execKey) ? "user" : "crash",
+          transcriptRelayError: "Operation subprocess did not start",
+        });
+        return;
+      }
+
       if (result && !probeIsAuthoritative) {
         this.logger.info(
           `[Chorus] backend ${result.isNew ? "started new" : "resumed"} session ${result.sessionId ?? sessionId ?? "(none)"}`
@@ -746,7 +841,16 @@ export class Waker {
       }
     } catch (err) {
       this.logger.warn(`[Chorus] wake failed for ${key}: ${err}`);
-      if (sessionId && requestedRuntimeCwd && typeof err?.code === "string") {
+      if (operationRequestUuid && sessionId) {
+        // Admission succeeded but setup/spawn threw: retire this exact turn so a
+        // failed launch cannot leave an indefinitely running operation.
+        await this.#retireUnstartedOperation({
+          sessionId, turnUuid: operationRequestUuid, status: "interrupted",
+          interruptedReason: execKey && this.interrupting.has(execKey) ? "user"
+            : requestedRuntimeCwd && typeof err?.code === "string" ? "invalid_path" : "crash",
+          transcriptRelayError: String(err?.message ?? err).slice(0, 500),
+        });
+      } else if (sessionId && requestedRuntimeCwd && typeof err?.code === "string") {
         const invalidPathTurnUuid = await this.#advanceTurn(sessionId, "running", entity);
         await this.#advanceTurn(
           sessionId,
@@ -785,6 +889,25 @@ export class Waker {
     }
   }
 
+  async #retireUnstartedOperation(report) {
+    try {
+      const result = await this.advanceTurn(report);
+      // Terminal retries are idempotent. A 404/409 means this exact row is gone
+      // or already settled differently; no other turn is selected or changed.
+      if (result?.ok || [404, 409].includes(result?.status)) return;
+    } catch (err) {
+      this.logger.warn(`[Chorus] Operation launch cleanup failed for ${report.turnUuid}: ${err}`);
+    }
+    if (this.shuttingDown) return; // offline reconcile / pending backfill owns restart
+    this.logger.warn(`[Chorus] Operation launch cleanup deferred for ${report.turnUuid}; retrying in 30s`);
+    const timer = setTimeout(() => {
+      this.operationRecoveryTimers.delete(timer);
+      void this.#retireUnstartedOperation(report);
+    }, 30_000);
+    timer.unref?.();
+    this.operationRecoveryTimers.add(timer);
+  }
+
   /**
    * Report an interrupted/crashed outcome via the injected reporter. Never throws
    * into the wake path — a reporter failure is logged and swallowed (the reporter

package/cli/windows-process-tree.mjs

@@ -0,0 +1,154 @@
+// Windows has no POSIX process groups. Capture PID + creation-time identities
+// before closing the backend, then inspect surviving descendants after exit.
+import { spawn } from "node:child_process";
+
+const SNAPSHOT_SCRIPT = "$ErrorActionPreference='Stop'; $ChorusProcesses=@(Get-CimInstance Win32_Process | Where-Object { $_.ProcessId -gt 0 -and $_.CreationDate } | ForEach-Object { @{pid=[int]$_.ProcessId; parentPid=[int]$_.ParentProcessId; startedAt=$_.CreationDate.ToUniversalTime().ToString('o')} }); ConvertTo-Json -InputObject $ChorusProcesses -Compress";
+const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const exited = child => child.exitCode != null || Boolean(child.signalCode);
+const same = (a, b) => a && b && a.pid === b.pid && a.startedAt === b.startedAt;
+
+/** Fixed system commands only; output, helpers and listeners share one deadline. */
+async function command(command, args, { deadline, spawnImpl = spawn, capture = false }) {
+  if (Date.now() >= deadline) throw new Error("WINDOWS_CLEANUP_TIMEOUT");
+  return new Promise((resolve, reject) => {
+    let child, timer, settled = false, bytes = 0;
+    const chunks = [];
+    const finish = (error, code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child?.stdout?.removeListener("data", onData);
+      child?.removeListener("exit", onExit);
+      if (error) {
+        try { child?.kill?.("SIGKILL"); } catch {}
+        reject(new Error("WINDOWS_CLEANUP_COMMAND_FAILED"));
+      } else resolve({ code, output: Buffer.concat(chunks).toString("utf8") });
+    };
+    const onData = chunk => {
+      bytes += chunk.length;
+      if (bytes > MAX_OUTPUT_BYTES) return finish(true);
+      chunks.push(Buffer.from(chunk));
+    };
+    const onError = () => finish(true);
+    const onExit = code => {
+      // Queries need close to drain stdout. taskkill does not capture output.
+      if (!capture) finish(false, code);
+    };
+    const onClose = code => {
+      finish(false, code);
+      child?.removeListener("error", onError);
+      child?.stdout?.removeListener("error", onError);
+    };
+    try {
+      child = spawnImpl(command, args, { stdio: ["ignore", capture ? "pipe" : "ignore", "ignore"], windowsHide: true, shell: false });
+      child.on("error", onError);
+      child.once("exit", onExit);
+      child.once("close", onClose);
+      child.stdout?.on("error", onError);
+      if (capture) child.stdout?.on("data", onData);
+      timer = setTimeout(() => finish(true), Math.max(0, deadline - Date.now()));
+    } catch { finish(true); }
+  });
+}
+
+export async function readWindowsProcessSnapshot(options) {
+  const { code, output } = await command("powershell.exe",
+    ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", SNAPSHOT_SCRIPT],
+    { ...options, capture: true });
+  if (code !== 0) throw new Error("WINDOWS_PROCESS_QUERY_FAILED");
+  let parsed;
+  try { parsed = JSON.parse(output.replace(/^\uFEFF/, "")); }
+  catch { throw new Error("WINDOWS_PROCESS_QUERY_INVALID"); }
+  const records = Array.isArray(parsed) ? parsed : [parsed];
+  if (records.length > 100_000) throw new Error("WINDOWS_PROCESS_QUERY_INVALID");
+  const seen = new Set();
+  for (const r of records) {
+    if (!r || !Number.isSafeInteger(r.pid) || r.pid < 0 ||
+        !Number.isSafeInteger(r.parentPid) || r.parentPid < 0 ||
+        typeof r.startedAt !== "string" || !Number.isFinite(Date.parse(r.startedAt)) ||
+        seen.has(r.pid)) throw new Error("WINDOWS_PROCESS_QUERY_INVALID");
+    seen.add(r.pid);
+  }
+  return records;
+}
+
+export class WindowsProcessTree {
+  constructor(child, { deadline, spawnImpl, snapshotImpl = readWindowsProcessSnapshot } = {}) {
+    this.child = child;
+    this.options = { deadline, spawnImpl };
+    this.snapshot = () => snapshotImpl(this.options);
+    this.owned = new Map();
+    this.capturePromise = null;
+    this.captureFailed = false;
+    this.escalated = false;
+  }
+
+  capture() {
+    return this.capturePromise ??= (async () => {
+      try {
+        const wasRunning = !exited(this.child);
+        const records = await this.snapshot();
+        const root = records.find(r => r.pid === this.child.pid);
+        // A PID found after our ChildProcess has exited belongs to someone else.
+        if (root && !exited(this.child)) this.owned.set(root.pid, root);
+        else if (wasRunning) this.captureFailed = true;
+        else if (!root && records.some(r => r.parentPid === this.child.pid)) {
+          // No trustworthy root identity: do not guess ownership or kill.
+          this.captureFailed = true;
+        }
+        this.expand(records);
+      } catch { this.captureFailed = true; }
+    })();
+  }
+
+  expand(records) {
+    const current = new Map(records.map(r => [r.pid, r]));
+    let changed;
+    do {
+      changed = false;
+      for (const record of records) {
+        if (this.owned.has(record.pid)) continue;
+        const parent = this.owned.get(record.parentPid);
+        // Retain ancestry through a departed parent, but never through a reused
+        // PID. Creation ordering also rejects an older, unrelated process.
+        if (parent && (!current.has(parent.pid) || same(parent, current.get(parent.pid))) &&
+            Date.parse(record.startedAt) >= Date.parse(parent.startedAt)) {
+          this.owned.set(record.pid, record); changed = true;
+        }
+      }
+    } while (changed);
+    return records.filter(r => same(r, this.owned.get(r.pid)));
+  }
+
+  async cleanup() {
+    await this.capture();
+    try {
+      let living = this.expand(await this.snapshot());
+      if (this.captureFailed) throw new Error("WINDOWS_TREE_UNCERTAIN");
+      if (!living.length) return { cleanupFailed: false, escalated: false };
+      // Target each surviving identity, including children whose root exited.
+      // Re-read before each taskkill to avoid killing a known reused PID.
+      for (const candidate of living) {
+        const fresh = await this.snapshot();
+        const actual = fresh.find(r => r.pid === candidate.pid);
+        this.expand(fresh);
+        if (!same(candidate, actual)) continue;
+        try {
+          this.escalated = true;
+          await command("taskkill", ["/PID", String(candidate.pid), "/T", "/F"], this.options);
+        } catch {
+          // A process can disappear during taskkill. Only the final identity
+          // probe distinguishes that race from a genuine termination failure.
+        }
+      }
+      living = this.expand(await this.snapshot());
+      if (living.length) throw new Error("WINDOWS_TREE_REMAINS");
+      return { cleanupFailed: false, escalated: true };
+    } catch {
+      // Still try to stop the exact ChildProcess if it has not exited. No
+      // unverified numeric PID is targeted on this failure path.
+      if (!exited(this.child)) { try { this.child.kill?.("SIGKILL"); } catch {} }
+      return { cleanupFailed: true, escalated: this.escalated };
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-aidlc/chorus",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "The Agent Harness for AI-Human Collaboration — session lifecycle, task state, sub-agent orchestration, observability, and failure recovery",
   "homepage": "https://github.com/Chorus-AIDLC/Chorus",
   "repository": {

package/prisma/migrations/20260927073000_add_daemon_operation_payload/migration.sql

@@ -0,0 +1 @@
+ALTER TABLE "DaemonSessionTurn" ADD COLUMN "operationPayload" JSONB;

package/prisma/schema.prisma

@@ -719,8 +719,9 @@ model DaemonSessionTurn {
   // immutable first-wake compatibility anchor.
   backendSessionId  String?
   seq               Int // monotonic per session
-  trigger           String // task_assigned | mentioned | elaboration | elaboration_verified | start_development | yolo_requested | resume | human_instruction
-  promptText        String? // free-text body for human_instruction; null otherwise (canonical source)
+  trigger           String // task_assigned | mentioned | elaboration | elaboration_verified | start_development | yolo_requested | resume | human_instruction | idea_creation_requested | research_requested
+  promptText        String? // human instruction body or server-composed operation compatibility snapshot
+  operationPayload  Json? // versioned dedicated operation; historical rows remain null
   status            String                    @default("pending") // pending | running | ended | interrupted
   // Discriminator for the `interrupted` status: `user` = user-requested interrupt,
   // `crash` = subprocess exited dirty, `shutdown` = daemon graceful shutdown killed