@open-mercato/cezar 0.1.5-pr506.357

package/dist/git-worktree.js

@@ -0,0 +1,297 @@
+import { execFile } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { readdir, rm } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+/**
+ * Git worktree per task (spec 006). Each run gets its own branch
+ * `cez/<id8>` checked out into `.ai/cezar/worktrees/<runId>` so agents never
+ * touch the user's working tree. Pattern ported from github-janitor's
+ * `git.ts` (createWorktree / autosaveCommit), minus the bare clone — we're
+ * already inside a working copy. Everything degrades: helpers never throw
+ * except `createWorktree`, whose failure the caller turns into a note.
+ */
+/** Repo-relative home of all task worktrees (gitignored via .ai/cezar/.gitignore). */
+export const WORKTREES_DIR = '.ai/cezar/worktrees';
+const DIFF_CAP = 400_000;
+/** Run git, never throw — degradation is the caller's policy. */
+function git(cwd, args) {
+    return new Promise((resolve) => {
+        execFile('git', args, { cwd, maxBuffer: 32 * 1024 * 1024, encoding: 'utf8' }, (err, stdout, stderr) => resolve({ ok: !err, stdout: stdout ?? '', stderr: stderr ?? '' }));
+    });
+}
+export function branchFor(runId) {
+    return `cez/${runId.slice(0, 8)}`;
+}
+/**
+ * Resolve the configured base branch to something `git worktree add` can
+ * fork from: the branch itself, else its remote-tracking ref (base exists
+ * only on origin), else null — the caller falls back to the current branch
+ * with a note. Never throws.
+ */
+export async function resolveBaseRef(repoRoot, base) {
+    for (const ref of [base, `origin/${base}`]) {
+        const res = await git(repoRoot, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+        if (res.ok)
+            return ref;
+    }
+    return null;
+}
+export function worktreePathFor(repoRoot, runId) {
+    return join(repoRoot, WORKTREES_DIR, runId);
+}
+/** Parse `git worktree list --porcelain` without assuming paths contain no spaces. */
+async function registeredWorktrees(repoRoot) {
+    const res = await git(repoRoot, ['worktree', 'list', '--porcelain']);
+    if (!res.ok)
+        return [];
+    const worktrees = [];
+    let current;
+    for (const line of res.stdout.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            if (current)
+                worktrees.push(current);
+            current = { path: line.slice('worktree '.length) };
+        }
+        else if (current && line.startsWith('branch ')) {
+            current.branch = line.slice('branch '.length);
+        }
+        else if (!line && current) {
+            worktrees.push(current);
+            current = undefined;
+        }
+    }
+    if (current)
+        worktrees.push(current);
+    return worktrees;
+}
+function worktreeInfo(path, branch, baseBranch) {
+    return { path, branch, baseBranch };
+}
+/** Git canonicalizes symlinked path prefixes (macOS `/var` → `/private/var`). */
+function canonicalPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/**
+ * Establish the task worktree idempotently. Besides the fresh
+ * `git worktree add -b` path, recover the two normal restart/deletion cases:
+ * reuse an already-registered task worktree, or reattach a surviving task
+ * branch after its directory/registration was removed. Existing non-empty
+ * unregistered paths are never deleted because they may hold recoverable
+ * uncommitted work.
+ */
+export async function createWorktree(repoRoot, runId, baseBranch) {
+    let base = baseBranch;
+    if (!base || base === 'HEAD') {
+        // Detached HEAD — pin the base to the current commit so the record and
+        // later diffs stay meaningful.
+        const head = await git(repoRoot, ['rev-parse', 'HEAD']);
+        if (!head.ok)
+            throw new Error(`git rev-parse HEAD failed: ${head.stderr.trim()}`);
+        base = head.stdout.trim();
+    }
+    const branch = branchFor(runId);
+    const absolutePath = join(canonicalPath(repoRoot), WORKTREES_DIR, runId);
+    const branchRef = `refs/heads/${branch}`;
+    // A missing directory can leave stale administrative metadata behind.
+    // Prune first so the checks below describe the filesystem as it exists now.
+    await git(repoRoot, ['worktree', 'prune']);
+    const canonicalTarget = canonicalPath(absolutePath);
+    let registered = await registeredWorktrees(repoRoot);
+    let atPath = registered.find((item) => canonicalPath(item.path) === canonicalTarget);
+    if (atPath) {
+        if (atPath.branch !== branchRef) {
+            throw new Error(`managed worktree path is registered to ${atPath.branch ?? 'a detached HEAD'}, expected ${branchRef}`);
+        }
+        return worktreeInfo(atPath.path, branch, base);
+    }
+    // If the directory survived but its administrative entry did not, let Git
+    // repair it. This is non-destructive; an unrepairable non-empty directory is
+    // preserved and reported instead of being recursively removed.
+    if (existsSync(absolutePath)) {
+        await git(repoRoot, ['worktree', 'repair', absolutePath]);
+        registered = await registeredWorktrees(repoRoot);
+        atPath = registered.find((item) => canonicalPath(item.path) === canonicalTarget);
+        if (atPath) {
+            if (atPath.branch !== branchRef) {
+                throw new Error(`managed worktree path is registered to ${atPath.branch ?? 'a detached HEAD'}, expected ${branchRef}`);
+            }
+            return worktreeInfo(atPath.path, branch, base);
+        }
+        const entries = await readdir(absolutePath).catch(() => ['unreadable']);
+        if (entries.length > 0) {
+            throw new Error(`managed worktree path already exists and could not be repaired: ${absolutePath}`);
+        }
+    }
+    const branchExists = await git(repoRoot, ['show-ref', '--verify', '--quiet', branchRef]);
+    if (branchExists.ok) {
+        // The task branch may still be checked out after its directory was moved.
+        // Reuse only a path whose basename is the full run id; a same-prefix UUID
+        // collision must fail rather than point two tasks at one worktree.
+        const byBranch = registered.find((item) => item.branch === branchRef);
+        if (byBranch) {
+            if (basename(byBranch.path) !== runId) {
+                throw new Error(`task branch ${branch} is already checked out at ${byBranch.path}`);
+            }
+            return worktreeInfo(byBranch.path, branch, base);
+        }
+        const attach = await git(repoRoot, ['worktree', 'add', absolutePath, branch]);
+        if (!attach.ok) {
+            throw new Error(`git worktree reattach failed: ${attach.stderr.trim() || attach.stdout.trim()}`);
+        }
+        return worktreeInfo(absolutePath, branch, base);
+    }
+    const create = await git(repoRoot, ['worktree', 'add', '-b', branch, absolutePath, base]);
+    if (!create.ok) {
+        throw new Error(`git worktree add failed: ${create.stderr.trim() || create.stdout.trim()}`);
+    }
+    return worktreeInfo(absolutePath, branch, base);
+}
+/**
+ * Best-effort on-disk size of a worktree directory in bytes, via POSIX
+ * `du -sk` (kibibytes → bytes). Returns `null` when `du` is unavailable —
+ * including all of Windows, where `du` is not a command — or on any error.
+ * Never throws and never blocks: worktree retention is count-based, so a null
+ * size only blanks the panel's size column, it does not affect reclamation.
+ */
+export function worktreeSizeBytes(path) {
+    return new Promise((resolve) => {
+        execFile('du', ['-sk', path], { encoding: 'utf8' }, (err, stdout) => {
+            if (err) {
+                resolve(null);
+                return;
+            }
+            const kib = Number.parseInt(stdout.trim().split(/\s+/)[0] ?? '', 10);
+            resolve(Number.isFinite(kib) ? kib * 1024 : null);
+        });
+    });
+}
+/** Remove a task worktree and its branch. Best effort — never throws. */
+export async function removeWorktree(repoRoot, worktreePath, branch) {
+    await git(repoRoot, ['worktree', 'remove', '--force', worktreePath]);
+    await rm(worktreePath, { recursive: true, force: true }).catch(() => undefined);
+    await git(repoRoot, ['worktree', 'prune']);
+    if (branch)
+        await git(repoRoot, ['branch', '-D', branch]);
+}
+/**
+ * Stage and commit everything in the worktree as a "cezar autosave" commit
+ * (janitor pattern) — the agent's progress is always recoverable from the
+ * `cez/<id8>` branch history. Quietly a no-op when nothing changed.
+ */
+export async function autosaveCommit(dir) {
+    const status = await git(dir, ['status', '--porcelain']);
+    if (!status.ok || !status.stdout.trim())
+        return false;
+    await git(dir, ['add', '-A']);
+    // Commit as the CURRENT git user, so the branch's commits (and any PR opened from it) are
+    // attributed to the real author and pass CLA / attribution checks. The old hardcoded
+    // `cezar <cezar@local>` identity made every autosave look like a non-GitHub user. Fall back to
+    // that identity ONLY when the machine has no git identity configured — otherwise `git commit`
+    // would fail and the autosave (the run's recovery point) would be lost.
+    const identityArgs = (await gitHasIdentity(dir))
+        ? []
+        : ['-c', 'user.name=cezar', '-c', 'user.email=cezar@local'];
+    const commit = await git(dir, [
+        ...identityArgs,
+        'commit',
+        '--no-verify',
+        '-m',
+        'cezar autosave',
+    ]);
+    return commit.ok;
+}
+/** Does this repo/worktree resolve a git author identity (name + email)? Ambient config wins so
+ *  autosave commits carry the user's own identity — see autosaveCommit. */
+async function gitHasIdentity(dir) {
+    const [name, email] = await Promise.all([
+        git(dir, ['config', 'user.name']),
+        git(dir, ['config', 'user.email']),
+    ]);
+    return name.ok && name.stdout.trim() !== '' && email.ok && email.stdout.trim() !== '';
+}
+/**
+ * "What did this task change": diff of the worktree (committed + uncommitted
+ * + untracked, via `add -N`) against the merge-base with its base branch —
+ * so the diff stays *this task's* changes even after the base moves on.
+ */
+export async function worktreeDiff(worktreePath, baseBranch, cap = DIFF_CAP) {
+    await git(worktreePath, ['add', '-N', '.']); // intent-to-add: untracked files show up
+    const mergeBase = await git(worktreePath, ['merge-base', baseBranch, 'HEAD']);
+    const base = mergeBase.ok && mergeBase.stdout.trim() ? mergeBase.stdout.trim() : baseBranch;
+    const res = await git(worktreePath, ['diff', base]);
+    if (!res.ok)
+        return `(diff failed: ${res.stderr.trim() || 'unknown git error'})`;
+    if (res.stdout.length > cap)
+        return `${res.stdout.slice(0, cap)}\n… (diff truncated)`;
+    return res.stdout;
+}
+/**
+ * `git diff --stat` version of `worktreeDiff` (spec 010 — the variant
+ * comparison columns). Same merge-base anchoring; returns '' on any failure.
+ */
+export async function worktreeDiffStat(worktreePath, baseBranch) {
+    await git(worktreePath, ['add', '-N', '.']); // intent-to-add: untracked files show up
+    const mergeBase = await git(worktreePath, ['merge-base', baseBranch, 'HEAD']);
+    const base = mergeBase.ok && mergeBase.stdout.trim() ? mergeBase.stdout.trim() : baseBranch;
+    const res = await git(worktreePath, ['diff', '--stat', base]);
+    return res.ok ? res.stdout.trim() : '';
+}
+/**
+ * Parse `git diff --shortstat` output — " 3 files changed, 10 insertions(+),
+ * 2 deletions(-)". Every part is optional: insertions-only and deletions-only
+ * diffs omit the other counter, and an empty diff prints nothing at all
+ * (→ all zeros). The wording is stable porcelain English — git does not
+ * localize `--shortstat` — so matching the words is safe.
+ */
+export function parseShortstat(s) {
+    const files = /(\d+) files? changed/.exec(s);
+    const adds = /(\d+) insertions?\(\+\)/.exec(s);
+    const dels = /(\d+) deletions?\(-\)/.exec(s);
+    return {
+        files: files ? Number(files[1]) : 0,
+        adds: adds ? Number(adds[1]) : 0,
+        dels: dels ? Number(dels[1]) : 0,
+    };
+}
+/**
+ * `git diff --shortstat` of the worktree vs its base (#389) — same
+ * merge-base anchoring and intent-to-add as `worktreeDiff`, parsed into
+ * numbers. Null on git failure (the caller notes it, never fails the run);
+ * an empty diff is a valid all-zero stat.
+ */
+export async function worktreeShortstat(worktreePath, baseBranch) {
+    await git(worktreePath, ['add', '-N', '.']); // intent-to-add: untracked files show up
+    const mergeBase = await git(worktreePath, ['merge-base', baseBranch, 'HEAD']);
+    const base = mergeBase.ok && mergeBase.stdout.trim() ? mergeBase.stdout.trim() : baseBranch;
+    const res = await git(worktreePath, ['diff', '--shortstat', base]);
+    return res.ok ? parseShortstat(res.stdout) : null;
+}
+/**
+ * Startup reconcile: `git worktree prune` + remove every directory under
+ * `.ai/cezar/worktrees/` whose run id is no longer in the store (and its
+ * branch). Returns the removed run ids for the boot log. Never throws.
+ */
+export async function pruneOrphans(repoRoot, validIds) {
+    await git(repoRoot, ['worktree', 'prune']);
+    let entries;
+    try {
+        entries = await readdir(join(repoRoot, WORKTREES_DIR), { withFileTypes: true });
+    }
+    catch {
+        return []; // no worktrees dir yet
+    }
+    const removed = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || validIds.has(entry.name))
+            continue;
+        await removeWorktree(repoRoot, worktreePathFor(repoRoot, entry.name), branchFor(entry.name));
+        removed.push(entry.name);
+    }
+    return removed;
+}
+//# sourceMappingURL=git-worktree.js.map

