@open-mercato/cezar 0.1.5-pr506.357

package/dist/config.d.ts

@@ -0,0 +1,144 @@
+import { z } from 'zod';
+/**
+ * Optional advanced config at `.ai/cezar/config.json`. Zero-config rule:
+ * a missing file behaves exactly like the default below, an unreadable or
+ * invalid file degrades to the default too (never blocks startup). The key
+ * can be overridden or emptied (`"skillsRepos": []` disables team skills).
+ */
+declare const skillsRepoSchema: z.ZodObject<{
+    /** `owner/name` (GitHub shorthand), a full git URL, or a local/file:// path. */
+    repo: z.ZodString;
+    ref: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+    ref: string;
+}, {
+    repo: string;
+    ref?: string | undefined;
+}>;
+export type SkillsRepoSource = z.infer<typeof skillsRepoSchema>;
+export declare const DEFAULT_SKILLS_REPOS: SkillsRepoSource[];
+declare const configSchema: z.ZodObject<{
+    skillsRepos: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** `owner/name` (GitHub shorthand), a full git URL, or a local/file:// path. */
+        repo: z.ZodString;
+        ref: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        repo: string;
+        ref: string;
+    }, {
+        repo: string;
+        ref?: string | undefined;
+    }>, "many">>;
+    /** How many tasks may run at once (spec 006). Non-git dirs always run 1. */
+    maxParallel: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Count-based worktree retention (#483): keep the last N *finished*
+     * worktrees materialized on disk; reclaim older ones (directory only — the
+     * `cez/<id8>` branch is kept, so the work stays recoverable). 0 = unlimited
+     * (never auto-reclaim). Default 10. `.catch(10)` keeps it additive-safe: a
+     * bad value degrades to the default instead of discarding the rest.
+     */
+    worktreeRetention: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    /**
+     * Per-task memory ceiling in MiB (whole process tree). When a running task's
+     * RSS crosses this the engine pauses it with a warning and lets the queue
+     * advance (#memory-guard). 0 / unset = no limit. `.catch(undefined)` keeps
+     * the key additive-safe: a bad value degrades to "no limit".
+     */
+    memoryLimitMb: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    /**
+     * Which agent backend a task uses unless overridden per task (GUI) or per
+     * step (workflow). The GUI only offers runners actually installed; this is
+     * the preselected default. Also the runner the chain planner uses.
+     */
+    defaultRunner: z.ZodDefault<z.ZodEnum<["claude", "codex", "opencode"]>>;
+    /** Model for the chain planner (spec 008) — cheap but reliable at JSON. */
+    plannerModel: z.ZodDefault<z.ZodString>;
+    /** Model for the task namer (spec 2026-07-17-task-auto-naming) — the cheapest
+     *  alias that answers strict JSON; naming is fire-and-forget and never blocks. */
+    namerModel: z.ZodDefault<z.ZodString>;
+    /** Live title updates: refresh the display title through the namer on each
+     *  turn end. Absent = the `CEZ_TITLE_UPDATES` env decides (default ON — owner
+     *  decision on PR #479). */
+    liveTitleUpdates: z.ZodOptional<z.ZodBoolean>;
+    /** Optional diff-first review gate (#489): when a successful run with changes
+     *  should park at `review` for a human. Absent = the `CEZ_REVIEW_GATE` env
+     *  decides (default OFF — the deliberate inverse of `liveTitleUpdates`).
+     *  Autonomous runs always skip the gate regardless of this. */
+    reviewGate: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Branch task worktrees fork from and draft PRs target (e.g. `develop`).
+     * Unset = the branch currently checked out. Settable from the Repo tab.
+     */
+    baseBranch: z.ZodOptional<z.ZodString>;
+    /**
+     * Default extra system prompt applied to every run's agent steps (claude:
+     * `--append-system-prompt`; codex/opencode: prepended to the opening user
+     * message — the AgentRunSpec seam handles the per-backend delivery).
+     * Settings is the single edit place; `POST /api/runs` can override it per
+     * run (`systemPrompt`). `.catch(undefined)` keeps the key additive-safe: a
+     * bad value degrades to unset without discarding the rest of the config.
+     */
+    systemPrompt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    /**
+     * Per-runner default model preset (Settings → Agents, redesign R6 1.5): the
+     * model id the composer preselects for that runner. Missing = auto (the
+     * runner decides). A capability (`model`), never a vendor config format.
+     * `.catch(undefined)` keeps the key additive-safe like `systemPrompt`: a
+     * bad value degrades to unset without discarding the rest of the config.
+     */
+    defaultModels: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        claude: z.ZodOptional<z.ZodString>;
+        codex: z.ZodOptional<z.ZodString>;
+        opencode: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        claude?: string | undefined;
+        codex?: string | undefined;
+        opencode?: string | undefined;
+    }, {
+        claude?: string | undefined;
+        codex?: string | undefined;
+        opencode?: string | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    skillsRepos: {
+        repo: string;
+        ref: string;
+    }[];
+    maxParallel: number;
+    worktreeRetention: number;
+    defaultRunner: "claude" | "codex" | "opencode";
+    plannerModel: string;
+    namerModel: string;
+    memoryLimitMb?: number | undefined;
+    liveTitleUpdates?: boolean | undefined;
+    reviewGate?: boolean | undefined;
+    baseBranch?: string | undefined;
+    systemPrompt?: string | undefined;
+    defaultModels?: {
+        claude?: string | undefined;
+        codex?: string | undefined;
+        opencode?: string | undefined;
+    } | undefined;
+}, {
+    skillsRepos?: {
+        repo: string;
+        ref?: string | undefined;
+    }[] | undefined;
+    maxParallel?: number | undefined;
+    worktreeRetention?: unknown;
+    memoryLimitMb?: unknown;
+    defaultRunner?: "claude" | "codex" | "opencode" | undefined;
+    plannerModel?: string | undefined;
+    namerModel?: string | undefined;
+    liveTitleUpdates?: boolean | undefined;
+    reviewGate?: boolean | undefined;
+    baseBranch?: string | undefined;
+    systemPrompt?: unknown;
+    defaultModels?: unknown;
+}>;
+export type CezConfig = z.infer<typeof configSchema>;
+/** Read `.ai/cezar/config.json` on demand — never cached, never throws. */
+export declare function loadConfig(repoRoot: string): Promise<CezConfig>;
+export {};

