@deftai/directive-core 0.88.0 → 0.89.0

package/dist/finish-loop/main.js

@@ -0,0 +1,365 @@
+/**
+ * CLI entry for pr:finish-loop and directive:finish-loop (#871).
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { runDirectiveFinishLoop } from "./directive-finish-loop.js";
+import { runPrFinishLoop } from "./pr-finish-loop.js";
+import { EXIT_BLOCKED, EXIT_OK } from "./types.js";
+const PR_HELP = "usage: task pr:finish-loop -- <pr_number> [options]\n" +
+    "\n" +
+    "Walk-away PR finish loop (#871 Wave 5). Requires a finish-loop human-origin\n" +
+    "grant (`deft authz:grant -- --template finish-loop`) or DEFT_ALLOW_FINISH_LOOP=1.\n" +
+    "Polls via pr:watch until CLEAN. NEW_P0_P1 → exit 1 (agent address path).\n" +
+    "Respects plan.policy.requireHumanMerge (never force bot merge).\n" +
+    "\n" +
+    "options:\n" +
+    "  -h, --help              Show this help\n" +
+    "  --json                  Emit structured JSON\n" +
+    "  --one-shot              Single pr:watch probe\n" +
+    "  --merge                 Attempt merge when CLEAN and policy allows\n" +
+    "  --max-wait-minutes N    pr:watch cap (default 30)\n" +
+    "  --poll-seconds N        pr:watch interval (default 90)\n" +
+    "  --repo OWNER/REPO       Override repository\n" +
+    "  --project-root PATH     Project root (default cwd)\n" +
+    "\n" +
+    "exit codes:\n" +
+    "  0  CLEAN / MERGED\n" +
+    "  1  ACTION_REQUIRED (NEW_P0_P1 address, or require-human-merge)\n" +
+    "  2  BLOCKED (no grant) / watch error / timeout\n";
+const DIRECTIVE_HELP = "usage: task directive:finish-loop -- [options]\n" +
+    "\n" +
+    "Outer walk-away cascade (#871 Wave 5). Gates on finish-loop grant, scans\n" +
+    "xbrief active/pending queue, logs `.deft-cache/finish-loop-progress.jsonl`,\n" +
+    "optionally shepherds a PR via pr:finish-loop. Implementation steps are\n" +
+    "agent-orchestrated (exit 1 AGENT_STEP) — full autonomous coding is not\n" +
+    "inlined in the CLI.\n" +
+    "\n" +
+    "Mint once, walk away:\n" +
+    "  deft authz:grant -- --template finish-loop\n" +
+    "  task directive:finish-loop --\n" +
+    "\n" +
+    "options:\n" +
+    "  -h, --help              Show this help\n" +
+    "  --json                  Emit structured JSON\n" +
+    "  --pr N                  Shepherd PR N via pr:finish-loop this run\n" +
+    "  --merge                 Pass --merge to pr:finish-loop\n" +
+    "  --one-shot              Single pr:watch probe\n" +
+    "  --max-iterations N      Outer loop cap (default 20)\n" +
+    "  --max-wait-minutes N    pr:watch cap\n" +
+    "  --poll-seconds N        pr:watch interval\n" +
+    "  --repo OWNER/REPO       Override repository\n" +
+    "  --project-root PATH     Project root (default cwd)\n" +
+    "\n" +
+    "exit codes:\n" +
+    "  0  empty queue / clean complete\n" +
+    "  1  AGENT_STEP / address findings / require-human-merge\n" +
+    "  2  BLOCKED (grant/gate/max-iterations/error)\n";
+function takePositive(label, raw) {
+    if (raw === undefined)
+        return { error: `argument ${label}: expected one argument` };
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return { error: `invalid ${label} value: ${raw}` };
+    }
+    return { value: parsed };
+}
+export function parsePrFinishArgs(argv) {
+    const acc = {
+        prNumber: null,
+        repo: null,
+        projectRoot: process.cwd(),
+        maxWaitMinutes: null,
+        pollSeconds: null,
+        oneShot: false,
+        merge: false,
+        emitJson: false,
+        help: false,
+    };
+    let prNumber = null;
+    let repo = null;
+    let projectRoot = process.cwd();
+    let maxWaitMinutes = null;
+    let pollSeconds = null;
+    let oneShot = false;
+    let merge = false;
+    let emitJson = false;
+    let help = false;
+    const args = [...argv];
+    while (args[0] === "--")
+        args.shift();
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            break;
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--json") {
+            emitJson = true;
+        }
+        else if (arg === "--one-shot") {
+            oneShot = true;
+        }
+        else if (arg === "--merge") {
+            merge = true;
+        }
+        else if (arg === "--repo") {
+            const value = args[++i];
+            if (value === undefined)
+                return { ...acc, error: "argument --repo: expected one argument" };
+            repo = value;
+        }
+        else if (arg.startsWith("--repo=")) {
+            repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--project-root") {
+            const value = args[++i];
+            if (value === undefined) {
+                return { ...acc, error: "argument --project-root: expected one argument" };
+            }
+            projectRoot = value;
+        }
+        else if (arg.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--max-wait-minutes") {
+            const r = takePositive("--max-wait-minutes", args[++i]);
+            if ("error" in r)
+                return { ...acc, error: r.error };
+            maxWaitMinutes = r.value;
+        }
+        else if (arg === "--poll-seconds") {
+            const r = takePositive("--poll-seconds", args[++i]);
+            if ("error" in r)
+                return { ...acc, error: r.error };
+            pollSeconds = r.value;
+        }
+        else if (arg.startsWith("-")) {
+            return { ...acc, error: `unrecognized arguments: ${arg}` };
+        }
+        else if (prNumber === null) {
+            const n = Number(arg);
+            if (!Number.isInteger(n) || n <= 0) {
+                return { ...acc, error: `invalid PR number: ${arg}` };
+            }
+            prNumber = n;
+        }
+        else {
+            return { ...acc, error: `unrecognized arguments: ${arg}` };
+        }
+    }
+    if (help) {
+        return {
+            prNumber,
+            repo,
+            projectRoot,
+            maxWaitMinutes,
+            pollSeconds,
+            oneShot,
+            merge,
+            emitJson,
+            help,
+        };
+    }
+    if (prNumber === null) {
+        return { ...acc, error: "the following arguments are required: pr_number" };
+    }
+    return {
+        prNumber,
+        repo,
+        projectRoot,
+        maxWaitMinutes,
+        pollSeconds,
+        oneShot,
+        merge,
+        emitJson,
+        help,
+    };
+}
+export function parseDirectiveFinishArgs(argv) {
+    const acc = {
+        prNumber: null,
+        repo: null,
+        projectRoot: process.cwd(),
+        maxIterations: null,
+        maxWaitMinutes: null,
+        pollSeconds: null,
+        oneShot: false,
+        merge: false,
+        emitJson: false,
+        help: false,
+    };
+    let prNumber = null;
+    let repo = null;
+    let projectRoot = process.cwd();
+    let maxIterations = null;
+    let maxWaitMinutes = null;
+    let pollSeconds = null;
+    let oneShot = false;
+    let merge = false;
+    let emitJson = false;
+    let help = false;
+    const args = [...argv];
+    while (args[0] === "--")
+        args.shift();
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            break;
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--json") {
+            emitJson = true;
+        }
+        else if (arg === "--one-shot") {
+            oneShot = true;
+        }
+        else if (arg === "--merge") {
+            merge = true;
+        }
+        else if (arg === "--pr") {
+            const r = takePositive("--pr", args[++i]);
+            if ("error" in r)
+                return { ...acc, error: r.error };
+            prNumber = r.value;
+        }
+        else if (arg.startsWith("--pr=")) {
+            const r = takePositive("--pr", arg.slice("--pr=".length));
+            if ("error" in r)
+                return { ...acc, error: r.error };
+            prNumber = r.value;
+        }
+        else if (arg === "--repo") {
+            const value = args[++i];
+            if (value === undefined)
+                return { ...acc, error: "argument --repo: expected one argument" };
+            repo = value;
+        }
+        else if (arg.startsWith("--repo=")) {
+            repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--project-root") {
+            const value = args[++i];
+            if (value === undefined) {
+                return { ...acc, error: "argument --project-root: expected one argument" };
+            }
+            projectRoot = value;
+        }
+        else if (arg.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--max-iterations") {
+            const r = takePositive("--max-iterations", args[++i]);
+            if ("error" in r)
+                return { ...acc, error: r.error };
+            maxIterations = r.value;
+        }
+        else if (arg === "--max-wait-minutes") {
+            const r = takePositive("--max-wait-minutes", args[++i]);
+            if ("error" in r)
+                return { ...acc, error: r.error };
+            maxWaitMinutes = r.value;
+        }
+        else if (arg === "--poll-seconds") {
+            const r = takePositive("--poll-seconds", args[++i]);
+            if ("error" in r)
+                return { ...acc, error: r.error };
+            pollSeconds = r.value;
+        }
+        else if (arg.startsWith("-")) {
+            return { ...acc, error: `unrecognized arguments: ${arg}` };
+        }
+        else {
+            return { ...acc, error: `unrecognized arguments: ${arg}` };
+        }
+    }
+    return {
+        prNumber,
+        repo,
+        projectRoot,
+        maxIterations,
+        maxWaitMinutes,
+        pollSeconds,
+        oneShot,
+        merge,
+        emitJson,
+        help,
+    };
+}
+export function formatPrFinishHelp() {
+    return PR_HELP;
+}
+export function formatDirectiveFinishHelp() {
+    return DIRECTIVE_HELP;
+}
+export function cmdPrFinishLoop(argv = process.argv.slice(2)) {
+    const args = parsePrFinishArgs(argv);
+    if (args.help) {
+        process.stdout.write(formatPrFinishHelp());
+        return EXIT_OK;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`pr:finish-loop: ${args.error}\n`);
+        process.stderr.write("Try: task pr:finish-loop -- --help\n");
+        return EXIT_BLOCKED;
+    }
+    const root = resolve(args.projectRoot);
+    if (!existsSync(root)) {
+        process.stderr.write(`pr:finish-loop: --project-root does not exist: ${root}\n`);
+        return EXIT_BLOCKED;
+    }
+    const result = runPrFinishLoop({
+        projectRoot: root,
+        prNumber: args.prNumber,
+        repo: args.repo,
+        maxWaitMinutes: args.maxWaitMinutes ?? undefined,
+        pollSeconds: args.pollSeconds ?? undefined,
+        oneShot: args.oneShot,
+        merge: args.merge,
+    });
+    if (args.emitJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+export function cmdDirectiveFinishLoop(argv = process.argv.slice(2)) {
+    const args = parseDirectiveFinishArgs(argv);
+    if (args.help) {
+        process.stdout.write(formatDirectiveFinishHelp());
+        return EXIT_OK;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`directive:finish-loop: ${args.error}\n`);
+        process.stderr.write("Try: task directive:finish-loop -- --help\n");
+        return EXIT_BLOCKED;
+    }
+    const root = resolve(args.projectRoot);
+    if (!existsSync(root)) {
+        process.stderr.write(`directive:finish-loop: --project-root does not exist: ${root}\n`);
+        return EXIT_BLOCKED;
+    }
+    const result = runDirectiveFinishLoop({
+        projectRoot: root,
+        prNumber: args.prNumber,
+        repo: args.repo,
+        maxIterations: args.maxIterations ?? undefined,
+        maxWaitMinutes: args.maxWaitMinutes ?? undefined,
+        pollSeconds: args.pollSeconds ?? undefined,
+        oneShot: args.oneShot,
+        merge: args.merge,
+    });
+    if (args.emitJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${result.message}\n`);
+        process.stdout.write(`  progress: ${result.progressPath}\n`);
+    }
+    return result.exitCode;
+}
+//# sourceMappingURL=main.js.map

package/dist/finish-loop/pr-finish-loop.d.ts

@@ -0,0 +1,34 @@
+/**
+ * pr:finish-loop — grant-gated PR watch until CLEAN (#871 Wave 5).
+ *
+ * - Polls via pr:watch until CLEAN / NEW_P0_P1 / terminal error
+ * - NEW_P0_P1 → exit ACTION_REQUIRED (address path is agent-orchestrated)
+ * - CLEAN + requireHumanMerge → halt with require-human-merge (do not force bot merge)
+ * - CLEAN + bot merge allowed + --merge → optional wait-mergeable-and-merge
+ * - Missing grants → fail closed BLOCKED
+ */
+import { evaluateAgentMerge } from "../policy/require-human-merge.js";
+import type { WatchOptions, WatchResult } from "../pr-watch/types.js";
+import { type PrFinishLoopResult } from "./types.js";
+export interface PrFinishLoopOptions {
+    readonly projectRoot: string;
+    readonly prNumber: number;
+    readonly repo?: string | null;
+    readonly maxWaitMinutes?: number;
+    readonly pollSeconds?: number;
+    readonly oneShot?: boolean;
+    /** Attempt merge when CLEAN and policy allows (default false). */
+    readonly merge?: boolean;
+    readonly skipGrantGate?: boolean;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly now?: Date;
+    /** Inject watch for tests. */
+    readonly watchFn?: (prNumber: number, repo: string | null, options?: WatchOptions) => WatchResult;
+    /** Inject merge cascade for tests; returns exit code. */
+    readonly mergeFn?: (prNumber: number, repo: string | null) => number;
+    readonly agentMergeFn?: typeof evaluateAgentMerge;
+    readonly writeProgress?: boolean;
+    readonly iteration?: number;
+}
+export declare function runPrFinishLoop(options: PrFinishLoopOptions): PrFinishLoopResult;
+//# sourceMappingURL=pr-finish-loop.d.ts.map

