rl-workspaces 0.0.0-stage → 0.5.0

package/dist/common.js

@@ -0,0 +1,262 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { spawnSync, spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import lockfile from "proper-lockfile";
+import { readJsonObject } from "./json.js";
+export const now = () => new Date().toISOString();
+export const message = (error) => error instanceof Error ? error.message : String(error);
+export const json = (data) => console.log(JSON.stringify(data, null, 2));
+export function canonical(value) {
+    const absolute = path.resolve(value);
+    try {
+        return fs.realpathSync(absolute);
+    }
+    catch (error) {
+        if (!["ENOENT", "ENOTDIR"].includes(error.code ?? ""))
+            throw error;
+        const parent = path.dirname(absolute);
+        return parent === absolute
+            ? absolute
+            : path.join(canonical(parent), path.basename(absolute));
+    }
+}
+export const expandHome = (value) => value === "~"
+    ? os.homedir()
+    : value.startsWith("~/")
+        ? path.join(os.homedir(), value.slice(2))
+        : value;
+export function inside(child, parent) {
+    const relative = path.relative(parent, child);
+    return (!!relative &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+export function gitEnv() {
+    const env = { ...process.env };
+    for (const key of [
+        "GIT_DIR",
+        "GIT_WORK_TREE",
+        "GIT_COMMON_DIR",
+        "GIT_INDEX_FILE",
+    ])
+        delete env[key];
+    return env;
+}
+export function run(argv, cwd, raw = false) {
+    const result = spawnSync(argv[0], argv.slice(1), {
+        cwd,
+        encoding: "utf8",
+        env: argv[0] === "git" ? gitEnv() : process.env,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(result.stderr.trim() || `Command failed: ${argv.join(" ")}`);
+    return raw ? result.stdout : result.stdout.trim();
+}
+export const git = (cwd, ...args) => run(["git", "-C", cwd, ...args], cwd);
+export const gitRaw = (cwd, ...args) => run(["git", "-C", cwd, ...args], cwd, true);
+export async function execute(argv, cwd, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(argv[0], argv.slice(1), {
+            cwd,
+            timeout: options.timeoutMs,
+            env: options.env ?? (argv[0] === "git" ? gitEnv() : process.env),
+            detached: options.processGroup,
+            stdio: options.interactive
+                ? "inherit"
+                : ["pipe", "pipe", options.terminalError ? "inherit" : "pipe"],
+        });
+        let stdout = "", stderr = "";
+        let outputBytes = 0;
+        let overflow = false;
+        let forceKill;
+        const kill = (signal) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            try {
+                if (options.processGroup && child.pid)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === "EPERM" && options.processGroup)
+                    child.kill(signal);
+                else if (code !== "ESRCH")
+                    throw error;
+            }
+        };
+        const abort = () => {
+            kill("SIGTERM");
+            forceKill ??= setTimeout(() => kill("SIGKILL"), 1000);
+            forceKill.unref();
+        };
+        const append = (chunk, target) => {
+            outputBytes += chunk.length;
+            if (options.maxOutputBytes && outputBytes > options.maxOutputBytes) {
+                overflow = true;
+                abort();
+            }
+            else if (target === "stdout")
+                stdout += chunk;
+            else
+                stderr += chunk;
+        };
+        child.stdout?.on("data", (chunk) => {
+            append(chunk, "stdout");
+        });
+        child.stderr?.on("data", (chunk) => {
+            append(chunk, "stderr");
+        });
+        child.stdin?.on("error", () => { });
+        child.stdin?.end(options.input);
+        const interrupt = () => child.kill("SIGINT");
+        const terminate = () => child.kill("SIGTERM");
+        process.on("SIGINT", interrupt);
+        process.on("SIGTERM", terminate);
+        const cleanup = () => {
+            if (forceKill)
+                clearTimeout(forceKill);
+            options.signal?.removeEventListener("abort", abort);
+            process.off("SIGINT", interrupt);
+            process.off("SIGTERM", terminate);
+        };
+        child.on("error", (error) => {
+            cleanup();
+            reject(error);
+        });
+        child.on("close", (code, signal) => {
+            cleanup();
+            if (overflow) {
+                reject(new Error("Command output exceeded the configured size limit"));
+                return;
+            }
+            resolve({
+                code: code ?? 128 + (os.constants.signals[signal] ?? 1),
+                stdout,
+                stderr,
+            });
+        });
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+    });
+}
+export function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function readJson(file) {
+    return readJsonObject(file);
+}
+export function atomicWrite(file, text) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = path.join(path.dirname(file), `.rl-${randomUUID()}`);
+    try {
+        const fd = fs.openSync(temporary, "wx", 0o600);
+        try {
+            fs.writeFileSync(fd, text);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}
+export const writeJson = (file, data) => atomicWrite(file, JSON.stringify(data, null, 2) + "\n");
+export async function locked(directory, name, action) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const release = await lockfile.lock(directory, {
+        realpath: false,
+        lockfilePath: path.join(directory, name),
+        stale: 120000,
+        retries: { retries: 300, factor: 1, minTimeout: 25, maxTimeout: 100 },
+    });
+    try {
+        return await action();
+    }
+    finally {
+        await release();
+    }
+}
+export function shellQuote(value) {
+    return /^[\w@%+=:,./-]+$/.test(value)
+        ? value
+        : "'" + value.replaceAll("'", "'\"'\"'") + "'";
+}
+export function sessionId(value) {
+    if (typeof value !== "string" ||
+        !/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(value))
+        throw new Error("Expected the agent's full session UUID, not a name or prefix");
+    return value.toLowerCase();
+}
+// Normalize timezone offsets while retaining Python's microsecond timestamp precision.
+export function timestamp(value) {
+    if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(value) ||
+        !Number.isFinite(Date.parse(value)))
+        throw new Error("Invalid timestamp");
+    const fraction = /\.(\d+)/.exec(value)?.[1] ?? "";
+    return (BigInt(Date.parse(value)) * 1000000n +
+        BigInt(fraction.slice(3, 9).padEnd(6, "0")));
+}
+export function args(argv, strings, booleans = [], short = {}) {
+    const options = {};
+    for (const name of strings)
+        options[name] = {
+            type: "string",
+            ...(short[name] ? { short: short[name] } : {}),
+        };
+    for (const name of booleans)
+        options[name] = {
+            type: "boolean",
+            ...(short[name] ? { short: short[name] } : {}),
+        };
+    return parseArgs({
+        args: argv,
+        options,
+        allowPositionals: true,
+        strict: true,
+    });
+}
+export function required(values, key) {
+    const value = values[key];
+    if (typeof value !== "string" || !value)
+        throw new Error(`Missing --${key}`);
+    return value;
+}
+export function arity(values, min, max = min) {
+    if (values.length < min || values.length > max)
+        throw new Error("Invalid command arguments; run rl --help");
+}
+export async function pooled(items, limit, action) {
+    const results = new Array(items.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await action(items[index]);
+        }
+    }));
+    return results;
+}
+export const isSymlink = (file) => {
+    try {
+        return fs.lstatSync(file).isSymbolicLink();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+};

package/dist/delete.js

@@ -0,0 +1,113 @@
+import path from "node:path";
+import { args, canonical, execute, git, inside, locked, message, pooled, required, } from "./common.js";
+import { Store } from "./store.js";
+import { worktrees } from "./repos.js";
+import { candidates, select } from "./picker.js";
+import { assertReady, GIT_WORKFLOW_DIRECTORY, GIT_WORKFLOW_LOCK, } from "./git-safety.js";
+export async function main(argv) {
+    const { values, positionals } = args(argv, ["repo", "state-dir", "base-dir", "jobs", "default-base"], ["dry-run", "force"]);
+    const jobs = Number(values.jobs ?? 4);
+    if (!Number.isInteger(jobs) || jobs < 1 || jobs > 32)
+        throw new Error("jobs must be an integer from 1 to 32");
+    const repo = canonical(required(values, "repo")), base = canonical(required(values, "base-dir")), registered = worktrees(repo), items = new Map();
+    for (const item of candidates(repo, base))
+        items.set(item.name, item);
+    let names = positionals;
+    if (!names.length)
+        names = (await select(new Store(repo, required(values, "state-dir")), [...items.values()], String(values["default-base"] ?? "origin/test"), true)).map((item) => item.name);
+    names = [...new Set(names)];
+    if (!names.length)
+        return 0;
+    const unknown = names.filter((name) => !items.has(name));
+    if (unknown.length)
+        throw new Error("Not registered managed worktrees: " + unknown.join(", "));
+    const selected = names.map((name) => items.get(name));
+    for (const item of selected)
+        if (registered.some((other) => inside(canonical(other.worktree), item.path)))
+            throw new Error(`${item.name} contains another registered worktree; delete its children first`);
+    for (const item of selected)
+        console.log(`${values["dry-run"] ? "Would delete" : "Selected"}: ${item.name} [branch: ${item.branch || "(detached)"}]${item.locked ? " [locked: will be skipped]" : ""}`);
+    if (values["dry-run"])
+        return 0;
+    const store = new Store(repo, required(values, "state-dir"));
+    return locked(path.join(store.root, GIT_WORKFLOW_DIRECTORY), GIT_WORKFLOW_LOCK, async () => {
+        await store.locked(() => store.records());
+        process.chdir(repo);
+        console.log(`Removing ${selected.length} workspace(s), up to ${jobs} at a time...`);
+        const removed = [], failed = [];
+        await pooled(selected, jobs, async (item) => {
+            try {
+                const current = worktrees(repo).find((entry) => canonical(entry.worktree) === item.path);
+                if (!current ||
+                    (current.branch ?? "").replace(/^refs\/heads\//, "") !== item.branch)
+                    throw new Error("Workspace branch changed; inspect it and retry");
+                if (!values.force && !item.branch)
+                    throw new Error("Detached workspace may contain unmerged commits; inspect it or use --force");
+                if (!values.force)
+                    assertReady(item.path, true, item.branch);
+                if (!values.force && item.branch) {
+                    const upstream = git(repo, "for-each-ref", "--format=%(upstream)", `refs/heads/${item.branch}`);
+                    const merged = await execute([
+                        "git",
+                        "-C",
+                        repo,
+                        "merge-base",
+                        "--is-ancestor",
+                        `refs/heads/${item.branch}`,
+                        upstream || "HEAD",
+                    ], repo);
+                    if (merged.code)
+                        throw new Error("Branch has unmerged commits; merge it first or use --force");
+                }
+                const result = await execute([
+                    "git",
+                    "-C",
+                    repo,
+                    "worktree",
+                    "remove",
+                    ...(values.force ? ["--force"] : []),
+                    item.path,
+                ], repo);
+                if (result.code)
+                    throw new Error(result.stderr.trim());
+                removed.push(item);
+                console.log(`Removed worktree: ${item.name}`);
+            }
+            catch (error) {
+                failed.push(item);
+                console.error(`Failed: ${item.name}: ${message(error)}`);
+            }
+        });
+        await store.locked(() => store.archiveWorktrees(removed.map((item) => item.path)));
+        let cleanupFailed = false;
+        const branches = [
+            ...new Set(removed.map((item) => item.branch).filter(Boolean)),
+        ];
+        if (branches.length) {
+            const result = await execute([
+                "git",
+                "-C",
+                repo,
+                "branch",
+                values.force ? "-D" : "-d",
+                "--",
+                ...branches,
+            ], repo);
+            process.stdout.write(result.stdout);
+            if (result.code) {
+                cleanupFailed = true;
+                console.error("Some worktrees were removed but local branch cleanup failed:\n" +
+                    result.stderr.trim());
+            }
+        }
+        if (removed.length) {
+            const result = await execute(["git", "-C", repo, "worktree", "prune"], repo);
+            if (result.code) {
+                cleanupFailed = true;
+                console.error("Worktree pruning failed: " + result.stderr.trim());
+            }
+        }
+        console.log(`Removed ${removed.length} worktree(s); failed ${failed.length}. Saved documentation and session history retained.`);
+        return failed.length || cleanupFailed ? 1 : 0;
+    });
+}

package/dist/display.js

@@ -0,0 +1,134 @@
+import { activityView } from "./activity.js";
+import { accessLabel } from "./access.js";
+import { stripVTControlCharacters } from "node:util";
+import { homedir } from "node:os";
+import path from "node:path";
+// Keep names and remote titles on one terminal line without control sequences.
+const text = (value) => stripVTControlCharacters(String(value ?? ""))
+    .replace(/[\x00-\x1f\x7f-\x9f]/g, " ")
+    .trim();
+export function prText(pr) {
+    if (!pr)
+        return "PR: none saved. Run rl pr sync to refresh.";
+    const number = typeof pr.number === "number" ? ` #${pr.number}` : "";
+    const state = [pr.isDraft ? "draft" : "", text(pr.state).toLowerCase()]
+        .filter(Boolean)
+        .join(" · ");
+    return [
+        `PR${number}${pr.title ? `: ${text(pr.title)}` : ""}${state ? ` [${state}]` : ""}`,
+        pr.headRefName && pr.baseRefName
+            ? `  ${text(pr.headRefName)} → ${text(pr.baseRefName)}`
+            : "",
+        `  ${text(pr.url)}`,
+        pr.syncedAt ? `  Cached ${text(pr.syncedAt)}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+export function statusText(data, git, workflow = null) {
+    const color = process.env.NO_COLOR === undefined &&
+        process.env.FORCE_COLOR !== "0" &&
+        process.env.TERM !== "dumb" &&
+        (!!process.stdout.isTTY || !!process.env.FORCE_COLOR);
+    const paint = (value, code) => color ? `\x1b[${code}m${value}\x1b[0m` : value;
+    const muted = (value) => paint(value, 90);
+    const row = (label, value) => `  ${muted(label.padEnd(10))}${value}`;
+    const files = (count, state, code) => count ? paint(`${count} ${state} file${count === 1 ? "" : "s"}`, code) : "";
+    const changes = [
+        files(git.staged, "staged", 32),
+        files(git.unstaged, "modified", 33),
+        files(git.untracked, "untracked", 33),
+        files(git.conflicts, "conflicted", 31),
+    ].filter(Boolean);
+    const home = homedir();
+    const directory = data.worktree === home
+        ? "~"
+        : data.worktree.startsWith(home + path.sep)
+            ? "~" + data.worktree.slice(home.length)
+            : data.worktree;
+    const lines = [
+        "",
+        `  ${paint(text(data.id), 1)}`,
+        "",
+        ...(data.branch !== data.id ? [row("Branch", text(data.branch))] : []),
+        row("Path", muted(text(directory))),
+        ...(data.baseBranch ? [row("Base", text(data.baseBranch))] : []),
+        row("Git", git.availability === "ok"
+            ? changes.join(" · ") || paint("clean", 32)
+            : paint(text(git.error ?? git.availability), 31)),
+    ];
+    if (git.upstream) {
+        const sync = git.ahead === 0 && git.behind === 0
+            ? paint("up to date", 32)
+            : git.ahead === null || git.behind === null
+                ? muted("commit counts unavailable")
+                : `${paint(`${git.ahead} ahead`, git.ahead ? 32 : 90)} · ${paint(`${git.behind} behind`, git.behind ? 33 : 90)} ${muted("(commits)")}`;
+        lines.push(row("Upstream", `${sync} ${muted("· " + text(git.upstream))}`));
+    }
+    lines.push("");
+    const pr = data.pr;
+    if (pr) {
+        const number = typeof pr.number === "number" ? ` #${pr.number}` : "";
+        const state = text(pr.state).toLowerCase();
+        const label = [pr.isDraft ? "draft" : "", state]
+            .filter(Boolean)
+            .join(" · ");
+        const badge = paint(label, pr.isDraft
+            ? 33
+            : state === "open"
+                ? 32
+                : state === "merged"
+                    ? 35
+                    : state === "closed"
+                        ? 31
+                        : 33);
+        const target = pr.baseRefName
+            ? `${pr.headRefName && pr.headRefName !== data.branch ? text(pr.headRefName) + " " : ""}→ ${text(pr.baseRefName)}`
+            : "";
+        lines.push(`  ${paint(`PR${number}`, 1)}${badge ? ` · ${badge}` : ""}${target ? ` ${muted("· " + target)}` : ""}`);
+        if (pr.title)
+            lines.push(`  ${text(pr.title)}`);
+        lines.push(`  ${paint(text(pr.url), 36)}`);
+        if (pr.syncedAt) {
+            const stamp = text(pr.syncedAt);
+            lines.push(`  ${muted(`Cached ${Number.isFinite(Date.parse(stamp)) ? accessLabel(stamp) : stamp}`)}`);
+        }
+    }
+    else {
+        lines.push(`  ${paint("PR", 1)} ${muted("· none saved")}`, `  ${muted("Run rl pr sync to refresh")}`);
+    }
+    lines.push("", `  ${paint("Sessions", 1)}`);
+    for (const agent of ["codex", "claude"]) {
+        const activity = activityView(data.activity?.[agent]).filter((item) => !item.childId);
+        const states = ["working", "idle", "stale"]
+            .map((state) => {
+            const count = activity.filter((item) => item.state === state).length;
+            return count
+                ? paint(`${count} ${state}`, state === "working" ? 32 : state === "stale" ? 33 : 90)
+                : "";
+        })
+            .filter(Boolean);
+        lines.push(row(agent === "codex" ? "Codex" : "Claude", `${data.sessions[agent].length} saved${states.length ? ` · ${states.join(" · ")}` : ""}`));
+    }
+    if (workflow) {
+        lines.push("", `  ${paint("Workflow", 1)} · ${text(workflow.workflow)} · ${text(workflow.status)}`, row("Steps", `${workflow.completed}/${workflow.total} completed`), ...(workflow.owner
+            ? [
+                row("Owner", `${workflow.owner.agent} · native subagents · ${workflow.owner.sessionId}`),
+            ]
+            : []), ...(workflow.verdict
+            ? [
+                row("Review", `${workflow.score === null ? "not scored" : `${workflow.score}/100`} · ${text(workflow.verdict)}`),
+            ]
+            : []));
+    }
+    const handoff = data.task?.handoffs.at(-1);
+    if (handoff) {
+        lines.push("", `  ${paint("Task", 1)} · ${paint(data.task.state, data.task.state === "paused" ? 33 : 32)}`, `  ${text(handoff.summary)}`, row("Next", text(handoff.next)));
+        if (handoff.blockers)
+            lines.push(row("Blockers", paint(text(handoff.blockers), 33)));
+    }
+    if (Object.values(data.sessions).some((sessions) => sessions.length))
+        lines.push("", `  ${muted("Resume with")} ${paint("rl resume", 36)}`);
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/doctor.js

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import path from "node:path";
+import { adapters, agentAdapter } from "./agent-registry.js";
+import { activityView, STALE_AFTER_MS } from "./activity.js";
+import { execute, isSymlink, json, message } from "./common.js";
+import { hookCommand } from "./store.js";
+import { isJsonObject, readJsonObject } from "./json.js";
+const PROBE_TIMEOUT_MS = 2000;
+const MAX_VERSION_LENGTH = 200;
+export async function doctor(store, selected, asJson = false) {
+    const [file, data] = store.current();
+    const selectedAdapters = selected
+        ? [agentAdapter(selected)]
+        : Object.values(adapters);
+    const agents = await Promise.all(selectedAdapters.map(async (adapter) => {
+        const configPath = path.join(data.worktree, adapter.configPath);
+        const expectedEvents = Object.keys({
+            ...adapter.events,
+            ...(data.extendedHooks ? adapter.extraEvents : {}),
+        });
+        const executablePath = (process.env.PATH ?? "")
+            .split(path.delimiter)
+            .map((directory) => path.resolve(data.worktree, directory, adapter.name))
+            .find((candidate) => {
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                return fs.statSync(candidate).isFile();
+            }
+            catch {
+                return false;
+            }
+        }) ?? null;
+        let configError = null;
+        let installedEvents = [];
+        try {
+            if (isSymlink(configPath) || isSymlink(path.dirname(configPath)))
+                throw new Error("Hook configuration is a symlink");
+            const config = readJsonObject(configPath);
+            if (!isJsonObject(config.hooks))
+                throw new Error("Missing hooks object");
+            const command = hookCommand(store, data, adapter.name);
+            const hooks = config.hooks;
+            installedEvents = expectedEvents.filter((event) => {
+                const groups = hooks[event];
+                if (!Array.isArray(groups))
+                    return false;
+                return groups.some((group) => isJsonObject(group) &&
+                    (group.matcher === undefined ||
+                        group.matcher === "" ||
+                        group.matcher === "*") &&
+                    Array.isArray(group.hooks) &&
+                    group.hooks.some((h) => isJsonObject(h) &&
+                        h.type === "command" &&
+                        h.command === command &&
+                        h.async !== true));
+            });
+        }
+        catch (error) {
+            configError = message(error);
+        }
+        const missingEvents = expectedEvents.filter((event) => !installedEvents.includes(event));
+        let cliAvailable = false, version = null, cliError = null, launchVerified = false;
+        try {
+            const result = await execute([adapter.name, "--version"], data.worktree, { timeoutMs: PROBE_TIMEOUT_MS });
+            cliAvailable = result.code === 0;
+            version = result.stdout.trim().slice(0, MAX_VERSION_LENGTH) || null;
+            if (!cliAvailable)
+                cliError = "Version probe failed or timed out";
+            if (cliAvailable) {
+                const help = await execute(adapter.name === "codex"
+                    ? [adapter.name, "exec", "--help"]
+                    : [adapter.name, "--help"], data.worktree, { timeoutMs: PROBE_TIMEOUT_MS });
+                launchVerified =
+                    help.code === 0 &&
+                        (adapter.name === "codex"
+                            ? /codex exec/.test(help.stdout) && /PROMPT/.test(help.stdout)
+                            : /--print/.test(help.stdout) && /--resume/.test(help.stdout));
+            }
+        }
+        catch (error) {
+            cliError = message(error);
+        }
+        const health = data.hookHealth?.[adapter.name];
+        return {
+            agent: adapter.name,
+            configPath,
+            installed: !configError && missingEvents.length === 0,
+            installedEvents,
+            missingEvents,
+            configError,
+            cliAvailable,
+            executablePath,
+            launchVerified,
+            extendedHooks: !!data.extendedHooks,
+            delivery: health?.lastSuccess ? "observed" : "not-observed",
+            version,
+            cliError,
+            compatibility: "unverified",
+            trust: "unknown",
+            lastSuccess: health?.lastSuccess ?? null,
+            lastError: health?.lastError ?? null,
+            activity: activityView(data.activity?.[adapter.name]),
+        };
+    }));
+    let stateWritable = true;
+    try {
+        fs.accessSync(store.root, fs.constants.W_OK);
+        fs.accessSync(path.dirname(file), fs.constants.W_OK);
+    }
+    catch {
+        stateWritable = false;
+    }
+    const report = {
+        workspace: data.worktree,
+        stateDirectory: path.dirname(file),
+        stateWritable,
+        staleAfterMs: STALE_AFTER_MS,
+        agents,
+    };
+    if (asJson)
+        json(report);
+    else {
+        console.log(`RL doctor: ${data.worktree}\nState writable from this process: ${stateWritable ? "yes" : "no"}`);
+        for (const item of agents) {
+            console.log(`\n${item.agent}: hooks ${item.installed ? "installed" : "incomplete"}; CLI ${item.cliAvailable ? (item.version ?? "available") : "unavailable"}`);
+            console.log(`  CLI: ${item.executablePath ?? "not on PATH"}; launch flags: ${item.launchVerified ? "verified in installed help" : "unverified"}; hook trust: unknown`);
+            console.log(`  Last received event: ${item.lastSuccess ? `${item.lastSuccess.event} at ${item.lastSuccess.at}` : "none"}`);
+            if (item.missingEvents.length)
+                console.log(`  Missing hooks: ${item.missingEvents.join(", ")}. Run rl adopt.`);
+            if (item.configError)
+                console.log(`  Configuration error: ${item.configError}`);
+            if (item.cliError)
+                console.log(`  CLI error: ${item.cliError}`);
+            if (item.lastError)
+                console.log(`  Last recorded hook error: ${item.lastError.message} at ${item.lastError.at}`);
+            for (const activity of item.activity)
+                console.log(`  ${activity.sessionId}${activity.childId ? ` / child ${activity.childId}` : ""}: ${activity.state}${activity.resumable ? "" : " (observation only)"}`);
+        }
+        console.log("\nInstallation does not prove hooks are enabled or trusted. Review agent hook settings and start a session here to verify delivery. Version compatibility is not certified. Activity is based on received events; after 30 minutes without an event it is stale, not confirmed running. Agent sandbox access may differ from this process.");
+    }
+    return stateWritable &&
+        agents.every((item) => item.installed && item.cliAvailable)
+        ? 0
+        : 1;
+}

package/dist/git-safety.js

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+import { git } from "./common.js";
+export const GIT_WORKFLOW_DIRECTORY = ".git-workflow";
+export const GIT_WORKFLOW_LOCK = ".lock";
+const OPERATION_FILES = [
+    "MERGE_HEAD",
+    "CHERRY_PICK_HEAD",
+    "REVERT_HEAD",
+    "rebase-merge",
+    "rebase-apply",
+    "sequencer",
+];
+/** Shared mutation guard; untracked content counts as dirty. */
+export function assertReady(root, clean, expectedBranch) {
+    if (git(root, "branch", "--show-current") !== expectedBranch)
+        throw new Error("Workspace branch changed; retry from the intended branch");
+    for (const marker of OPERATION_FILES)
+        if (fs.existsSync(git(root, "rev-parse", "--path-format=absolute", "--git-path", marker)))
+            throw new Error(`An operation is already in progress in ${root}; finish or abort it first`);
+    if (git(root, "ls-files", "--unmerged"))
+        throw new Error(`Unresolved conflicts in ${root}`);
+    if (clean && git(root, "status", "--porcelain", "--untracked-files=normal"))
+        throw new Error(`Workspace is dirty: ${root}. Commit or stash changes explicitly first`);
+}