@cairn-tool/cairn 3.4.0 → 3.6.0

package/dist/qa/agents/cursor.js

@@ -0,0 +1,143 @@
+import { flatten } from "../format.js";
+import { isRecord, num, sessionIdOf } from "./types.js";
+const TOOL_ARG_FIELDS = [
+    "command",
+    "path",
+    "globPattern",
+    "pattern",
+    "query",
+    "target_notebook",
+    "url",
+];
+/** Return [display name, short args] from a Cursor `tool_call` object. */
+export function toolLabel(toolCall) {
+    for (const [key, payload] of Object.entries(toolCall)) {
+        if (!(key.endsWith("ToolCall") && isRecord(payload)))
+            continue;
+        const raw = key.slice(0, -"ToolCall".length);
+        const name = raw ? raw[0].toUpperCase() + raw.slice(1) : key;
+        const args = isRecord(payload["args"]) ? payload["args"] : {};
+        let summary = "";
+        for (const fieldName of TOOL_ARG_FIELDS) {
+            const value = args[fieldName];
+            if (value !== undefined && value !== null && value !== "" && value !== 0 && value !== false) {
+                summary = flatten(String(value));
+                break;
+            }
+        }
+        return [name, summary];
+    }
+    return ["tool", ""];
+}
+export function toolFailed(toolCall) {
+    for (const [key, payload] of Object.entries(toolCall)) {
+        if (key.endsWith("ToolCall") && isRecord(payload)) {
+            const result = payload["result"];
+            return isRecord(result) && "error" in result;
+        }
+    }
+    return false;
+}
+function cursorUsage(raw) {
+    if (!isRecord(raw))
+        return null;
+    return {
+        inputTokens: num(raw["inputTokens"]),
+        outputTokens: num(raw["outputTokens"]),
+        cacheReadTokens: num(raw["cacheReadTokens"]),
+        cacheWriteTokens: num(raw["cacheWriteTokens"]),
+    };
+}
+export const cursorProfile = {
+    name: "cursor",
+    binaries: ["cursor-agent", "agent"],
+    defaultModel: "cursor-grok-4.6-high",
+    buildArgv(input, binary) {
+        return [
+            binary,
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--force",
+            "--trust",
+            "--workspace",
+            input.repo,
+            "--model",
+            input.model,
+            input.prompt,
+        ];
+    },
+    normalize(raw) {
+        const kind = raw["type"];
+        const subtype = raw["subtype"];
+        const sessionId = sessionIdOf(raw);
+        if (kind === "thinking") {
+            if (subtype === "delta") {
+                const text = raw["text"];
+                return {
+                    kind: "thinking",
+                    phase: "delta",
+                    text: typeof text === "string" ? text : "",
+                    sessionId,
+                };
+            }
+            if (subtype === "completed")
+                return { kind: "thinking", phase: "completed", sessionId };
+            return null;
+        }
+        if (kind === "assistant") {
+            const message = isRecord(raw["message"]) ? raw["message"] : {};
+            const rawContent = message["content"];
+            const content = typeof rawContent === "string"
+                ? [{ type: "text", text: rawContent }]
+                : Array.isArray(rawContent)
+                    ? rawContent
+                    : [];
+            const events = [];
+            for (const part of content) {
+                if (isRecord(part) && part["type"] === "text" && part["text"]) {
+                    events.push({ kind: "text", text: String(part["text"]), sessionId });
+                }
+            }
+            return events.length === 0 ? null : events;
+        }
+        if (kind === "tool_call") {
+            const tool = isRecord(raw["tool_call"]) ? raw["tool_call"] : {};
+            const [name, summary] = toolLabel(tool);
+            if (subtype === "started") {
+                return { kind: "tool", phase: "started", name, summary, sessionId };
+            }
+            if (subtype === "completed") {
+                return {
+                    kind: "tool",
+                    phase: "completed",
+                    name,
+                    summary,
+                    failed: toolFailed(tool),
+                    sessionId,
+                };
+            }
+            return null;
+        }
+        if (kind === "result") {
+            const usage = cursorUsage(raw["usage"]);
+            const error = raw["is_error"]
+                ? String(raw["result"] ? raw["result"] : "agent reported an error")
+                : undefined;
+            if (!usage && !error)
+                return null;
+            return {
+                kind: "usage",
+                usage: usage ?? {},
+                ...(error ? { error } : {}),
+                sessionId,
+            };
+        }
+        if (kind === "system" && subtype === "init") {
+            const model = raw["model"];
+            return { kind: "init", model: model ? String(model) : undefined, sessionId };
+        }
+        return null;
+    },
+};
+//# sourceMappingURL=cursor.js.map