package/dist/git-worktree.js.map

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

package/dist/handoff.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-task handoff journal (spec 007): `.ai/cezar/runs/<runId>.handoff.md`,
+ * next to the run's NDJSON events and outside the task worktree — it survives
+ * worktree removal. Cez seeds the skeleton and appends heartbeats; the agent
+ * (told via CEZ_HANDOFF_FILE + the system-prompt fragment below) keeps the
+ * "Progress log" and "Resume notes" sections up to date. Everything here is
+ * best-effort: the handoff is a journal, never a reason to fail a run.
+ */
+export declare function handoffPath(dataDir: string, runId: string): string;
+export interface HandoffSeed {
+    id: string;
+    title: string;
+    workflow: string;
+    task: string;
+    branch?: string;
+    worktreePath?: string;
+}
+/** Create the handoff skeleton. Idempotent — an existing file (resume,
+ *  continuation) is never overwritten. Returns the file path. */
+export declare function seedHandoffFile(dataDir: string, run: HandoffSeed): string;
+/**
+ * Cez's own heartbeat (the janitor pattern): insert `- <ISO ts> — <note>`
+ * right under the `## Progress log` header (newest at the top), so the file
+ * stays current even when the agent forgets to write. Missing header →
+ * append at the end of the file; missing file → no-op.
+ */
+export declare function appendHandoffHeartbeat(dataDir: string, runId: string, note: string): void;
+/** Full handoff markdown, or '' when the file doesn't exist (yet). */
+export declare function readHandoff(dataDir: string, runId: string): string;
+/**
+ * First few non-empty lines under "## Progress log" (spec 010 — the variant
+ * comparison columns). Stops at the next `## ` header; '' when there's no
+ * Progress log section or it's empty.
+ */
+export declare function handoffProgressExcerpt(text: string, maxLines?: number): string;
+export declare function deleteHandoff(dataDir: string, runId: string): void;
+/**
+ * Is the global follow-up inbox on? (#471)
+ *
+ * Opt-in, off by default: agents kept hanging on stale, pre-saved follow-ups,
+ * which made skill behavior unpredictable. This is the single source of truth —
+ * `resolveCapabilities` reports it to the UI and `RunManager` enforces it on
+ * every run, so the HTTP route, the `cezar run` CLI and the inbox's own "▶ Run"
+ * cannot drift apart. The per-task handoff journal is a separate feature and is
+ * never gated by this.
+ *
+ * An exact `'1'` opts in — the house spelling (`AGENTS.md`: "opt-in behind a
+ * `CEZ_*` flag, off by default").
+ */
+export declare function followupsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Appended to every agent step's `--append-system-prompt` (spec 007). The
+ * matching handoff/task env vars are set on every agent process;
+ * CEZ_TODOS_FILE carries a usable path only when follow-up generation is
+ * enabled (#444, #471) — opted-out runs get it empty, never absent, so an
+ * inherited value from a parent cezar cannot shine through
+ * (`RunManager.agentEnv`).
+ */
+export declare const HANDOFF_ONLY_INSTRUCTIONS = "## Handoff (cezar)\n\nCEZ_HANDOFF_FILE (env) is the absolute path to this task's rolling handoff file. Treat it like a HANDOFF.md:\n1. At the start of work, read it \u2014 \"Resume notes\" left by a previous session is your starting context.\n2. After every meaningful milestone (passing tests, a commit, a PR, a scope decision), append one terse timestamped line under \"## Progress log\", newest at the top.\n3. Before finishing or pausing, update \"## Resume notes\" with what's done, what's next and any blockers. Leave it empty only when the task is truly complete.\n\nTask completion marker: when the task's goal is fully achieved and you have no question for the user, end your final message with a line containing exactly CEZ:DONE \u2014 cez then closes the session and marks the task finished. If you are waiting on the user (a question, a decision, missing input), just end your message normally; the session stays open for their reply. Never emit CEZ:DONE while anything is unfinished or unverified.\n\nStill-working marker: if you end a turn while still working on your OWN downstream work \u2014 a sub-agent you dispatched, or a long-running command you're monitoring \u2014 and are NOT waiting on the user for anything, end your final message with a line containing exactly CEZ:MONITORING. cez then shows the task as \"monitoring\" (still working) instead of asking for your attention. Use CEZ:MONITORING only for that in-progress case; use CEZ:DONE when the goal is done; end plainly (no marker) only when you are genuinely waiting on the user. Never combine CEZ:MONITORING with CEZ:DONE.";
+export declare const FOLLOWUP_INSTRUCTIONS = "## Follow-ups (cezar)\n\nCEZ_TODOS_FILE (env) is the absolute path to the user's follow-up inbox \u2014 a JSON array. When you finish the task and a concrete follow-up remains for the user or a next agent, read the file (treat a missing file as []), append ONE object and write the whole array back:\n{ \"ts\": \"<ISO 8601>\", \"taskId\": \"<value of CEZ_TASK_ID>\", \"summary\": \"<one sentence: what was done / what's next>\", \"action\": \"<imperative user action, optional>\", \"prUrl\": \"<optional>\", \"suggestedSkill\": \"<optional skill name for the follow-up>\", \"suggestedArgs\": \"<optional>\", \"suggestedPrompt\": \"<optional freeform prompt for the follow-up task>\", \"runnable\": <true when an agent can execute this follow-up, false when it is a note> }\nSet \"runnable\": false for anything a human must do or merely read \u2014 manual QA, \"remember to\u2026\", informational notes \u2014 and leave out suggestedSkill/suggestedPrompt for those; the inbox then offers \"Acknowledge\" instead of \"Run\". Set \"runnable\": true only when suggestedSkill or suggestedPrompt says what to actually execute.\nNever modify or remove existing entries \u2014 append only.";
+/** Default-on combined contract retained for old callers and runs. */
+export declare const HANDOFF_INSTRUCTIONS = "## Handoff (cezar)\n\nCEZ_HANDOFF_FILE (env) is the absolute path to this task's rolling handoff file. Treat it like a HANDOFF.md:\n1. At the start of work, read it \u2014 \"Resume notes\" left by a previous session is your starting context.\n2. After every meaningful milestone (passing tests, a commit, a PR, a scope decision), append one terse timestamped line under \"## Progress log\", newest at the top.\n3. Before finishing or pausing, update \"## Resume notes\" with what's done, what's next and any blockers. Leave it empty only when the task is truly complete.\n\nTask completion marker: when the task's goal is fully achieved and you have no question for the user, end your final message with a line containing exactly CEZ:DONE \u2014 cez then closes the session and marks the task finished. If you are waiting on the user (a question, a decision, missing input), just end your message normally; the session stays open for their reply. Never emit CEZ:DONE while anything is unfinished or unverified.\n\nStill-working marker: if you end a turn while still working on your OWN downstream work \u2014 a sub-agent you dispatched, or a long-running command you're monitoring \u2014 and are NOT waiting on the user for anything, end your final message with a line containing exactly CEZ:MONITORING. cez then shows the task as \"monitoring\" (still working) instead of asking for your attention. Use CEZ:MONITORING only for that in-progress case; use CEZ:DONE when the goal is done; end plainly (no marker) only when you are genuinely waiting on the user. Never combine CEZ:MONITORING with CEZ:DONE.\n\n## Follow-ups (cezar)\n\nCEZ_TODOS_FILE (env) is the absolute path to the user's follow-up inbox \u2014 a JSON array. When you finish the task and a concrete follow-up remains for the user or a next agent, read the file (treat a missing file as []), append ONE object and write the whole array back:\n{ \"ts\": \"<ISO 8601>\", \"taskId\": \"<value of CEZ_TASK_ID>\", \"summary\": \"<one sentence: what was done / what's next>\", \"action\": \"<imperative user action, optional>\", \"prUrl\": \"<optional>\", \"suggestedSkill\": \"<optional skill name for the follow-up>\", \"suggestedArgs\": \"<optional>\", \"suggestedPrompt\": \"<optional freeform prompt for the follow-up task>\", \"runnable\": <true when an agent can execute this follow-up, false when it is a note> }\nSet \"runnable\": false for anything a human must do or merely read \u2014 manual QA, \"remember to\u2026\", informational notes \u2014 and leave out suggestedSkill/suggestedPrompt for those; the inbox then offers \"Acknowledge\" instead of \"Run\". Set \"runnable\": true only when suggestedSkill or suggestedPrompt says what to actually execute.\nNever modify or remove existing entries \u2014 append only.";

package/dist/handoff.js

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Per-task handoff journal (spec 007): `.ai/cezar/runs/<runId>.handoff.md`,
+ * next to the run's NDJSON events and outside the task worktree — it survives
+ * worktree removal. Cez seeds the skeleton and appends heartbeats; the agent
+ * (told via CEZ_HANDOFF_FILE + the system-prompt fragment below) keeps the
+ * "Progress log" and "Resume notes" sections up to date. Everything here is
+ * best-effort: the handoff is a journal, never a reason to fail a run.
+ */
+export function handoffPath(dataDir, runId) {
+    return join(dataDir, 'runs', `${runId}.handoff.md`);
+}
+/** Create the handoff skeleton. Idempotent — an existing file (resume,
+ *  continuation) is never overwritten. Returns the file path. */
+export function seedHandoffFile(dataDir, run) {
+    const file = handoffPath(dataDir, run.id);
+    if (existsSync(file))
+        return file;
+    const header = `# Handoff — ${run.title}\n\n` +
+        `**Task id:** ${run.id}\n` +
+        `**Workflow:** ${run.workflow}\n` +
+        (run.branch ? `**Branch:** ${run.branch}\n` : '') +
+        (run.worktreePath ? `**Worktree:** ${run.worktreePath}\n` : '') +
+        `\n## Goal\n\n${run.task.trim()}\n\n` +
+        `## Progress log\n\n` +
+        `## Resume notes\n`;
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, header, 'utf8');
+    }
+    catch {
+        // best effort — a read-only data dir must not break the run
+    }
+    return file;
+}
+/**
+ * Cez's own heartbeat (the janitor pattern): insert `- <ISO ts> — <note>`
+ * right under the `## Progress log` header (newest at the top), so the file
+ * stays current even when the agent forgets to write. Missing header →
+ * append at the end of the file; missing file → no-op.
+ */
+export function appendHandoffHeartbeat(dataDir, runId, note) {
+    const file = handoffPath(dataDir, runId);
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return; // not seeded — nothing to heartbeat
+    }
+    const line = `- ${new Date().toISOString()} — ${note}\n`;
+    const marker = '## Progress log\n';
+    const idx = text.indexOf(marker);
+    const next = idx >= 0
+        ? `${text.slice(0, idx + marker.length)}\n${line}${text.slice(idx + marker.length).replace(/^\n+/, '')}`
+        : `${text}${text.endsWith('\n') || text === '' ? '' : '\n'}${line}`;
+    try {
+        writeFileSync(file, next, 'utf8');
+    }
+    catch {
+        // best effort
+    }
+}
+/** Full handoff markdown, or '' when the file doesn't exist (yet). */
+export function readHandoff(dataDir, runId) {
+    try {
+        return readFileSync(handoffPath(dataDir, runId), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * First few non-empty lines under "## Progress log" (spec 010 — the variant
+ * comparison columns). Stops at the next `## ` header; '' when there's no
+ * Progress log section or it's empty.
+ */
+export function handoffProgressExcerpt(text, maxLines = 3) {
+    const marker = '## Progress log';
+    const idx = text.indexOf(marker);
+    if (idx < 0)
+        return '';
+    const lines = [];
+    for (const line of text.slice(idx + marker.length).split('\n')) {
+        if (line.startsWith('## '))
+            break;
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        lines.push(trimmed);
+        if (lines.length >= maxLines)
+            break;
+    }
+    return lines.join('\n');
+}
+export function deleteHandoff(dataDir, runId) {
+    try {
+        rmSync(handoffPath(dataDir, runId), { force: true });
+    }
+    catch {
+        // best effort
+    }
+}
+/**
+ * Is the global follow-up inbox on? (#471)
+ *
+ * Opt-in, off by default: agents kept hanging on stale, pre-saved follow-ups,
+ * which made skill behavior unpredictable. This is the single source of truth —
+ * `resolveCapabilities` reports it to the UI and `RunManager` enforces it on
+ * every run, so the HTTP route, the `cezar run` CLI and the inbox's own "▶ Run"
+ * cannot drift apart. The per-task handoff journal is a separate feature and is
+ * never gated by this.
+ *
+ * An exact `'1'` opts in — the house spelling (`AGENTS.md`: "opt-in behind a
+ * `CEZ_*` flag, off by default").
+ */
+export function followupsEnabled(env = process.env) {
+    return env.CEZ_FOLLOWUPS === '1';
+}
+/**
+ * Appended to every agent step's `--append-system-prompt` (spec 007). The
+ * matching handoff/task env vars are set on every agent process;
+ * CEZ_TODOS_FILE carries a usable path only when follow-up generation is
+ * enabled (#444, #471) — opted-out runs get it empty, never absent, so an
+ * inherited value from a parent cezar cannot shine through
+ * (`RunManager.agentEnv`).
+ */
+export const HANDOFF_ONLY_INSTRUCTIONS = `## Handoff (cezar)
+
+CEZ_HANDOFF_FILE (env) is the absolute path to this task's rolling handoff file. Treat it like a HANDOFF.md:
+1. At the start of work, read it — "Resume notes" left by a previous session is your starting context.
+2. After every meaningful milestone (passing tests, a commit, a PR, a scope decision), append one terse timestamped line under "## Progress log", newest at the top.
+3. Before finishing or pausing, update "## Resume notes" with what's done, what's next and any blockers. Leave it empty only when the task is truly complete.
+
+Task completion marker: when the task's goal is fully achieved and you have no question for the user, end your final message with a line containing exactly CEZ:DONE — cez then closes the session and marks the task finished. If you are waiting on the user (a question, a decision, missing input), just end your message normally; the session stays open for their reply. Never emit CEZ:DONE while anything is unfinished or unverified.
+
+Still-working marker: if you end a turn while still working on your OWN downstream work — a sub-agent you dispatched, or a long-running command you're monitoring — and are NOT waiting on the user for anything, end your final message with a line containing exactly CEZ:MONITORING. cez then shows the task as "monitoring" (still working) instead of asking for your attention. Use CEZ:MONITORING only for that in-progress case; use CEZ:DONE when the goal is done; end plainly (no marker) only when you are genuinely waiting on the user. Never combine CEZ:MONITORING with CEZ:DONE.`;
+export const FOLLOWUP_INSTRUCTIONS = `## Follow-ups (cezar)
+
+CEZ_TODOS_FILE (env) is the absolute path to the user's follow-up inbox — a JSON array. When you finish the task and a concrete follow-up remains for the user or a next agent, read the file (treat a missing file as []), append ONE object and write the whole array back:
+{ "ts": "<ISO 8601>", "taskId": "<value of CEZ_TASK_ID>", "summary": "<one sentence: what was done / what's next>", "action": "<imperative user action, optional>", "prUrl": "<optional>", "suggestedSkill": "<optional skill name for the follow-up>", "suggestedArgs": "<optional>", "suggestedPrompt": "<optional freeform prompt for the follow-up task>", "runnable": <true when an agent can execute this follow-up, false when it is a note> }
+Set "runnable": false for anything a human must do or merely read — manual QA, "remember to…", informational notes — and leave out suggestedSkill/suggestedPrompt for those; the inbox then offers "Acknowledge" instead of "Run". Set "runnable": true only when suggestedSkill or suggestedPrompt says what to actually execute.
+Never modify or remove existing entries — append only.`;
+/** Default-on combined contract retained for old callers and runs. */
+export const HANDOFF_INSTRUCTIONS = `${HANDOFF_ONLY_INSTRUCTIONS}\n\n${FOLLOWUP_INSTRUCTIONS}`;
+//# sourceMappingURL=handoff.js.map

package/dist/handoff.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};