@cleocode/core 2026.6.12 → 2026.6.13

package/dist/selfimprove/budget.js

@@ -0,0 +1,203 @@
+/**
+ * Budget caps + circuit-breaker state machine for the self-improvement loop
+ * (T11889 · T11889-C).
+ *
+ * The loop is an AUTONOMOUS dogfooding engine — it boots a sandbox, replays a
+ * scenario, and on a regression it WRITES a leased DHQ row and opens a draft PR.
+ * Two guardrails bound that autonomy:
+ *
+ *   1. {@link SelfImproveBudget} — HARD, in-code caps (`maxTokens`, `maxUsd`,
+ *      `maxPrs = 1`, `maxWorktrees = 1`). These are REAL, not advisory: the engine
+ *      asks {@link CircuitBreaker.assertWithinBudget} BEFORE each costed step, so a
+ *      cap is enforced as a PRE-FLIGHT check (never merely observed after the fact).
+ *      `MemoryMax=32G` is NOT an in-code cap — a CORE function cannot portably
+ *      self-confine to a cgroup (`systemd-run` is Linux-only) — it is an OPERATIONAL
+ *      launch-wrapper documented on {@link MEMORY_MAX_LAUNCH_WRAPPER}; the in-process
+ *      complement is the gondolin VM's own `memory` option.
+ *   2. {@link CircuitBreaker} — a one-way latch that HALTS the run (no further ops,
+ *      no DHQ write, no PR) the moment any of these trip:
+ *        - an architectural gate goes RED (`gateRed`);
+ *        - the writer lease throws {@link "../store/writer-lease.js".LeaseUnavailableError}
+ *          (a `require`-mode acquisition FAILURE — `leaseUnavailable`);
+ *        - a budget cap would be exceeded (`budgetOverrun`);
+ *        - a DB error escapes the leased section (`dbError`).
+ *      It does NOT trip on "daemon OFF": the default lease mode is `local` (no
+ *      daemon), so daemon-off is the NORMAL operating state — tripping on it would
+ *      block EVERY write in the default config (P5 spec §B.7 correction).
+ *
+ * This module is PURE — no DB, no native handle, no `cleo` mutation, no I/O.
+ * Import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/budget
+ * @epic T11889
+ * @task T11913
+ */
+/**
+ * The default budget for a self-improvement run. `maxPrs` / `maxWorktrees` are
+ * `1` by contract; `maxTokens` / `maxUsd` are conservative defaults overridable
+ * via {@link resolveBudget} (env) or an explicit partial.
+ */
+export const DEFAULT_BUDGET = {
+    maxTokens: 200_000,
+    maxUsd: 5,
+    maxPrs: 1,
+    maxWorktrees: 1,
+};
+/**
+ * The launch-boundary memory cap — an OPERATIONAL wrapper, NOT an in-code cap.
+ *
+ * A CORE function cannot portably self-confine to a cgroup (`systemd-run` is
+ * Linux-only; re-exec'ing under it from inside the engine is fragile), so the
+ * runbook / spawn wrapper that invokes `cleo selfimprove run` wraps it on Linux.
+ * On macOS the gondolin VM's own `memory` option bounds the guest. Exported as a
+ * documented constant so the spawn wrapper and the runbook share one SSoT string.
+ */
+export const MEMORY_MAX_LAUNCH_WRAPPER = 'systemd-run --user --scope -p MemoryMax=32G -p MemorySwapMax=0';
+/** A fresh, zeroed {@link BudgetSpend}. */
+export function emptySpend() {
+    return { tokens: 0, usd: 0, prs: 0, worktrees: 0 };
+}
+/**
+ * Thrown by {@link CircuitBreaker.assertWithinBudget} when a step's charge would
+ * push the accumulated spend past a cap. Carries the offending dimension so the
+ * engine can trip the breaker with `reason: 'budgetOverrun'` and surface WHICH cap.
+ */
+export class BudgetExceededError extends Error {
+    /** Stable machine-readable code. */
+    code = 'E_SELFIMPROVE_BUDGET_EXCEEDED';
+    /** Which cap was exceeded. */
+    dimension;
+    /**
+     * @param dimension - The exceeded cap dimension.
+     * @param attempted - The accumulated value the step would have reached.
+     * @param cap - The cap that bounds it.
+     */
+    constructor(dimension, attempted, cap) {
+        super(`self-improve budget exceeded: ${dimension} would reach ${attempted}, cap is ${cap}`);
+        this.name = 'BudgetExceededError';
+        this.dimension = dimension;
+    }
+}
+/**
+ * A one-way circuit-breaker latch + pre-flight budget gate for ONE run.
+ *
+ * Once {@link trip} is called the breaker stays OPEN for the run's lifetime —
+ * there is no reset (a run is single-use; the next run constructs a fresh
+ * breaker). {@link assertOpen} short-circuits B.4-B.5 to a no-op the moment the
+ * latch is set, and {@link assertWithinBudget} is the PRE-FLIGHT check the engine
+ * runs before each costed step.
+ *
+ * PURE — holds only in-memory counters; no I/O.
+ */
+export class CircuitBreaker {
+    #budget;
+    #spend;
+    #open = false;
+    #reason = null;
+    #detail = null;
+    /**
+     * @param budget - The caps for this run (defaults to {@link DEFAULT_BUDGET}).
+     * @param spend - The starting spend (defaults to a zeroed accumulator).
+     */
+    constructor(budget = DEFAULT_BUDGET, spend = emptySpend()) {
+        this.#budget = budget;
+        this.#spend = spend;
+    }
+    /** Whether the breaker has latched OPEN. */
+    get isOpen() {
+        return this.#open;
+    }
+    /** The current latch state (open flag + reason + detail). */
+    get state() {
+        return { open: this.#open, reason: this.#reason, detail: this.#detail };
+    }
+    /** The accumulated spend so far (a live read of the internal counters). */
+    get spend() {
+        return { ...this.#spend };
+    }
+    /**
+     * Latch the breaker OPEN. Idempotent: the FIRST trip wins — a later trip does
+     * not overwrite the original reason (the first fault is the relevant one).
+     *
+     * @param reason - The trip reason.
+     * @param detail - A human-readable detail for logs / the run report.
+     */
+    trip(reason, detail) {
+        if (this.#open)
+            return;
+        this.#open = true;
+        this.#reason = reason;
+        this.#detail = detail;
+    }
+    /**
+     * Throw if the breaker is OPEN — the engine calls this at the top of each
+     * phase so a tripped breaker short-circuits the rest of the run.
+     *
+     * @throws {Error} `E_SELFIMPROVE_CIRCUIT_OPEN` when the breaker is latched.
+     */
+    assertClosed() {
+        if (this.#open) {
+            const err = new Error(`self-improve circuit-breaker OPEN (${this.#reason}): ${this.#detail}`);
+            err.code = 'E_SELFIMPROVE_CIRCUIT_OPEN';
+            throw err;
+        }
+    }
+    /**
+     * PRE-FLIGHT budget check for a costed step. Computes the spend the step WOULD
+     * reach and — if any dimension would exceed its cap — TRIPS the breaker with
+     * `reason: 'budgetOverrun'` and throws {@link BudgetExceededError} BEFORE the
+     * step runs. On success it COMMITS the charge to the accumulator.
+     *
+     * @param charge - The increment the step would add.
+     * @throws {BudgetExceededError} When a cap would be exceeded (and trips the breaker).
+     */
+    chargeOrTrip(charge) {
+        const next = {
+            tokens: this.#spend.tokens + (charge.tokens ?? 0),
+            usd: this.#spend.usd + (charge.usd ?? 0),
+            prs: this.#spend.prs + (charge.prs ?? 0),
+            worktrees: this.#spend.worktrees + (charge.worktrees ?? 0),
+        };
+        const checks = [
+            ['maxTokens', next.tokens, this.#budget.maxTokens],
+            ['maxUsd', next.usd, this.#budget.maxUsd],
+            ['maxPrs', next.prs, this.#budget.maxPrs],
+            ['maxWorktrees', next.worktrees, this.#budget.maxWorktrees],
+        ];
+        for (const [dimension, attempted, cap] of checks) {
+            if (attempted > cap) {
+                const err = new BudgetExceededError(dimension, attempted, cap);
+                this.trip('budgetOverrun', err.message);
+                throw err;
+            }
+        }
+        this.#spend.tokens = next.tokens;
+        this.#spend.usd = next.usd;
+        this.#spend.prs = next.prs;
+        this.#spend.worktrees = next.worktrees;
+    }
+}
+/**
+ * Resolve the effective {@link SelfImproveBudget}, layering env overrides over an
+ * explicit partial over {@link DEFAULT_BUDGET}. `maxPrs` / `maxWorktrees` are
+ * ALWAYS clamped to at most `1` regardless of override — the one-PR / one-sandbox
+ * ceiling is a hard invariant, not a tunable.
+ *
+ * Env overrides (numeric): `CLEO_SELFIMPROVE_MAX_TOKENS`, `CLEO_SELFIMPROVE_MAX_USD`.
+ *
+ * @param overrides - Optional explicit partial caps (test / caller injection).
+ * @param env - The environment to read overrides from (defaults to `process.env`).
+ * @returns The resolved, invariant-clamped budget.
+ */
+export function resolveBudget(overrides = {}, env = process.env) {
+    const envTokens = Number(env.CLEO_SELFIMPROVE_MAX_TOKENS);
+    const envUsd = Number(env.CLEO_SELFIMPROVE_MAX_USD);
+    const maxTokens = overrides.maxTokens ??
+        (Number.isFinite(envTokens) && envTokens > 0 ? envTokens : DEFAULT_BUDGET.maxTokens);
+    const maxUsd = overrides.maxUsd ?? (Number.isFinite(envUsd) && envUsd > 0 ? envUsd : DEFAULT_BUDGET.maxUsd);
+    // The one-PR / one-sandbox ceiling is invariant — clamp to at most 1.
+    const maxPrs = Math.min(1, overrides.maxPrs ?? DEFAULT_BUDGET.maxPrs);
+    const maxWorktrees = Math.min(1, overrides.maxWorktrees ?? DEFAULT_BUDGET.maxWorktrees);
+    return { maxTokens, maxUsd, maxPrs, maxWorktrees };
+}
+//# sourceMappingURL=budget.js.map

package/dist/selfimprove/budget.js.map

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

package/dist/selfimprove/dhq-adapter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Durable DHQ adapter for the self-improvement loop (T11889 · T11889-C).
+ *
+ * This adapter sits OUTSIDE the store chokepoint (it is in `selfimprove/`, not
+ * `store/`), so it MUST NOT open a raw native handle (Gate-3). It is the lease
+ * boundary: EVERY write it performs is wrapped in
+ * {@link "../store/writer-lease.js".withWriterLease}`('project', 'bulk', …)`, which
+ * serializes the write against any other writer on the `(project, bulk)` lane. It
+ * then calls the Gate-3 accessors in
+ * {@link "../store/selfimprove-dhq-store.js"} (the ONLY native-handle toucher) —
+ * whose prepared statements target ONLY `selfimprove_dhq`.
+ *
+ * Two invariants the rest of the loop relies on:
+ *
+ *   1. **No raw / unleased write.** Reads go straight through the accessor (the
+ *      shared handle, no lease); every WRITE goes through {@link upsertOpenDhq} /
+ *      {@link recordPrUrl}, both of which acquire the lease first. There is no
+ *      code path here that mutates `cleo.db` without the lease.
+ *   2. **`selfimprove_dhq` ONLY — never a prod `tasks`/`brain` row.** The lease
+ *      SERIALIZES the write; it does NOT confine it to a table. The
+ *      table-confinement is ENTIRELY this adapter's discipline: it calls only the
+ *      `selfimprove_dhq` accessors, whose SQL references no other table. A unit
+ *      test asserts the accessor SQL targets `selfimprove_dhq` and nothing else.
+ *
+ * Lease-mode note (P5 spec §B.7): the default mode is `local` (no daemon), where a
+ * contended lease DEGRADES under `busy_timeout` rather than throwing. To get a hard
+ * denial signal for the circuit-breaker, the process runs in `require` mode
+ * (`CLEO_WRITER_LEASE_MODE=require`), where an unacquirable lease THROWS
+ * {@link "../store/writer-lease.js".LeaseUnavailableError}. This adapter does NOT
+ * swallow that throw — it propagates so {@link runSelfImprove} trips the breaker.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/dhq-adapter
+ * @epic T11889
+ * @task T11913
+ */
+import { type SelfimproveDhqRow } from '../store/selfimprove-dhq-store.js';
+/**
+ * The fields the engine supplies to {@link upsertOpenDhq}. `now` and the fixed
+ * `status: 'open'` are stamped by the accessor; `dhqId` / `severity` carry through.
+ */
+export interface UpsertDhqInput {
+    /** Stable `'DHQ-###'` handle (used only on first insert for a hash). */
+    readonly dhqId: string;
+    /** The scenario name replayed. */
+    readonly scenario: string;
+    /** sha256 of the normalized regression signature — the idempotency key. */
+    readonly questionHash: string;
+    /** Human-readable DHQ title. */
+    readonly title: string;
+    /** The envelope-diff payload (the evidence) as serialized JSON. */
+    readonly regressionJson: string;
+    /** Severity classification, or `null` until triaged. */
+    readonly severity: string | null;
+    /** Ties the row to ONE loop run. */
+    readonly runId: string;
+}
+/** The durable DHQ adapter — the lease boundary for the self-improvement loop. */
+export interface DhqAdapter {
+    /**
+     * Read the open DHQ row for a `question_hash` (lease-free — readers share the
+     * handle). Returns `null` when no open row exists.
+     */
+    readOpen(questionHash: string): Promise<SelfimproveDhqRow | null>;
+    /**
+     * UPSERT exactly ONE open DHQ row for a `question_hash`, under the
+     * `(project, bulk)` writer lease. Idempotent via the partial-UNIQUE index: a
+     * repeated open regression refreshes the existing row.
+     */
+    upsertOpenDhq(input: UpsertDhqInput): Promise<void>;
+    /**
+     * Record the draft PR URL on the open DHQ row for a `question_hash`, under the
+     * `(project, bulk)` writer lease.
+     *
+     * @returns The number of rows updated (0 when no open row exists).
+     */
+    recordPrUrl(questionHash: string, prUrl: string): Promise<number>;
+}
+/**
+ * Construct the durable DHQ adapter bound to a project working directory.
+ *
+ * Every WRITE method acquires the `(project, bulk)` writer lease via
+ * {@link "../store/writer-lease.js".withWriterLease} before delegating to the
+ * Gate-3 accessor. The native handle is resolved per call through
+ * {@link "../store/selfimprove-dhq-store.js".getSelfimproveDhqNativeDb} (the
+ * chokepoint singleton — no raw open). The clock is injectable for deterministic
+ * tests; production uses `Date.now`.
+ *
+ * @param opts - Adapter options.
+ * @param opts.cwd - Project working directory for scope resolution (defaults to `cwd`).
+ * @param opts.now - Injectable clock (defaults to {@link Date.now}).
+ * @returns A {@link DhqAdapter}.
+ *
+ * @example
+ * ```ts
+ * const adapter = createDhqAdapter({ cwd: projectRoot });
+ * await adapter.upsertOpenDhq({ dhqId: 'DHQ-001', … }); // leased UPSERT
+ * ```
+ */
+export declare function createDhqAdapter(opts?: {
+    cwd?: string;
+    now?: () => number;
+}): DhqAdapter;
+//# sourceMappingURL=dhq-adapter.d.ts.map

package/dist/selfimprove/dhq-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dhq-adapter.d.ts","sourceRoot":"","sources":["../../src/selfimprove/dhq-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EAIvB,MAAM,mCAAmC,CAAC;AAG3C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAClE;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;;;OAKG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GAAG,UAAU,CAoC5F"}

package/dist/selfimprove/dhq-adapter.js

@@ -0,0 +1,95 @@
+/**
+ * Durable DHQ adapter for the self-improvement loop (T11889 · T11889-C).
+ *
+ * This adapter sits OUTSIDE the store chokepoint (it is in `selfimprove/`, not
+ * `store/`), so it MUST NOT open a raw native handle (Gate-3). It is the lease
+ * boundary: EVERY write it performs is wrapped in
+ * {@link "../store/writer-lease.js".withWriterLease}`('project', 'bulk', …)`, which
+ * serializes the write against any other writer on the `(project, bulk)` lane. It
+ * then calls the Gate-3 accessors in
+ * {@link "../store/selfimprove-dhq-store.js"} (the ONLY native-handle toucher) —
+ * whose prepared statements target ONLY `selfimprove_dhq`.
+ *
+ * Two invariants the rest of the loop relies on:
+ *
+ *   1. **No raw / unleased write.** Reads go straight through the accessor (the
+ *      shared handle, no lease); every WRITE goes through {@link upsertOpenDhq} /
+ *      {@link recordPrUrl}, both of which acquire the lease first. There is no
+ *      code path here that mutates `cleo.db` without the lease.
+ *   2. **`selfimprove_dhq` ONLY — never a prod `tasks`/`brain` row.** The lease
+ *      SERIALIZES the write; it does NOT confine it to a table. The
+ *      table-confinement is ENTIRELY this adapter's discipline: it calls only the
+ *      `selfimprove_dhq` accessors, whose SQL references no other table. A unit
+ *      test asserts the accessor SQL targets `selfimprove_dhq` and nothing else.
+ *
+ * Lease-mode note (P5 spec §B.7): the default mode is `local` (no daemon), where a
+ * contended lease DEGRADES under `busy_timeout` rather than throwing. To get a hard
+ * denial signal for the circuit-breaker, the process runs in `require` mode
+ * (`CLEO_WRITER_LEASE_MODE=require`), where an unacquirable lease THROWS
+ * {@link "../store/writer-lease.js".LeaseUnavailableError}. This adapter does NOT
+ * swallow that throw — it propagates so {@link runSelfImprove} trips the breaker.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/dhq-adapter
+ * @epic T11889
+ * @task T11913
+ */
+import { getSelfimproveDhqNativeDb, readOpenSelfimproveDhq, setSelfimproveDhqPrUrl, upsertOpenSelfimproveDhq, } from '../store/selfimprove-dhq-store.js';
+import { withWriterLease } from '../store/writer-lease.js';
+/**
+ * Construct the durable DHQ adapter bound to a project working directory.
+ *
+ * Every WRITE method acquires the `(project, bulk)` writer lease via
+ * {@link "../store/writer-lease.js".withWriterLease} before delegating to the
+ * Gate-3 accessor. The native handle is resolved per call through
+ * {@link "../store/selfimprove-dhq-store.js".getSelfimproveDhqNativeDb} (the
+ * chokepoint singleton — no raw open). The clock is injectable for deterministic
+ * tests; production uses `Date.now`.
+ *
+ * @param opts - Adapter options.
+ * @param opts.cwd - Project working directory for scope resolution (defaults to `cwd`).
+ * @param opts.now - Injectable clock (defaults to {@link Date.now}).
+ * @returns A {@link DhqAdapter}.
+ *
+ * @example
+ * ```ts
+ * const adapter = createDhqAdapter({ cwd: projectRoot });
+ * await adapter.upsertOpenDhq({ dhqId: 'DHQ-001', … }); // leased UPSERT
+ * ```
+ */
+export function createDhqAdapter(opts = {}) {
+    const cwd = opts.cwd;
+    const now = opts.now ?? (() => Date.now());
+    return {
+        async readOpen(questionHash) {
+            const native = await getSelfimproveDhqNativeDb(cwd);
+            return readOpenSelfimproveDhq(native, questionHash);
+        },
+        async upsertOpenDhq(input) {
+            // EVERY write is leased — never raw / unleased. The lease serializes against
+            // other writers on (project, bulk); the table-confinement is the accessor's.
+            await withWriterLease('project', 'bulk', async () => {
+                const native = await getSelfimproveDhqNativeDb(cwd);
+                const row = {
+                    dhqId: input.dhqId,
+                    scenario: input.scenario,
+                    questionHash: input.questionHash,
+                    title: input.title,
+                    regressionJson: input.regressionJson,
+                    severity: input.severity,
+                    runId: input.runId,
+                    now: now(),
+                };
+                upsertOpenSelfimproveDhq(native, row);
+            });
+        },
+        async recordPrUrl(questionHash, prUrl) {
+            return withWriterLease('project', 'bulk', async () => {
+                const native = await getSelfimproveDhqNativeDb(cwd);
+                return setSelfimproveDhqPrUrl(native, questionHash, prUrl, now());
+            });
+        },
+    };
+}
+//# sourceMappingURL=dhq-adapter.js.map

package/dist/selfimprove/dhq-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dhq-adapter.js","sourceRoot":"","sources":["../../src/selfimprove/dhq-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EAGtB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AA6C3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA6C,EAAE;IAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3C,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,YAAoB;YACjC,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,GAAG,CAAC,CAAC;YACpD,OAAO,sBAAsB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACtD,CAAC;QAED,KAAK,CAAC,aAAa,CAAC,KAAqB;YACvC,6EAA6E;YAC7E,6EAA6E;YAC7E,MAAM,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE;gBAClD,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,GAAG,CAAC,CAAC;gBACpD,MAAM,GAAG,GAAyB;oBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,YAAY,EAAE,KAAK,CAAC,YAAY;oBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,cAAc,EAAE,KAAK,CAAC,cAAc;oBACpC,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,GAAG,EAAE,GAAG,EAAE;iBACX,CAAC;gBACF,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,YAAoB,EAAE,KAAa;YACnD,OAAO,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE;gBACnD,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,GAAG,CAAC,CAAC;gBACpD,OAAO,sBAAsB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YACpE,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/selfimprove/draft-pr.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Draft-PR egress for the self-improvement loop (T11889 · T11889-C).
+ *
+ * On a detected regression the loop's ONLY outbound action is to open ONE DRAFT
+ * PR against the cleocode repo (ADR-065 — PRs target `main` via the Merge Queue;
+ * NEVER a direct push to `main`, NEVER an auto-merge, NEVER a publish). This module
+ * is the egress primitive, modeled on `propose-patch.ts` (the closest "agent
+ * proposes a fix PR" exemplar) with three self-dogfooding hardenings:
+ *
+ *   1. **`--draft` is ALWAYS appended** to `gh pr create` — the PR is never
+ *      ready-for-merge; a human reviews and undrafts it.
+ *   2. **Dry-run is the DEFAULT.** `openDraftPr` returns the planned `steps[]`
+ *      WITHOUT invoking git/gh unless `execute: true` is passed. So the loop is
+ *      side-effect-free at egress by default.
+ *   3. **Branch `feat/T11889-selfimprove-<scenario>-<ts>`** — a feature branch
+ *      (ADR-065); no main mutation path exists in this module.
+ *
+ * The live path wraps the git/gh shell-out in
+ * {@link "../sentient/skill-provenance.js".withProvenance}`('pr-generator', …)`
+ * (the established legal PR-cutting origin — the `SkillWriteOrigin` union is
+ * closed) and returns the `gh`-emitted PR URL so the caller can record it back
+ * into `selfimprove_dhq.pr_url` via the leased adapter.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/draft-pr
+ * @epic T11889
+ * @task T11913
+ */
+/**
+ * Pluggable command runner. Returns stdout as UTF-8 text or throws on non-zero
+ * exit. Production default wraps `child_process.execFileSync` with piped stdio.
+ */
+export type CommandRunner = (file: string, args: readonly string[]) => string;
+/** Failure codes from {@link openDraftPr}. */
+export type DraftPrErrorCode = 
+/** Patch file does not exist on disk. */
+'E_NOT_FOUND'
+/** Patch file exists but is empty. */
+ | 'E_PATCH_EMPTY'
+/** `gh` CLI missing / not authenticated. */
+ | 'E_GH_UNAVAILABLE'
+/** Shell-out failure during the live PR cut. */
+ | 'E_DRAFT_PR_FAILED';
+/** Args for {@link openDraftPr}. */
+export interface OpenDraftPrArgs {
+    /** The scenario name whose regression this PR addresses (branch slug). */
+    readonly scenario: string;
+    /** Path to a unified-diff file with the proposed fix. Resolved against {@link cwd}. */
+    readonly diffPath: string;
+    /** PR title. */
+    readonly title: string;
+    /** PR body markdown (the trailer is appended automatically). */
+    readonly body: string;
+    /**
+     * When `true`, actually cut the branch + open the draft PR. DEFAULT `false`
+     * (dry-run) — the loop is side-effect-free at egress unless `--execute` flows
+     * through to here.
+     *
+     * @defaultValue false
+     */
+    readonly execute?: boolean;
+    /** Working directory for path resolution + git ops. Defaults to {@link process.cwd}. */
+    readonly cwd?: string;
+    /** Injectable command runner (tests capture the shell-out). Defaults to {@link execFileSync}. */
+    readonly run?: CommandRunner;
+    /** Injectable timestamp source for the branch suffix (tests pin it). Defaults to now. */
+    readonly timestamp?: () => string;
+}
+/** Dry-run result — the planned steps, no side effects. */
+export interface DraftPrDryRun {
+    readonly kind: 'dry-run';
+    readonly scenario: string;
+    readonly branchName: string;
+    /** The planned shell steps; the `gh pr create` step includes `--draft`. */
+    readonly steps: readonly string[];
+}
+/** Live result — the opened draft PR. */
+export interface DraftPrOk {
+    readonly kind: 'ok';
+    readonly scenario: string;
+    readonly branchName: string;
+    /** The draft PR URL emitted by `gh pr create --draft`. */
+    readonly prUrl: string;
+}
+/** Failure result. */
+export interface DraftPrFailure {
+    readonly kind: 'error';
+    readonly code: DraftPrErrorCode;
+    readonly message: string;
+}
+/** Discriminated-union result of {@link openDraftPr}. */
+export type DraftPrResult = DraftPrDryRun | DraftPrOk | DraftPrFailure;
+/**
+ * Compute the feature branch name for a scenario's draft PR (ADR-065 feature
+ * branch — `feat/T11889-selfimprove-<scenario>-<ts>`). The timestamp is
+ * colon/dot-sanitized so it is a valid git ref.
+ *
+ * @param scenario - The scenario name.
+ * @param ts - The ISO timestamp string.
+ * @returns The branch name.
+ */
+export declare function draftPrBranchName(scenario: string, ts: string): string;
+/**
+ * Open ONE DRAFT PR carrying a proposed self-improvement fix.
+ *
+ * DRY-RUN by default ({@link OpenDraftPrArgs.execute} falsey): returns the planned
+ * `steps[]` (the `gh pr create` step ALWAYS carries `--draft`) WITHOUT touching
+ * git/gh — so the loop is egress-side-effect-free unless `--execute` is threaded
+ * through. The live path (`execute: true`) cuts the feature branch, applies the
+ * diff, commits, pushes the FEATURE branch (NEVER `main`), and runs
+ * `gh pr create --base main --head <branch> --draft`, returning the PR URL.
+ *
+ * NEVER pushes `main`, NEVER auto-merges, NEVER publishes — the only egress is a
+ * draft PR against a feature branch.
+ *
+ * @param args - See {@link OpenDraftPrArgs}.
+ * @returns A {@link DraftPrResult} describing the outcome.
+ *
+ * @example
+ * ```ts
+ * // dry-run (default): no side effects, steps include `--draft`
+ * const plan = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body });
+ * // live: cuts branch + opens draft PR
+ * const res = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body, execute: true });
+ * ```
+ */
+export declare function openDraftPr(args: OpenDraftPrArgs): Promise<DraftPrResult>;
+//# sourceMappingURL=draft-pr.d.ts.map

package/dist/selfimprove/draft-pr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-pr.d.ts","sourceRoot":"","sources":["../../src/selfimprove/draft-pr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAeH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAM9E,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB;AAC1B,yCAAyC;AACvC,aAAa;AACf,sCAAsC;GACpC,eAAe;AACjB,4CAA4C;GAC1C,kBAAkB;AACpB,gDAAgD;GAC9C,mBAAmB,CAAC;AAExB,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,iGAAiG;IACjG,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CACnC;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sBAAsB;AACtB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAItE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAgF/E"}