rl-workspaces 0.0.0-stage → 0.6.0

package/dist/store.js

@@ -0,0 +1,379 @@
+import { automationContext } from "./session-workflows.js";
+import { adapters } from "./agent-registry.js";
+import { validateTracking } from "./activity.js";
+import { lastAccessed } from "./access.js";
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { atomicWrite, canonical, git, gitRaw, inside, isSymlink, locked, message, now, object, readJson, sessionId, shellQuote, timestamp, writeJson, } from "./common.js";
+import { NOTE_TEMPLATES } from "./templates.js";
+import { handoffText, validateTask } from "./task-state.js";
+const HOOK_TIMEOUT_SECONDS = 10;
+const CODEX_END_TIMEOUT_SECONDS = 3;
+export function branchStatus(repo, data) {
+    const result = {
+        availability: data.status,
+        branch: null,
+        expectedBranch: data.branch,
+        head: null,
+        upstream: null,
+        ahead: null,
+        behind: null,
+        staged: 0,
+        unstaged: 0,
+        untracked: 0,
+        conflicts: 0,
+        dirty: null,
+        branchChanged: false,
+    };
+    if (data.status === "deleted")
+        return result;
+    if (!fs.existsSync(data.worktree))
+        return { ...result, availability: "missing" };
+    try {
+        const root = canonical(data.worktree);
+        if (canonical(git(root, "rev-parse", "--show-toplevel")) !== root ||
+            canonical(git(root, "rev-parse", "--path-format=absolute", "--git-common-dir")) !==
+                canonical(git(repo, "rev-parse", "--path-format=absolute", "--git-common-dir")))
+            throw new Error("Worktree path no longer belongs to this repository");
+        const entries = gitRaw(root, "--no-optional-locks", "status", "--porcelain=v2", "--branch", "--untracked-files=normal", "-z").split("\0");
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry.startsWith("# branch.head "))
+                result.branch = entry.slice(14);
+            else if (entry.startsWith("# branch.oid "))
+                result.head = entry.slice(13);
+            else if (entry.startsWith("# branch.upstream "))
+                result.upstream = entry.slice(18);
+            else if (entry.startsWith("# branch.ab ")) {
+                const [ahead, behind] = entry.slice(12).split(" ");
+                result.ahead = Number(ahead.slice(1));
+                result.behind = Number(behind.slice(1));
+            }
+            else if (/^[12u] /.test(entry)) {
+                const xy = entry.split(" ")[1];
+                result.staged += Number(xy[0] !== ".");
+                result.unstaged += Number(xy[1] !== ".");
+                result.conflicts += Number(entry[0] === "u");
+                if (entry[0] === "2")
+                    i++;
+            }
+            else if (entry.startsWith("? "))
+                result.untracked++;
+        }
+        result.dirty = !!(result.staged ||
+            result.unstaged ||
+            result.untracked ||
+            result.conflicts);
+        result.branchChanged = result.branch !== data.branch;
+        result.availability = "ok";
+    }
+    catch (error) {
+        result.availability = "error";
+        result.error = message(error);
+    }
+    return result;
+}
+export class Store {
+    repo;
+    stateDir;
+    root;
+    constructor(repo, stateDir) {
+        this.repo = canonical(repo);
+        this.stateDir = canonical(stateDir);
+        this.root = path.join(this.stateDir, createHash("sha256").update(this.repo).digest("hex").slice(0, 24));
+    }
+    archiveWorktrees(paths) {
+        for (const [file, data] of this.records()) {
+            if (data.status !== "active" || !paths.includes(data.worktree))
+                continue;
+            data.status = "deleted";
+            data.deletedAt = now();
+            this.save(file, data);
+        }
+    }
+    readDocument(file, kind) {
+        return fs.readFileSync(path.join(path.dirname(file), kind + ".md"), "utf8");
+    }
+    updateDocument(file, data, kind, action, text) {
+        const content = action === "append"
+            ? this.readDocument(file, kind).trimEnd() +
+                `\n\n### Update ${now()}\n\n` +
+                text.trimEnd() +
+                "\n"
+            : text;
+        atomicWrite(path.join(path.dirname(file), kind + ".md"), content);
+        this.save(file, data);
+    }
+    locked(action) {
+        return locked(this.root, ".typescript.lock", action);
+    }
+    records() {
+        if (!fs.existsSync(this.root))
+            return [];
+        const records = [];
+        for (const key of fs.readdirSync(this.root).sort()) {
+            const file = path.join(this.root, key, "instance.json");
+            if (!fs.existsSync(file))
+                continue;
+            const data = readJson(file);
+            try {
+                if (data.schemaVersion !== 1 ||
+                    data.key !== key ||
+                    data.repository !== this.repo ||
+                    !["active", "deleted"].includes(String(data.status)) ||
+                    typeof data.id !== "string" ||
+                    !data.id ||
+                    typeof data.branch !== "string" ||
+                    !data.branch ||
+                    typeof data.worktree !== "string" ||
+                    !path.isAbsolute(data.worktree) ||
+                    !(data.pr === null ||
+                        (object(data.pr) && typeof data.pr.url === "string")) ||
+                    !object(data.sessions) ||
+                    (data.extendedHooks !== undefined &&
+                        typeof data.extendedHooks !== "boolean"))
+                    throw new Error();
+                validateTracking(data);
+                if (data.task !== undefined)
+                    validateTask(data.task);
+                for (const agent of ["codex", "claude"]) {
+                    const sessions = data.sessions[agent];
+                    if (!Array.isArray(sessions))
+                        throw new Error();
+                    const seen = new Set();
+                    for (const item of sessions) {
+                        if (!object(item) ||
+                            sessionId(item.id) !== item.id ||
+                            seen.has(item.id) ||
+                            typeof item.createdAt !== "string" ||
+                            typeof item.lastUsedAt !== "string")
+                            throw new Error();
+                        seen.add(item.id);
+                        timestamp(item.createdAt);
+                        timestamp(item.lastUsedAt);
+                    }
+                }
+            }
+            catch {
+                throw new Error(`Invalid instance metadata: ${file}`);
+            }
+            records.push([file, data]);
+        }
+        return records;
+    }
+    worktree(cwd) {
+        const root = canonical(git(cwd, "rev-parse", "--show-toplevel"));
+        if (canonical(git(root, "rev-parse", "--path-format=absolute", "--git-common-dir")) !==
+            canonical(git(this.repo, "rev-parse", "--path-format=absolute", "--git-common-dir")))
+            throw new Error("Current directory does not belong to the configured RL repository");
+        const branch = git(root, "branch", "--show-current");
+        if (!branch)
+            throw new Error("RL instances require a checked-out branch");
+        return [root, branch];
+    }
+    current(cwd = process.cwd()) {
+        return this.instanceForWorktree(...this.worktree(cwd));
+    }
+    // Call only with a worktree validated by worktree().
+    instanceForWorktree(root, branch) {
+        for (const [file, data] of this.records())
+            if (data.status === "active" && data.worktree === root) {
+                if (data.branch !== branch)
+                    throw new Error(`Instance owns branch ${data.branch}; current branch is ${branch}`);
+                return [file, data];
+            }
+        throw new Error("No RL instance for this worktree. Run 'rl adopt' first");
+    }
+    save(file, data) {
+        data.updatedAt = now();
+        writeJson(file, data);
+    }
+    touch(file, data, stamp = now()) {
+        const previous = lastAccessed(data);
+        data.lastAccessedAt =
+            previous && timestamp(previous) > timestamp(stamp) ? previous : stamp;
+        this.save(file, data);
+    }
+    async adopt(cwd, baseBranch, extendedHooks) {
+        const [root, branch] = this.worktree(cwd);
+        if (this.stateDir === root || inside(this.stateDir, root))
+            throw new Error("RL_STATE_DIR must be outside the worktree so state survives deletion");
+        return this.locked(() => {
+            for (const [file, data] of this.records())
+                if (data.status === "active" && data.worktree === root) {
+                    if (data.branch !== branch)
+                        throw new Error(`This instance already owns branch ${data.branch}`);
+                    if (extendedHooks !== undefined)
+                        data.extendedHooks = extendedHooks;
+                    installHooks(this, file, data);
+                    this.touch(file, data);
+                    return [file, data];
+                }
+            const key = randomUUID(), stamp = now(), file = path.join(this.root, key, "instance.json");
+            const data = {
+                schemaVersion: 1,
+                key,
+                id: branch,
+                repository: this.repo,
+                branch,
+                worktree: root,
+                status: "active",
+                createdAt: stamp,
+                lastAccessedAt: stamp,
+                updatedAt: stamp,
+                sessions: { codex: [], claude: [] },
+                pr: null,
+            };
+            if (extendedHooks !== undefined)
+                data.extendedHooks = extendedHooks;
+            if (baseBranch)
+                data.baseBranch = baseBranch;
+            // Discovery also covers worktrees without instance records. Carry their
+            // snapshot into the newly adopted instance without another network lookup.
+            try {
+                const cache = readJson(path.join(this.root, "pr-cache.json"));
+                const entries = cache.branches;
+                const entry = object(entries) ? entries[branch] : undefined;
+                const pr = object(entry) ? entry.pr : undefined;
+                if (object(pr) &&
+                    pr.headRefName === branch &&
+                    typeof pr.url === "string")
+                    data.pr = pr;
+            }
+            catch {
+                /* Missing/disposable cache does not prevent adoption. */
+            }
+            writeJson(file, data);
+            for (const [name, template] of Object.entries(NOTE_TEMPLATES))
+                atomicWrite(path.join(path.dirname(file), name), template);
+            installHooks(this, file, data);
+            return [file, data];
+        });
+    }
+    assertSessionOwner(file, agent, id) {
+        for (const [otherFile, other] of this.records())
+            if (otherFile !== file &&
+                (other.sessions[agent].some((s) => s.id === id) ||
+                    other.activity?.[agent]?.some((s) => s.sessionId === id)))
+                throw new Error(`Session ${id} already belongs to RL instance ${other.id}`);
+    }
+    recordSession(file, data, agent, id, stamp = now()) {
+        this.associateSession(file, data, agent, id, stamp);
+        this.touch(file, data, stamp);
+    }
+    // Mutate the supplied record; callers persist session and activity together.
+    associateSession(file, data, agent, id, stamp = now()) {
+        const sid = sessionId(id);
+        this.assertSessionOwner(file, agent, sid);
+        const item = data.sessions[agent].find((s) => s.id === sid);
+        if (!item)
+            data.sessions[agent].push({
+                id: sid,
+                createdAt: stamp,
+                lastUsedAt: stamp,
+            });
+        else if (timestamp(stamp) > timestamp(item.lastUsedAt))
+            item.lastUsedAt = stamp;
+    }
+}
+export function hookCommand(store, data, agent) {
+    return ([
+        "rl",
+        "__hook",
+        "--repo",
+        store.repo,
+        "--state-dir",
+        store.stateDir,
+        "hook",
+        data.key,
+        agent,
+    ]
+        .map(shellQuote)
+        .join(" ") + " # rl-session-hook");
+}
+function installHooks(store, file, data) {
+    const updates = [];
+    const commands = {};
+    for (const adapter of Object.values(adapters)) {
+        const agent = adapter.name, relative = adapter.configPath;
+        const target = path.join(data.worktree, relative);
+        if (isSymlink(target) || isSymlink(path.dirname(target)))
+            throw new Error(`Refusing to install workspace hooks through a symlink: ${target}`);
+        const config = fs.existsSync(target) ? readJson(target) : {};
+        const hooks = (config.hooks ??= {});
+        if (!object(hooks))
+            throw new Error(`Invalid hooks object in ${target}`);
+        commands[agent] = hookCommand(store, data, agent);
+        for (const event of Object.keys({
+            ...adapter.events,
+            ...(data.extendedHooks ? adapter.extraEvents : {}),
+        })) {
+            const groups = hooks[event] ?? [];
+            if (!Array.isArray(groups))
+                throw new Error(`Invalid ${event} hooks in ${target}`);
+            const kept = [];
+            for (const group of groups) {
+                if (!object(group) || !Array.isArray(group.hooks))
+                    throw new Error(`Invalid hook group in ${target}`);
+                const handlers = group.hooks.filter((h) => !(object(h) &&
+                    typeof h.command === "string" &&
+                    (h.command === data.hookCommands?.[agent] ||
+                        h.command.endsWith(" # rl-session-hook"))));
+                if (handlers.length)
+                    kept.push({ ...group, hooks: handlers });
+            }
+            kept.push({
+                hooks: [
+                    {
+                        type: "command",
+                        command: commands[agent],
+                        timeout: event === "Interrupt" ||
+                            (agent === "codex" && event === "SessionEnd")
+                            ? CODEX_END_TIMEOUT_SECONDS
+                            : HOOK_TIMEOUT_SECONDS,
+                    },
+                ],
+            });
+            hooks[event] = kept;
+        }
+        updates.push([target, config]);
+    }
+    for (const [target, config] of updates)
+        if (!fs.existsSync(target) ||
+            JSON.stringify(readJson(target)) !== JSON.stringify(config))
+            writeJson(target, config);
+    const exclude = path.resolve(data.worktree, git(data.worktree, "rev-parse", "--git-path", "info/exclude"));
+    const text = fs.existsSync(exclude) ? fs.readFileSync(exclude, "utf8") : "";
+    const missing = ["/.codex/hooks.json", "/.claude/settings.local.json"].filter((entry) => !text.split(/\r?\n/).includes(entry));
+    if (missing.length)
+        atomicWrite(exclude, text +
+            (text && !text.endsWith("\n") ? "\n" : "") +
+            missing.join("\n") +
+            "\n");
+    if (JSON.stringify(data.hookCommands) !== JSON.stringify(commands)) {
+        data.hookCommands = commands;
+        store.save(file, data);
+    }
+}
+export function contextText(file, data) {
+    const sections = [
+        `RL feature workspace: ${data.id}\nBranch: ${data.branch}`,
+        "The following RL-owned documents are shared living feature documentation, not just conversation memory. Read them before starting work, and read the full files when excerpts are truncated. At meaningful milestones and before finishing your task, document what changed, what remains, implementation details (file/symbol references, flows, APIs, data structures), decisions and rationale, checks actually run, and blockers. Keep completed and planned work distinct; do not mark unverified work as tested or done. Respect your assigned scope and permissions; read-only agents should return proposed documentation updates to their parent. Use 'rl context append <file>' for durable domain or design notes and 'rl progress append <file>' for milestone/handoff updates ('-' reads stdin). Append is locked so concurrent agents do not overwrite one another. Use 'rl context set <file>' or 'rl progress set <file>' only for a deliberate replacement after reading the latest document and coordinating with other writers. Re-read the documents before planning subsequent work.",
+    ];
+    sections.push("When the user asks to pause or save this task for later, save a task handoff with rl_task_pause through MCP, or 'rl pause --summary <text> --changes <text> --validation <text> --next <text> [--blockers <text>]'. Include the current session UUID (Codex shell commands can infer it), concrete changes, checks actually run and their results, remaining work, and blockers. Use 'Not run' for unperformed checks. A pause saves task state; it does not terminate the agent. The user can return with 'rl continue'.");
+    const automation = automationContext(data.worktree);
+    if (automation)
+        sections.push(automation);
+    const latest = data.task?.handoffs.at(-1);
+    if (latest)
+        sections.push(`RL task state: ${data.task.state}\n\n${handoffText(latest)}`);
+    for (const name of ["context.md", "progress.md"]) {
+        const source = path.join(path.dirname(file), name), text = fs.readFileSync(source, "utf8");
+        sections.push(`${name} (${source}):\n${text.slice(0, 12000)}`);
+        if (text.length > 12000)
+            sections.push("[Excerpt truncated; read the file for the full context.]");
+    }
+    sections.push("Cached GitHub PR state:\n" + JSON.stringify(data.pr));
+    return sections.join("\n\n");
+}

