wicked-crew 0.6.0 → 0.7.0

package/dist/core/bridge-reaper.js

@@ -0,0 +1,286 @@
+/**
+ * ACP bridge child reaper — bridges must die with the daemon (crew#285).
+ *
+ * # The defect
+ *
+ * The engine spawns ACP bridge binaries as direct OS children of this daemon process,
+ * and the only kill handles for them live in the engine's in-memory registry. When the
+ * daemon dies — pkill during a restart, an operator's Ctrl-C, a plain `process.exit` —
+ * that registry dies with it and nothing reaps the bridges: they linger detached until
+ * their own session-idle logic (if any) gets around to exiting. Operators observed
+ * three `claude-agent-acp` processes coexisting while exactly one unit was executing.
+ *
+ * Same defect family as crew#277's cancel-orphans, but for daemon death rather than
+ * run cancellation.
+ *
+ * # The fix, in two halves
+ *
+ * 1. THIS MODULE (daemon side): a central registry of bridge child pids plus an OS
+ *    process-table sweep, wired into the daemon's shutdown path. On SIGTERM/SIGINT the
+ *    daemon SIGTERMs every bridge child, waits a short grace for them to exit, then
+ *    SIGKILLs survivors. On plain `exit` (where no async work is possible) it fires a
+ *    synchronous best-effort SIGTERM sweep.
+ *
+ *    `register()` exists for any JS-side spawn site (and for tests); the engine-spawned
+ *    bridges are found by `discoverBridgeChildren()` — a scan of the OS process table
+ *    for DIRECT children of this daemon whose command line names a bridge binary. The
+ *    direct-child restriction is the safety rail: another daemon's bridges have a
+ *    different parent pid and are never touched.
+ *
+ * 2. `packages/agent-acp-bridges` (bridge side): the bridge treats stdin EOF as the
+ *    portable parent-death signal and reaps its own CLI child instead of lingering
+ *    until the CLI finishes. See `bridge.mjs`. That half covers our own bridges even
+ *    when the daemon dies too hard (SIGKILL) for this module to run at all.
+ *
+ * # Why a process-table sweep rather than tracked pids alone
+ *
+ * The spawn happens inside the engine (the native actor thread), which reports no pid
+ * back to JS — there is nothing for the daemon to `register()`. The bridges ARE this
+ * process's direct children though, and their command lines name the bridge binaries
+ * (npm `.bin` shims exec `node .../<bridge-name>/...`), so a ppid-filtered scan
+ * recovers exactly the set the in-memory kill handles would have covered. The sweep
+ * fails OPEN (returns nothing) when the platform tooling is unavailable: a shutdown
+ * that cannot enumerate children must still shut down.
+ */
+import { spawnSync } from 'node:child_process';
+/**
+ * The bridge binaries the engine spawns by bare name on PATH. Mirrors the set audited
+ * by `bridge-names.test.ts` (declared dependencies of this package + the shims a real
+ * install produces); `bridge-reaper.test.ts` cross-checks this list against those same
+ * dependency manifests so a bridge added or dropped there cannot silently drift here.
+ */
+export const BRIDGE_BINS = [
+    'agy-acp',
+    'claude-agent-acp',
+    'codex-acp',
+    'pi-acp',
+];
+/** How long a SIGTERM'd bridge gets to exit before the SIGKILL escalation. */
+export const BRIDGE_KILL_GRACE_MS = 2000;
+/** How often the grace window re-checks survivor liveness. */
+const POLL_INTERVAL_MS = 100;
+/**
+ * One line of a `pid ppid command` process listing → the pids of DIRECT children of
+ * `parentPid` whose command line names a bridge binary. Pure, so the parsing is
+ * testable without a real process table.
+ */
+/**
+ * Matches `bin` as a whole command token, never a substring: start/whitespace/path-sep/
+ * quote before; an optional Windows launcher extension (.cmd/.exe/.bat) and then
+ * end/whitespace/path-sep/quote after — so `pi-acp`, `/x/pi-acp`, `"C:\\x\\pi-acp.cmd"`
+ * all match while `api-acp` and `copy-of-pi-acp-backup` never do.
+ */
+function bridgeTokenRe(bin) {
+    const esc = bin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?:^|[\\s/\\\\"'])${esc}(?:\\.(?:cmd|exe|bat))?(?:[\\s/\\\\"']|$)`, 'i');
+}
+/** Precompiled per-bin matchers — the scan loops run one test per line, no per-line RegExp churn. */
+const BRIDGE_TOKEN_RES = BRIDGE_BINS.map((bin) => bridgeTokenRe(bin));
+export function parseBridgeChildren(listing, parentPid) {
+    const pids = [];
+    for (const line of listing.split('\n')) {
+        const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+        if (m === null)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        const command = m[3];
+        if (ppid !== parentPid || pid === parentPid)
+            continue;
+        // Token-boundary match: `pi-acp` must not match inside `api-acp` (Copilot review
+        // on #300 post-merge). A bridge binary appears as its own token — start-of-line,
+        // whitespace, or a path separator before it; end-of-token after.
+        if (BRIDGE_TOKEN_RES.some((re) => re.test(command)))
+            pids.push(pid);
+    }
+    return pids;
+}
+/** `pid ppid command` listing of every process, or null when the platform tooling fails. */
+function listProcesses() {
+    try {
+        const out = process.platform === 'win32'
+            ? // wmic is removed on current Windows; CIM via PowerShell is the stable surface.
+                spawnSync('powershell', [
+                    '-NoProfile',
+                    '-Command',
+                    "Get-CimInstance Win32_Process | ForEach-Object { '{0} {1} {2}' -f $_.ProcessId, $_.ParentProcessId, $_.CommandLine }",
+                ], { encoding: 'utf8', windowsHide: true, maxBuffer: 16 * 1024 * 1024 })
+            : // POSIX keywords (`args`, not the BSD/procps-specific `command`): same spelling
+                // works on macOS and Linux.
+                spawnSync('ps', ['-A', '-o', 'pid=,ppid=,args='], {
+                    encoding: 'utf8',
+                    maxBuffer: 16 * 1024 * 1024,
+                });
+        if (out.error !== undefined || out.status !== 0 || typeof out.stdout !== 'string')
+            return null;
+        return out.stdout;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pids of every live bridge process that is a direct child of `parentPid`. Fails open:
+ * an unreadable process table yields `[]`, never a throw — shutdown must proceed.
+ */
+export function discoverBridgeChildren(parentPid = process.pid) {
+    const listing = listProcesses();
+    return listing === null ? [] : parseBridgeChildren(listing, parentPid);
+}
+/**
+ * Pids of bridge processes ORPHANED by a previous daemon generation: reparented to
+ * init (ppid 1). Deliberately conservative — a bridge owned by another LIVE daemon
+ * still has that daemon as its parent and is never matched, so a boot sweep cannot
+ * shoot a neighbour's workers (#285, Copilot review: shutdown-only reaping leaves
+ * pre-existing orphans alive forever).
+ */
+export function parseOrphanedBridges(listing) {
+    const pids = [];
+    for (const line of listing.split('\n')) {
+        const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+        if (m === null)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        const command = m[3];
+        if (ppid !== 1 || pid === process.pid)
+            continue;
+        if (BRIDGE_TOKEN_RES.some((re) => re.test(command)))
+            pids.push(pid);
+    }
+    return pids;
+}
+/**
+ * True when `pid`'s working directory sits inside an engine run worktree — the cwd
+ * contract of every engine-spawned bridge. A user's own nohup'd `*-acp` process also
+ * reparents to init but runs from an arbitrary cwd, so this is the discriminator that
+ * keeps the boot sweep from shooting it (Copilot review on #300). POSIX only (lsof);
+ * anywhere the cwd cannot be read the answer is false — never kill on uncertainty.
+ */
+function pidRunsInRunWorktree(pid) {
+    if (process.platform === 'win32')
+        return false;
+    try {
+        const out = spawnSync('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+            encoding: 'utf8',
+            maxBuffer: 1024 * 1024,
+        });
+        if (out.error !== undefined || out.status !== 0 || typeof out.stdout !== 'string')
+            return false;
+        const cwd = out.stdout.split('\n').find((l) => l.startsWith('n'))?.slice(1) ?? '';
+        return cwd.includes('wicked-worktrees');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Boot-time sweep: SIGTERM orphaned bridges from a prior daemon generation — ppid 1
+ * AND cwd inside a run worktree, so user-started bridges are never matched.
+ */
+export function reapOrphansAtBoot(io = {}) {
+    const listing = listProcesses();
+    if (listing === null)
+        return [];
+    const orphans = parseOrphanedBridges(listing).filter((pid) => (io.cwdInWorktree ?? pidRunsInRunWorktree)(pid));
+    const reaped = [];
+    for (const pid of orphans) {
+        try {
+            (io.kill ?? process.kill)(pid, 'SIGTERM');
+            reaped.push(pid);
+        }
+        catch {
+            // ESRCH (already gone) / EPERM (not ours): skip silently — fail open.
+        }
+    }
+    return reaped;
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * The central bridge-child registry plus the shutdown path that empties it.
+ *
+ * A single instance (`bridgeReaper`) is wired into the daemon's shutdown handlers;
+ * tests construct their own with fake IO.
+ */
+export class BridgeReaper {
+    tracked = new Set();
+    io;
+    constructor(io = {}) {
+        this.io = io;
+    }
+    /** Track a bridge child pid. Invalid pids (spawn failures yield `undefined`) are ignored. */
+    register(pid) {
+        if (typeof pid === 'number' && Number.isInteger(pid) && pid > 0)
+            this.tracked.add(pid);
+    }
+    /** Stop tracking a pid — call when the child's `close`/`exit` is observed. */
+    unregister(pid) {
+        this.tracked.delete(pid);
+    }
+    /** Currently tracked pids (registered only; discovery happens at kill time). */
+    pids() {
+        return [...this.tracked];
+    }
+    /**
+     * Deliver `signal`. For the signal-0 liveness probe, EPERM means "alive but not
+     * ours" and counts as existing; for real signals EPERM means the kill was NOT
+     * delivered and must not be reported as success (Copilot review on #300).
+     */
+    signal(pid, signal) {
+        try {
+            (this.io.kill ?? process.kill)(pid, signal);
+            return true;
+        }
+        catch (err) {
+            const eperm = err.code === 'EPERM';
+            return signal === 0 ? eperm : false;
+        }
+    }
+    /** Registered pids ∪ discovered direct-child bridges, deduplicated. */
+    targets() {
+        const all = new Set(this.tracked);
+        for (const pid of (this.io.discover ?? discoverBridgeChildren)(process.pid))
+            all.add(pid);
+        return [...all];
+    }
+    /**
+     * Graceful reap: SIGTERM every target, poll liveness for the grace window, SIGKILL
+     * survivors. Idempotent — dead pids are skipped, and the registry is cleared so a
+     * second invocation (the `exit` sweep after a signal-path shutdown) finds nothing
+     * registered and only re-discovers what actually still lives.
+     */
+    async shutdown() {
+        const graceMs = this.io.graceMs ?? BRIDGE_KILL_GRACE_MS;
+        const sleep = this.io.sleep ?? defaultSleep;
+        const targets = this.targets().filter((pid) => this.signal(pid, 0));
+        for (const pid of targets)
+            this.signal(pid, 'SIGTERM');
+        const deadline = Date.now() + graceMs;
+        let survivors = targets.filter((pid) => this.signal(pid, 0));
+        while (survivors.length > 0 && Date.now() < deadline) {
+            await sleep(Math.min(POLL_INTERVAL_MS, graceMs));
+            survivors = survivors.filter((pid) => this.signal(pid, 0));
+        }
+        const killed = survivors.filter((pid) => this.signal(pid, 'SIGKILL'));
+        this.tracked.clear();
+        return {
+            terminated: targets.filter((pid) => !survivors.includes(pid)),
+            killed,
+            undeliverable: survivors.filter((pid) => !killed.includes(pid)),
+        };
+    }
+    /**
+     * Synchronous best-effort sweep for the `exit` event, where no async work (and so no
+     * grace window) is possible. SIGTERM only — a synchronous SIGKILL would deny a bridge
+     * the chance to reap ITS child CLI, recreating the orphan problem one level down.
+     * The bridges' own stdin-EOF watchdog is the backstop for anything that ignores this.
+     */
+    sweepSync() {
+        for (const pid of this.targets())
+            this.signal(pid, 'SIGTERM');
+        this.tracked.clear();
+    }
+}
+/** The daemon-wide reaper the CLI wires into its shutdown handlers. */
+export const bridgeReaper = new BridgeReaper();
+//# sourceMappingURL=bridge-reaper.js.map

package/dist/core/bridge-reaper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-reaper.js","sourceRoot":"","sources":["../../src/core/bridge-reaper.ts"],"names":[],"mappings":"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"}

package/dist/core/deliver.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The first-class deliver phase (crew#293) — a run opens its own PR, opt-in.
+ *
+ * Productizes the operator-side `feature-pr` overlay proven during the DES-MERGE-001 campaign:
+ * a Tool phase appended after the workflow's last phase that COMMITS the run's work, pushes the
+ * run's branch and opens a PR via `gh`. What was data on one machine becomes a launch option
+ * (`deliver: "pr"` on `POST /runs`), composed PER RUN — the shared workflow def is never mutated.
+ *
+ * Field-proven hardening, replicated here:
+ *  (a) the branch is derived from the run worktree's basename (`wicked/<run-id>`), falling back
+ *      to the current branch when that ref does not exist;
+ *  (b) the script REFUSES to push `main`/`master` (or an empty/detached branch name) — the
+ *      deliver phase only ever pushes run branches;
+ *  (c) it STAGES AND COMMITS the run's work, then rebases onto origin's default branch before
+ *      pushing, and a conflicting rebase FAILS the phase visibly (aborting the rebase, pushing
+ *      nothing) rather than pushing a conflicted tree;
+ *  (d) `git push -u origin <branch>`;
+ *  (e) `gh pr create --head <branch> --fill`, with gh's output and exit status captured
+ *      SEPARATELY so a gh failure fails the phase carrying gh's own message;
+ *  (f) the PR URL is the last line of the phase output.
+ *
+ * One deliberate change from the field version: NO gh account is baked into crew code (the
+ * overlay guarded a personal account). Instead, when the `GH_ACCOUNT` env var is set the script
+ * compares it against `gh api user -q .login` and runs
+ * `gh auth switch --hostname github.com --user "$GH_ACCOUNT"` only when they differ.
+ *
+ * Merge stays human: the phase opens the PR, never merges it.
+ *
+ * ## crew#317 — "pushed an empty branch and reported success"
+ *
+ * Run `d1bc72c2` (wicked-studio) delivered nothing while reporting `completed`. The persisted
+ * unit is the evidence, and it names the cause precisely. Its `tool_cmd` was NOT this script —
+ * it was the operator's hand-written `feature-pr` OVERLAY def, which begins `set -e` with **no
+ * `pipefail`**, so `gh pr create … | tail -1` reported `tail`'s status (0) and the phase passed
+ * with gh's error text where the PR URL belongs:
+ *
+ * ```text
+ * could not compute title or body defaults: could not find any commits between origin/main and
+ * wicked/d1bc72c2-…
+ * ```
+ *
+ * So the masking mechanism the issue hypothesised is real, but it belonged to the overlay, not
+ * here: `pipefail` IS in force for this executor (it is line 1 of this script, `bash -lc` runs it
+ * verbatim, and core's `run_tool_cmd` maps any non-zero exit to `StepStatus::Failed`). The three
+ * defects this script genuinely shared with the overlay are fixed below:
+ *
+ *  1. **No commit.** Agents write files and do not commit, so the pushed branch equalled the
+ *     default branch. The script now stages and commits the run's work itself, and REFUSES to
+ *     push when there is nothing to deliver.
+ *  2. **A masked result.** `| tail -1` discarded everything gh said except one line and made the
+ *     phase's verdict depend on a pipe option. gh's output and status are now captured
+ *     separately, and success is re-derived from a real PR URL rather than from an exit code.
+ *  3. **Ungoverned.** The phase shipped `verified_evidence: false` / `validator_pin: null`, so
+ *     nothing re-derived what it claimed. It now declares `verified_evidence: true` — see
+ *     {@link deliverPrPhase}.
+ */
+import type { PhaseDef, WorkflowDef } from './types.js';
+/** The id of the appended phase — also the collision probe when a def already delivers. */
+export declare const DELIVER_PHASE_ID = "deliver";
+/**
+ * The hardened deliver script, run as `bash -lc <script>` (login shell so the operator's PATH —
+ * where `gh` lives — is loaded, same as the field overlay).
+ *
+ * `set -euo pipefail` is load-bearing and verified in force for this executor (crew#317): the
+ * engine spawns `bash -lc` with this text verbatim, and `run_tool_cmd` turns a non-zero exit into
+ * `StepStatus::Failed`. It is no longer the ONLY thing standing between a failed `gh` and a green
+ * phase, though — the gh result is captured explicitly and success is re-derived from evidence.
+ *
+ * `intent` (the run's problem statement) rides in the commit subject; it is sanitised by
+ * {@link commitSubjectIntent} before it is spliced in.
+ */
+export declare function deliverPrScript(intent?: string): string;
+/**
+ * The deliver phase definition — the PhaseDef JSON shape core accepts, fully spelled out so the
+ * composed def round-trips through `registerWorkflow` (core's serde) and crew's own `WorkflowDef`
+ * type without casts. `gate: 'auto'` + `executes_code: false`: the phase is deterministic tooling,
+ * not governed agent work — its failure surface is the exit code + output, which core reports as
+ * a failed unit.
+ *
+ * ## Why `verified_evidence: true` and `validator_pin: null` (crew#317)
+ *
+ * The phase that touches the remote was the one phase nothing re-derived. The engine's phase model
+ * DOES let a Tool-executor phase carry a deterministic floor, and the mechanism is the flag rather
+ * than a pin crew mints itself:
+ *
+ *  - a pin is a CONTENT ADDRESS into core's validator vault, and `attach_pinned_validators` is
+ *    fail-closed on one that does not resolve — it BAILS the run at plan time. Authoring and
+ *    approving a validator is `wicked-core provision-validator` + `approve-validator`, neither of
+ *    which is exposed through the napi surface crew drives, so a pin invented here would fail
+ *    every run of every deliver-composed workflow on a machine that had not been seeded by hand;
+ *  - `verified_evidence: true` with no pin of its own is armed AT REGISTRATION by
+ *    `enforce_verified_evidence` with the built-in evidence floor (`EVIDENCE_FLOOR_PIN`,
+ *    criterion: "the run left a change in its worktree (done is re-derived from the diff, never
+ *    asserted)"), which `pre_distribute` seeds on the plan path so it always resolves. Same
+ *    mechanism `feature/test`, `bug/verify` and `migration/verify` reach it by.
+ *
+ * The floor then re-runs against the run's worktree at the gate, INDEPENDENTLY of anything this
+ * script printed, and denies the phase when the run left no change. Layer 2 (the agent judge)
+ * stays out of it: core hands the Tool path `agent_verdict: None`, so a tool phase's floor is
+ * deterministic and costs no LLM call. The PR-URL and branch-ahead assertions stay in the script
+ * because no vaulted floor can see the remote.
+ */
+export declare function deliverPrPhase(dependsOn?: string[], intent?: string): PhaseDef;
+/**
+ * Compose a PER-RUN workflow def: `base`'s phases (untouched — the shared def is never mutated)
+ * plus the deliver phase appended last, under a run-scoped id. The caller registers the result
+ * with the engine for THIS run only; nothing is written to the overlay dir and the composed id
+ * never enters the user-workflow registry, so the catalog (`GET /workflows`) stays clean.
+ *
+ * `intent` is the run's problem statement — it names WHAT was delivered in the commit subject
+ * (`wicked-crew run <run-id>: <intent>`); omit it and the subject carries the run id alone.
+ *
+ * Throws when `base` already carries a `deliver` phase — appending a second phase with the same
+ * id would be ambiguous at best; the caller launches such a def as-is instead (see
+ * `CoreAdapter.launchRun`).
+ */
+export declare function composeDeliverWorkflow(base: WorkflowDef, runId: string, intent?: string): WorkflowDef;
+//# sourceMappingURL=deliver.d.ts.map

package/dist/core/deliver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliver.d.ts","sourceRoot":"","sources":["../../src/core/deliver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,YAAY,CAAC;AA0B1C;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAqEvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,SAAS,GAAE,MAAM,EAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAgBlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,CAmBb"}