sequant 2.2.0 → 2.4.0

package/dist/src/commands/locks.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `sequant locks` — inspect and clear per-issue concurrency locks (#625).
+ */
+export interface LocksListOptions {
+    json?: boolean;
+}
+export interface LocksClearOptions {
+    force?: boolean;
+    json?: boolean;
+}
+export interface LocksAcquireOptions {
+    command?: string;
+    skipPidCheck?: boolean;
+    force?: boolean;
+    signalOther?: boolean;
+    json?: boolean;
+}
+export interface LocksReleaseOptions {
+    json?: boolean;
+}
+export interface LocksCheckOptions {
+    json?: boolean;
+}
+export interface LocksCheckBatchOptions {
+    json?: boolean;
+}
+/** `sequant locks list` — print every active lock with staleness metadata. */
+export declare function locksListCommand(options?: LocksListOptions): Promise<void>;
+/**
+ * `sequant locks clear <issue>` — remove a lock manually.
+ * By default refuses to clear a fresh same-host lock whose PID is alive;
+ * pass `--force` to override.
+ */
+export declare function locksClearCommand(issueArg: string, options?: LocksClearOptions): Promise<void>;
+/**
+ * `sequant locks acquire <issue>` — claim the lock from a shell context
+ * (e.g. a skill SKILL.md). Use `--skip-pid-check` for skill shells whose
+ * Node PID dies between acquire and release; stale recovery then falls back
+ * to age-only (2h).
+ *
+ * Exit codes:
+ *   0 — acquired
+ *   1 — locked by another holder (printed to stderr unless --json)
+ *   2 — invalid arguments
+ */
+export declare function locksAcquireCommand(issueArg: string, options?: LocksAcquireOptions): Promise<void>;
+/**
+ * `sequant locks release <issue>` — release a lock previously acquired by
+ * a skill shell on this host. Refuses to release locks held by a foreign
+ * host or by a different process (use `locks clear --force` for that).
+ */
+export declare function locksReleaseCommand(issueArg: string, options?: LocksReleaseOptions): Promise<void>;
+/**
+ * `sequant locks check <issue>` — read-only lock probe for `/assess`-style
+ * skills. Prints holder info if any, exit code 0 when free, 1 when held.
+ */
+export declare function locksCheckCommand(issueArg: string, options?: LocksCheckOptions): Promise<void>;
+/**
+ * `sequant locks check-batch <issue1> <issue2> ...` — read-only batch probe
+ * used by `/assess`. Text mode emits one canonical warning line per held
+ * issue (nothing for unheld), so the skill can paste the output directly
+ * above its dashboard. JSON mode emits a structured `{ warnings: [...] }`.
+ *
+ * Exit code is always 0 — `/assess` is read-only and should never abort
+ * on locked issues; the warning is informational.
+ */
+export declare function locksCheckBatchCommand(issueArgs: string[], options?: LocksCheckBatchOptions): Promise<void>;

package/dist/src/commands/locks.js

@@ -0,0 +1,290 @@
+/**
+ * `sequant locks` — inspect and clear per-issue concurrency locks (#625).
+ */
+import chalk from "chalk";
+import { LockManager, formatLockedMessage, } from "../lib/locks/index.js";
+/** Human-readable line for the `--signal-other` log output (#637). */
+function formatSignalLine(issue, pid, result) {
+    switch (result.reason) {
+        case "sent":
+            return `Signaled PID ${pid} (SIGTERM) for #${issue}`;
+        case "cross-host":
+            return `Could not signal PID ${pid} for #${issue} (cross-host holder)`;
+        case "self-or-parent":
+            return `Refused to signal PID ${pid} for #${issue} (matches this process or its parent)`;
+        case "pid-dead":
+            return `Could not signal PID ${pid} for #${issue} (already exited)`;
+        case "kill-failed":
+            return `Could not signal PID ${pid} for #${issue} (kill syscall failed)`;
+        case "orchestrator":
+            return `Skipped signal for #${issue} (orchestrator mode)`;
+    }
+}
+function parseIssue(arg) {
+    const issue = Number.parseInt(arg, 10);
+    if (!Number.isInteger(issue) || issue <= 0) {
+        console.error(chalk.red(`Invalid issue number: ${arg}`));
+        process.exitCode = 1;
+        return null;
+    }
+    return issue;
+}
+/** `sequant locks list` — print every active lock with staleness metadata. */
+export async function locksListCommand(options = {}) {
+    const manager = new LockManager();
+    if (manager.isNoop) {
+        if (options.json) {
+            console.log(JSON.stringify({ locks: [], orchestratorMode: true }));
+        }
+        else {
+            console.log(chalk.gray("Lock operations are disabled (SEQUANT_ORCHESTRATOR set)."));
+        }
+        return;
+    }
+    const listings = manager.list();
+    if (options.json) {
+        console.log(JSON.stringify({ locks: listings }, null, 2));
+        return;
+    }
+    if (listings.length === 0) {
+        console.log(chalk.gray("No active locks."));
+        return;
+    }
+    console.log(chalk.bold(`Active locks (${listings.length}):`));
+    console.log("");
+    for (const l of listings) {
+        const ageMinutes = Math.floor(l.ageMs / 60_000);
+        const staleTag = l.stale ? chalk.yellow(`  (stale: ${l.staleReason})`) : "";
+        console.log(`  #${l.issue}  pid=${l.holder.pid}  host=${l.holder.hostname}  ` +
+            `age=${ageMinutes}m  started=${l.holder.startedAt}${staleTag}`);
+        console.log(`    command: ${l.holder.command}`);
+    }
+}
+/**
+ * `sequant locks clear <issue>` — remove a lock manually.
+ * By default refuses to clear a fresh same-host lock whose PID is alive;
+ * pass `--force` to override.
+ */
+export async function locksClearCommand(issueArg, options = {}) {
+    const issue = Number.parseInt(issueArg, 10);
+    if (!Number.isInteger(issue) || issue <= 0) {
+        console.error(chalk.red(`Invalid issue number: ${issueArg}`));
+        process.exitCode = 1;
+        return;
+    }
+    const manager = new LockManager();
+    if (manager.isNoop) {
+        console.log(chalk.gray("Lock operations are disabled (SEQUANT_ORCHESTRATOR set)."));
+        return;
+    }
+    const result = manager.clearLock(issue, { safetyCheck: !options.force });
+    if (options.json) {
+        console.log(JSON.stringify({ issue, ...result }));
+        return;
+    }
+    if (result.cleared) {
+        console.log(chalk.green(`✓ Cleared lock for #${issue}`));
+        return;
+    }
+    switch (result.reason) {
+        case "no-lock":
+            console.log(chalk.gray(`No lock found for #${issue}`));
+            return;
+        case "fresh-same-host-alive": {
+            const holder = manager.check(issue);
+            console.log(chalk.yellow(`Refusing to clear fresh lock on #${issue}` +
+                (holder ? ` (PID ${holder.pid} appears alive on this host)` : "") +
+                `. Re-run with --force if you really want to clear it.`));
+            process.exitCode = 1;
+            return;
+        }
+        default:
+            console.log(chalk.gray(`No-op (${result.reason})`));
+    }
+}
+/**
+ * `sequant locks acquire <issue>` — claim the lock from a shell context
+ * (e.g. a skill SKILL.md). Use `--skip-pid-check` for skill shells whose
+ * Node PID dies between acquire and release; stale recovery then falls back
+ * to age-only (2h).
+ *
+ * Exit codes:
+ *   0 — acquired
+ *   1 — locked by another holder (printed to stderr unless --json)
+ *   2 — invalid arguments
+ */
+export async function locksAcquireCommand(issueArg, options = {}) {
+    const issue = parseIssue(issueArg);
+    if (issue === null)
+        return;
+    const command = options.command ?? "unknown";
+    const manager = new LockManager();
+    if (manager.isNoop) {
+        if (options.json) {
+            console.log(JSON.stringify({ acquired: true, orchestratorMode: true }));
+        }
+        else {
+            console.log(chalk.gray("Lock operations are disabled (SEQUANT_ORCHESTRATOR set)."));
+        }
+        return;
+    }
+    if (options.force) {
+        const { previous } = manager.forceAcquire(issue, command, {
+            skipPidCheck: options.skipPidCheck,
+        });
+        if (previous && options.signalOther) {
+            const result = manager.signalOther(previous);
+            if (!options.json) {
+                console.log(chalk.gray(formatSignalLine(issue, previous.pid, result)));
+            }
+        }
+        if (options.json) {
+            console.log(JSON.stringify({
+                acquired: true,
+                forced: true,
+                previousHolder: previous,
+            }));
+        }
+        else {
+            console.log(chalk.green(`✓ Acquired lock for #${issue} (forced)`));
+        }
+        return;
+    }
+    const result = manager.acquire(issue, command, {
+        skipPidCheck: options.skipPidCheck,
+    });
+    if (result.acquired) {
+        if (options.json) {
+            console.log(JSON.stringify({ acquired: true, lockPath: result.lockPath }));
+        }
+        else {
+            console.log(chalk.green(`✓ Acquired lock for #${issue}`));
+        }
+        return;
+    }
+    // Blocked.
+    process.exitCode = 1;
+    if (options.json) {
+        console.log(JSON.stringify({
+            acquired: false,
+            holder: result.holder,
+            lockPath: result.lockPath,
+        }));
+    }
+    else {
+        console.error(chalk.yellow(formatLockedMessage(issue, result.holder)));
+    }
+}
+/**
+ * `sequant locks release <issue>` — release a lock previously acquired by
+ * a skill shell on this host. Refuses to release locks held by a foreign
+ * host or by a different process (use `locks clear --force` for that).
+ */
+export async function locksReleaseCommand(issueArg, options = {}) {
+    const issue = parseIssue(issueArg);
+    if (issue === null)
+        return;
+    const manager = new LockManager();
+    if (manager.isNoop) {
+        if (options.json) {
+            console.log(JSON.stringify({ issue, released: false, orchestratorMode: true }));
+        }
+        else {
+            console.log(chalk.gray("Lock operations are disabled (SEQUANT_ORCHESTRATOR set)."));
+        }
+        return;
+    }
+    const released = manager.releaseExternal(issue);
+    if (options.json) {
+        console.log(JSON.stringify({ issue, released }));
+        return;
+    }
+    if (released) {
+        console.log(chalk.green(`✓ Released lock for #${issue}`));
+    }
+    else {
+        console.log(chalk.gray(`No releasable lock for #${issue}`));
+    }
+}
+/**
+ * `sequant locks check <issue>` — read-only lock probe for `/assess`-style
+ * skills. Prints holder info if any, exit code 0 when free, 1 when held.
+ */
+export async function locksCheckCommand(issueArg, options = {}) {
+    const issue = parseIssue(issueArg);
+    if (issue === null)
+        return;
+    const manager = new LockManager();
+    if (manager.isNoop) {
+        if (options.json) {
+            console.log(JSON.stringify({ locked: false, orchestratorMode: true }));
+        }
+        else {
+            console.log(chalk.gray("Lock operations are disabled (SEQUANT_ORCHESTRATOR set)."));
+        }
+        return;
+    }
+    const holder = manager.check(issue);
+    if (!holder) {
+        if (options.json) {
+            console.log(JSON.stringify({ issue, locked: false }));
+        }
+        else {
+            console.log(chalk.gray(`#${issue} is not locked`));
+        }
+        return;
+    }
+    process.exitCode = 1;
+    if (options.json) {
+        console.log(JSON.stringify({ issue, locked: true, holder }));
+    }
+    else {
+        console.log(chalk.yellow(formatLockedMessage(issue, holder)));
+    }
+}
+/**
+ * `sequant locks check-batch <issue1> <issue2> ...` — read-only batch probe
+ * used by `/assess`. Text mode emits one canonical warning line per held
+ * issue (nothing for unheld), so the skill can paste the output directly
+ * above its dashboard. JSON mode emits a structured `{ warnings: [...] }`.
+ *
+ * Exit code is always 0 — `/assess` is read-only and should never abort
+ * on locked issues; the warning is informational.
+ */
+export async function locksCheckBatchCommand(issueArgs, options = {}) {
+    const issues = [];
+    for (const arg of issueArgs) {
+        const issue = Number.parseInt(arg, 10);
+        if (!Number.isInteger(issue) || issue <= 0) {
+            console.error(chalk.red(`Invalid issue number: ${arg}`));
+            process.exitCode = 2;
+            return;
+        }
+        issues.push(issue);
+    }
+    const manager = new LockManager();
+    if (manager.isNoop) {
+        if (options.json) {
+            console.log(JSON.stringify({ warnings: [], orchestratorMode: true, checked: 0 }));
+        }
+        // Non-JSON: silent in orchestrator mode (matches `acquire`/`release`
+        // semantics — no spurious output for /assess in MCP-driven runs).
+        return;
+    }
+    const warnings = [];
+    for (const issue of issues) {
+        const holder = manager.check(issue);
+        if (holder)
+            warnings.push({ issue, holder });
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ warnings, checked: issues.length }, null, 2));
+        return;
+    }
+    // Text mode: one line per held issue (canonical `⚠` format that /assess
+    // pastes verbatim into its dashboard). Empty output when nothing is held.
+    for (const { issue, holder } of warnings) {
+        console.log(`⚠ #${issue} held by PID ${holder.pid} on ${holder.hostname} ` +
+            `since ${holder.startedAt} (${holder.command})`);
+    }
+}

