@aperant/framework 0.6.4 → 0.6.6

package/dist/__test-helpers/run-cmd.mjs

@@ -2,16 +2,18 @@
  * run-cmd.mjs — D-05 in-process command harness.
  *
  * `runCmd(cmdFn, args, opts)` invokes a Layer 1 command function in-process
- * (no subprocess), captures stdout, traps any process.exit calls (via a
- * try/finally restore), and returns:
+ * (no subprocess), captures stdout + stderr, traps any process.exit calls
+ * (via a try/finally restore), stubs `process.stdin.isTTY` /
+ * `process.stdout.isTTY` to `false` for the trapped invocation duration, and
+ * returns:
  *
- *     { result, stdout, exitCode }
+ *     { result, stdout, stderr, exitCode }
  *
  * `result` is the cmd function's return value (typically `{envelope, exitCode}`
  * after the migration; `null` if the cmd called process.exit before returning).
- * `stdout` is the captured stdout.write payload (string). `exitCode` is the
- * effective exit code: the trapped exit code if process.exit was called, else
- * `result.exitCode`, else 0.
+ * `stdout` / `stderr` are the captured `*.write` payloads (string). `exitCode`
+ * is the effective exit code: the trapped exit code if process.exit was called,
+ * else `result.exitCode`, else 0.
  *
  * D-05 (d) decision: strictExit DEFAULTS TO TRUE — the harness throws a
  * strict-mode-violation Error any time a Layer 1 cmd calls process.exit.
@@ -19,10 +21,23 @@
  * `{ strictExit: false }` until the underlying cmd is rewritten. After Wave 5
  * (subtask 25) zero `strictExit: false` opt-outs remain in __tests__/.
  *
- * Restoration: process.exit and process.stdout.write are saved at entry and
- * restored unconditionally in a try/finally. A test that crashes mid-call
- * still leaves the global state byte-identical for the next test in the file.
+ * Restoration: process.exit, process.stdout.write, process.stderr.write, and
+ * the two `isTTY` bits are saved at entry and restored unconditionally in a
+ * try/finally. A test that crashes mid-call still leaves the global state
+ * byte-identical for the next test in the file.
+ *
+ * Cache resets (F3 subtask 1): by default the harness clears the two
+ * path-keyed module-graph caches that can leak across cmd invocations within
+ * a single vitest worker — `skill-discover._discoverCache` and the
+ * `agent-identity` identity cache. The `gate/registry` and
+ * `consistency/registry` registries are NOT cleared by default because their
+ * built-in entries are populated by barrel imports that ESM evaluates exactly
+ * ONCE per process — clearing them would leave subsequent cmd invocations
+ * looking at an empty registry. Tests that specifically need an empty
+ * registry import `__resetCaches()` from those modules directly.
  */