package/dist/qa/agents/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../src/qa/agents/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,eAAe,GAAG;IACtB,SAAS;IACT,MAAM;IACN,aAAa;IACb,SAAS;IACT,OAAO;IACP,iBAAiB;IACjB,KAAK;CACG,CAAC;AAEX,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,QAAiC;IACzD,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC;YAAE,SAAS;QAC/D,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9D,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,IAAI,OAAO,GAAG,EAAE,CAAC;QACjB,KAAK,MAAM,SAAS,IAAI,eAAe,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;gBAC5F,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBACjC,MAAM;YACR,CAAC;QACH,CAAC;QACD,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,QAAiC;IAC1D,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAClD,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YACjC,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,IAAI,MAAM,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO;QACL,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACpC,YAAY,EAAE,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACtC,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;QAC5C,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,CAAC,cAAc,EAAE,OAAO,CAAC;IACnC,YAAY,EAAE,sBAAsB;IACpC,SAAS,CAAC,KAAqB,EAAE,MAAc;QAC7C,OAAO;YACL,MAAM;YACN,IAAI;YACJ,iBAAiB;YACjB,aAAa;YACb,SAAS;YACT,SAAS;YACT,aAAa;YACb,KAAK,CAAC,IAAI;YACV,SAAS;YACT,KAAK,CAAC,KAAK;YACX,KAAK,CAAC,MAAM;SACb,CAAC;IACJ,CAAC;IACD,SAAS,CAAC,GAA4B;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;QACzB,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAEnC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACxB,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;gBACxB,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;gBACzB,OAAO;oBACL,IAAI,EAAE,UAAU;oBAChB,KAAK,EAAE,OAAO;oBACd,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;oBAC1C,SAAS;iBACV,CAAC;YACJ,CAAC;YACD,IAAI,OAAO,KAAK,WAAW;gBAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;YACxF,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/D,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;YACtC,MAAM,OAAO,GACX,OAAO,UAAU,KAAK,QAAQ;gBAC5B,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;gBACtC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;oBACzB,CAAC,CAAC,UAAU;oBACZ,CAAC,CAAC,EAAE,CAAC;YACX,MAAM,MAAM,GAAc,EAAE,CAAC;YAC7B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC3B,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC9D,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;gBACvE,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;QAC7C,CAAC;QAED,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;YACtE,CAAC;YACD,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBAC5B,OAAO;oBACL,IAAI,EAAE,MAAM;oBACZ,KAAK,EAAE,WAAW;oBAClB,IAAI;oBACJ,OAAO;oBACP,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC;oBACxB,SAAS;iBACV,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACxC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;gBAC3B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,yBAAyB,CAAC;gBACnE,CAAC,CAAC,SAAS,CAAC;YACd,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YAClC,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,KAAK,IAAI,EAAE;gBAClB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3B,SAAS;aACV,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;YAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC;QAC/E,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAC"}

package/dist/qa/agents/index.d.ts

