@isaacriehm/cairn-core 0.1.0

package/dist/events/reader.js

@@ -0,0 +1,139 @@
+/**
+ * Invalidation event reader + retention GC.
+ *
+ * `eventsSince(repoRoot, sinceMs)` — list events with ts > sinceMs,
+ * sorted ascending. Used by the plugin Stop hook to surface only events
+ * that landed during the current session.
+ *
+ * `gcStaleEvents(repoRoot, opts?)` — drops events older than 7 days.
+ * Wired into the standard sweep so the events directory stays bounded.
+ */
+import { existsSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { eventsDir } from "./paths.js";
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+export function eventsSince(args) {
+    const dir = eventsDir(args.repoRoot);
+    const events = [];
+    const malformed = [];
+    if (!existsSync(dir))
+        return { events, malformed };
+    const entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+    for (const e of entries) {
+        if (!e.isFile() || !e.name.endsWith(".json"))
+            continue;
+        const abs = join(dir, e.name);
+        let body;
+        try {
+            body = readFileSync(abs, "utf8");
+        }
+        catch {
+            malformed.push(e.name);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            malformed.push(e.name);
+            continue;
+        }
+        if (!isInvalidationEvent(parsed)) {
+            malformed.push(e.name);
+            continue;
+        }
+        if (parsed.ts > args.sinceMs)
+            events.push(parsed);
+    }
+    events.sort((a, b) => a.ts - b.ts);
+    if (typeof args.limit === "number" && events.length > args.limit) {
+        events.length = args.limit;
+    }
+    return { events, malformed };
+}
+/**
+ * Remove event files older than `maxAgeMs` (default 7 days). Uses each
+ * file's parsed `ts` when present; falls back to `mtimeMs` otherwise.
+ */
+export function gcStaleEvents(args) {
+    const dir = eventsDir(args.repoRoot);
+    const removed = [];
+    const kept = [];
+    if (!existsSync(dir))
+        return { removed, kept };
+    const maxAge = args.maxAgeMs ?? SEVEN_DAYS_MS;
+    const now = args.now ? args.now() : Date.now();
+    const entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+    for (const e of entries) {
+        if (!e.isFile() || !e.name.endsWith(".json"))
+            continue;
+        const abs = join(dir, e.name);
+        let ts = null;
+        try {
+            const parsed = JSON.parse(readFileSync(abs, "utf8"));
+            if (typeof parsed?.ts === "number")
+                ts = parsed.ts;
+        }
+        catch {
+            ts = null;
+        }
+        if (ts === null) {
+            try {
+                ts = statSync(abs).mtimeMs;
+            }
+            catch {
+                ts = 0;
+            }
+        }
+        if (now - ts >= maxAge) {
+            try {
+                rmSync(abs, { force: true });
+                removed.push(e.name);
+            }
+            catch {
+                kept.push(e.name);
+            }
+        }
+        else {
+            kept.push(e.name);
+        }
+    }
+    return { removed, kept };
+}
+function isInvalidationEvent(x) {
+    if (x === null || typeof x !== "object")
+        return false;
+    const o = x;
+    if (typeof o["ts"] !== "number")
+        return false;
+    if (typeof o["kind"] !== "string")
+        return false;
+    if (!Array.isArray(o["refs"]))
+        return false;
+    for (const r of o["refs"])
+        if (!isRef(r))
+            return false;
+    const source = o["source"];
+    if (source === null || typeof source !== "object")
+        return false;
+    const s = source;
+    if (s["session_id"] !== null && typeof s["session_id"] !== "string")
+        return false;
+    if (typeof s["tool"] !== "string")
+        return false;
+    if (o["path"] !== undefined && typeof o["path"] !== "string")
+        return false;
+    return true;
+}
+function isRef(x) {
+    if (x === null || typeof x !== "object")
+        return false;
+    const o = x;
+    return (typeof o["id"] === "string" &&
+        (o["kind"] === "decision" ||
+            o["kind"] === "invariant" ||
+            o["kind"] === "task" ||
+            o["kind"] === "path"));
+}
+//# sourceMappingURL=reader.js.map

package/dist/events/reader.js.map

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

package/dist/events/writer.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Invalidation event writer.
+ *
+ * Per PLUGIN_ARCHITECTURE §7 (three-layer conflict catch, layer 2),
+ * every locked write to global state emits a small JSON file under
+ * `.cairn/events/`. Plugin Stop hooks in other live sessions poll
+ * that directory and surface an inline A/B/C if the event touches a
+ * DEC/§V they have in scope.
+ *
+ * Files: `.cairn/events/<msTs>-<kind>.json` — sortable by name. ts
+ * collisions resolved with a short crypto suffix.
+ *
+ * Retention: events older than 7 days are GC'd by `gcStaleEvents`.
+ */
+/**
+ * Reference into the canonical zone — what this event invalidates.
+ * Decision/invariant ids are filtered against the reading session's
+ * in-scope set; path entries match against scope-globs.
+ */
+export interface InvalidationEventRef {
+    kind: "decision" | "invariant" | "task" | "path";
+    id: string;
+}
+export interface InvalidationEventSource {
+    /** Claude Code session id of the writer, if known. */
+    session_id: string | null;
+    /** MCP tool name (e.g. `cairn_record_decision`) or other emitter id. */
+    tool: string;
+}
+export interface InvalidationEvent {
+    /** ms-since-epoch — set by the writer if not provided. */
+    ts: number;
+    /** Short event kind. Decision-recorded, archived, task-created, etc. */
+    kind: string;
+    /** Things this event invalidates. Empty array allowed for diagnostic events. */
+    refs: InvalidationEventRef[];
+    /** Path relative to repo root, when applicable. */
+    path?: string;
+    /** Where the event came from. */
+    source: InvalidationEventSource;
+}
+export interface WriteInvalidationEventInput {
+    kind: string;
+    refs: InvalidationEventRef[];
+    source: InvalidationEventSource;
+    path?: string;
+    /** Override Date.now() — tests use this. */
+    ts?: number;
+}
+export interface WriteInvalidationEventResult {
+    /** Absolute path to the event file written. */
+    filePath: string;
+    /** Final event payload (with ts filled in). */
+    event: InvalidationEvent;
+}
+/**
+ * Write a single invalidation event. Best-effort — failures throw, but
+ * locked-write callers should swallow + log so the underlying write is
+ * never rolled back by an emit failure.
+ */
+export declare function writeInvalidationEvent(repoRoot: string, input: WriteInvalidationEventInput): WriteInvalidationEventResult;

package/dist/events/writer.js

@@ -0,0 +1,68 @@
+/**
+ * Invalidation event writer.
+ *
+ * Per PLUGIN_ARCHITECTURE §7 (three-layer conflict catch, layer 2),
+ * every locked write to global state emits a small JSON file under
+ * `.cairn/events/`. Plugin Stop hooks in other live sessions poll
+ * that directory and surface an inline A/B/C if the event touches a
+ * DEC/§V they have in scope.
+ *
+ * Files: `.cairn/events/<msTs>-<kind>.json` — sortable by name. ts
+ * collisions resolved with a short crypto suffix.
+ *
+ * Retention: events older than 7 days are GC'd by `gcStaleEvents`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { eventsDir } from "./paths.js";
+/**
+ * Write a single invalidation event. Best-effort — failures throw, but
+ * locked-write callers should swallow + log so the underlying write is
+ * never rolled back by an emit failure.
+ */
+export function writeInvalidationEvent(repoRoot, input) {
+    const ts = input.ts ?? Date.now();
+    const event = {
+        ts,
+        kind: input.kind,
+        refs: input.refs,
+        source: input.source,
+        ...(input.path !== undefined ? { path: input.path } : {}),
+    };
+    const dir = eventsDir(repoRoot);
+    mkdirSync(dir, { recursive: true });
+    // Filename: `<14-digit-ts>-<kind>.json`. ms epoch is ~13 digits today;
+    // pad to 14 so files sort lexically by ts even past year 2286. On
+    // collision append a short random suffix.
+    const tsStr = String(ts).padStart(14, "0");
+    const safeKind = sanitizeKind(input.kind);
+    let filename = `${tsStr}-${safeKind}.json`;
+    let filePath = join(dir, filename);
+    // wx + retry on EEXIST; bound the retries to a tiny number — Date.now()
+    // collisions across writers within the same ms are vanishingly rare,
+    // and the random suffix breaks ties in O(1) attempts.
+    let attempts = 0;
+    while (true) {
+        try {
+            writeFileSync(filePath, `${JSON.stringify(event, null, 2)}\n`, {
+                encoding: "utf8",
+                flag: "wx",
+            });
+            return { filePath, event };
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST" || attempts >= 4)
+                throw err;
+            const suffix = randomBytes(2).toString("hex");
+            filename = `${tsStr}-${safeKind}-${suffix}.json`;
+            filePath = join(dir, filename);
+            attempts += 1;
+        }
+    }
+}
+function sanitizeKind(raw) {
+    return raw.replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "event";
+}
+//# sourceMappingURL=writer.js.map

package/dist/events/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/events/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgDvC;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAgB,EAChB,KAAkC;IAElC,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IAClC,MAAM,KAAK,GAAsB;QAC/B,EAAE;QACF,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1D,CAAC;IAEF,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAChC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEpC,uEAAuE;IACvE,kEAAkE;IAClE,0CAA0C;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,QAAQ,GAAG,GAAG,KAAK,IAAI,QAAQ,OAAO,CAAC;IAC3C,IAAI,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnC,wEAAwE;IACxE,qEAAqE;IACrE,sDAAsD;IACtD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,aAAa,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;gBAC7D,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,IAAI;aACX,CAAC,CAAC;YACH,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,QAAQ,IAAI,QAAQ,IAAI,CAAC;gBAAE,MAAM,GAAG,CAAC;YAClD,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC9C,QAAQ,GAAG,GAAG,KAAK,IAAI,QAAQ,IAAI,MAAM,OAAO,CAAC;YACjD,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC/B,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC;AACjF,CAAC"}

package/dist/frontend-types.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Frontend adapter contract per `docs/WORKFLOW_GUIDE.md` §0.1.
+ *
+ * The orchestrator + grounding daemon + MCP server are frontend-agnostic.
+ * The operator console is a swappable adapter that consumes a uniform
+ * task/run/UAT bundle and renders/listens via its native primitive.
+ *
+ * Adapters live in `cairn/src/frontend/<name>/`. Each implements
+ * `FrontendAdapter`. The `cairn run --frontend <name>` CLI loads + starts
+ * registered adapters; on operator events, adapters drop normalized JSON rows
+ * to `.cairn/inbox/<ts>-<source>-<slug>.json`. The orchestrator (Phase 8)
+ * picks them up. Phase 5 lands ingress-only — no orchestrator yet.
+ */
+export type NotifyLevel = "info" | "warn" | "error";
+/**
+ * A normalized inbox entry kind. Adapters drop one of these to
+ * `.cairn/inbox/`. The orchestrator multiplexes on `kind`.
+ */
+export type InboxKind = "task" | "slash" | "free_text" | "voice" | "interaction";
+export interface FrontendTask {
+    source: string;
+    intent: string;
+    rawText: string;
+    authorId: string;
+    channelId?: string;
+    guildId?: string;
+    messageId?: string;
+    receivedAt: string;
+}
+export interface VoiceMessage {
+    source: string;
+    attachmentUrl: string;
+    mime?: string;
+    authorId: string;
+    channelId: string;
+    guildId?: string;
+    messageId: string;
+    receivedAt: string;
+}
+export interface SlashEvent {
+    source: string;
+    command: string;
+    options: Record<string, string | number | boolean>;
+    authorId: string;
+    channelId?: string;
+    guildId?: string;
+    messageId?: string;
+    receivedAt: string;
+}
+export interface FreeTextEvent {
+    source: string;
+    intent: string;
+    rawText: string;
+    authorId: string;
+    channelId?: string;
+    guildId?: string;
+    messageId?: string;
+    receivedAt: string;
+}
+export interface InteractionEvent {
+    source: string;
+    bundleId: string;
+    choiceId: string;
+    freeText?: string;
+    authorId: string;
+    channelId?: string;
+    guildId?: string;
+    messageId?: string;
+    receivedAt: string;
+}
+export interface DialogChoice {
+    /** Stable id ("a" | "b" | ... | "e_other"). */
+    id: string;
+    label: string;
+}
+export interface DialogSpec {
+    /** Origin run / task id used to correlate adapter responses. */
+    bundleId: string;
+    prompt: string;
+    /**
+     * 2-5 choices. Last MUST be `E) Other` per WORKFLOW_GUIDE §1.4.
+     * If more than 4 orthogonal questions arise, caller MUST collapse to a
+     * single tightened-spec proposal per §1.0 (cap = 2 questions/turn).
+     */
+    choices: DialogChoice[];
+    channelId?: string;
+    timeoutMs?: number;
+    /**
+     * When true, the adapter notifies authorized operators (push, mention,
+     * etc. — adapter-defined) so they see the run is paused. Used for
+     * agent-initiated `cairn_ask_operator`; routine confirmations leave
+     * this false to avoid noise.
+     */
+    pingOperators?: boolean;
+    /**
+     * §3.4 win 1 — multi-step walks (per-question tightener resolution,
+     * /oops branches) edit one message in place instead of posting N+1
+     * messages. Set this to the previous step's `bundleId`; the adapter
+     * looks it up in its dialog-message map and edits that message
+     * (same channel, new prompt + buttons). When the bundleId is
+     * unknown (gone, never registered) the adapter falls back to a
+     * fresh send.
+     */
+    replaceBundleId?: string;
+    /**
+     * Terminal-dialog flag. When true (default), the adapter compacts
+     * the message on click — strips buttons, appends an "Answered" line
+     * — so the channel scrollback shows what was chosen. Walk steps
+     * that intend to be replaced by a follow-on dialog (per-Q tightener)
+     * MUST pass false: otherwise the compaction race-edits the message
+     * the next step is about to overwrite, and either the answer
+     * annotation or the next prompt loses depending on REST ordering.
+     * Adapter still fires `deferUpdate` so the click acknowledges.
+     */
+    compactOnAnswer?: boolean;
+}
+export interface DialogResponse {
+    bundleId: string;
+    choiceId: string;
+    /** Populated only when `choiceId` is the `E) Other` option. */
+    freeText?: string;
+    timedOut?: boolean;
+}
+export interface ApprovalArtifact {
+    kind: "gif" | "screenshot" | "table" | "diff" | "log" | "url" | "text";
+    label?: string;
+    path?: string;
+    url?: string;
+    content?: string;
+}
+export interface ApprovalBundle {
+    bundleId: string;
+    runId: string;
+    taskId?: string;
+    goal: string;
+    diffSummary?: string;
+    acceptance?: {
+        id: string;
+        status: "pass" | "fail" | "pending";
+        note?: string;
+    }[];
+    artifacts?: ApprovalArtifact[];
+    channelId?: string;
+    timeoutMs?: number;
+}
+export interface Approval {
+    bundleId: string;
+    decision: "approve" | "reject" | "ask";
+    reason?: string;
+    timedOut?: boolean;
+}
+export interface PostUpdate {
+    taskId: string;
+    runId?: string;
+    status: string;
+    /**
+     * Free-form body. ≤1024 chars renders as inline embed `details` field
+     * (§3.3 win 3 — drops the live-status + content-message split). >1024
+     * chars falls back to the chunked secondary-embed path.
+     */
+    body?: string;
+    /**
+     * Original task spec (the operator's verbatim ask). Replaces the
+     * standalone `🆕 Task` drop card — the body lives on the same live
+     * status embed as everything else, so the channel only ever shows
+     * one self-updating message per task. Truncated at 1024 chars.
+     */
+    taskBody?: string;
+    channelId?: string;
+    /**
+     * Tier-0 (Haiku) summary of what the agent is doing right now —
+     * one-line, present-progressive ("Reading core/src/X", "Editing
+     * platform/Y"). Surfaces inside the live status embed so the
+     * operator sees ongoing activity instead of a static "running" badge.
+     * Set on a throttled cadence by the orchestrator during the
+     * implementer phase.
+     */
+    activity?: string;
+    /**
+     * Second-source visibility — extracted from claude stream-json events.
+     * Independent of the Tier-0 summary; renders even when the Tier-0 call
+     * fails. Each list capped + deduped at the source.
+     */
+    tools?: {
+        files?: string[];
+        bash?: string[];
+        searches?: string[];
+    };
+    /**
+     * Curated narrative tail from `.cairn/runs/active/<run_id>/log.jsonl`
+     * (§3.3 win 1) — last N transitions, pre-formatted. Renders inside the
+     * live status embed's description so operator sees actual progress
+     * instead of a static "phase: running" line.
+     */
+    recentEvents?: string[];
+    /**
+     * §3.4 win 3 — when status === "failed", the orchestrator classifies
+     * which gate eject the run so the embed renders class-colored title +
+     * emoji. Operator can route differently per class.
+     */
+    failureClass?: "sensor" | "reviewer" | "uat" | "hard" | "halt";
+    /**
+     * §3.4 win 2 — failure remediation guidance surfaced as a dedicated
+     * embed field. `reason` is a one-liner; `suggestedActions` are the
+     * operator's next moves (`/ship-anyway`, re-submit, open thread).
+     */
+    remediation?: {
+        reason: string;
+        suggestedActions: string[];
+    };
+}
+export type IngestHandler<T> = (item: T) => void | Promise<void>;
+export interface FrontendAdapter {
+    readonly name: string;
+    /** Connects, registers commands, prepares to ingest events. */
+    start(): Promise<void>;
+    /** Disconnects + cleans up. Idempotent. */
+    stop(): Promise<void>;
+    onTask(handler: IngestHandler<FrontendTask>): void;
+    onVoice(handler: IngestHandler<VoiceMessage>): void;
+    onSlash(handler: IngestHandler<SlashEvent>): void;
+    onFreeText(handler: IngestHandler<FreeTextEvent>): void;
+    onInteraction(handler: IngestHandler<InteractionEvent>): void;
+    postTaskUpdate(update: PostUpdate): Promise<void>;
+    requestApproval(bundle: ApprovalBundle): Promise<Approval>;
+    requestDialog(spec: DialogSpec): Promise<DialogResponse>;
+    notify(level: NotifyLevel, message: string): Promise<void>;
+    /**
+     * Show a "typing" / activity indicator on the given channel until the
+     * returned stop fn is called. Adapters without a native typing
+     * indicator should no-op.
+     */
+    startTyping?(channelId: string): () => void;
+    /**
+     * Pre-flight check: is this channel still reachable + writable?
+     * Adapters that maintain channels MUST return false when the channel
+     * has been deleted or the adapter lacks access. The orchestrator uses
+     * this to skip dispatching a queued task whose channel is gone.
+     * Adapters without channels should leave this undefined; the
+     * orchestrator treats undefined as "always alive".
+     */
+    isChannelAlive?(channelId: string): Promise<boolean>;
+}

package/dist/frontend-types.js

@@ -0,0 +1,15 @@
+/**
+ * Frontend adapter contract per `docs/WORKFLOW_GUIDE.md` §0.1.
+ *
+ * The orchestrator + grounding daemon + MCP server are frontend-agnostic.
+ * The operator console is a swappable adapter that consumes a uniform
+ * task/run/UAT bundle and renders/listens via its native primitive.
+ *
+ * Adapters live in `cairn/src/frontend/<name>/`. Each implements
+ * `FrontendAdapter`. The `cairn run --frontend <name>` CLI loads + starts
+ * registered adapters; on operator events, adapters drop normalized JSON rows
+ * to `.cairn/inbox/<ts>-<source>-<slug>.json`. The orchestrator (Phase 8)
+ * picks them up. Phase 5 lands ingress-only — no orchestrator yet.
+ */
+export {};
+//# sourceMappingURL=frontend-types.js.map

package/dist/frontend-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-types.js","sourceRoot":"","sources":["../src/frontend-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/gc/apply.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Apply a single GcCommitProposal to the mirror checkout: write the patch
+ * files, run `git add` + `git commit`, return the resulting SHA.
+ *
+ * The caller is responsible for filtering proposals by `class` (only safe is
+ * auto-applied in v1; code / high-stakes are surfaced for confirm).
+ *
+ * No push happens here — the GC sweep + canary verification + push policy is
+ * orchestrated by `runGcBatch` (sweep.ts).
+ */
+import type { GcCommitProposal } from "./types.js";
+export interface ApplyCommitOptions {
+    repoRoot: string;
+    proposal: GcCommitProposal;
+    /** Override the commit author (smoke convenience). */
+    author?: {
+        name: string;
+        email: string;
+    };
+}
+export interface ApplyCommitResult {
+    commit_sha: string;
+    paths_written: string[];
+    paths_deleted: string[];
+}
+export declare function applyCommit(opts: ApplyCommitOptions): Promise<ApplyCommitResult>;

package/dist/gc/apply.js

@@ -0,0 +1,48 @@
+/**
+ * Apply a single GcCommitProposal to the mirror checkout: write the patch
+ * files, run `git add` + `git commit`, return the resulting SHA.
+ *
+ * The caller is responsible for filtering proposals by `class` (only safe is
+ * auto-applied in v1; code / high-stakes are surfaced for confirm).
+ *
+ * No push happens here — the GC sweep + canary verification + push policy is
+ * orchestrated by `runGcBatch` (sweep.ts).
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { simpleGit } from "simple-git";
+export async function applyCommit(opts) {
+    const written = [];
+    const deleted = [];
+    for (const [rel, content] of Object.entries(opts.proposal.patch)) {
+        const abs = resolve(opts.repoRoot, rel);
+        if (content === "") {
+            try {
+                rmSync(abs, { force: true });
+                deleted.push(rel);
+            }
+            catch {
+                // file may not exist; ignore
+            }
+        }
+        else {
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, content, "utf8");
+            written.push(rel);
+        }
+    }
+    const git = simpleGit({ baseDir: opts.repoRoot });
+    if (opts.author !== undefined) {
+        await git.addConfig("user.name", opts.author.name, false, "local");
+        await git.addConfig("user.email", opts.author.email, false, "local");
+    }
+    await git.add(opts.proposal.paths);
+    await git.commit(opts.proposal.commit_message);
+    const sha = (await git.revparse(["HEAD"])).trim();
+    return {
+        commit_sha: sha,
+        paths_written: written,
+        paths_deleted: deleted,
+    };
+}
+//# sourceMappingURL=apply.js.map

package/dist/gc/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/gc/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgBvC,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAwB;IACxD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACjE,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACxC,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;YAAC,MAAM,CAAC;gBACP,6BAA6B;YAC/B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7C,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACnE,MAAM,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAElD,OAAO;QACL,UAAU,EAAE,GAAG;QACf,aAAa,EAAE,OAAO;QACtB,aAAa,EAAE,OAAO;KACvB,CAAC;AACJ,CAAC"}

package/dist/gc/canary.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Batch canary — verifies a multi-commit GC batch hasn't broken anything that
+ * shows only when the commits are taken together: "individually safe,
+ * collectively broken."
+ *
+ * Two checks run after the batch lands locally and BEFORE any push:
+ *
+ *   1. workflow.md re-render against a synthetic-task fixture.
+ *      The orchestrator injects this template on every run; if a GC batch
+ *      removed a placeholder section, broke a `{{var}}` token, or left
+ *      orphaned `{{#each}}` blocks, the next live run would silently produce
+ *      a malformed prompt. Render the template against a known-good fixture
+ *      and assert (a) every `{{...}}` resolves and (b) the expected section
+ *      headers (`## Task`, `## Acceptance criteria`, `## Decisions in scope`,
+ *      `## Sensors that will run`) survive.
+ *
+ *   2. Manifest rebuild + ground-zone consistency.
+ *      Re-run `buildManifest` against the post-batch tree. If it throws or
+ *      produces zero entries (the canonical zone went empty), the batch
+ *      broke ground.
+ *
+ * Both checks are pure-mechanical — no claude burn — and run in milliseconds.
+ * They are not exhaustive (no runtime sensor sweep against a synthetic diff
+ * yet; that's deferred to a richer Phase 12.x revision when the orchestrator
+ * exposes an "isolated sensor sweep" entry point).
+ */
+import type { CanarySyntheticContext } from "./types.js";
+export interface BatchCanaryResult {
+    ok: boolean;
+    failures: string[];
+    /** Number of files in the rebuilt manifest. */
+    manifest_files: number;
+    /** Length of the rendered workflow.md template. */
+    rendered_length: number;
+}
+export interface BatchCanaryOptions {
+    repoRoot: string;
+    /** Override the synthetic context. Defaults to a minimal fixture. */
+    syntheticContext?: CanarySyntheticContext;
+}
+export declare function buildSyntheticContext(): CanarySyntheticContext;
+export declare function verifyBatchCanary(opts: BatchCanaryOptions): BatchCanaryResult;