package/dist/finish-loop/pr-finish-loop.js

@@ -0,0 +1,217 @@
+/**
+ * pr:finish-loop — grant-gated PR watch until CLEAN (#871 Wave 5).
+ *
+ * - Polls via pr:watch until CLEAN / NEW_P0_P1 / terminal error
+ * - NEW_P0_P1 → exit ACTION_REQUIRED (address path is agent-orchestrated)
+ * - CLEAN + requireHumanMerge → halt with require-human-merge (do not force bot merge)
+ * - CLEAN + bot merge allowed + --merge → optional wait-mergeable-and-merge
+ * - Missing grants → fail closed BLOCKED
+ */
+import { evaluateAgentMerge } from "../policy/require-human-merge.js";
+import { EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CLEAN, VERDICT_NEW_P0_P1, } from "../pr-watch/constants.js";
+import { watch } from "../pr-watch/watch.js";
+import { evaluateFinishLoopGrant } from "./grant-gate.js";
+import { appendFinishLoopProgress, makeProgressLine } from "./progress.js";
+import { EXIT_ACTION_REQUIRED, EXIT_BLOCKED, EXIT_OK } from "./types.js";
+export function runPrFinishLoop(options) {
+    const projectRoot = options.projectRoot;
+    const prNumber = options.prNumber;
+    const iteration = options.iteration ?? 0;
+    const writeProgress = options.writeProgress !== false;
+    const log = (phase, haltReason, message, extra) => {
+        if (!writeProgress)
+            return;
+        appendFinishLoopProgress(projectRoot, makeProgressLine({
+            phase,
+            iteration,
+            haltReason,
+            message,
+            prNumber,
+            grantId: null,
+            queueCount: null,
+            exitCode: null,
+            extra,
+        }));
+    };
+    // --- Grant gate ---
+    if (options.skipGrantGate !== true) {
+        const gate = evaluateFinishLoopGrant({
+            projectRoot,
+            env: options.env,
+            now: options.now,
+        });
+        if (!gate.allowed) {
+            const message = `BLOCKED pr:finish-loop: ${gate.reason}`;
+            log("gate", "grant-deny", message, { code: gate.code });
+            if (writeProgress) {
+                appendFinishLoopProgress(projectRoot, makeProgressLine({
+                    phase: "halt",
+                    iteration,
+                    haltReason: gate.code === "authz-grant-expired" ? "grant-expired" : "grant-missing",
+                    message,
+                    prNumber,
+                    grantId: gate.grantId,
+                    queueCount: null,
+                    exitCode: EXIT_BLOCKED,
+                }));
+            }
+            return {
+                exitCode: EXIT_BLOCKED,
+                haltReason: gate.code === "authz-grant-expired" ? "grant-expired" : "grant-missing",
+                message,
+                prNumber,
+                watchVerdict: null,
+                mergeAttempted: false,
+                mergeSkippedReason: null,
+                grantId: gate.grantId,
+            };
+        }
+        log("gate", null, `grant ok: ${gate.reason}`, { grantId: gate.grantId });
+    }
+    // --- pr:watch ---
+    const watchFn = options.watchFn ?? watch;
+    const repo = options.repo ?? process.env.GH_REPO ?? null;
+    let watchResult;
+    try {
+        watchResult = watchFn(prNumber, repo, {
+            maxWaitMinutes: options.maxWaitMinutes,
+            pollSeconds: options.pollSeconds,
+            oneShot: options.oneShot === true,
+        });
+    }
+    catch (err) {
+        const message = `pr:finish-loop watch error: ${err instanceof Error ? err.message : String(err)}`;
+        log("pr-watch", "error", message);
+        return {
+            exitCode: EXIT_BLOCKED,
+            haltReason: "error",
+            message,
+            prNumber,
+            watchVerdict: null,
+            mergeAttempted: false,
+            mergeSkippedReason: null,
+            grantId: null,
+        };
+    }
+    const verdict = watchResult.verdict;
+    log("pr-watch", null, `pr:watch verdict=${verdict}`, {
+        exitCode: watchResult.exitCode,
+    });
+    if (watchResult.exitCode === EXIT_NEW_P0_P1 || verdict === VERDICT_NEW_P0_P1) {
+        const message = `pr:finish-loop ACTION_REQUIRED: NEW_P0_P1 on PR #${prNumber}. ` +
+            "Address path is agent-orchestrated: fix findings, push, re-run " +
+            "`task pr:finish-loop -- <N>` (or review-cycle skill).";
+        log("address", "address-findings", message);
+        return {
+            exitCode: EXIT_ACTION_REQUIRED,
+            haltReason: "address-findings",
+            message,
+            prNumber,
+            watchVerdict: verdict,
+            mergeAttempted: false,
+            mergeSkippedReason: null,
+            grantId: null,
+        };
+    }
+    if (watchResult.exitCode !== EXIT_CLEAN && verdict !== VERDICT_CLEAN) {
+        const message = `pr:finish-loop BLOCKED: watch exit=${watchResult.exitCode} verdict=${verdict}` +
+            (watchResult.probe.error !== null ? ` error=${watchResult.probe.error}` : "");
+        log("halt", "error", message);
+        return {
+            exitCode: EXIT_BLOCKED,
+            haltReason: "error",
+            message,
+            prNumber,
+            watchVerdict: verdict,
+            mergeAttempted: false,
+            mergeSkippedReason: null,
+            grantId: null,
+        };
+    }
+    // CLEAN path
+    if (options.merge !== true) {
+        const message = `pr:finish-loop CLEAN on PR #${prNumber}. Merge not requested ` +
+            "(pass --merge to attempt when policy allows). " +
+            "When plan.policy.requireHumanMerge is true, a human must merge.";
+        log("halt", "clean", message);
+        return {
+            exitCode: EXIT_OK,
+            haltReason: "clean",
+            message,
+            prNumber,
+            watchVerdict: VERDICT_CLEAN,
+            mergeAttempted: false,
+            mergeSkippedReason: "merge-not-requested",
+            grantId: null,
+        };
+    }
+    // Respect requireHumanMerge — never force bot merge
+    const agentMergeFn = options.agentMergeFn ?? evaluateAgentMerge;
+    const hm = agentMergeFn(projectRoot);
+    if (!hm.allowed) {
+        const message = `pr:finish-loop CLEAN on PR #${prNumber} but merge blocked by human-merge gate: ` +
+            `${hm.message} Human action required: merge in GitHub UI or ` +
+            "`deft policy:allow-bot-merge -- --confirm` / DEFT_ALLOW_BOT_MERGE=1.";
+        log("merge", "require-human-merge", message);
+        return {
+            exitCode: EXIT_ACTION_REQUIRED,
+            haltReason: "require-human-merge",
+            message,
+            prNumber,
+            watchVerdict: VERDICT_CLEAN,
+            mergeAttempted: false,
+            mergeSkippedReason: "require-human-merge",
+            grantId: null,
+        };
+    }
+    // Optional merge when policy allows
+    if (options.mergeFn !== undefined) {
+        const rc = options.mergeFn(prNumber, repo);
+        if (rc === 0) {
+            const message = `pr:finish-loop MERGED PR #${prNumber}`;
+            log("merge", "merged", message);
+            return {
+                exitCode: EXIT_OK,
+                haltReason: "merged",
+                message,
+                prNumber,
+                watchVerdict: VERDICT_CLEAN,
+                mergeAttempted: true,
+                mergeSkippedReason: null,
+                grantId: null,
+            };
+        }
+        const message = `pr:finish-loop merge attempt failed exit=${rc} for PR #${prNumber}`;
+        log("merge", "error", message);
+        return {
+            exitCode: EXIT_BLOCKED,
+            haltReason: "error",
+            message,
+            prNumber,
+            watchVerdict: VERDICT_CLEAN,
+            mergeAttempted: true,
+            mergeSkippedReason: null,
+            grantId: null,
+        };
+    }
+    // Documented agent/orchestration path when mergeFn not injected:
+    // real cascade is task pr:wait-mergeable-and-merge (not inlined here to
+    // keep unit tests free of gh).
+    const message = `pr:finish-loop CLEAN on PR #${prNumber}; bot merge allowed by policy. ` +
+        "Run `task pr:wait-mergeable-and-merge -- <N>` to complete merge cascade, " +
+        "or pass an injected mergeFn in automation.";
+    log("merge", "clean", message);
+    return {
+        exitCode: EXIT_OK,
+        haltReason: "clean",
+        message,
+        prNumber,
+        watchVerdict: VERDICT_CLEAN,
+        mergeAttempted: false,
+        mergeSkippedReason: "merge-cascade-documented",
+        grantId: null,
+    };
+}
+// silence unused EXIT_TERMINAL_ERROR import if tree-shaken — keep for docs parity
+void EXIT_TERMINAL_ERROR;
+//# sourceMappingURL=pr-finish-loop.js.map