@@ -0,0 +1,32 @@
+import type { QaAgentProfile } from "./types.js";
+/**
+ * Every backend `qa run` can spawn.
+ *
+ * Registering another assistant is a new module plus a line here. Nothing
+ * outside this directory may branch on an agent's name: argv, event parsing,
+ * and the default model are read from the profile.
+ */
+export declare const AGENTS: readonly QaAgentProfile[];
+export declare const SUPPORTED_AGENTS: readonly string[];
+export declare function resolveAgent(name: string): QaAgentProfile;
+export declare function defaultModels(): Record<string, string>;
+/**
+ * Resolve the executable for one profile. An explicit `--agent` path overrides
+ * every backend — that is the fake-agent test hook. PATH lookup is lazy and
+ * cached per profile so a cursor-only queue does not fail because `claude` is
+ * absent.
+ */
+export declare function resolveBinary(name: string, explicit: string | null): string;
+/**
+ * The executable to *display* for a profile, for --dry-run only.
+ *
+ * Falls back to the profile's first candidate name when nothing is on PATH: previewing a
+ * queue launches nothing, so requiring the backend to be installed would make `qa run
+ * --dry-run` fail on exactly the machine you would preview a queue on — and would make the
+ * e2e suite depend on cursor-agent and claude being present on the CI runner. An explicit
+ * --agent is still validated, because a bad path there is a real invocation error.
+ */
+export declare function displayBinary(name: string, explicit: string | null): string;
+export declare function agentCaps(parallel: number): ReadonlyMap<string, number>;
+export type { AgentArgvInput, NormalizedEvents, QaAgentProfile, QaEvent } from "./types.js";
+export { asEventList } from "./types.js";

package/dist/qa/agents/index.js

@@ -0,0 +1,83 @@
+import { UserError, which } from "../config.js";
+import { findExplicitAgent } from "../config.js";
+import { claudeCodeProfile } from "./claude-code.js";
+import { cursorProfile } from "./cursor.js";
+/**
+ * Every backend `qa run` can spawn.
+ *
+ * Registering another assistant is a new module plus a line here. Nothing
+ * outside this directory may branch on an agent's name: argv, event parsing,
+ * and the default model are read from the profile.
+ */
+export const AGENTS = [cursorProfile, claudeCodeProfile];
+for (const profile of AGENTS) {
+    if (profile.maxParallel !== undefined &&
+        (!Number.isInteger(profile.maxParallel) || profile.maxParallel < 1)) {
+        throw new Error(`qa agent profile ${profile.name} maxParallel must be >= 1`);
+    }
+}
+export const SUPPORTED_AGENTS = AGENTS.map((profile) => profile.name);
+const BY_NAME = new Map(AGENTS.map((profile) => [profile.name, profile]));
+const binaryCache = new Map();
+export function resolveAgent(name) {
+    const profile = BY_NAME.get(name);
+    if (!profile) {
+        throw new UserError(`Unknown agent: ${name} (known: ${SUPPORTED_AGENTS.join(", ")})`);
+    }
+    return profile;
+}
+export function defaultModels() {
+    return Object.fromEntries(AGENTS.map((profile) => [profile.name, profile.defaultModel]));
+}
+/**
+ * Resolve the executable for one profile. An explicit `--agent` path overrides
+ * every backend — that is the fake-agent test hook. PATH lookup is lazy and
+ * cached per profile so a cursor-only queue does not fail because `claude` is
+ * absent.
+ */
+export function resolveBinary(name, explicit) {
+    if (explicit)
+        return findExplicitAgent(explicit);
+    const hit = binaryCache.get(name);
+    if (hit)
+        return hit;
+    const profile = resolveAgent(name);
+    for (const candidate of profile.binaries) {
+        const found = which(candidate);
+        if (found) {
+            binaryCache.set(name, found);
+            return found;
+        }
+    }
+    throw new UserError(`${profile.binaries[0]} not on PATH; pass --agent /path/to/${profile.binaries[0]}`);
+}
+/**
+ * The executable to *display* for a profile, for --dry-run only.
+ *
+ * Falls back to the profile's first candidate name when nothing is on PATH: previewing a
+ * queue launches nothing, so requiring the backend to be installed would make `qa run
+ * --dry-run` fail on exactly the machine you would preview a queue on — and would make the
+ * e2e suite depend on cursor-agent and claude being present on the CI runner. An explicit
+ * --agent is still validated, because a bad path there is a real invocation error.
+ */
+export function displayBinary(name, explicit) {
+    if (explicit)
+        return findExplicitAgent(explicit);
+    try {
+        return resolveBinary(name, null);
+    }
+    catch {
+        return resolveAgent(name).binaries[0];
+    }
+}
+export function agentCaps(parallel) {
+    const caps = new Map();
+    for (const profile of AGENTS) {
+        // An absent cap means --parallel alone decides, so a queue of one backend can use
+        // every slot the user asked for.
+        caps.set(profile.name, Math.min(profile.maxParallel ?? parallel, parallel));
+    }
+    return caps;
+}
+export { asEventList } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/qa/agents/index.js.map

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