package/dist/summary.js

@@ -0,0 +1,164 @@
+import { pullRequestBase } from "./base.js";
+import fs from "node:fs";
+import path from "node:path";
+import { args, arity, atomicWrite, canonical, expandHome, git, gitRaw, isSymlink, now, required, } from "./common.js";
+import { branchStatus, Store } from "./store.js";
+import { NOTE_TEMPLATES } from "./templates.js";
+const longest = (text) => Math.max(0, ...Array.from(text.matchAll(/`+/g), (match) => match[0].length));
+function fence(text) {
+    const delimiter = "`".repeat(Math.max(3, longest(text) + 1));
+    return `${delimiter}text\n${text.trimEnd()}\n${delimiter}`;
+}
+function inline(text) {
+    text = text.replaceAll("\n", "\\n").replaceAll("\r", "\\r");
+    const delimiter = "`".repeat(longest(text) + 1);
+    return `${delimiter} ${text} ${delimiter}`;
+}
+function quote(text) {
+    return text.trimEnd()
+        ? text
+            .trimEnd()
+            .split(/\r?\n/)
+            .map((line) => (line ? "> " + line : ">"))
+            .join("\n")
+        : "> No notes recorded.";
+}
+function resolveBase(root, requested, explicit) {
+    const candidates = [requested];
+    if (!requested.startsWith("origin/"))
+        candidates.push("origin/" + requested);
+    else if (!explicit)
+        candidates.push(requested.slice(7));
+    for (const candidate of candidates) {
+        try {
+            return [
+                candidate,
+                git(root, "rev-parse", "--verify", "--end-of-options", candidate + "^{commit}"),
+            ];
+        }
+        catch {
+            /* Try local/remote fallback. */
+        }
+    }
+    if (explicit)
+        throw new Error(`Comparison base does not exist: ${requested}`);
+    return [null, null];
+}
+function render(store, data, context, progress, defaultBase, requested) {
+    const root = data.worktree, status = branchStatus(store.repo, data);
+    if (status.availability !== "ok")
+        throw new Error(status.error || "Worktree is unavailable");
+    if (status.branchChanged)
+        throw new Error("The checked-out branch changed while preparing the summary; retry on the instance branch");
+    const head = git(root, "rev-parse", "--verify", "HEAD^{commit}");
+    const prBase = requested ? null : pullRequestBase(store.repo, data.pr);
+    const comparison = requested ||
+        prBase?.target ||
+        (typeof data.baseBranch === "string" ? data.baseBranch : defaultBase);
+    if (prBase && !prBase.resolved)
+        throw new Error(`PR target branch is unavailable locally: ${prBase.target}. Fetch its ref or refresh the snapshot with 'rl pr sync'.`);
+    const [base, baseOid] = prBase?.resolved
+        ? [prBase.resolved.ref, prBase.resolved.oid]
+        : resolveBase(root, comparison, !!requested);
+    const parts = [
+        "# RL worktree summary",
+        `Generated: ${now()}`,
+        `- Instance: ${inline(data.id)}\n- Repository: ${inline(store.repo)}\n- Worktree: ${inline(root)}\n- Branch: ${inline(data.branch)}\n- HEAD: ${inline(head)}`,
+        "This report combines saved documentation with local Git evidence. Recorded progress is authored by you or your agents; commits and file changes do not establish completion or successful validation. No agent was called and no remote state was fetched. Git data is sampled while the command runs.",
+        "## Recorded implementation progress",
+        quote(progress),
+        "## Feature and domain context",
+        quote(context),
+        "## Committed work",
+    ];
+    if (baseOid && base) {
+        let mergeBase;
+        try {
+            mergeBase = git(root, "merge-base", baseOid, head);
+        }
+        catch {
+            throw new Error(`No common ancestor between HEAD and ${base}; choose another --base`);
+        }
+        parts.push(`Comparison reference: ${inline(base)} (${inline(baseOid)}). Changes are measured from its merge-base with HEAD: ${inline(mergeBase)}.`);
+        const commits = git(root, "log", "--no-decorate", "--format=%h %s", `${mergeBase}..${head}`, "--");
+        parts.push("### Commits", commits ? fence(commits) : "No commits since the comparison merge-base.");
+        const changes = git(root, "diff", "--no-ext-diff", "--no-textconv", "--stat", mergeBase, head, "--");
+        parts.push("### Committed file changes", changes ? fence(changes) : "No net committed file changes.");
+    }
+    else
+        parts.push(`The configured comparison base ${inline(comparison)} could not be resolved. Committed work was omitted; run \`rl summary --base <branch-or-commit>\` to include it.`);
+    parts.push("## Uncommitted work", `Git status entries: ${status.staged} staged, ${status.unstaged} unstaged, ${status.untracked} untracked, ${status.conflicts} conflicts. An untracked directory counts as one status entry.`);
+    for (const [title, flags] of [
+        ["Staged changes", ["--cached"]],
+        ["Unstaged changes", []],
+    ]) {
+        const changes = git(root, "diff", "--no-ext-diff", "--no-textconv", ...flags, "--stat", "--");
+        parts.push("### " + title, changes ? fence(changes) : "None.");
+    }
+    const files = gitRaw(root, "ls-files", "--others", "--exclude-standard", "-z")
+        .split("\0")
+        .filter(Boolean);
+    parts.push("### Untracked files", files.length
+        ? fence(files.map((name) => JSON.stringify(name)).join("\n"))
+        : "None.", "## Upstream status");
+    parts.push(status.upstream
+        ? `Upstream: ${inline(status.upstream)}. ` +
+            (status.ahead !== null
+                ? `Ahead ${status.ahead}, behind ${status.behind} using locally cached refs.`
+                : "Ahead/behind counts are unavailable.")
+        : "No upstream is configured for this branch.");
+    parts.push("## Pull request (cached)", data.pr
+        ? fence(JSON.stringify(data.pr, null, 2))
+        : "No PR snapshot saved. Use `rl pr sync` to associate or refresh one.");
+    return parts.join("\n\n") + "\n";
+}
+export async function main(argv) {
+    const { values, positionals } = args(argv, ["repo", "state-dir", "default-base", "output", "base"], ["stdout", "force"], { output: "o" });
+    arity(positionals, 0);
+    if (values.force && !values.output)
+        throw new Error("--force is only needed with --output");
+    if (values.stdout && values.output)
+        throw new Error("Choose --stdout or --output");
+    const store = new Store(required(values, "repo"), required(values, "state-dir"));
+    const { file, data, context, progress } = await store.locked(() => {
+        const [file, data] = store.current();
+        const note = (name) => {
+            const text = fs.readFileSync(path.join(path.dirname(file), name), "utf8");
+            return text === NOTE_TEMPLATES[name] ? "" : text;
+        };
+        return {
+            file,
+            data,
+            context: note("context.md"),
+            progress: note("progress.md"),
+        };
+    });
+    const report = render(store, data, context, progress, required(values, "default-base"), typeof values.base === "string" ? values.base : undefined);
+    if (values.stdout) {
+        process.stdout.write(report);
+        return 0;
+    }
+    const target = values.output
+        ? path.resolve(expandHome(String(values.output)))
+        : path.join(path.dirname(file), "summary.md");
+    if (path.extname(target).toLowerCase() !== ".md")
+        throw new Error("Summary output must have a .md extension");
+    if (isSymlink(target))
+        throw new Error(`Refusing to overwrite a symlink: ${target}`);
+    if (["context.md", "progress.md"].some((name) => canonical(target) === canonical(path.join(path.dirname(file), name))))
+        throw new Error("Summary output cannot replace the instance's source documentation");
+    if (values.output && !values.force) {
+        try {
+            fs.writeFileSync(target, report, { flag: "wx" });
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                throw new Error(`Output already exists: ${target}. Use --force to replace it`);
+            throw error;
+        }
+    }
+    else
+        atomicWrite(target, report);
+    console.log(target);
+    return 0;
+}

package/dist/task-state.js

@@ -0,0 +1,65 @@
+import { object, sessionId, timestamp } from "./common.js";
+export const MAX_HANDOFF_TEXT = 16000;
+export const HANDOFF_FIELDS = [
+    "summary",
+    "changes",
+    "validation",
+    "next",
+    "blockers",
+];
+export function handoffNotes(value) {
+    if (!object(value))
+        throw new Error("Handoff must be an object");
+    const notes = {};
+    for (const field of HANDOFF_FIELDS) {
+        const text = value[field] === undefined
+            ? field === "blockers"
+                ? ""
+                : undefined
+            : value[field];
+        if (typeof text !== "string" ||
+            (field !== "blockers" && !text.trim()) ||
+            text.includes("\0"))
+            throw new Error(`Handoff ${field} must be non-empty text (use 'Not run' for unperformed validation)`);
+        notes[field] = text.trim();
+    }
+    if (Object.values(notes).join("\n").length > MAX_HANDOFF_TEXT)
+        throw new Error(`Handoff text must be at most ${MAX_HANDOFF_TEXT} characters`);
+    return notes;
+}
+export function validateTask(value) {
+    if (!object(value) ||
+        !["paused", "active"].includes(String(value.state)) ||
+        !Array.isArray(value.handoffs) ||
+        !value.handoffs.length)
+        throw new Error("Invalid task handoff state");
+    const ids = new Set();
+    for (const item of value.handoffs) {
+        if (!object(item) ||
+            !["codex", "claude"].includes(String(item.agent)) ||
+            sessionId(item.id) !== item.id ||
+            sessionId(item.sessionId) !== item.sessionId ||
+            ids.has(item.id) ||
+            typeof item.savedAt !== "string")
+            throw new Error("Invalid task handoff");
+        ids.add(item.id);
+        timestamp(item.savedAt);
+        handoffNotes(item);
+    }
+    if (value.continuedAt !== undefined) {
+        if (typeof value.continuedAt !== "string")
+            throw new Error("Invalid continuation time");
+        timestamp(value.continuedAt);
+    }
+}
+export function handoffText(handoff) {
+    return [
+        `Task handoff saved ${handoff.savedAt}`,
+        `Session: ${handoff.agent} ${handoff.sessionId}`,
+        `Summary:\n${handoff.summary}`,
+        `Changes:\n${handoff.changes}`,
+        `Reported validation:\n${handoff.validation}`,
+        `Next steps:\n${handoff.next}`,
+        `Blockers:\n${handoff.blockers || "None reported"}`,
+    ].join("\n\n");
+}