package/dist/config.js

@@ -0,0 +1,106 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+/**
+ * Optional advanced config at `.ai/cezar/config.json`. Zero-config rule:
+ * a missing file behaves exactly like the default below, an unreadable or
+ * invalid file degrades to the default too (never blocks startup). The key
+ * can be overridden or emptied (`"skillsRepos": []` disables team skills).
+ */
+const skillsRepoSchema = z.object({
+    /** `owner/name` (GitHub shorthand), a full git URL, or a local/file:// path. */
+    repo: z.string().min(1),
+    ref: z.string().min(1).default('main'),
+});
+export const DEFAULT_SKILLS_REPOS = [
+    { repo: 'open-mercato/skills', ref: 'main' },
+];
+const configSchema = z.object({
+    skillsRepos: z.array(skillsRepoSchema).default(DEFAULT_SKILLS_REPOS),
+    /** How many tasks may run at once (spec 006). Non-git dirs always run 1. */
+    maxParallel: z.number().int().min(1).max(16).default(2),
+    /**
+     * Count-based worktree retention (#483): keep the last N *finished*
+     * worktrees materialized on disk; reclaim older ones (directory only — the
+     * `cez/<id8>` branch is kept, so the work stays recoverable). 0 = unlimited
+     * (never auto-reclaim). Default 10. `.catch(10)` keeps it additive-safe: a
+     * bad value degrades to the default instead of discarding the rest.
+     */
+    worktreeRetention: z.number().int().min(0).max(1000).default(10).catch(10),
+    /**
+     * Per-task memory ceiling in MiB (whole process tree). When a running task's
+     * RSS crosses this the engine pauses it with a warning and lets the queue
+     * advance (#memory-guard). 0 / unset = no limit. `.catch(undefined)` keeps
+     * the key additive-safe: a bad value degrades to "no limit".
+     */
+    memoryLimitMb: z.number().int().min(0).max(1_048_576).optional().catch(undefined),
+    /**
+     * Which agent backend a task uses unless overridden per task (GUI) or per
+     * step (workflow). The GUI only offers runners actually installed; this is
+     * the preselected default. Also the runner the chain planner uses.
+     */
+    defaultRunner: z.enum(['claude', 'codex', 'opencode']).default('claude'),
+    /** Model for the chain planner (spec 008) — cheap but reliable at JSON. */
+    plannerModel: z.string().min(1).default('sonnet'),
+    /** Model for the task namer (spec 2026-07-17-task-auto-naming) — the cheapest
+     *  alias that answers strict JSON; naming is fire-and-forget and never blocks. */
+    namerModel: z.string().min(1).default('haiku'),
+    /** Live title updates: refresh the display title through the namer on each
+     *  turn end. Absent = the `CEZ_TITLE_UPDATES` env decides (default ON — owner
+     *  decision on PR #479). */
+    liveTitleUpdates: z.boolean().optional(),
+    /** Optional diff-first review gate (#489): when a successful run with changes
+     *  should park at `review` for a human. Absent = the `CEZ_REVIEW_GATE` env
+     *  decides (default OFF — the deliberate inverse of `liveTitleUpdates`).
+     *  Autonomous runs always skip the gate regardless of this. */
+    reviewGate: z.boolean().optional(),
+    /**
+     * Branch task worktrees fork from and draft PRs target (e.g. `develop`).
+     * Unset = the branch currently checked out. Settable from the Repo tab.
+     */
+    baseBranch: z.string().trim().min(1).optional(),
+    /**
+     * Default extra system prompt applied to every run's agent steps (claude:
+     * `--append-system-prompt`; codex/opencode: prepended to the opening user
+     * message — the AgentRunSpec seam handles the per-backend delivery).
+     * Settings is the single edit place; `POST /api/runs` can override it per
+     * run (`systemPrompt`). `.catch(undefined)` keeps the key additive-safe: a
+     * bad value degrades to unset without discarding the rest of the config.
+     */
+    systemPrompt: z.string().trim().min(1).max(20_000).optional().catch(undefined),
+    /**
+     * Per-runner default model preset (Settings → Agents, redesign R6 1.5): the
+     * model id the composer preselects for that runner. Missing = auto (the
+     * runner decides). A capability (`model`), never a vendor config format.
+     * `.catch(undefined)` keeps the key additive-safe like `systemPrompt`: a
+     * bad value degrades to unset without discarding the rest of the config.
+     */
+    defaultModels: z
+        .object({
+        claude: z.string().trim().min(1).max(200).optional(),
+        codex: z.string().trim().min(1).max(200).optional(),
+        opencode: z.string().trim().min(1).max(200).optional(),
+    })
+        .optional()
+        .catch(undefined),
+});
+/** Read `.ai/cezar/config.json` on demand — never cached, never throws. */
+export async function loadConfig(repoRoot) {
+    let raw;
+    try {
+        raw = await readFile(join(repoRoot, '.ai/cezar', 'config.json'), 'utf8');
+    }
+    catch {
+        return configSchema.parse({});
+    }
+    try {
+        const parsed = configSchema.safeParse(JSON.parse(raw));
+        if (parsed.success)
+            return parsed.data;
+    }
+    catch {
+        // fall through — malformed JSON degrades to the default
+    }
+    return configSchema.parse({});
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/core/agent-runner.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The backend-agnostic seam for running one agent task. Adapted from
+ * @cezar/core's `agents/agent-runner.ts`, trimmed for single-user local use:
+ * no token-budget circuit breaker, no zod response schemas — one run is one
+ * agent-CLI session streaming normalized events.
+ *
+ * Three interchangeable backends implement this seam, each as a persistent
+ * process so multi-turn follow-ups, `waiting`, interrupt and resume all work:
+ *  - `claude`   — Claude Code CLI, stream-json over stdin/stdout;
+ *  - `codex`    — `codex app-server`, JSON-RPC 2.0 (JSONL) over stdin/stdout;
+ *  - `opencode` — `opencode serve`, HTTP + SSE.
+ */
+import type { UiEvent } from './ui-events.js';
+/** `claude-cli` is the legacy id kept so old run records still parse. */
+export type AgentBackend = 'claude' | 'codex' | 'opencode' | 'claude-cli';
+/** The user-selectable runners (what config/GUI expose). */
+export type RunnerId = 'claude' | 'codex' | 'opencode';
+export declare const RUNNER_IDS: readonly RunnerId[];
+export interface AgentRunSpec {
+    /** Appended to the CLI's default system prompt (`--append-system-prompt`). */
+    systemPrompt?: string;
+    userPrompt: string;
+    /** Image blocks delivered with the first user message — screenshots pasted
+     *  into the new-task form (spec 002's paste path, at task start). */
+    images?: ContentBlock[];
+    /** The directory the agent runs in — also the only writable root. */
+    cwd: string;
+    /** Tool allowlist; the CLI is default-deny for anything not listed — but
+     *  the zero-config default (`DEFAULT_ALLOWED_TOOLS`) includes `Bash`
+     *  unrestricted unless `bashAllowlist` is set, so treat the default as
+     *  full shell access in `cwd`, not a sandboxed allowlist (#430). */
+    allowedTools?: string[];
+    /** When `Bash` is allowed, restrict it to commands starting with one of these. */
+    bashAllowlist?: string[];
+    /** Extra directories the agent may read/write besides `cwd`. */
+    additionalDirectories?: string[];
+    /** Extra env vars for the agent process (merged over `process.env`) —
+     *  e.g. CEZ_HANDOFF_FILE / CEZ_TODOS_FILE / CEZ_TASK_ID (spec 007). */
+    env?: Record<string, string>;
+    model?: string;
+    /** Wall-clock kill switch for the run (ms). */
+    timeoutMs?: number;
+    /**
+     * Stable session id (UUID) so the user can take over interactively later:
+     * `cd <repo> && claude --resume <sessionId>`.
+     */
+    sessionId?: string;
+    /**
+     * Spawn `claude --resume <sessionId>` instead of starting a fresh session —
+     * picks up the on-disk conversation (used by "Continue" after a run ends).
+     */
+    resume?: boolean;
+}
+/**
+ * Backends without a dedicated system-prompt channel (codex app-server,
+ * opencode serve) deliver `spec.systemPrompt` as a leading block of the
+ * opening user message — the documented per-backend mapping (spec §protocol
+ * v2: claude = `--append-system-prompt`, codex/opencode = prepended here).
+ */
+export declare function prependSystemPrompt(systemPrompt: string | undefined, userPrompt: string): string;
+/** One content block of a user message — mirrors the Anthropic wire format
+ *  so it can be written to the claude CLI's stdin verbatim. */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+};
+/** Normalized event stream — the GUI renders these, the store persists them. */
+export type AgentEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool-call';
+    id: string;
+    tool: string;
+    input: unknown;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    result: string;
+    isError: boolean;
+}
+/** An image inside a tool result (screenshot tools, Read on a PNG…) —
+ *  raw base64 here; the run manager persists it and re-emits a URL. */
+ | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+} | {
+    type: 'token-usage';
+    tokensUsed: number;
+} | {
+    type: 'cost';
+    usd: number;
+}
+/** The backend's real session id, once known — codex threads and opencode
+ *  sessions mint their own id, so the run manager persists this to enable
+ *  resume ("Continue") and "open in CLI". Claude's equals `spec.sessionId`. */
+ | {
+    type: 'session';
+    sessionId: string;
+} | {
+    type: 'turn-end';
+} | {
+    type: 'note';
+    message: string;
+} | {
+    type: 'done';
+} | {
+    type: 'error';
+    message: string;
+};
+export interface AgentToolCallRecord {
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface AgentRunResult {
+    /** Concatenated assistant text across the run, trimmed. */
+    text: string;
+    toolCalls: AgentToolCallRecord[];
+    /** Cost-weighted token usage; 0 when the backend surfaced no telemetry. */
+    tokensUsed: number;
+    sessionId?: string;
+}
+export interface SessionOptions {
+    /** Close the session shortly after the first turn ends (single-turn
+     *  behavior, used for non-interactive workflow steps). Interactive
+     *  sessions omit this and control `end()` themselves. */
+    autoEndAfterFirstTurn?: boolean;
+    /** Protocol-v2 channel: receives the normalized `UiEvent` stream emitted
+     *  ALONGSIDE the v1 `AgentEvent`s (additive — v1 keeps flowing unchanged).
+     *  RunManager consumption lands in R2 step 2.1. */
+    onUiEvent?: (event: UiEvent) => void;
+}
+/**
+ * A live agent session over one spawned backend process. The process stays
+ * alive between turns and reads further user messages — that's what makes
+ * mid-task follow-ups possible. Implemented identically by every backend
+ * (claude stdin, codex app-server, opencode serve).
+ */
+export interface AgentSession {
+    /** Resolves when the backend process exits — the session is fully over. */
+    result: Promise<AgentRunResult>;
+    /** OS pid of the spawned backend process — the root of the run's process
+     *  tree (agents spawn Bash children under it). Absent when the spawn
+     *  failed before a pid existed. Feeds live resource telemetry (#348). */
+    readonly pid?: number;
+    /** Write a user message into the live session. False when it is closed. */
+    sendMessage(content: ContentBlock[]): boolean;
+    /** Graceful close: end input, then a SIGTERM→SIGKILL watchdog. */
+    end(): void;
+    /** Hard stop (used by cancel). */
+    interrupt(): void;
+    /** True while the session still accepts messages. */
+    readonly open: boolean;
+}
+export interface AgentRunner {
+    readonly backend: AgentBackend;
+    run(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void): Promise<AgentRunResult>;
+    startSession(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void, opts?: SessionOptions): AgentSession;
+    interrupt(): Promise<void>;
+}

package/dist/core/agent-runner.js

@@ -0,0 +1,23 @@
+/**
+ * The backend-agnostic seam for running one agent task. Adapted from
+ * @cezar/core's `agents/agent-runner.ts`, trimmed for single-user local use:
+ * no token-budget circuit breaker, no zod response schemas — one run is one
+ * agent-CLI session streaming normalized events.
+ *
+ * Three interchangeable backends implement this seam, each as a persistent
+ * process so multi-turn follow-ups, `waiting`, interrupt and resume all work:
+ *  - `claude`   — Claude Code CLI, stream-json over stdin/stdout;
+ *  - `codex`    — `codex app-server`, JSON-RPC 2.0 (JSONL) over stdin/stdout;
+ *  - `opencode` — `opencode serve`, HTTP + SSE.
+ */
+export const RUNNER_IDS = ['claude', 'codex', 'opencode'];
+/**
+ * Backends without a dedicated system-prompt channel (codex app-server,
+ * opencode serve) deliver `spec.systemPrompt` as a leading block of the
+ * opening user message — the documented per-backend mapping (spec §protocol
+ * v2: claude = `--append-system-prompt`, codex/opencode = prepended here).
+ */
+export function prependSystemPrompt(systemPrompt, userPrompt) {
+    return systemPrompt ? `${systemPrompt}\n\n---\n\n${userPrompt}` : userPrompt;
+}
+//# sourceMappingURL=agent-runner.js.map

package/dist/core/agent-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.js","sourceRoot":"","sources":["../../src/core/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAsC/E;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAgC,EAAE,UAAkB;IACtF,OAAO,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,cAAc,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AAC/E,CAAC"}

package/dist/core/backend-detect.d.ts

@@ -0,0 +1,16 @@
+export interface BackendCheck {
+    name: 'claude' | 'codex' | 'opencode' | 'gh' | 'git';
+    available: boolean;
+    version?: string;
+    hint?: string;
+}
+/**
+ * Probe the host for everything cez leans on: the agent CLIs (`claude`, and
+ * the optional `codex` / `opencode` alternatives), `gh` (GitHub auth for PR
+ * creation) and `git`. Nothing is required except at least one agent CLI — the
+ * GUI degrades gracefully, only offers the runners that are present, and shows
+ * the hints for the rest.
+ */
+export declare function detectEnvironment(): Promise<BackendCheck[]>;
+/** The host's GitHub token: logged-in `gh` first, `GITHUB_TOKEN` fallback. */
+export declare function readHostGithubToken(): Promise<string | null>;

package/dist/core/backend-detect.js

@@ -0,0 +1,118 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+/**
+ * Probe the host for everything cez leans on: the agent CLIs (`claude`, and
+ * the optional `codex` / `opencode` alternatives), `gh` (GitHub auth for PR
+ * creation) and `git`. Nothing is required except at least one agent CLI — the
+ * GUI degrades gracefully, only offers the runners that are present, and shows
+ * the hints for the rest.
+ */
+export async function detectEnvironment() {
+    return Promise.all([probeClaude(), probeCodex(), probeOpencode(), probeGh(), probeGit()]);
+}
+async function probeClaude() {
+    if (process.env.CEZ_DRY_RUN === '1') {
+        return { name: 'claude', available: true, version: 'mock (CEZ_DRY_RUN=1)' };
+    }
+    try {
+        const { stdout } = await exec('claude', ['--version'], { timeout: 10_000 });
+        const version = stdout.trim();
+        // A generic `claude` binary (a shell wrapper, an unrelated tool) can shadow
+        // the real CLI on $PATH — reject anything that doesn't match the banner.
+        if (!/^\d+\.\d+|^claude(\s+code)?\s+version\s+\d+\.\d+/i.test(version)) {
+            return {
+                name: 'claude',
+                available: false,
+                hint: `\`claude\` is on PATH but doesn't look like Claude Code (got: ${version.slice(0, 80)})`,
+            };
+        }
+        return {
+            name: 'claude',
+            available: true,
+            version,
+            hint: 'if not authenticated, run `claude` once and log in',
+        };
+    }
+    catch {
+        return {
+            name: 'claude',
+            available: false,
+            hint: 'install Claude Code (npm i -g @anthropic-ai/claude-code) and log in',
+        };
+    }
+}
+async function probeCodex() {
+    const bin = process.env.CEZ_CODEX_BIN ?? 'codex';
+    try {
+        const { stdout } = await exec(bin, ['--version'], { timeout: 10_000 });
+        return {
+            name: 'codex',
+            available: true,
+            version: stdout.trim(),
+            hint: 'if not authenticated, run `codex` once and log in',
+        };
+    }
+    catch {
+        return {
+            name: 'codex',
+            available: false,
+            hint: 'optional: install the Codex CLI (npm i -g @openai/codex) and log in to use the Codex runner',
+        };
+    }
+}
+async function probeOpencode() {
+    const bin = process.env.CEZ_OPENCODE_BIN ?? 'opencode';
+    try {
+        const { stdout } = await exec(bin, ['--version'], { timeout: 10_000 });
+        return {
+            name: 'opencode',
+            available: true,
+            version: stdout.trim(),
+            hint: 'if no provider is configured, run `opencode` once to set one up',
+        };
+    }
+    catch {
+        return {
+            name: 'opencode',
+            available: false,
+            hint: 'optional: install OpenCode (https://opencode.ai) and configure a provider to use the OpenCode runner',
+        };
+    }
+}
+async function probeGh() {
+    try {
+        const { stdout } = await exec('gh', ['auth', 'token'], { timeout: 10_000 });
+        return { name: 'gh', available: stdout.trim().length > 0, version: 'authenticated' };
+    }
+    catch {
+        return {
+            name: 'gh',
+            available: false,
+            hint: 'install the GitHub CLI and run `gh auth login` (only needed for PR creation)',
+        };
+    }
+}
+async function probeGit() {
+    try {
+        const { stdout } = await exec('git', ['--version'], { timeout: 10_000 });
+        return { name: 'git', available: true, version: stdout.trim() };
+    }
+    catch {
+        return { name: 'git', available: false, hint: 'install git' };
+    }
+}
+/** The host's GitHub token: logged-in `gh` first, `GITHUB_TOKEN` fallback. */
+export async function readHostGithubToken() {
+    try {
+        const { stdout } = await exec('gh', ['auth', 'token'], { timeout: 10_000 });
+        const token = stdout.trim();
+        if (token)
+            return token;
+    }
+    catch {
+        // fall through to the env var
+    }
+    return process.env.GITHUB_TOKEN?.trim() || null;
+}
+//# sourceMappingURL=backend-detect.js.map

package/dist/core/backend-detect.js.map

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

package/dist/core/claude-cli-runner.d.ts

@@ -0,0 +1,56 @@
+import type { AgentEvent, AgentRunResult, AgentRunSpec, AgentRunner, AgentSession, SessionOptions } from './agent-runner.js';
+export type { AgentSession, SessionOptions } from './agent-runner.js';
+/** Default wall-clock cap for a single run before SIGTERM → SIGKILL.
+ *  Interactive sessions pass `timeoutMs: 0` to disable it entirely. */
+export declare const DEFAULT_RUN_TIMEOUT_MS: number;
+/** Grace period between SIGTERM and SIGKILL when a timeout fires. */
+export declare const KILL_GRACE_MS = 10000;
+/** After `end()` closes stdin: claude in stream-json mode can ignore EOF and
+ *  hang (janitor-confirmed CLI bug) — escalate SIGTERM, then SIGKILL. */
+export declare const EOF_TERM_GRACE_MS = 8000;
+export declare const EOF_KILL_GRACE_MS = 4000;
+/** Reopen window after a turn ends before an auto-ended session closes stdin. */
+export declare const AUTO_END_DELAY_MS = 250;
+export interface ClaudeCliRunnerOptions {
+    /** Override the binary name/path; defaults to `claude` on PATH. */
+    bin?: string;
+    /** Wall-clock timeout for a run (ms); per-spec `timeoutMs` still wins. */
+    timeoutMs?: number;
+}
+/**
+ * `AgentRunner` over the Claude Code CLI in headless stream-json mode. Auth =
+ * the host's logged-in Pro/Max subscription (no API key needed). Sandboxing is
+ * `--allowedTools` (default-deny for anything not listed) + running inside the
+ * repo `cwd`; `Bash` is narrowed to `Bash(<prefix>:*)` patterns only when
+ * `bashAllowlist` is set — the zero-config default has no allowlist, so `Bash`
+ * is unrestricted shell access (#430).
+ *
+ * Session mechanics (multi-turn stdin, EOF watchdog, reopen window) follow
+ * github-janitor's `claudeRunner.ts`; the original single-turn adaptation
+ * came from @cezar/core's `ClaudeCodeCliRunner`.
+ */
+export declare class ClaudeCliRunner implements AgentRunner {
+    readonly backend: "claude";
+    private readonly bin;
+    private readonly timeoutMs;
+    private lastSession;
+    constructor(opts?: ClaudeCliRunnerOptions);
+    /** One-shot run: start a session and auto-end it after the first turn. */
+    run(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void): Promise<AgentRunResult>;
+    interrupt(): Promise<void>;
+    startSession(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void, opts?: SessionOptions): AgentSession;
+}
+/**
+ * Build the headless argv. `--input-format stream-json` reads user messages
+ * from stdin; `--output-format stream-json --verbose` gives per-event NDJSON;
+ * `--permission-mode dontAsk` keeps headless runs non-interactive: tools in
+ * `--allowedTools` proceed and everything else is denied instead of prompting.
+ * `CEZ_APPROVAL_GATE=1` opts back into Claude's approval UI (#435).
+ */
+export declare function buildClaudeArgs(spec: AgentRunSpec, env?: NodeJS.ProcessEnv): string[];
+/**
+ * Map `allowedTools` onto claude's `--allowedTools` syntax. `Bash` with a
+ * `bashAllowlist` becomes one `Bash(<prefix>:*)` entry per allowed prefix;
+ * `Bash` with no allowlist stays plain `Bash`.
+ */
+export declare function buildAllowedTools(allowedTools: string[], bashAllowlist?: string[]): string[];