package/dist/qa/agents/types.d.ts

@@ -0,0 +1,61 @@
+import type { Usage } from "../outcome.js";
+/**
+ * Normalized harness event. Slot.applyEvent consumes only this; vendor JSON never
+ * reaches the TUI, reports, or tracker.
+ */
+export type QaEvent = {
+    kind: "text";
+    text: string;
+    sessionId?: string;
+} | {
+    kind: "thinking";
+    phase: "delta" | "completed";
+    text?: string;
+    sessionId?: string;
+} | {
+    kind: "tool";
+    phase: "started" | "completed";
+    name: string;
+    summary: string;
+    failed?: boolean;
+    sessionId?: string;
+} | {
+    kind: "usage";
+    usage: Usage;
+    error?: string;
+    sessionId?: string;
+} | {
+    kind: "init";
+    model?: string;
+    sessionId?: string;
+};
+export type NormalizedEvents = QaEvent | QaEvent[] | null;
+/** Enough of a case for argv construction without importing Case. */
+export interface AgentArgvInput {
+    repo: string;
+    model: string;
+    prompt: string;
+}
+/**
+ * Per-backend profile. Registering another assistant is a new module plus a
+ * line in index.ts. Nothing outside src/qa/agents/ may branch on an agent's name.
+ */
+export interface QaAgentProfile {
+    readonly name: string;
+    /** PATH candidates, first match wins. */
+    readonly binaries: readonly string[];
+    readonly defaultModel: string;
+    /**
+     * A real concurrency limit for this backend, or absent when the vendor imposes none we
+     * know of. Combined with --parallel by min(), so an absent cap means --parallel alone
+     * decides. Never set this to the *default* of --parallel: that silently caps the flag.
+     * Must be >= 1 when present.
+     */
+    readonly maxParallel?: number;
+    buildArgv(input: AgentArgvInput, binary: string): string[];
+    normalize(raw: Record<string, unknown>): NormalizedEvents;
+}
+export declare function asEventList(events: NormalizedEvents): QaEvent[];
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function sessionIdOf(raw: Record<string, unknown>): string | undefined;
+export declare function num(value: unknown): number | undefined;

package/dist/qa/agents/types.js