package/dist/finish-loop/progress.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Heartbeat surface for walk-away finish-loop (#871).
+ * Append-only JSONL at `.deft-cache/finish-loop-progress.jsonl`.
+ */
+import type { FinishLoopProgressLine } from "./types.js";
+export declare const FINISH_LOOP_PROGRESS_REL: string;
+export declare function finishLoopProgressPath(projectRoot: string): string;
+export declare function utcIso(now?: Date): string;
+export declare function makeProgressLine(partial: Omit<FinishLoopProgressLine, "schemaVersion" | "ts"> & {
+    readonly ts?: string;
+}): FinishLoopProgressLine;
+/**
+ * Append one progress line. Creates parent dirs via containedWrite.
+ * #2951 Phase 2: product write sink routes through containedWrite.
+ */
+export declare function appendFinishLoopProgress(projectRoot: string, line: FinishLoopProgressLine): string;
+//# sourceMappingURL=progress.d.ts.map

package/dist/finish-loop/progress.js

@@ -0,0 +1,45 @@
+/**
+ * Heartbeat surface for walk-away finish-loop (#871).
+ * Append-only JSONL at `.deft-cache/finish-loop-progress.jsonl`.
+ */
+import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+export const FINISH_LOOP_PROGRESS_REL = join(".deft-cache", "finish-loop-progress.jsonl");
+export function finishLoopProgressPath(projectRoot) {
+    return resolve(projectRoot, FINISH_LOOP_PROGRESS_REL);
+}
+export function utcIso(now) {
+    return (now ?? new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function makeProgressLine(partial) {
+    return {
+        schemaVersion: 1,
+        ts: partial.ts ?? utcIso(),
+        phase: partial.phase,
+        iteration: partial.iteration,
+        haltReason: partial.haltReason,
+        message: partial.message.replace(/[\r\n]+/g, " "),
+        prNumber: partial.prNumber,
+        grantId: partial.grantId,
+        queueCount: partial.queueCount,
+        exitCode: partial.exitCode,
+        extra: partial.extra,
+    };
+}
+/**
+ * Append one progress line. Creates parent dirs via containedWrite.
+ * #2951 Phase 2: product write sink routes through containedWrite.
+ */
+export function appendFinishLoopProgress(projectRoot, line) {
+    const root = resolve(projectRoot);
+    const path = finishLoopProgressPath(root);
+    const payload = { ...line };
+    containedWrite({
+        root,
+        target: path,
+        data: `${JSON.stringify(payload)}\n`,
+        mode: "append",
+    });
+    return path;
+}
+//# sourceMappingURL=progress.js.map

package/dist/finish-loop/queue.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Scope queue scan for directive:finish-loop (#871).
+ * Lists xbrief/active + xbrief/pending (and legacy vbrief/) story files.
+ * Implementation work is agent-owned; this is the gate's empty-queue detector.
+ */
+export interface QueueEntry {
+    readonly path: string;
+    readonly lifecycle: "active" | "pending";
+    readonly name: string;
+}
+/**
+ * Scan project root for in-flight / pending story xBRIEFs.
+ * Does not invent work — empty means the outer loop may halt cleanly.
+ */
+export declare function scanFinishLoopQueue(projectRoot: string): QueueEntry[];
+//# sourceMappingURL=queue.d.ts.map