@open-mercato/cezar 0.1.5-pr506.357

package/dist/runs/auto-name.d.ts

@@ -0,0 +1,75 @@
+import { type TaskRefs } from './task-refs.js';
+/**
+ * The one-shot LLM namer (spec 2026-07-17-task-auto-naming): turns a task's
+ * INTENT — skill + arguments + prompt + PR/issue context, never the agent's
+ * streamed words — into a short `<number>: <gerund phrase>` display title with
+ * structured, regex-cross-checked PR/issue numbers. Mirrors the planner (spec
+ * 008): `[cez-namer]` dry-run marker, strict JSON, never blocks, never fails a
+ * run. This module is the pure half; the runner call lives in `generateRunName`.
+ */
+export declare const NAMER_TIMEOUT_MS = 20000;
+/** Title budget in code points — the tasks table shows ~20-25 chars, 40 is the hard cap. */
+export declare const TITLE_MAX = 40;
+/**
+ * Master switch for ALL LLM naming (creation-time and live refresh):
+ * `CEZ_AUTONAME=0` kills it outright; under `CEZ_DRY_RUN=1` naming is off by
+ * default too (the mock's canned title would REPLACE honest heuristic titles
+ * in demos and e2e) unless `CEZ_AUTONAME=1` forces it — the hook the dry-run
+ * naming tests use.
+ */
+export declare function autoNamingActive(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Live title updates switch (owner decision on PR #479 — deliberately ON by
+ * default, deviating from the cost-opt-in house rule; cost is bounded by the
+ * cheap `namerModel`, one call per turn end, and the skip conditions in
+ * `RunManager.recordTurnEnd`). Precedence: `config.liveTitleUpdates` (the
+ * Settings toggle) wins over the `CEZ_TITLE_UPDATES` env default (`'0'` = off)
+ * wins over the built-in ON.
+ */
+export declare function liveTitleUpdatesEnabled(config: {
+    liveTitleUpdates?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;
+export declare const NAMER_SYSTEM_PROMPT: string;
+export interface NamerContext {
+    task: string;
+    skillName?: string;
+    skillDescription?: string;
+    /** Live refresh only (spec step 3): the just-finished turn's text. */
+    turnText?: string;
+    /** Live refresh only: current `git diff --shortstat` line. */
+    diffStat?: string;
+}
+export interface NameResult {
+    titleSummary: string;
+    prNumber?: number;
+    issueNumber?: number;
+}
+/** The `[cez-namer]` marker lets the CEZ_DRY_RUN mock recognize a naming call. */
+export declare function buildNamerPrompt(ctx: NamerContext): string;
+/**
+ * Anti-hallucination cross-check: the model's `pr`/`issue` is accepted only
+ * when the regex layer agrees or the number literally occurs in the task text;
+ * on any disagreement the regex wins. The regex's own explicit findings always
+ * carry through, so a lying model can add nothing and remove nothing.
+ */
+export declare function crossCheckRefs(raw: {
+    pr?: number;
+    issue?: number;
+}, task: string, refs: TaskRefs): {
+    prNumber?: number;
+    issueNumber?: number;
+};
+/** Enforce the title contract regardless of what the model produced. */
+export declare function postValidateTitle(title: string, refNumber?: number): string;
+/**
+ * The one-shot runner call: never throws, never blocks a run — every failure
+ * path (runner error, timeout, junk twice) answers null and the caller keeps
+ * the heuristic title. `namerModel` is a Claude alias, so it is passed only
+ * when the namer runs on Claude (the `plannerModel` precedent).
+ */
+export declare function generateRunName(repoRoot: string, ctx: NamerContext): Promise<NameResult | null>;
+/**
+ * Raw model text → validated NameResult, or null when the answer is junk
+ * (caller retries once, then keeps the heuristic title).
+ */
+export declare function composeNameResult(rawText: string, ctx: NamerContext): NameResult | null;

package/dist/runs/auto-name.js

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+import { loadConfig } from '../config.js';
+import { createRunner } from '../core/runner-factory.js';
+import { parseStructured } from '../planner.js';
+import { extractTaskRefs, refineTaskRefs, titleRefNumber } from './task-refs.js';
+/**
+ * The one-shot LLM namer (spec 2026-07-17-task-auto-naming): turns a task's
+ * INTENT — skill + arguments + prompt + PR/issue context, never the agent's
+ * streamed words — into a short `<number>: <gerund phrase>` display title with
+ * structured, regex-cross-checked PR/issue numbers. Mirrors the planner (spec
+ * 008): `[cez-namer]` dry-run marker, strict JSON, never blocks, never fails a
+ * run. This module is the pure half; the runner call lives in `generateRunName`.
+ */
+export const NAMER_TIMEOUT_MS = 20_000;
+/** Title budget in code points — the tasks table shows ~20-25 chars, 40 is the hard cap. */
+export const TITLE_MAX = 40;
+/**
+ * Master switch for ALL LLM naming (creation-time and live refresh):
+ * `CEZ_AUTONAME=0` kills it outright; under `CEZ_DRY_RUN=1` naming is off by
+ * default too (the mock's canned title would REPLACE honest heuristic titles
+ * in demos and e2e) unless `CEZ_AUTONAME=1` forces it — the hook the dry-run
+ * naming tests use.
+ */
+export function autoNamingActive(env = process.env) {
+    if (env.CEZ_AUTONAME === '0')
+        return false;
+    if (env.CEZ_DRY_RUN === '1' && env.CEZ_AUTONAME !== '1')
+        return false;
+    return true;
+}
+/**
+ * Live title updates switch (owner decision on PR #479 — deliberately ON by
+ * default, deviating from the cost-opt-in house rule; cost is bounded by the
+ * cheap `namerModel`, one call per turn end, and the skip conditions in
+ * `RunManager.recordTurnEnd`). Precedence: `config.liveTitleUpdates` (the
+ * Settings toggle) wins over the `CEZ_TITLE_UPDATES` env default (`'0'` = off)
+ * wins over the built-in ON.
+ */
+export function liveTitleUpdatesEnabled(config, env = process.env) {
+    if (config.liveTitleUpdates !== undefined)
+        return config.liveTitleUpdates;
+    return env.CEZ_TITLE_UPDATES !== '0';
+}
+export const NAMER_SYSTEM_PROMPT = 'You are a task-naming assistant for an AI coding agent cockpit. Respond with ONLY a JSON object: ' +
+    '{"title": string, "pr"?: number, "issue"?: number}. Rules: "title" is a terse lowercase gerund phrase ' +
+    'naming the task INTENT (e.g. "implementing cr fixes", "verifying pr ui"), at most 40 characters, no ' +
+    'trailing period, and NEVER a restatement of an assistant reply. When the task is about a GitHub pull ' +
+    'request or issue, set "pr" or "issue" to that number and do NOT repeat the number inside the title ' +
+    'text. Never invent a number that is not in the task.';
+const namerResponseSchema = z.object({
+    title: z.string().min(1),
+    pr: z.number().int().positive().optional(),
+    issue: z.number().int().positive().optional(),
+});
+/** The `[cez-namer]` marker lets the CEZ_DRY_RUN mock recognize a naming call. */
+export function buildNamerPrompt(ctx) {
+    const refs = advisoryRefs(ctx);
+    const lines = [
+        '[cez-namer] Name this task.',
+        '',
+        ...(ctx.skillName ? [`Selected skill: /${ctx.skillName}`] : []),
+        ...(ctx.skillDescription ? [`Skill description: ${ctx.skillDescription}`] : []),
+        'Task:',
+        clip(ctx.task, 500),
+    ];
+    if (refs.length)
+        lines.push('', `References found programmatically (advisory): ${refs.join(', ')}`);
+    if (ctx.turnText)
+        lines.push('', 'Latest progress (context only — do not quote it):', clip(ctx.turnText, 400));
+    if (ctx.diffStat)
+        lines.push('', `Change size so far: ${ctx.diffStat}`);
+    return lines.join('\n');
+}
+function advisoryRefs(ctx) {
+    const refs = refineTaskRefs(extractTaskRefs(ctx.task), ctx.skillName);
+    const out = [];
+    if (refs.prNumber !== undefined)
+        out.push(`pr ${refs.prNumber}`);
+    if (refs.issueNumber !== undefined)
+        out.push(`issue ${refs.issueNumber}`);
+    if (refs.ambiguousNumber !== undefined)
+        out.push(`number ${refs.ambiguousNumber} (kind unknown)`);
+    return out;
+}
+function clip(text, max) {
+    const chars = [...text.trim()];
+    return chars.length > max ? `${chars.slice(0, max).join('')}…` : chars.join('');
+}
+/**
+ * Anti-hallucination cross-check: the model's `pr`/`issue` is accepted only
+ * when the regex layer agrees or the number literally occurs in the task text;
+ * on any disagreement the regex wins. The regex's own explicit findings always
+ * carry through, so a lying model can add nothing and remove nothing.
+ */
+export function crossCheckRefs(raw, task, refs) {
+    const inTask = (n) => n !== undefined && new RegExp(`(^|\\D)${n}(\\D|$)`).test(task);
+    const claimedPr = refs.prNumber ?? (raw.pr !== undefined && (inTask(raw.pr) || refs.ambiguousNumber === raw.pr) ? raw.pr : undefined);
+    const claimedIssue = refs.issueNumber ?? (raw.issue !== undefined && (inTask(raw.issue) || refs.ambiguousNumber === raw.issue) ? raw.issue : undefined);
+    return {
+        ...(claimedPr !== undefined ? { prNumber: claimedPr } : {}),
+        ...(claimedIssue !== undefined ? { issueNumber: claimedIssue } : {}),
+    };
+}
+/** Enforce the title contract regardless of what the model produced. */
+export function postValidateTitle(title, refNumber) {
+    let t = title.trim().replace(/\.+$/, '').replace(/\s+/g, ' ');
+    // The number leads; strip a model-repeated number from the phrase first.
+    if (refNumber !== undefined) {
+        t = t.replace(new RegExp(`^#?${refNumber}\\s*[:—-]?\\s*`), '');
+    }
+    if (t)
+        t = t[0]?.toLowerCase() + t.slice(1);
+    const chars = [...t];
+    if (chars.length > TITLE_MAX)
+        t = `${chars.slice(0, TITLE_MAX - 1).join('').trimEnd()}…`;
+    return refNumber !== undefined ? `${refNumber}: ${t}`.trim().replace(/:\s*$/, ':') : t;
+}
+/**
+ * The one-shot runner call: never throws, never blocks a run — every failure
+ * path (runner error, timeout, junk twice) answers null and the caller keeps
+ * the heuristic title. `namerModel` is a Claude alias, so it is passed only
+ * when the namer runs on Claude (the `plannerModel` precedent).
+ */
+export async function generateRunName(repoRoot, ctx) {
+    try {
+        const config = await loadConfig(repoRoot);
+        const runner = createRunner(config.defaultRunner);
+        const model = config.defaultRunner === 'claude' ? config.namerModel : undefined;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const result = await runner.run({
+                systemPrompt: NAMER_SYSTEM_PROMPT,
+                userPrompt: buildNamerPrompt(ctx),
+                cwd: repoRoot,
+                allowedTools: [],
+                model,
+                timeoutMs: NAMER_TIMEOUT_MS,
+                // Shadow the argv-capture hook: dry-run tests capture the AGENT's argv
+                // through CEZ_MOCK_ARGS_FILE; the namer's bookkeeping call must not
+                // interleave lines into that file.
+                env: { CEZ_MOCK_ARGS_FILE: '' },
+            });
+            const composed = composeNameResult(result.text, ctx);
+            if (composed)
+                return composed;
+        }
+    }
+    catch {
+        // runner unavailable / crashed — the heuristic title stays
+    }
+    return null;
+}
+/**
+ * Raw model text → validated NameResult, or null when the answer is junk
+ * (caller retries once, then keeps the heuristic title).
+ */
+export function composeNameResult(rawText, ctx) {
+    const parsed = parseStructured(rawText, namerResponseSchema);
+    if (!parsed)
+        return null;
+    const refs = refineTaskRefs(extractTaskRefs(ctx.task), ctx.skillName);
+    const checked = crossCheckRefs(parsed, ctx.task, refs);
+    const refNumber = checked.prNumber ?? checked.issueNumber ?? titleRefNumber(refs);
+    const titleSummary = postValidateTitle(parsed.title, refNumber);
+    if (!titleSummary || titleSummary === String(refNumber ?? ''))
+        return null;
+    return { titleSummary, ...checked };
+}
+//# sourceMappingURL=auto-name.js.map

package/dist/runs/auto-name.js.map

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

package/dist/runs/retention.d.ts

@@ -0,0 +1,60 @@
+import type { RunRecord } from './store.js';
+/** A run is reclaimable when it is finished, still has a materialized worktree
+ *  directory, and has not already been reclaimed. */
+export declare function isReclaimable(run: RunRecord): boolean;
+/**
+ * Given every run and the keep-count `keep`, return the ids of the finished
+ * worktrees whose *directory* should be reclaimed: keep the `keep`
+ * most-recently-finished reclaimable worktrees, reclaim the rest.
+ *
+ * `keep === 0` means "unlimited — never auto-reclaim" and returns `[]`.
+ * Pure: no I/O, no mutation of the input.
+ */
+export declare function selectReclaimableWorktrees(runs: readonly RunRecord[], keep: number): string[];
+/** The slice of the runs store the enforcer needs. Kept structural so the
+ *  enforcer stays easy to test and never imports the concrete store. */
+export interface RetentionStore {
+    listRuns(): RunRecord[];
+    updateRun(id: string, patch: {
+        worktreeReclaimedAt?: string;
+    }): unknown;
+}
+/** The slice of the store the re-materializer needs. */
+export interface RematerializeStore {
+    getRun(id: string): RunRecord | undefined;
+    updateRun(id: string, patch: {
+        worktreeReclaimedAt?: string;
+    }): unknown;
+}
+/**
+ * If retention (#483) reclaimed this run's worktree — branch kept, directory
+ * gone, `worktreeReclaimedAt` stamped — re-materialize the directory (via the
+ * idempotent `createWorktree`, which reattaches the surviving `cez/<id8>`
+ * branch) and CLEAR the stamp. Called on the resume/continue path so a resumed
+ * run regains its isolated tree and becomes eligible for retention again;
+ * without it the run would keep a directory on disk while staying invisible to
+ * the enforcer forever (a leak). Returns true when it re-materialized.
+ * Best-effort: never throws (the caller falls back to the repo root).
+ */
+export declare function rematerializeReclaimedWorktree(repoRoot: string, store: RematerializeStore, runId: string): Promise<boolean>;
+/**
+ * Enforce the retention budget: reclaim the *directory* of every over-limit
+ * finished worktree (branch kept via `removeWorktree` without the branch arg),
+ * stamping `worktreeReclaimedAt` on each run actually reclaimed. Returns the
+ * reclaimed run ids (for logging/SSE).
+ *
+ * Never throws (helper discipline). `removeWorktree` is best-effort and does not
+ * report failure, so a run is stamped only once its directory is confirmed gone
+ * — a locked/permission failure leaves the stamp unset so the next pass retries.
+ * Idempotent under races: `removeWorktree` is `--force` + `prune` and a repeated
+ * stamp is harmless.
+ */
+export interface ReclaimOptions {
+    /** Timestamp source for the stamp — injectable for deterministic tests. */
+    now?: () => string;
+    /** Directory reclaimer — defaults to the real `removeWorktree` (branch kept).
+     *  Injectable so tests can exercise the "removal failed" branch without brittle
+     *  filesystem-permission tricks. */
+    remove?: (repoRoot: string, worktreePath: string) => Promise<void>;
+}
+export declare function reclaimWorktrees(repoRoot: string, store: RetentionStore, keep: number, opts?: ReclaimOptions): Promise<string[]>;

package/dist/runs/retention.js

@@ -0,0 +1,86 @@
+// Count-based worktree retention (#483). A busy cockpit leaves one full repo
+// checkout per finished task under `.ai/cezar/worktrees/<runId>`; nothing bounds
+// the total, so disk saturates. This module decides *which* finished worktrees
+// to reclaim (directory only — the `cez/<id8>` branch is kept, so the work stays
+// recoverable) and the thin I/O enforcer that performs the reclaim. The selector
+// is pure and unit-testable; the enforcer never throws (helper discipline).
+import { existsSync } from 'node:fs';
+import { createWorktree, removeWorktree } from '../git-worktree.js';
+/** The "finished" status set — mirrors `RunStore.archiveFinished`. A run at the
+ *  `review` gate is deliberately excluded: it still needs its worktree to render
+ *  the diff and open a draft PR, so reclaiming it would break the gate. */
+const FINISHED = new Set(['done', 'failed', 'cancelled']);
+/** Recency key for retention ordering: when a run finished, falling back to when
+ *  it was created (a finished run should always have `finishedAt`, but old
+ *  records may not). Lexicographic compare is correct for ISO-8601 timestamps. */
+function recencyKey(run) {
+    return run.finishedAt ?? run.createdAt;
+}
+/** A run is reclaimable when it is finished, still has a materialized worktree
+ *  directory, and has not already been reclaimed. */
+export function isReclaimable(run) {
+    return FINISHED.has(run.status) && !!run.worktreePath && !run.worktreeReclaimedAt;
+}
+/**
+ * Given every run and the keep-count `keep`, return the ids of the finished
+ * worktrees whose *directory* should be reclaimed: keep the `keep`
+ * most-recently-finished reclaimable worktrees, reclaim the rest.
+ *
+ * `keep === 0` means "unlimited — never auto-reclaim" and returns `[]`.
+ * Pure: no I/O, no mutation of the input.
+ */
+export function selectReclaimableWorktrees(runs, keep) {
+    if (!Number.isFinite(keep) || keep <= 0)
+        return [];
+    const reclaimable = runs
+        .filter(isReclaimable)
+        .sort((a, b) => (recencyKey(a) < recencyKey(b) ? 1 : recencyKey(a) > recencyKey(b) ? -1 : 0));
+    return reclaimable.slice(keep).map((r) => r.id);
+}
+/**
+ * If retention (#483) reclaimed this run's worktree — branch kept, directory
+ * gone, `worktreeReclaimedAt` stamped — re-materialize the directory (via the
+ * idempotent `createWorktree`, which reattaches the surviving `cez/<id8>`
+ * branch) and CLEAR the stamp. Called on the resume/continue path so a resumed
+ * run regains its isolated tree and becomes eligible for retention again;
+ * without it the run would keep a directory on disk while staying invisible to
+ * the enforcer forever (a leak). Returns true when it re-materialized.
+ * Best-effort: never throws (the caller falls back to the repo root).
+ */
+export async function rematerializeReclaimedWorktree(repoRoot, store, runId) {
+    const run = store.getRun(runId);
+    if (!run?.worktreePath || !run.worktreeReclaimedAt || existsSync(run.worktreePath))
+        return false;
+    try {
+        await createWorktree(repoRoot, runId, run.baseBranch ?? 'HEAD');
+        store.updateRun(runId, { worktreeReclaimedAt: undefined });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function reclaimWorktrees(repoRoot, store, keep, opts = {}) {
+    const now = opts.now ?? (() => new Date().toISOString());
+    const remove = opts.remove ?? ((root, path) => removeWorktree(root, path)); // branch kept
+    const runs = store.listRuns();
+    const byId = new Map(runs.map((r) => [r.id, r]));
+    const reclaimed = [];
+    for (const id of selectReclaimableWorktrees(runs, keep)) {
+        const run = byId.get(id);
+        if (!run?.worktreePath)
+            continue;
+        try {
+            await remove(repoRoot, run.worktreePath);
+            if (existsSync(run.worktreePath))
+                continue; // reclaim failed; retry next pass
+            store.updateRun(id, { worktreeReclaimedAt: now() });
+            reclaimed.push(id);
+        }
+        catch {
+            // best-effort: never let retention crash a terminal transition or startup.
+        }
+    }
+    return reclaimed;
+}
+//# sourceMappingURL=retention.js.map

package/dist/runs/retention.js.map

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

package/dist/runs/review-gate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Optional diff-first review gate (#489, spec `2026-07-18-optional-review-gate`).
+ *
+ * The review gate (spec 009) used to fire for EVERY successful run whose worktree
+ * held changes — parking it at `review` until a human accepts. This resolver makes
+ * that opt-in. It mirrors `liveTitleUpdatesEnabled` (`src/runs/auto-name.ts`) but
+ * with the OPPOSITE default: OFF unless explicitly turned on.
+ *
+ * Precedence: the `config.reviewGate` Settings toggle wins when set; otherwise the
+ * `CEZ_REVIEW_GATE` env decides — enabled ONLY by the exact string `'1'` (anything
+ * else, including `'true'`/`'yes'`/unset, is off); otherwise off.
+ *
+ * Autonomy is applied by the callers, not here: a run parks at `review` only when
+ * `worktreeHasDiff && reviewGateEnabled(config) && !run.autonomous`.
+ */
+export declare function reviewGateEnabled(config: {
+    reviewGate?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;

package/dist/runs/review-gate.js

@@ -0,0 +1,21 @@
+/**
+ * Optional diff-first review gate (#489, spec `2026-07-18-optional-review-gate`).
+ *
+ * The review gate (spec 009) used to fire for EVERY successful run whose worktree
+ * held changes — parking it at `review` until a human accepts. This resolver makes
+ * that opt-in. It mirrors `liveTitleUpdatesEnabled` (`src/runs/auto-name.ts`) but
+ * with the OPPOSITE default: OFF unless explicitly turned on.
+ *
+ * Precedence: the `config.reviewGate` Settings toggle wins when set; otherwise the
+ * `CEZ_REVIEW_GATE` env decides — enabled ONLY by the exact string `'1'` (anything
+ * else, including `'true'`/`'yes'`/unset, is off); otherwise off.
+ *
+ * Autonomy is applied by the callers, not here: a run parks at `review` only when
+ * `worktreeHasDiff && reviewGateEnabled(config) && !run.autonomous`.
+ */
+export function reviewGateEnabled(config, env = process.env) {
+    if (config.reviewGate !== undefined)
+        return config.reviewGate;
+    return env.CEZ_REVIEW_GATE === '1';
+}
+//# sourceMappingURL=review-gate.js.map

package/dist/runs/review-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-gate.js","sourceRoot":"","sources":["../../src/runs/review-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAgC,EAChC,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC;IAC9D,OAAO,GAAG,CAAC,eAAe,KAAK,GAAG,CAAC;AACrC,CAAC"}