package/dist/src/commands/merge.js

@@ -14,6 +14,7 @@
 import { spawnSync } from "child_process";
 import { ui, colors } from "../lib/cli-ui.js";
 import { runMergeChecks, formatReportMarkdown, } from "../lib/merge-check/index.js";
+import { LockManager, formatLockedMessage } from "../lib/locks/index.js";
 /**
  * Determine exit code from batch verdict
  */
@@ -68,6 +69,16 @@ export async function mergeCommand(issues, options) {
         console.log(colors.muted(issueNumbers.length > 0
             ? `Checking issues: ${issueNumbers.map((i) => `#${i}`).join(", ")} (mode: ${mode})`
             : `Auto-detecting issues from most recent run (mode: ${mode})`));
+        // #625: read-only lock awareness — warn but proceed.
+        const lockManager = new LockManager();
+        if (!lockManager.isNoop) {
+            for (const issue of issueNumbers) {
+                const holder = lockManager.check(issue);
+                if (holder) {
+                    console.log(colors.muted(`  !  ${formatLockedMessage(issue, holder)}`));
+                }
+            }
+        }
         console.log("");
     }
     try {

package/dist/src/commands/prompt.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `sequant prompt <issue> "<message>"` — send a message into a running
+ * headless `sequant run` session via the interactive relay (#383).
+ */
+import { type RelayMessageType } from "../lib/relay/types.js";
+import type { IssueState } from "../lib/workflow/state-schema.js";
+export interface PromptCommandOptions {
+    type?: string;
+    json?: boolean;
+    /**
+     * If set, poll the outbox for a reply that matches the new message ID and
+     * print it inline. Exits 0 on reply, 1 on timeout (#645, Gap 4).
+     */
+    waitSeconds?: number;
+    /** Test seam: override the poll interval (ms). Default 250. */
+    waitPollIntervalMs?: number;
+}
+export interface ParsedPromptArgs {
+    issue: number | null;
+    message: string;
+    type: RelayMessageType;
+}
+/** Validate raw CLI args. Throws on invalid type or empty message. */
+export declare function parseRelayPromptArgs(args: string[], options?: {
+    type?: string;
+}): ParsedPromptArgs;
+/** Identify candidate active runs for auto-resolution (AC-17b). */
+export declare function findActiveIssues(issues: IssueState[], isAlive: (pid: number) => boolean, cwd?: string): number[];
+/**
+ * Resolve which issue to target.
+ * - Explicit `issue` arg: use as-is.
+ * - Single active run: auto-resolve.
+ * - Zero active runs: error.
+ * - Multiple active runs: error with usage hint.
+ */
+export declare function resolveTargetIssue(args: {
+    explicit: number | null;
+    activeIssues: number[];
+}): {
+    issue: number;
+    reason: "explicit" | "single-active";
+};
+export declare function promptCommand(argsAndOptions: {
+    args: string[];
+    options: PromptCommandOptions;
+}): Promise<void>;

package/dist/src/commands/prompt.js

@@ -0,0 +1,273 @@
+/**
+ * `sequant prompt <issue> "<message>"` — send a message into a running
+ * headless `sequant run` session via the interactive relay (#383).
+ */
+import { existsSync, statSync, readFileSync } from "fs";
+import chalk from "chalk";
+import { RelayMessageTypeSchema, RelayResponseSchema, } from "../lib/relay/types.js";
+import { appendInboxMessage } from "../lib/relay/writer.js";
+import { cleanupStalePid, readPidFile } from "../lib/relay/pid.js";
+import { outboxPathFor } from "../lib/relay/paths.js";
+import { StateManager } from "../lib/workflow/state-manager.js";
+/** Validate raw CLI args. Throws on invalid type or empty message. */
+export function parseRelayPromptArgs(args, options = {}) {
+    // Allowed shapes:
+    //   ["<message>"]           — single arg, auto-resolve issue
+    //   ["<issue>", "<message>"] — both positional
+    let issueArg;
+    let messageArg;
+    if (args.length === 1) {
+        messageArg = args[0];
+    }
+    else if (args.length >= 2) {
+        issueArg = args[0];
+        messageArg = args.slice(1).join(" ");
+    }
+    else {
+        throw new Error('Usage: sequant prompt [issue] "<message>" [--type TYPE]');
+    }
+    if (!messageArg || messageArg.trim() === "") {
+        throw new Error("Message cannot be empty");
+    }
+    let issue = null;
+    if (issueArg !== undefined) {
+        const n = Number.parseInt(issueArg, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`Invalid issue number: '${issueArg}'`);
+        }
+        issue = n;
+    }
+    const rawType = options.type ?? "query";
+    const parsedType = RelayMessageTypeSchema.safeParse(rawType);
+    if (!parsedType.success) {
+        throw new Error(`Invalid --type '${rawType}'. Valid values: query, directive, abort.`);
+    }
+    return { issue, message: messageArg, type: parsedType.data };
+}
+/** Identify candidate active runs for auto-resolution (AC-17b). */
+export function findActiveIssues(issues, isAlive, cwd = process.cwd()) {
+    const active = [];
+    for (const issue of issues) {
+        if (issue.status !== "in_progress")
+            continue;
+        const pid = readPidFile(issue.number, cwd);
+        if (pid !== null && isAlive(pid)) {
+            active.push(issue.number);
+        }
+    }
+    return active;
+}
+/**
+ * Resolve which issue to target.
+ * - Explicit `issue` arg: use as-is.
+ * - Single active run: auto-resolve.
+ * - Zero active runs: error.
+ * - Multiple active runs: error with usage hint.
+ */
+export function resolveTargetIssue(args) {
+    if (args.explicit !== null) {
+        return { issue: args.explicit, reason: "explicit" };
+    }
+    if (args.activeIssues.length === 0) {
+        throw new Error("No active sequant runs found. Start one with `sequant run <issue>` first.");
+    }
+    if (args.activeIssues.length > 1) {
+        const list = args.activeIssues.map((n) => `#${n}`).join(", ");
+        throw new Error(`Multiple active runs: ${list}. Specify an issue number.\n` +
+            `Usage: sequant prompt ${args.activeIssues[0]} "your message"`);
+    }
+    return { issue: args.activeIssues[0], reason: "single-active" };
+}
+export async function promptCommand(argsAndOptions) {
+    const { args, options } = argsAndOptions;
+    const parsed = parseRelayPromptArgs(args, { type: options.type });
+    // Resolve target issue.
+    const stateManager = new StateManager();
+    let issueState;
+    let issueNumber;
+    if (parsed.issue !== null) {
+        issueNumber = parsed.issue;
+        issueState = await stateManager.getIssueState(issueNumber);
+    }
+    else {
+        const all = stateManager.stateExists()
+            ? Object.values(await stateManager.getAllIssueStates())
+            : [];
+        const { defaultIsPidAlive } = await import("../lib/locks/lock-manager.js");
+        const active = findActiveIssues(all, defaultIsPidAlive);
+        const target = resolveTargetIssue({
+            explicit: null,
+            activeIssues: active,
+        });
+        issueNumber = target.issue;
+        issueState = await stateManager.getIssueState(issueNumber);
+    }
+    // Liveness check — refuse to write to a dead session.
+    const cleanup = cleanupStalePid(issueNumber);
+    if (cleanup.warning) {
+        // Also reflect deactivation in state.
+        if (issueState?.relay) {
+            try {
+                await stateManager.setRelayState(issueNumber, null);
+            }
+            catch {
+                /* swallow */
+            }
+        }
+        if (options.json) {
+            console.log(JSON.stringify({
+                ok: false,
+                issue: issueNumber,
+                error: cleanup.warning,
+            }));
+        }
+        else {
+            console.error(chalk.yellow(cleanup.warning));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    if (!cleanup.alive) {
+        const msg = `No relay PID found for #${issueNumber}. Is the run active?`;
+        if (options.json) {
+            console.log(JSON.stringify({ ok: false, issue: issueNumber, error: msg }));
+        }
+        else {
+            console.error(chalk.yellow(msg));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // Write to inbox (the worktree path is recorded in IssueState).
+    const message = appendInboxMessage(issueNumber, {
+        type: parsed.type,
+        ...(parsed.type === "abort" && parsed.message.trim() === ""
+            ? {}
+            : { message: parsed.message }),
+    }, { worktreePath: issueState?.worktree });
+    // Increment relay messageCount in state.
+    try {
+        await stateManager.incrementRelayMessageCount(issueNumber, 1);
+    }
+    catch {
+        /* swallow */
+    }
+    // Re-fetch state with a fresh manager to bypass any cached snapshot from
+    // the start-of-command read. Without this, `currentPhase` shown in the
+    // confirmation can be a phase-old (#645, Gap 6: user reported "exec phase"
+    // while state.json had advanced to qa).
+    let freshPhase;
+    let freshStartedAt;
+    try {
+        const freshState = await new StateManager().getIssueState(issueNumber);
+        freshPhase = freshState?.currentPhase;
+        freshStartedAt = freshState?.relay?.startedAt;
+    }
+    catch {
+        // Fall back to the issueState we already have.
+        freshPhase = issueState?.currentPhase;
+        freshStartedAt = issueState?.relay?.startedAt;
+    }
+    let elapsedSegment = "";
+    if (freshStartedAt) {
+        const ms = Date.now() - new Date(freshStartedAt).getTime();
+        elapsedSegment = `, ${formatElapsed(ms)} elapsed`;
+    }
+    // Omit the phase label when we don't have a fresh reading (#645, Gap 6) —
+    // a wrong phase is worse than no phase. Callers asking for JSON still get
+    // an explicit `phase: null` for that case.
+    const phaseSegment = freshPhase
+        ? ` (${freshPhase} phase${elapsedSegment})`
+        : "";
+    const confirmation = `Message sent to #${issueNumber}${phaseSegment}`;
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            issue: issueNumber,
+            messageId: message.id,
+            type: parsed.type,
+            phase: freshPhase ?? null,
+        }));
+    }
+    else {
+        console.log(chalk.green(confirmation));
+    }
+    // Optional --wait: poll outbox for a reply that references our message id.
+    // Times out with exit 1 if no matching reply lands within the window.
+    if (typeof options.waitSeconds === "number" &&
+        options.waitSeconds > 0 &&
+        parsed.type !== "abort") {
+        const reply = await waitForReply({
+            issueNumber,
+            worktreePath: issueState?.worktree,
+            inReplyTo: message.id,
+            timeoutMs: options.waitSeconds * 1000,
+            pollIntervalMs: options.waitPollIntervalMs ?? 250,
+        });
+        if (reply) {
+            if (options.json) {
+                console.log(JSON.stringify({ ok: true, reply }));
+            }
+            else {
+                console.log(chalk.cyan(`Reply: ${reply.message}`));
+            }
+        }
+        else {
+            const msg = `No reply received within ${options.waitSeconds}s. Message may be archived without a response.`;
+            if (options.json) {
+                console.log(JSON.stringify({ ok: false, timeout: true, error: msg }));
+            }
+            else {
+                console.error(chalk.yellow(msg));
+            }
+            process.exitCode = 1;
+        }
+    }
+}
+async function waitForReply(options) {
+    const outboxPath = outboxPathFor(options.issueNumber, {
+        worktreePath: options.worktreePath,
+    });
+    // Seed offset at current EOF: only NEW replies count for this prompt's wait.
+    let offset = existsSync(outboxPath) ? statSync(outboxPath).size : 0;
+    let partial = "";
+    const deadline = Date.now() + options.timeoutMs;
+    while (Date.now() < deadline) {
+        if (existsSync(outboxPath)) {
+            try {
+                const size = statSync(outboxPath).size;
+                if (size > offset) {
+                    const chunk = readFileSync(outboxPath, "utf-8").slice(offset);
+                    offset = size;
+                    const lines = (partial + chunk).split("\n");
+                    partial = lines.pop() ?? "";
+                    for (const line of lines) {
+                        if (line.trim() === "")
+                            continue;
+                        try {
+                            const parsed = RelayResponseSchema.safeParse(JSON.parse(line));
+                            if (parsed.success &&
+                                parsed.data.inReplyTo === options.inReplyTo) {
+                                return parsed.data;
+                            }
+                        }
+                        catch {
+                            /* skip malformed */
+                        }
+                    }
+                }
+            }
+            catch {
+                /* transient — try again */
+            }
+        }
+        await new Promise((r) => setTimeout(r, options.pollIntervalMs));
+    }
+    return null;
+}
+function formatElapsed(ms) {
+    const totalSec = Math.max(0, Math.floor(ms / 1000));
+    const minutes = Math.floor(totalSec / 60);
+    const seconds = totalSec % 60;
+    return `${minutes}m ${seconds}s`;
+}