@@ -0,0 +1,18 @@
+export function asEventList(events) {
+    if (events === null)
+        return [];
+    if (Array.isArray(events))
+        return [...events];
+    return [events];
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function sessionIdOf(raw) {
+    const value = raw["session_id"];
+    return value ? String(value) : undefined;
+}
+export function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+//# sourceMappingURL=types.js.map

package/dist/qa/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/qa/agents/types.ts"],"names":[],"mappings":"AAmEA,MAAM,UAAU,WAAW,CAAC,MAAwB;IAClD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAC9C,OAAO,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAA4B;IACtD,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,KAAc;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC"}

package/dist/qa/async.d.ts

@@ -0,0 +1,27 @@
+/** A latch workers await while dispatch is paused. Opening it wakes everyone at once. */
+export declare class Gate {
+    private opened;
+    private waiters;
+    constructor(opened?: boolean);
+    get isOpen(): boolean;
+    set(opened: boolean): void;
+    wait(): Promise<void>;
+}
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function signalNumber(sig: NodeJS.Signals): number;
+/**
+ * Actions that must run exactly once, on every exit path. LIFO, idempotent, synchronous only —
+ * a `process.on('exit')` handler cannot await. The terminal restore and the lock release both
+ * register here rather than installing competing handlers that fight over process.exit.
+ *
+ * Signals are deliberately NOT handled here: the harness maps them to requestStop() so a run
+ * unwinds gracefully, and the resulting normal exit fires this via 'exit'.
+ */
+export declare class Cleanup {
+    private actions;
+    private ran;
+    private installed;
+    add(action: () => void): void;
+    run(): void;
+    install(onFatal: (err: unknown) => void): void;
+}

package/dist/qa/async.js

@@ -0,0 +1,91 @@
+import { constants as osConstants } from "node:os";
+/** A latch workers await while dispatch is paused. Opening it wakes everyone at once. */
+export class Gate {
+    opened;
+    waiters = [];
+    constructor(opened = true) {
+        this.opened = opened;
+    }
+    get isOpen() {
+        return this.opened;
+    }
+    set(opened) {
+        this.opened = opened;
+        if (!opened)
+            return;
+        const pending = this.waiters;
+        this.waiters = [];
+        for (const wake of pending)
+            wake();
+    }
+    wait() {
+        if (this.opened)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export function signalNumber(sig) {
+    return osConstants.signals[sig] ?? 0;
+}
+/**
+ * Actions that must run exactly once, on every exit path. LIFO, idempotent, synchronous only —
+ * a `process.on('exit')` handler cannot await. The terminal restore and the lock release both
+ * register here rather than installing competing handlers that fight over process.exit.
+ *
+ * Signals are deliberately NOT handled here: the harness maps them to requestStop() so a run
+ * unwinds gracefully, and the resulting normal exit fires this via 'exit'.
+ */
+export class Cleanup {
+    actions = [];
+    ran = false;
+    installed = false;
+    add(action) {
+        this.actions.push(action);
+    }
+    run() {
+        if (this.ran)
+            return;
+        this.ran = true;
+        for (const action of [...this.actions].reverse()) {
+            try {
+                action();
+            }
+            catch {
+                /* a failing cleanup must not block the others */
+            }
+        }
+    }
+    install(onFatal) {
+        if (this.installed)
+            return;
+        this.installed = true;
+        process.on("exit", () => this.run());
+        const fatal = (err) => {
+            this.run();
+            onFatal(err);
+            process.exit(1);
+        };
+        process.on("uncaughtException", fatal);
+        process.on("unhandledRejection", fatal);
+    }
+}
+//# sourceMappingURL=async.js.map

package/dist/qa/async.js.map

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

package/dist/qa/casefile.d.ts

@@ -0,0 +1,35 @@
+/** One `_plans/tc-<N>.yaml`, validated. Everything the harness needs about a case. */
+export interface CaseFile {
+    /** `tc-24` — the identity, derived from the filename and cross-checked against `id`. */
+    name: string;
+    number: number;
+    /** Absolute path to the YAML itself. */
+    file: string;
+    /** YAML `id`, as written (`TC-24`). */
+    id: string;
+    /** YAML `name` — the human title. */
+    title: string;
+    agent: string;
+    /** YAML `model`, or null when the case defers to `--model`. */
+    model: string | null;
+    parallel: boolean;
+    tags: string[];
+    /** The plan body, verbatim. */
+    plan: string;
+}
+/** `tc-24.yaml` -> `tc-24`, or null when the name is not a case file at all. */
+export declare function caseNameOf(entry: string): string | null;
+/**
+ * Validate one parsed YAML document against the schema. Every problem is reported, not just the
+ * first, so a single run tells the author everything wrong with the file.
+ */
+export declare function validateCaseFile(doc: unknown, name: string, file: string, fail: (message: string) => void): CaseFile | null;
+export interface LoadResult {
+    cases: CaseFile[];
+    errors: string[];
+}
+/**
+ * Every `tc-<N>.yaml` under `_plans/`, parsed and validated. Errors accumulate across files so one
+ * invocation reports every broken case rather than stopping at the first.
+ */
+export declare function loadCaseFiles(plansDir: string): LoadResult;