@wjarka/cezarion 0.10.0-pr30.54

package/dist/release/stable.js

@@ -0,0 +1,55 @@
+/** Stable-release decisions — the pure half of `scripts/release.mjs`.
+ *
+ *  Sibling of `snapshot.ts`, but for the *owner-driven* `latest` channel. The
+ *  `Release` workflow (`.github/workflows/release.yml`) is run manually and
+ *  never fires from a push, so — unlike snapshots — a stable release is the only
+ *  thing that ever moves the `latest` dist-tag (spec
+ *  `.ai/specs/2026-07-18-npm-preview-publish.md`, #482).
+ *
+ *  Two decisions live here so they stay unit-testable and side-effect-free: the next stable
+ *  version for a given bump, and the pin style the release set is stamped with. Crucially,
+ *  stable releases use a **caret** range — the opposite of the snapshot stamper's exact pin —
+ *  so a stable `cezarion` picks up compatible patch releases of the implementation package.
+ */
+import { stampManifestSet } from './manifests.js';
+export const RELEASE_BUMPS = ['patch', 'minor', 'major', 'existing'];
+export function isReleaseBump(value) {
+    return RELEASE_BUMPS.includes(value);
+}
+/** Compute the next stable version from the current base and a bump mode.
+ *
+ *  `base` must be a plain `major.minor.patch` (no prerelease/build suffix) — a
+ *  stable release should never start from a snapshot version. `existing` returns
+ *  the base verbatim; the increments zero out the lower components the way
+ *  `npm version` does. Returns `null` for an unparseable base so the caller can
+ *  fail loudly instead of publishing a garbage version. */
+export function computeStableVersion(bump, base) {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(base.trim());
+    if (!m)
+        return null;
+    const [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    switch (bump) {
+        case 'existing':
+            return `${major}.${minor}.${patch}`;
+        case 'patch':
+            return `${major}.${minor}.${patch + 1}`;
+        case 'minor':
+            return `${major}.${minor + 1}.0`;
+        case 'major':
+            return `${major + 1}.0.0`;
+        default:
+            return null;
+    }
+}
+/** Stamp the release set to a stable version.
+ *
+ *  Mirror of `stampSnapshotManifests`, differing in exactly one decision: intra-release
+ *  dependencies get a **caret** range (`^0.1.6`), not an exact pin. A stable `cezarion` should
+ *  follow compatible releases of the implementation package, and a stable service should follow
+ *  compatible releases of the api-client; a snapshot must pin the one exact build it was cut
+ *  from. Everything else — which manifests exist, which sections carry the pin, what the alias
+ *  inherits — lives in `manifests.ts` so the two channels cannot drift apart. */
+export function stampStableManifests(manifests, version) {
+    return stampManifestSet(manifests, version, (v) => `^${v}`);
+}
+//# sourceMappingURL=stable.js.map

package/dist/release/stable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable.js","sourceRoot":"","sources":["../../src/release/stable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,gBAAgB,EAA+C,MAAM,gBAAgB,CAAC;AAO/F,MAAM,CAAC,MAAM,aAAa,GAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAE7F,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAQ,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;2DAM2D;AAC3D,MAAM,UAAU,oBAAoB,CAAC,IAAiB,EAAE,IAAY;IAClE,MAAM,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACpD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,UAAU;YACb,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;QACtC,KAAK,OAAO;YACV,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,KAAK,OAAO;YACV,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC;QACnC,KAAK,OAAO;YACV,OAAO,GAAG,KAAK,GAAG,CAAC,MAAM,CAAC;QAC5B;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAID;;;;;;;iFAOiF;AACjF,MAAM,UAAU,oBAAoB,CAClC,SAA6B,EAC7B,OAAe;IAEf,OAAO,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/dist/runs/agent-tmpdir.d.ts

@@ -0,0 +1,41 @@
+/** Where a run's agent-scoped temp directory lives. */
+export declare function agentTmpDir(dataDir: string, runId: string): string;
+/**
+ * The preflight's failure. Named so the spawn path can tell it apart from an
+ * ordinary crash and turn it into the run's `error` — the same treatment
+ * `ModelIdentityError` gets, and the same channel the thread footer renders.
+ */
+export declare class AgentTempDirError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: unknown);
+}
+/** Opt-out spelling matches the house style for default-on behaviour
+ *  (`CEZ_AUTONAME=0`, `CEZ_SKILLS_AUTO_UPDATE=0`): only an exact `0` disables. */
+export declare function agentTmpDirEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The `TMPDIR`/`TEMP`/`TMP` overrides for this run, after proving the resolved
+ * directory actually accepts writes. Throws `AgentTempDirError` when it does
+ * not — callers turn that into the run's error rather than spawning.
+ *
+ * All three spellings are set, on every platform: a tool that reads `TMP` (or
+ * `TEMP`) would otherwise keep following the host value straight back to the
+ * exhausted directory this exists to escape.
+ *
+ * Returns `{}` under the opt-out, without probing anything: the hatch turns the
+ * whole feature off, preflight included, so it stays an escape someone can
+ * actually take.
+ */
+export declare function agentTmpEnv(dataDir: string, runId: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Reap one run's directory. Scratch, not an artifact: nothing reads it once the
+ * agent is gone, and a Continue re-creates it through `agentTmpEnv`. Never
+ * throws — reaping must not break a terminal transition.
+ */
+export declare function removeAgentTmpDir(dataDir: string, runId: string): void;
+/**
+ * Remove every per-run directory that is not in `keepRunIds` — the startup
+ * sweep, so a crash (which never reaches the terminal-transition reap) cannot
+ * accumulate them forever. Confined to `<dataDir>/tmp`; sibling run state is
+ * never enumerated, let alone touched. Returns the ids actually reaped.
+ */
+export declare function sweepAgentTmpDirs(dataDir: string, keepRunIds: Iterable<string>): string[];

package/dist/runs/agent-tmpdir.js

@@ -0,0 +1,183 @@
+/**
+ * Task-scoped temp directory for spawned agents (#785).
+ *
+ * Every agent used to inherit the host's `TMPDIR`/`TEMP`/`TMP` verbatim — they
+ * ride in on `buildChildEnv`'s base allowlist — so every run on the machine
+ * shared one directory. On a box that runs agents continuously and never
+ * reboots, that directory is a tmpfs nobody reaps, and once it hits its quota
+ * the failure is *silent*: the Claude Code CLI roots its scratch tree at
+ * `os.tmpdir()` and round-trips each `Bash` command's stdout/stderr through a
+ * file there. Under `EDQUOT` the inode is still allocated, so the file is
+ * created and the write fails — the command runs, its side effects land, and
+ * the agent reads back an empty result with a bogus exit status. Nothing in the
+ * cockpit says anything is wrong.
+ *
+ * Two properties fix that, and this module owns both:
+ *
+ *   1. **Isolation** — each run gets `<dataDir>/tmp/<runId>`, on the same disk
+ *      as the run's own state rather than a shared tmpfs, reaped when the run
+ *      ends. `buildChildEnv` applies the per-run env last, so these values win
+ *      over the host's without any allowlist change.
+ *   2. **Fail loud** — the directory is write-probed before the backend spawns.
+ *      A run that cannot get a working temp directory fails immediately with a
+ *      named, actionable error instead of spawning an agent that will run blind.
+ *
+ * `CEZ_AGENT_TMPDIR=0` opts out of BOTH — cezar keeps its hands off the temp
+ * directory entirely and the pre-#785 behaviour is back, byte for byte. That is
+ * deliberate: an escape hatch that still imposed the preflight would be a hatch
+ * you cannot actually escape through, and this repo's graceful-degradation rule
+ * says a new check must never become the only way to run.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Run ids are uuids; anything else must never reach a recursive `rmSync`.
+ *
+ *  `.` and `..` are excluded explicitly, not as pedantry: they match the
+ *  character class, and `join(dataDir, 'tmp', '..')` resolves to `<dataDir>`
+ *  itself — a recursive removal of every run's state. A guard that admits the
+ *  one input capable of turning this helper into data loss is not a guard. */
+function safeRunId(id) {
+    return /^[A-Za-z0-9._-]+$/.test(id) && id !== '.' && id !== '..';
+}
+/** Where a run's agent-scoped temp directory lives. */
+export function agentTmpDir(dataDir, runId) {
+    return join(dataDir, 'tmp', runId);
+}
+/** The root every per-run directory hangs off — the ONLY tree this module
+ *  removes anything from (`runs/`, `runs.json` and `worktrees/` are siblings). */
+function agentTmpRoot(dataDir) {
+    return join(dataDir, 'tmp');
+}
+/** `errno` → the phrasing a human recognises from their shell. */
+const REASONS = {
+    EDQUOT: 'Disk quota exceeded',
+    ENOSPC: 'No space left on device',
+    EACCES: 'Permission denied',
+    EPERM: 'Operation not permitted',
+    EROFS: 'Read-only file system',
+};
+/**
+ * The preflight's failure. Named so the spawn path can tell it apart from an
+ * ordinary crash and turn it into the run's `error` — the same treatment
+ * `ModelIdentityError` gets, and the same channel the thread footer renders.
+ */
+export class AgentTempDirError extends Error {
+    path;
+    constructor(path, reason) {
+        const code = reason?.code;
+        const why = (code && REASONS[code])
+            ?? code
+            ?? (reason instanceof Error ? reason.message : String(reason));
+        super(`agent temp directory is not writable: ${path} (${why}) — free disk space, `
+            + 'or set CEZ_AGENT_TMPDIR=0 to fall back to the host TMPDIR');
+        this.name = 'AgentTempDirError';
+        this.path = path;
+    }
+}
+/** Opt-out spelling matches the house style for default-on behaviour
+ *  (`CEZ_AUTONAME=0`, `CEZ_SKILLS_AUTO_UPDATE=0`): only an exact `0` disables. */
+export function agentTmpDirEnabled(env = process.env) {
+    return env.CEZ_AGENT_TMPDIR !== '0';
+}
+/** Distinguishes concurrent probes from one process; the pid alone would let two
+ *  spawns racing on the same directory delete each other's file mid-probe. */
+let probeSeq = 0;
+/**
+ * Write-probe `dir`. Creating the file is not enough to prove the directory
+ * works — a quota-exhausted tmpfs still allocates the inode and only fails the
+ * `write(2)` — so the probe writes real bytes and removes them again. A
+ * directory that is merely *full but writable* passes, by design.
+ */
+function probeWritable(dir) {
+    const probe = join(dir, `.cez-tmp-probe-${process.pid}-${(probeSeq += 1)}`);
+    try {
+        writeFileSync(probe, 'cez');
+    }
+    catch (err) {
+        throw new AgentTempDirError(dir, err);
+    }
+    finally {
+        try {
+            rmSync(probe, { force: true });
+        }
+        catch {
+            // best-effort: a probe we could not remove is not a reason to fail a run.
+        }
+    }
+}
+/**
+ * The `TMPDIR`/`TEMP`/`TMP` overrides for this run, after proving the resolved
+ * directory actually accepts writes. Throws `AgentTempDirError` when it does
+ * not — callers turn that into the run's error rather than spawning.
+ *
+ * All three spellings are set, on every platform: a tool that reads `TMP` (or
+ * `TEMP`) would otherwise keep following the host value straight back to the
+ * exhausted directory this exists to escape.
+ *
+ * Returns `{}` under the opt-out, without probing anything: the hatch turns the
+ * whole feature off, preflight included, so it stays an escape someone can
+ * actually take.
+ */
+export function agentTmpEnv(dataDir, runId, env = process.env) {
+    if (!agentTmpDirEnabled(env))
+        return {};
+    const dir = agentTmpDir(dataDir, runId);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (err) {
+        throw new AgentTempDirError(dir, err);
+    }
+    probeWritable(dir);
+    return { TMPDIR: dir, TEMP: dir, TMP: dir };
+}
+/**
+ * Reap one run's directory. Scratch, not an artifact: nothing reads it once the
+ * agent is gone, and a Continue re-creates it through `agentTmpEnv`. Never
+ * throws — reaping must not break a terminal transition.
+ */
+export function removeAgentTmpDir(dataDir, runId) {
+    if (!safeRunId(runId))
+        return;
+    try {
+        rmSync(agentTmpDir(dataDir, runId), { recursive: true, force: true });
+    }
+    catch {
+        // best-effort; the startup sweep picks up whatever survives.
+    }
+}
+/**
+ * Remove every per-run directory that is not in `keepRunIds` — the startup
+ * sweep, so a crash (which never reaches the terminal-transition reap) cannot
+ * accumulate them forever. Confined to `<dataDir>/tmp`; sibling run state is
+ * never enumerated, let alone touched. Returns the ids actually reaped.
+ */
+export function sweepAgentTmpDirs(dataDir, keepRunIds) {
+    const root = agentTmpRoot(dataDir);
+    if (!existsSync(root))
+        return [];
+    const keep = new Set(keepRunIds);
+    const reaped = [];
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    for (const name of entries) {
+        if (keep.has(name) || !safeRunId(name))
+            continue;
+        try {
+            rmSync(join(root, name), { recursive: true, force: true });
+            reaped.push(name);
+        }
+        catch {
+            // best-effort: a locked directory is retried on the next boot.
+        }
+    }
+    return reaped;
+}
+//# sourceMappingURL=agent-tmpdir.js.map

package/dist/runs/agent-tmpdir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tmpdir.js","sourceRoot":"","sources":["../../src/runs/agent-tmpdir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;8EAK8E;AAC9E,SAAS,SAAS,CAAC,EAAU;IAC3B,OAAO,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,CAAC;AACnE,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,KAAa;IACxD,OAAO,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AACrC,CAAC;AAED;kFACkF;AAClF,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,kEAAkE;AAClE,MAAM,OAAO,GAAqC;IAChD,MAAM,EAAE,qBAAqB;IAC7B,MAAM,EAAE,yBAAyB;IACjC,MAAM,EAAE,mBAAmB;IAC3B,KAAK,EAAE,yBAAyB;IAChC,KAAK,EAAE,uBAAuB;CAC/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,MAAe;QACvC,MAAM,IAAI,GAAI,MAA4C,EAAE,IAAI,CAAC;QACjE,MAAM,GAAG,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;eAC9B,IAAI;eACJ,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACjE,KAAK,CACH,yCAAyC,IAAI,KAAK,GAAG,uBAAuB;cACxE,2DAA2D,CAChE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;kFACkF;AAClF,MAAM,UAAU,kBAAkB,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IACrE,OAAO,GAAG,CAAC,gBAAgB,KAAK,GAAG,CAAC;AACtC,CAAC;AAED;8EAC8E;AAC9E,IAAI,QAAQ,GAAG,CAAC,CAAC;AAEjB;;;;;GAKG;AACH,SAAS,aAAa,CAAC,GAAW;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,kBAAkB,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5E,IAAI,CAAC;QACH,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,KAAa,EACb,GAAG,GAAsB,OAAO,CAAC,GAAG;IAEpC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC;QACH,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IACD,aAAa,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,KAAa;IAC9D,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;QAAE,OAAO;IAC9B,IAAI,CAAC;QACH,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;IAC/D,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,UAA4B;IAC7E,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACjC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;aACjD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;aAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,SAAS;QACjD,IAAI,CAAC;YACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;QACjE,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,75 @@
+import { type TaskRefs } from './task-refs.ts';
+/**
+ * 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,179 @@
+import { z } from 'zod';
+import { loadConfig } from '../config.js';
+import { createRunner } from '../core/runner-factory.js';
+import { parseStructured } from '../planner.js';
+import { resolveProfileEnvForRoot } from '../workspace/agent-profiles.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;
+        // Name under the project's own agent account (spec 2026-07-29-agent-profiles) — naming is
+        // a model call like any other, and billing it to the personal subscription for a work
+        // project is the exact confusion accounts exist to remove.
+        const { env: profileEnv } = await resolveProfileEnvForRoot(repoRoot, config.defaultRunner);
+        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: { ...profileEnv, 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;
+    // #623: a terse title is one phrase, not concatenated progress narration. Reject
+    // unambiguous missing sentence whitespace (the observed `.Config` / `.The`
+    // shape) and keep the honest heuristic title instead of trying to guess
+    // where a model's prose should have been split.
+    if (/[.!?][A-Z]/.test(parsed.title))
+        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/event-history.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { type RunEvent, type RunHistoryContext, type RunHistoryEvent, type RunHistoryPage } from '../contract/index.js';
+declare const pageCursorSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"page">;
+    direction: z.ZodEnum<{
+        newer: "newer";
+        older: "older";
+    }>;
+    fileSize: z.ZodNumber;
+    boundarySeq: z.ZodNumber;
+}, z.core.$strip>;
+declare const liveCursorSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"live">;
+    offset: z.ZodNumber;
+    boundarySeq: z.ZodNumber;
+}, z.core.$strip>;
+export declare class HistoryCursorError extends Error {
+    readonly status: 400 | 409;
+    constructor(status: 400 | 409, message: string);
+}
+export declare function decodePageCursor(cursor: string): z.infer<typeof pageCursorSchema>;
+export declare function decodeLiveCursor(cursor: string): z.infer<typeof liveCursorSchema>;
+interface CanonicalItem {
+    key: string;
+    firstSeq: number;
+    lastSeq: number;
+}
+/**
+ * Classify the source events into the same protocol-level item units the cockpit renders.
+ *
+ * Projection always operates on complete collected turns. A v2-covered turn suppresses its v1
+ * tool twins; lifecycle snapshots sharing a step/item identity collapse to one item.
+ */
+export declare function canonicalSessionItems(events: readonly RunEvent[]): CanonicalItem[];
+export interface HistoryReadInstrumentation {
+    fileSize: number;
+    bytesRead: number;
+    retainedEvents: number;
+}
+export declare function readRunHistoryPage(filePath: string, cursor?: string, onRead?: (instrumentation: HistoryReadInstrumentation) => void): Promise<RunHistoryPage>;
+/** One forward pass retaining the latest Plan snapshot and only the selector-equivalent agent episode. */
+export declare function deriveRunContextEvents(filePath: string): Promise<RunHistoryContext>;
+export declare function readEventsAfterLiveCursor(filePath: string, cursor: string): Promise<{
+    events: RunHistoryEvent[];
+    boundarySeq: number;
+}>;
+export declare function validateLiveCursor(filePath: string, cursor: string): Promise<void>;
+export {};