+import { __resetCaches as __resetAgentIdentityCaches } from '../cli/coordination/agent-identity.mjs';
+import { __resetCaches as __resetSkillDiscoverCaches } from '../cli/route/skill-discover.mjs';
 class ExitTrap extends Error {
     constructor(code) {
         super(`apt-tools cmd called process.exit(${code})`);
@@ -32,18 +47,26 @@ class ExitTrap extends Error {
 /**
  * @param {Function} cmdFn — the Layer 1 cmd function (sync or async).
  * @param {unknown[]} [args=[]] — argv-shaped positional args.
- * @param {{ strictExit?: boolean, env?: Record<string, string> }} [opts]
- * @returns {Promise<{ result: unknown, stdout: string, exitCode: number }>}
+ * @param {{ strictExit?: boolean, resetCaches?: boolean, env?: Record<string, string> }} [opts]
+ * @returns {Promise<{ result: unknown, stdout: string, stderr: string, exitCode: number }>}
  */
 export async function runCmd(cmdFn, args = [], opts = {}) {
-    const { strictExit = true } = opts;
+    const { strictExit = true, resetCaches = true } = opts;
+    if (resetCaches) {
+        __resetSkillDiscoverCaches();
+        __resetAgentIdentityCaches();
+    }
     let trappedExit = null;
     const origExit = process.exit;
-    // Save the unbound original — assignment to process.stdout.write replaces
+    // Save the unbound originals — assignment to process.stdout.write replaces
     // the property; restoration of the original reference returns the global
     // to byte-identical state (Function-identity check in self-tests).
     const origWrite = process.stdout.write;
+    const origErrWrite = process.stderr.write;
+    const origStdinIsTTY = process.stdin.isTTY;
+    const origStdoutIsTTY = process.stdout.isTTY;
     const stdoutBuf = [];
+    const stderrBuf = [];
     process.exit = (code) => {
         trappedExit = typeof code === 'number' ? code : 0;
         if (strictExit) {
@@ -59,6 +82,16 @@ export async function runCmd(cmdFn, args = [], opts = {}) {
         stdoutBuf.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8'));
         return true;
     };
+    process.stderr.write = (chunk, ..._rest) => {
+        stderrBuf.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8'));
+        return true;
+    };
+    // F3 subtask 1 (Q3): defensively force the non-interactive branch for any
+    // cmd that gates on isTTY (init.mjs:127,167,1013 + cmdState's TTY sidecar).
+    // Under vitest workers isTTY is usually `undefined`, but stubbing to `false`
+    // removes the Node-version drift risk.
+    process.stdin.isTTY = false;
+    process.stdout.isTTY = false;
     try {
         const result = await cmdFn(...args);
         const exitCode = trappedExit !== null
@@ -66,11 +99,16 @@ export async function runCmd(cmdFn, args = [], opts = {}) {
             : typeof result === 'object' && result !== null && typeof result.exitCode === 'number'
                 ? result.exitCode
                 : 0;
-        return { result, stdout: stdoutBuf.join(''), exitCode };
+        return { result, stdout: stdoutBuf.join(''), stderr: stderrBuf.join(''), exitCode };
     }
     catch (e) {
         if (e instanceof ExitTrap) {
-            return { result: null, stdout: stdoutBuf.join(''), exitCode: e.code };
+            return {
+                result: null,
+                stdout: stdoutBuf.join(''),
+                stderr: stderrBuf.join(''),
+                exitCode: e.code,
+            };
         }
         // Re-throw non-trap errors (including the strict-mode-violation Error
         // thrown above) so tests can assert via expect(...).rejects.
@@ -79,6 +117,9 @@ export async function runCmd(cmdFn, args = [], opts = {}) {
     finally {
         process.exit = origExit;
         process.stdout.write = origWrite;
+        process.stderr.write = origErrWrite;
+        process.stdin.isTTY = origStdinIsTTY;
+        process.stdout.isTTY = origStdoutIsTTY;
     }
 }
 //# sourceMappingURL=run-cmd.mjs.map

package/dist/__test-helpers/run-cmd.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run-cmd.mjs","sourceRoot":"","sources":["../../src/__test-helpers/run-cmd.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,QAAS,SAAQ,KAAK;IAC3B,YAAY,IAAI;QACf,KAAK,CAAC,qCAAqC,IAAI,GAAG,CAAC,CAAA;QACnD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IACjB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,GAAG,EAAE;IACvD,MAAM,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,IAAI,CAAA;IAElC,IAAI,WAAW,GAAG,IAAI,CAAA;IACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAA;IAC7B,0EAA0E;IAC1E,yEAAyE;IACzE,mEAAmE;IACnE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAA;IACtC,MAAM,SAAS,GAAG,EAAE,CAAA;IAEpB,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE;QACvB,WAAW,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;QACjD,IAAI,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACd,gBAAgB,WAAW,iDAAiD;gBAC3E,uFAAuF;gBACvF,yFAAyF,CAC1F,CAAA;QACF,CAAC;QACD,kEAAkE;QAClE,sDAAsD;QACtD,MAAM,IAAI,QAAQ,CAAC,WAAW,CAAC,CAAA;IAChC,CAAC,CAAA;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,EAAE,EAAE;QAC1C,SAAS,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAA;QACxF,OAAO,IAAI,CAAA;IACZ,CAAC,CAAA;IAED,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;QACnC,MAAM,QAAQ,GACb,WAAW,KAAK,IAAI;YACnB,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;gBACrF,CAAC,CAAC,MAAM,CAAC,QAAQ;gBACjB,CAAC,CAAC,CAAC,CAAA;QACN,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAA;IACxD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,IAAI,CAAC,YAAY,QAAQ,EAAE,CAAC;YAC3B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;QACtE,CAAC;QACD,sEAAsE;QACtE,6DAA6D;QAC7D,MAAM,CAAC,CAAA;IACR,CAAC;YAAS,CAAC;QACV,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAA;QACvB,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAA;IACjC,CAAC;AACF,CAAC"}
+{"version":3,"file":"run-cmd.mjs","sourceRoot":"","sources":["../../src/__test-helpers/run-cmd.mjs"],"names":[],"mappings":"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"}

package/dist/cli/ci-watch/lock.d.mts

@@ -0,0 +1,53 @@
+/**
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function readLock(root: string, pr: number | string): any;
+/**
+ * Try to acquire the per-PR lock. On EEXIST, parse the existing lock — if the
+ * holder PID is dead AND TTL has elapsed, unlink + retry once. Otherwise
+ * return `{status:'busy', holder}`.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {string} sessionId
+ * @param {number} [pid=process.pid]
+ */
+export function acquireLock(root: string, pr: number | string, sessionId: string, pid?: number): {
+    status: string;
+    lock: {
+        sessionId: string;
+        pid: number;
+        acquiredAt: string;
+        ttl_seconds: number;
+    };
+    holder?: undefined;
+} | {
+    status: string;
+    holder: any;
+    lock?: undefined;
+};
+/**
+ * Release the per-PR lock. Owner must match (`sessionId` equality). Returns
+ * `true` if released, `false` if the lock is missing or owned by someone
+ * else.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {string} sessionId
+ */
+export function releaseLock(root: string, pr: number | string, sessionId: string): boolean;
+/**
+ * Is the given lock stale (i.e., recoverable by a new caller)? Per D-05,
+ * BOTH conditions are required: dead PID AND past TTL.
+ *
+ * Exposed for unit tests; the orchestrator does not call this directly.
+ *
+ * @param {{ pid: number, acquiredAt: string, ttl_seconds: number }} lockData
+ */
+export function isStale(lockData: {
+    pid: number;
+    acquiredAt: string;
+    ttl_seconds: number;
+}): boolean;
+//# sourceMappingURL=lock.d.mts.map

package/dist/cli/ci-watch/lock.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.mts","sourceRoot":"","sources":["../../../src/cli/ci-watch/lock.mjs"],"names":[],"mappings":"AA8CA;;;GAGG;AACH,+BAHW,MAAM,MACN,MAAM,GAAC,MAAM,OAWvB;AAYD;;;;;;;;;GASG;AACH,kCALW,MAAM,MACN,MAAM,GAAC,MAAM,aACb,MAAM,QACN,MAAM;;;;;;;;;;;;;EAwDhB;AAED;;;;;;;;GAQG;AACH,kCAJW,MAAM,MACN,MAAM,GAAC,MAAM,aACb,MAAM,WAiBhB;AAED;;;;;;;GAOG;AACH,kCAFW;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,WAQlE"}

package/dist/cli/ci-watch/lock.mjs

@@ -0,0 +1,172 @@
+/**
+ * ci-watch/lock.mjs — per-PR O_EXCL atomic lock (D-05).
+ *
+ * Mirrors Claude Code's `cronTasksLock.ts`: a per-PR `.aperant/ci-watches/{pr}.lock`
+ * file created with `openSync(..., 'wx')` (O_EXCL). Two concurrent callers
+ * cannot both create the file; the loser reads the existing lock and decides
+ * whether to declare BUSY or recover a stale lock.
+ *
+ * Stale-recovery (spec.md §8): a lock is recoverable iff
+ *   (a) holder PID is dead (`!isPidAlive`), AND
+ *   (b) `Date.now() - acquiredAt > ttl_seconds*1000`.
+ * Live PID alone is NEVER recoverable, even past TTL — TTL alone is not
+ * enough. Per D-05: PID-based stale recovery.
+ *
+ * Lock file shape (spec.md §8):
+ *   { sessionId, pid, acquiredAt, ttl_seconds }
+ *
+ * Return shapes:
+ *   acquireLock → { status: 'ok', lock: {...} }
+ *              OR { status: 'busy', holder: {...} }
+ *   releaseLock → boolean (true on release, false if owner mismatch / missing)
+ *   readLock   → lock object or null
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isPidAlive } from '../lock/pid.mjs';
+const TTL_SECONDS = 1800; // 30 min — D-05
+function watchesDir(root) {
+    return join(resolve(root), '.aperant', 'ci-watches');
+}
+function lockPath(root, pr) {
+    return join(watchesDir(root), `${pr}.lock`);
+}
+/**
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function readLock(root, pr) {
+    const path = lockPath(root, pr);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        // A corrupted lock is treated as no lock — re-acquire will overwrite.
+        return null;
+    }
+}
+function writeLockFile(path, payload) {
+    mkdirSync(resolve(path, '..'), { recursive: true });
+    const fd = openSync(path, 'wx');
+    try {
+        writeSync(fd, `${JSON.stringify(payload, null, 2)}\n`, 0, 'utf-8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Try to acquire the per-PR lock. On EEXIST, parse the existing lock — if the
+ * holder PID is dead AND TTL has elapsed, unlink + retry once. Otherwise
+ * return `{status:'busy', holder}`.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {string} sessionId
+ * @param {number} [pid=process.pid]
+ */
+export function acquireLock(root, pr, sessionId, pid = process.pid) {
+    const path = lockPath(root, pr);
+    const payload = {
+        sessionId,
+        pid,
+        acquiredAt: new Date().toISOString(),
+        ttl_seconds: TTL_SECONDS,
+    };
+    try {
+        writeLockFile(path, payload);
+        return { status: 'ok', lock: payload };
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    // Lock file exists — inspect.
+    const existing = readLock(root, pr);
+    if (!existing) {
+        // Corrupted lock — treat as recoverable, unlink + retry once.
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            /* race — another caller cleaned up */
+        }
+        try {
+            writeLockFile(path, payload);
+            return { status: 'ok', lock: payload };
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                return { status: 'busy', holder: readLock(root, pr) };
+            }
+            throw err;
+        }
+    }
+    if (isStale(existing)) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            /* race — another caller cleaned up */
+        }
+        try {
+            writeLockFile(path, payload);
+            return { status: 'ok', lock: payload };
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                return { status: 'busy', holder: readLock(root, pr) };
+            }
+            throw err;
+        }
+    }
+    return { status: 'busy', holder: existing };
+}
+/**
+ * Release the per-PR lock. Owner must match (`sessionId` equality). Returns
+ * `true` if released, `false` if the lock is missing or owned by someone
+ * else.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {string} sessionId
+ */
+export function releaseLock(root, pr, sessionId) {
+    const path = lockPath(root, pr);
+    if (!existsSync(path))
+        return false;
+    const existing = readLock(root, pr);
+    if (!existing) {
+        // Corrupted — fail open (let next caller clean up).
+        return false;
+    }
+    if (existing.sessionId !== sessionId)
+        return false;
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is the given lock stale (i.e., recoverable by a new caller)? Per D-05,
+ * BOTH conditions are required: dead PID AND past TTL.
+ *
+ * Exposed for unit tests; the orchestrator does not call this directly.
+ *
+ * @param {{ pid: number, acquiredAt: string, ttl_seconds: number }} lockData
+ */
+export function isStale(lockData) {
+    if (!lockData || typeof lockData !== 'object')
+        return false;
+    const ttlMs = (lockData.ttl_seconds || TTL_SECONDS) * 1000;
+    const age = Date.now() - new Date(lockData.acquiredAt).getTime();
+    if (age <= ttlMs)
+        return false;
+    return !isPidAlive(lockData.pid);
+}
+//# sourceMappingURL=lock.mjs.map

package/dist/cli/ci-watch/lock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.mjs","sourceRoot":"","sources":["../../../src/cli/ci-watch/lock.mjs"],"names":[],"mappings":"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"}

package/dist/cli/ci-watch/state.d.mts

@@ -0,0 +1,36 @@
+/**
+ * Read the per-PR state file. Returns `null` when the file does not exist.
+ * Returns `{ error: 'corrupted', message }` when the file exists but is not
+ * parseable JSON — callers route that to the infra-backoff branch.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function readState(root: string, pr: number | string): any;
+/**
+ * Atomically write the per-PR state file. Caller passes the full state object
+ * — this function does not merge, it overwrites. Use `readState` first if a
+ * merge is needed.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {object} state
+ */
+export function writeState(root: string, pr: number | string, state: object): void;
+/**
+ * Delete the per-PR state file. No-op when the file does not exist.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function deleteState(root: string, pr: number | string): void;
+/**
+ * Enumerate every per-PR state file under `.aperant/ci-watches/`. Returns an
+ * array of parsed state objects in lexicographic filename order. Skips files
+ * whose name does not match `<pr>.json` and skips corrupted files (their
+ * presence does not block the rest of the listing).
+ *
+ * @param {string} root
+ */
+export function listWatches(root: string): any[];
+//# sourceMappingURL=state.d.mts.map

package/dist/cli/ci-watch/state.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.mts","sourceRoot":"","sources":["../../../src/cli/ci-watch/state.mjs"],"names":[],"mappings":"AAsCA;;;;;;;GAOG;AACH,gCAHW,MAAM,MACN,MAAM,GAAC,MAAM,OAUvB;AAED;;;;;;;;GAQG;AACH,iCAJW,MAAM,MACN,MAAM,GAAC,MAAM,SACb,MAAM,QAIhB;AAED;;;;;GAKG;AACH,kCAHW,MAAM,MACN,MAAM,GAAC,MAAM,QAKvB;AAED;;;;;;;GAOG;AACH,kCAFW,MAAM,SAgBhB"}

package/dist/cli/ci-watch/state.mjs

@@ -0,0 +1,103 @@
+/**
+ * ci-watch/state.mjs — per-PR state-file primitives for the /apt:watch-ci
+ * post-ship watcher (D-04).
+ *
+ * Storage shape (`.aperant/ci-watches/{pr}.json`), spec.md §8:
+ *
+ *   {
+ *     pr, task_id, host, scheduler_handle | null,
+ *     attempts, started_at, deadline, last_poll,
+ *     last_status | null, next_tick_interval_ms,
+ *     paused, auto_merge_on_green
+ *   }
+ *
+ * This module is pure read/write — classification logic lives in
+ * stop-matrix.mjs, the orchestrator lives in commands/ci-watch.mjs.
+ *
+ * Crash-safety: `writeState` goes through `atomicWriteJson` (tmp + fsync +
+ * rename). `readState` returns `null` for a missing file and never throws on
+ * a missing path — callers can distinguish "no watch yet" from "watch is
+ * corrupted".
+ *
+ * The corrupted-JSON branch returns a recoverable error envelope rather than
+ * throwing so the orchestrator can surface it without crashing the cron
+ * payload mid-tick.
+ */
+import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { atomicWriteJson } from '../util/io.mjs';
+function watchesDir(root) {
+    return join(resolve(root), '.aperant', 'ci-watches');
+}
+function stateFile(root, pr) {
+    return join(watchesDir(root), `${pr}.json`);
+}
+/**
+ * Read the per-PR state file. Returns `null` when the file does not exist.
+ * Returns `{ error: 'corrupted', message }` when the file exists but is not
+ * parseable JSON — callers route that to the infra-backoff branch.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function readState(root, pr) {
+    const path = stateFile(root, pr);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        return { error: 'corrupted', message: err.message };
+    }
+}
+/**
+ * Atomically write the per-PR state file. Caller passes the full state object
+ * — this function does not merge, it overwrites. Use `readState` first if a
+ * merge is needed.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {object} state
+ */
+export function writeState(root, pr, state) {
+    atomicWriteJson(stateFile(root, pr), state);
+}
+/**
+ * Delete the per-PR state file. No-op when the file does not exist.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function deleteState(root, pr) {
+    const path = stateFile(root, pr);
+    if (existsSync(path))
+        unlinkSync(path);
+}
+/**
+ * Enumerate every per-PR state file under `.aperant/ci-watches/`. Returns an
+ * array of parsed state objects in lexicographic filename order. Skips files
+ * whose name does not match `<pr>.json` and skips corrupted files (their
+ * presence does not block the rest of the listing).
+ *
+ * @param {string} root
+ */
+export function listWatches(root) {
+    const dir = watchesDir(root);
+    if (!existsSync(dir))
+        return [];
+    const watches = [];
+    for (const f of readdirSync(dir).sort()) {
+        if (!/^\d+\.json$/.test(f))
+            continue;
+        try {
+            watches.push(JSON.parse(readFileSync(join(dir, f), 'utf-8')));
+        }
+        catch {
+            // Skip corrupted state files — listWatches is a read-only enumerator
+            // and must not throw on partial corruption.
+        }
+    }
+    return watches;
+}
+//# sourceMappingURL=state.mjs.map

package/dist/cli/ci-watch/state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.mjs","sourceRoot":"","sources":["../../../src/cli/ci-watch/state.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAC3E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhD,SAAS,UAAU,CAAC,IAAI;IACvB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,YAAY,CAAC,CAAA;AACrD,CAAC;AAED,SAAS,SAAS,CAAC,IAAI,EAAE,EAAE;IAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,IAAI,EAAE,EAAE;IACjC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAClC,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAA;IACpD,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK;IACzC,eAAe,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,KAAK,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAI,EAAE,EAAE;IACnC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAChC,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,UAAU,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAI;IAC/B,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAA;IAC5B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAA;IAC/B,MAAM,OAAO,GAAG,EAAE,CAAA;IAClB,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,SAAQ;QACpC,IAAI,CAAC;YACJ,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;QAC9D,CAAC;QAAC,MAAM,CAAC;YACR,qEAAqE;YACrE,4CAA4C;QAC7C,CAAC;IACF,CAAC;IACD,OAAO,OAAO,CAAA;AACf,CAAC"}

package/dist/cli/ci-watch/stop-matrix.d.mts

@@ -0,0 +1,58 @@
+/**
+ * @typedef {Object} CheckRow
+ * @property {string} [name]
+ * @property {string} [conclusion] e.g. 'success' | 'failure' | 'cancelled' | 'timed_out' | 'neutral'
+ * @property {string} [state]
+ * @property {string} [bucket]
+ * @property {string} [failure_class] — optional pre-classified hint (test-only seam)
+ * @property {string} [log_fingerprint] — optional digest for identical-log detection
+ *
+ * @typedef {Object} ClassifyInput
+ * @property {CheckRow[]} checks
+ * @property {Object} state — per-PR state (see state.mjs §8)
+ * @property {Object} prMetadata — { state: 'OPEN'|'CLOSED'|'MERGED', reviewDecision?: string }
+ *
+ * @typedef {Object} ClassifyOutput
+ * @property {string} action
+ * @property {boolean} counts_toward_budget
+ * @property {string} reason
+ *
+ * @param {ClassifyInput} input
+ * @returns {ClassifyOutput}
+ */
+export function classify({ checks, state, prMetadata }: ClassifyInput): ClassifyOutput;
+export function isFailing(check: any): boolean;
+export type CheckRow = {
+    name?: string | undefined;
+    /**
+     * e.g. 'success' | 'failure' | 'cancelled' | 'timed_out' | 'neutral'
+     */
+    conclusion?: string | undefined;
+    state?: string | undefined;
+    bucket?: string | undefined;
+    /**
+     * — optional pre-classified hint (test-only seam)
+     */
+    failure_class?: string | undefined;
+    /**
+     * — optional digest for identical-log detection
+     */
+    log_fingerprint?: string | undefined;
+};
+export type ClassifyInput = {
+    checks: CheckRow[];
+    /**
+     * — per-PR state (see state.mjs §8)
+     */
+    state: Object;
+    /**
+     * — { state: 'OPEN'|'CLOSED'|'MERGED', reviewDecision?: string }
+     */
+    prMetadata: Object;
+};
+export type ClassifyOutput = {
+    action: string;
+    counts_toward_budget: boolean;
+    reason: string;
+};
+//# sourceMappingURL=stop-matrix.d.mts.map

package/dist/cli/ci-watch/stop-matrix.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-matrix.d.mts","sourceRoot":"","sources":["../../../src/cli/ci-watch/stop-matrix.mjs"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wDAHW,aAAa,GACX,cAAc,CA6H1B;AAED,+CAGC;;;;;;;;;;;;;;;;;;;YA5Ia,QAAQ,EAAE;;;;WACV,MAAM;;;;gBACN,MAAM;;;YAGN,MAAM;0BACN,OAAO;YACP,MAAM"}