@relay-baton/cli 1.0.0

package/dist/commands/execute.js

@@ -0,0 +1,183 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeCommand = executeCommand;
+const fs = __importStar(require("fs"));
+const core_1 = require("@relay-baton/core");
+const projectOptions_1 = require("./projectOptions");
+const agentFor_1 = require("./agentFor");
+async function executeCommand(opts) {
+    const projectContext = (0, projectOptions_1.resolveProjectContext)(opts, true);
+    const repoRoot = projectContext.repoRoot;
+    const { config } = core_1.ConfigLoader.load(repoRoot);
+    const sm = new core_1.SessionManager(repoRoot, config);
+    if (!sm.getMeta())
+        sm.init("");
+    const git = new core_1.GitService(repoRoot);
+    if (!git.isGitRepo()) {
+        console.error("[relay-baton] not a git repository. aborting.");
+        process.exit(2);
+    }
+    const meta = sm.getMeta();
+    const profileName = (opts.diet ?? meta.tokenDietProfile ?? projectContext.project?.defaultDiet ?? config.tokenDiet.profile);
+    if (!config.tokenDiet.profiles[profileName]) {
+        console.error(`unknown diet profile: ${profileName}`);
+        process.exit(2);
+    }
+    // A plan must exist.
+    const planPath = opts.from ?? sm.files.p("plan");
+    if (!fs.existsSync(planPath)) {
+        console.error(`[relay-baton] no plan found at ${planPath}. Run 'relay-baton plan "<task>"' first.`);
+        process.exit(2);
+    }
+    // If reading from a custom path, copy it into the session so the gate + agent see it.
+    if (opts.from && opts.from !== sm.files.p("plan")) {
+        fs.copyFileSync(opts.from, sm.files.p("plan"));
+    }
+    // Gate the plan before executing.
+    const planGate = new core_1.PlanQualityGate(repoRoot, config.tokenDiet.profiles[profileName]).check();
+    if (!planGate.ok) {
+        console.error("[relay-baton] Plan Quality Gate failed:");
+        for (const f of planGate.failures)
+            console.error("  - " + f);
+        if (!opts.force) {
+            console.error("[relay-baton] aborting. Fix plan.md or use --force.");
+            process.exit(3);
+        }
+    }
+    const executor = (opts.with ?? config.planExecute?.defaultExecutor ?? "codex");
+    const startedAt = new Date().toISOString();
+    sm.updateMeta({
+        workflowMode: "plan-execute",
+        executor,
+        status: "executing",
+        activeAgent: executor,
+        executeStartedAt: startedAt,
+        startedAt,
+        endedAt: undefined,
+        durationMs: undefined,
+        fallbackReason: null,
+    });
+    const adapter = (0, agentFor_1.adapterFor)(executor, config);
+    const prompt = core_1.PromptBuilder.executor();
+    const cmd = adapter.buildCommand({ task: prompt, prompt, repoRoot, sessionDir: sm.files.dir, dietProfile: profileName });
+    const detector = new core_1.FallbackDetector(config.fallbackPatterns);
+    console.log(`[relay-baton] executing plan with ${cmd.command} (${executor}) ...`);
+    const r = await (0, core_1.runAgent)({
+        command: cmd,
+        logFile: sm.files.p("commandsLog"),
+        authPolicy: config.authPolicy,
+        allowApiKeyEnv: opts.allowApiKeyEnv,
+        fallbackDetector: detector,
+        onStdout: l => process.stdout.write(l + "\n"),
+        onStderr: l => process.stderr.write(l + "\n"),
+        onFallback: hit => console.error(`[relay-baton] fallback pattern detected: ${hit.pattern}`),
+    });
+    const finish = (status, lastError, lastAgent) => {
+        const endedAt = new Date().toISOString();
+        sm.updateMeta({
+            status, lastError, lastAgent, activeAgent: "none",
+            endedAt, durationMs: Date.parse(endedAt) - Date.parse(startedAt),
+        });
+    };
+    if (r.error) {
+        console.error(r.error);
+        finish("failed", r.error, executor);
+        process.exit(1);
+    }
+    const shouldFallback = r.fallbackReason !== null;
+    if (!shouldFallback) {
+        finish(r.exitCode === 0 ? "completed" : "failed", r.exitCode === 0 ? null : `${executor} exited with ${r.exitCode}`, executor);
+        console.log("[relay-baton] execute finished without fallback.");
+        return;
+    }
+    // In-execute fallback: build a handoff and hand to the fallback agent,
+    // reusing the v0.4 quality gates (composition with fallback mode).
+    console.log("[relay-baton] building handoff for fallback agent...");
+    sm.updateMeta({ status: "fallback_detected", fallbackReason: r.fallbackReason, lastAgent: executor, activeAgent: "none" });
+    const wf = new core_1.BatonWorkflow(sm, config);
+    const h = wf.buildHandoff({
+        profileName,
+        fallbackReason: r.fallbackReason,
+        previousAgent: executor,
+        nextAgent: config.fallbackAgent,
+    });
+    const prevCount = sm.getMeta()?.handoffCount ?? 0;
+    sm.updateMeta({ handoffCount: prevCount + 1 });
+    const gate = new core_1.HandoffQualityGate(repoRoot).check();
+    const dietGate = new core_1.TokenDietQualityGate(repoRoot, profileName, config.tokenDiet.profiles[profileName])
+        .check({ wasTruncated: h.truncated });
+    let blocked = false;
+    if (!gate.ok) {
+        console.error("Handoff Quality Gate failed:");
+        for (const f of gate.failures)
+            console.error("  - " + f);
+        blocked = true;
+    }
+    if (!dietGate.ok) {
+        console.error("Token Diet Quality Gate failed:");
+        for (const f of dietGate.failures)
+            console.error("  - " + f);
+        blocked = true;
+    }
+    for (const w of dietGate.warnings)
+        console.error("warn: " + w);
+    if (blocked && !opts.force) {
+        console.error("[relay-baton] aborting fallback launch. Use --force to override.");
+        process.exit(3);
+    }
+    const fb = config.fallbackAgent;
+    sm.updateMeta({ status: "running_fallback", activeAgent: fb });
+    const fbAdapter = (0, agentFor_1.adapterFor)(fb, config);
+    const fbCmd = fbAdapter.buildCommand({
+        task: core_1.PromptBuilder.claudeContinuation(),
+        prompt: core_1.PromptBuilder.claudeContinuation(),
+        repoRoot, sessionDir: sm.files.dir,
+    });
+    const r2 = await (0, core_1.runAgent)({
+        command: fbCmd,
+        logFile: sm.files.p("commandsLog"),
+        authPolicy: config.authPolicy,
+        allowApiKeyEnv: opts.allowApiKeyEnv,
+        onStdout: l => process.stdout.write(l + "\n"),
+        onStderr: l => process.stderr.write(l + "\n"),
+    });
+    if (r2.error) {
+        console.error(r2.error);
+        finish("failed", r2.error, fb);
+        process.exit(1);
+    }
+    finish(r2.exitCode === 0 ? "completed" : "failed", r2.exitCode === 0 ? null : `${fb} exited with ${r2.exitCode}`, fb);
+}

package/dist/commands/git.d.ts

@@ -0,0 +1,6 @@
+import { ProjectOpts } from "./projectOptions";
+export interface GitStatusOpts extends ProjectOpts {
+    json?: boolean;
+    limit?: string;
+}
+export declare function gitStatusCommand(opts?: GitStatusOpts): Promise<void>;

package/dist/commands/git.js

@@ -0,0 +1,82 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitStatusCommand = gitStatusCommand;
+const fs = __importStar(require("fs"));
+const core_1 = require("@relay-baton/core");
+const projectOptions_1 = require("./projectOptions");
+async function gitStatusCommand(opts = {}) {
+    const repoRoot = (0, projectOptions_1.resolveRepoRoot)(opts);
+    const limit = Number.parseInt(opts.limit || "40", 10);
+    const git = new core_1.GitService(repoRoot);
+    const summary = git.summary(Number.isFinite(limit) ? limit : 40);
+    const tracking = git.compareBaseline(readBaseline(repoRoot));
+    if (opts.json) {
+        console.log(JSON.stringify({ repoRoot, ...summary, tracking }, null, 2));
+        return;
+    }
+    if (!summary.available) {
+        console.log("[relay-baton] git unavailable: current project is not a git repository.");
+        return;
+    }
+    console.log("branch:", summary.branch ?? "(detached)");
+    console.log("head:", summary.head ? summary.head.slice(0, 12) : "(none)");
+    console.log("upstream:", summary.upstream ?? "(none)");
+    console.log("ahead/behind:", `${summary.ahead}/${summary.behind}`);
+    console.log("clean:", summary.clean ? "yes" : "no");
+    console.log("changed:", summary.changed);
+    console.log("staged:", summary.staged);
+    console.log("unstaged:", summary.unstaged);
+    console.log("untracked:", summary.untracked);
+    if (tracking.baseline) {
+        console.log("changed since session start:", tracking.changedSinceBaseline ? "yes" : "no");
+        console.log("changed delta:", tracking.changedDelta ?? 0);
+    }
+    else {
+        console.log("session baseline:", "(none)");
+    }
+    for (const file of summary.files) {
+        console.log(`${file.code} ${file.path} (${file.label})`);
+    }
+}
+function readBaseline(repoRoot) {
+    try {
+        const raw = fs.readFileSync(new core_1.SessionFiles(repoRoot).p("gitBaseline"), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/guard.d.ts

@@ -0,0 +1,7 @@
+import { ProjectOpts } from "./projectOptions";
+export interface GuardOpts extends ProjectOpts {
+    json?: boolean;
+    /** Exit non-zero (10) when a stop condition is triggered. */
+    exitCode?: boolean;
+}
+export declare function guardCommand(opts?: GuardOpts): Promise<void>;

package/dist/commands/guard.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guardCommand = guardCommand;
+const core_1 = require("@relay-baton/core");
+const projectOptions_1 = require("./projectOptions");
+async function guardCommand(opts = {}) {
+    const repoRoot = (0, projectOptions_1.resolveRepoRoot)(opts);
+    const { config } = core_1.ConfigLoader.load(repoRoot);
+    const report = new core_1.GuardrailPolicy(repoRoot, config).evaluate();
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const verdict = report.blocked ? "BLOCKED" : "ok";
+        console.log(`[relay-baton] guardrails: ${verdict}`);
+        const { actual, limits } = report;
+        console.log(`steps: ${actual.steps}/${limits.maxSteps ?? "∞"}`);
+        console.log(`changed files: ${actual.changedFiles}/${limits.maxChangedFiles ?? "∞"}`);
+        console.log(`budget ratio: ${actual.budgetRatio == null ? "-" : actual.budgetRatio.toFixed(2)}/${limits.maxBudgetRatio ?? "∞"}`);
+        if (report.requireConfirmation)
+            console.log("mutating steps require explicit human confirmation");
+        for (const v of report.violations)
+            console.log(`- ${v.condition}: ${v.message}`);
+    }
+    // Advisory by default (read-only report). With --exit-code, a triggered stop
+    // condition sets a non-zero exit so a script/agent loop can halt — relay-baton
+    // still never halts an agent on its own.
+    if (opts.exitCode && report.blocked)
+        process.exitCode = 10;
+}

package/dist/commands/handoff.d.ts

@@ -0,0 +1,10 @@
+import { ProjectOpts } from "./projectOptions";
+export interface HandoffOpts extends ProjectOpts {
+    to: string;
+    diet?: string;
+    force?: boolean;
+    run?: boolean;
+    noRun?: boolean;
+    allowApiKeyEnv?: boolean;
+}
+export declare function handoffCommand(opts: HandoffOpts): Promise<void>;

package/dist/commands/handoff.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handoffCommand = handoffCommand;
+const core_1 = require("@relay-baton/core");
+const projectOptions_1 = require("./projectOptions");
+const auditApiKeyEnv_1 = require("./auditApiKeyEnv");
+async function handoffCommand(opts) {
+    const projectContext = (0, projectOptions_1.resolveProjectContext)(opts, true);
+    const repoRoot = projectContext.repoRoot;
+    const { config } = core_1.ConfigLoader.load(repoRoot);
+    const sm = new core_1.SessionManager(repoRoot, config);
+    if (!sm.getMeta())
+        sm.init("");
+    const git = new core_1.GitService(repoRoot);
+    if (!git.isGitRepo()) {
+        console.error("[relay-baton] not a git repository. aborting handoff.");
+        process.exit(2);
+    }
+    const profileName = (opts.diet ?? sm.getMeta()?.tokenDietProfile ?? projectContext.project?.defaultDiet ?? config.tokenDiet.profile);
+    if (!config.tokenDiet.profiles[profileName]) {
+        console.error(`unknown diet profile: ${profileName}`);
+        process.exit(2);
+    }
+    // v0.4 observability: stamp the start of this handoff and clear any stale
+    // endedAt/durationMs from a previous run/handoff in the same session.
+    const startedAt = new Date().toISOString();
+    sm.updateMeta({ startedAt, endedAt: undefined, durationMs: undefined });
+    const prevMeta = sm.getMeta();
+    // v2.5 pre-handoff hooks (opt-in, local-only; no-op when unconfigured).
+    const hooks = new core_1.HookRunner(repoRoot, config);
+    const runHooks = (phase) => {
+        for (const r of hooks.run(phase, {
+            allowApiKeyEnv: opts.allowApiKeyEnv,
+            onStdout: l => process.stdout.write(l + "\n"),
+            onStderr: l => process.stderr.write(l + "\n"),
+        })) {
+            if (!r.ok)
+                console.error(`[relay-baton] hook failed (${phase}): ${r.command} → ${r.exitCode ?? r.error}`);
+        }
+    };
+    runHooks("preHandoff");
+    const wf = new core_1.BatonWorkflow(sm, config);
+    const result = wf.buildHandoff({
+        profileName,
+        fallbackReason: prevMeta.fallbackReason,
+        previousAgent: prevMeta.lastAgent !== "none" ? prevMeta.lastAgent : "codex",
+        nextAgent: opts.to,
+    });
+    // v0.4 observability: count this successful handoff write.
+    const prevCount = sm.getMeta()?.handoffCount ?? 0;
+    sm.updateMeta({
+        status: "handoff_ready",
+        tokenDietProfile: profileName,
+        handoffCount: prevCount + 1,
+    });
+    console.log(`[relay-baton] handoff written: ${result.handoffPath} (${result.usedChars} chars, truncated=${result.truncated})`);
+    // v2.4 local usage insight (token proxy; never transmitted).
+    new core_1.UsageLedger(repoRoot).record("handoff", (0, core_1.isAgentId)(opts.to) ? opts.to : "none", result.usedChars, `${prevMeta.lastAgent}→${opts.to}`);
+    const gate = new core_1.HandoffQualityGate(repoRoot).check();
+    const dietGate = new core_1.TokenDietQualityGate(repoRoot, profileName, config.tokenDiet.profiles[profileName])
+        .check({ wasTruncated: result.truncated });
+    let blocked = false;
+    if (!gate.ok) {
+        console.error("[relay-baton] Handoff Quality Gate failed:");
+        for (const f of gate.failures)
+            console.error("  - " + f);
+        blocked = true;
+    }
+    if (!dietGate.ok) {
+        console.error("[relay-baton] Token Diet Quality Gate failed:");
+        for (const f of dietGate.failures)
+            console.error("  - " + f);
+        blocked = true;
+    }
+    for (const w of dietGate.warnings)
+        console.error("[relay-baton] warn: " + w);
+    // Redaction gate: never let high-severity secrets reach the next agent.
+    // Medium findings (home paths, oversized) are warnings only.
+    const redaction = result.redaction;
+    const highFindings = redaction.findings.filter(f => f.severity === "high");
+    if (highFindings.length > 0) {
+        console.error("[relay-baton] Redaction Gate failed (handoff would leak secrets to the next agent):");
+        for (const f of highFindings)
+            console.error(`  - ${f.category}: ${f.file}${f.line ? ":" + f.line : ""} (${f.hint})`);
+        blocked = true;
+    }
+    for (const f of redaction.findings.filter(f => f.severity !== "high")) {
+        console.error(`[relay-baton] warn: redaction ${f.category} in ${f.file}${f.line ? ":" + f.line : ""} (${f.hint})`);
+    }
+    if (blocked && !opts.force) {
+        console.error("[relay-baton] aborting. Use --force to override.");
+        process.exit(3);
+    }
+    if (opts.run === false || opts.noRun)
+        return;
+    if (opts.to !== "claude") {
+        console.error("[relay-baton] MVP only supports --to claude");
+        process.exit(2);
+    }
+    const adapter = new core_1.ClaudeCodeAdapter(config.agents.claude);
+    const prompt = core_1.PromptBuilder.claudeContinuation();
+    const cmd = adapter.buildCommand({ task: prevMeta.task, repoRoot, sessionDir: sm.files.dir, prompt });
+    sm.updateMeta({ activeAgent: "claude", status: "running_fallback" });
+    const r = await (0, core_1.runAgent)({
+        command: cmd,
+        logFile: sm.files.p("commandsLog"),
+        authPolicy: config.authPolicy,
+        allowApiKeyEnv: opts.allowApiKeyEnv,
+        onStdout: l => process.stdout.write(l + "\n"),
+        onStderr: l => process.stderr.write(l + "\n"),
+    });
+    (0, auditApiKeyEnv_1.auditApiKeyEnv)(repoRoot, r.passedThroughEnvVars, sm.getMeta()?.id);
+    if (r.error) {
+        console.error(r.error);
+        const endedAt = new Date().toISOString();
+        sm.updateMeta({
+            status: "failed", lastError: r.error, lastAgent: "claude", activeAgent: "none",
+            endedAt, durationMs: Date.parse(endedAt) - Date.parse(startedAt),
+        });
+        process.exit(1);
+    }
+    if (r.exitCode === 0)
+        runHooks("postExecute");
+    const endedAt = new Date().toISOString();
+    sm.updateMeta({
+        status: r.exitCode === 0 ? "completed" : "failed",
+        lastAgent: "claude",
+        activeAgent: "none",
+        lastError: r.exitCode === 0 ? null : `claude exited with ${r.exitCode}`,
+        endedAt,
+        durationMs: Date.parse(endedAt) - Date.parse(startedAt),
+    });
+}

package/dist/commands/handoffBundle.d.ts

@@ -0,0 +1,12 @@
+import { ProjectOpts } from "./projectOptions";
+export interface HandoffBundleOpts extends ProjectOpts {
+    json?: boolean;
+    dryRun?: boolean;
+    out?: string;
+}
+export declare function handoffBundleCommand(opts?: HandoffBundleOpts): Promise<void>;
+export interface HandoffInspectOpts {
+    json?: boolean;
+    out?: string;
+}
+export declare function handoffInspectCommand(bundle: string, opts?: HandoffInspectOpts): Promise<void>;

package/dist/commands/handoffBundle.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handoffBundleCommand = handoffBundleCommand;
+exports.handoffInspectCommand = handoffInspectCommand;
+const core_1 = require("@relay-baton/core");
+const projectOptions_1 = require("./projectOptions");
+async function handoffBundleCommand(opts = {}) {
+    const repoRoot = (0, projectOptions_1.resolveRepoRoot)(opts);
+    const result = new core_1.HandoffBundler(repoRoot).bundle({ bundleRoot: opts.out, dryRun: opts.dryRun });
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.available) {
+        console.log(`[relay-baton] handoff bundle unavailable: ${result.reason}`);
+        return;
+    }
+    const count = result.manifest?.files.length ?? 0;
+    const prefix = result.dryRun ? "would bundle" : "bundled";
+    console.log(`[relay-baton] ${prefix} ${count} artifact(s)`);
+    console.log(`bundle: ${result.bundleDir}`);
+    const r = result.redaction;
+    if (r && !r.clean) {
+        console.log(`⚠ redaction: ${r.findings.length} finding(s) — review before sharing`);
+        for (const f of r.findings.slice(0, 10)) {
+            console.log(`  - [${f.severity}] ${f.category}: ${f.file}${f.line ? ":" + f.line : ""} (${f.hint})`);
+        }
+    }
+    else if (r) {
+        console.log("redaction: clean");
+    }
+    if (!result.dryRun)
+        console.log("manifest: manifest.json");
+}
+async function handoffInspectCommand(bundle, opts = {}) {
+    const result = new core_1.HandoffBundleInspector({ bundleRoot: opts.out }).inspect(bundle);
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.available) {
+        console.log(`[relay-baton] cannot inspect bundle: ${result.reason}`);
+        return;
+    }
+    console.log(`[relay-baton] handoff bundle ${result.id}`);
+    console.log(`repoRoot: ${result.repoRoot ?? "unknown"}`);
+    console.log(`createdAt: ${result.createdAt ?? "unknown"}`);
+    console.log(`git: ${result.git?.branch ?? "(no git)"}${result.git ? ` · ${result.git.changed} changed` : ""}`);
+    console.log(`files: ${result.fileCount}, total ${result.totalBytes} bytes`);
+    console.log(`integrity: ${result.intact ? "intact" : "DAMAGED"}`);
+    console.log(`trust: ${result.safe ? "safe" : "UNSAFE — do not import"}`);
+    if (result.missing.length)
+        console.log(`missing: ${result.missing.join(", ")}`);
+    if (result.corrupt.length)
+        console.log(`corrupt: ${result.corrupt.join(", ")}`);
+    if (result.unsafe.length) {
+        console.log(`⚠ unsafe targets (path traversal / oversized): ${result.unsafe.length}`);
+        for (const f of result.files.filter(x => !x.safe)) {
+            console.log(`  - [${f.unsafeReason}] ${f.target}`);
+        }
+    }
+    if (result.redactionFindings != null)
+        console.log(`redaction findings recorded: ${result.redactionFindings}`);
+}

package/dist/commands/handoffHistory.d.ts

@@ -0,0 +1,23 @@
+import { ProjectOpts } from "./projectOptions";
+/**
+ * Returns the first non-empty line of `content`, trimmed and clipped to
+ * `maxLen` characters. Skips the leading `#` heading markers so the label
+ * is more descriptive (e.g. "Relay Baton Handoff" instead of "#").
+ */
+export declare function firstNonEmptyLine(content: string, maxLen?: number): string;
+export interface HandoffHistoryEntry {
+    /** Filename inside `.ai-session/` — e.g. "handoff.md" or "handoff.2026-...md" */
+    name: string;
+    /** Absolute path on disk. */
+    path: string;
+    /** Modification time in milliseconds since epoch. */
+    mtimeMs: number;
+    /** File size in bytes. */
+    size: number;
+    /** First non-empty content line, used as a row label. */
+    label: string;
+    /** True when this is the current `handoff.md` (not a backup). */
+    current: boolean;
+}
+export declare function collectHandoffHistory(repoRoot: string): HandoffHistoryEntry[];
+export declare function handoffHistoryCommand(opts?: ProjectOpts): Promise<void>;