commandmate 0.48.0 → 0.49.1

package/dist/cli/commands/wait-timing.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * wait Command - poll interval and the deadline arithmetic of a poll
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeadlineReached = exports.POLL_INTERVAL_MS = void 0;
+exports.nextPollWithinDeadlines = nextPollWithinDeadlines;
+exports.msBeforeDeadlines = msBeforeDeadlines;
+exports.readWithinDeadlines = readWithinDeadlines;
+exports.sleep = sleep;
+/** [IA3-02] Polling interval 5 seconds (matches tmux-capture-cache TTL=2s) */
+exports.POLL_INTERVAL_MS = 5000;
+/**
+ * Whether one more poll interval still lands inside `--timeout` and
+ * `--stall-timeout` (Issue #2463).
+ *
+ * The Auto-Yes hold asks before it sleeps. Otherwise a caller whose deadline
+ * lapses during the hold would hear 124 about a prompt it used to hear 10 about:
+ * the hold is there to give Auto-Yes a chance to answer, not to turn an open
+ * prompt into a timeout. The same two checks the top of {@link pollWorktree}'s
+ * loop makes, one interval ahead.
+ */
+function nextPollWithinDeadlines(options, startTime, lastActivityTime, now) {
+    const nextPollAt = now + exports.POLL_INTERVAL_MS;
+    if (options.timeout && nextPollAt - startTime >= options.timeout * 1000)
+        return false;
+    if (options.stallTimeout && nextPollAt - lastActivityTime >= options.stallTimeout * 1000) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Milliseconds left before `--timeout` or `--stall-timeout` would end the wait,
+ * whichever is sooner; `Infinity` when neither is set (Issue #3956).
+ */
+function msBeforeDeadlines(options, startTime, lastActivityTime, now) {
+    let remaining = Infinity;
+    if (options.timeout)
+        remaining = Math.min(remaining, startTime + options.timeout * 1000 - now);
+    if (options.stallTimeout) {
+        remaining = Math.min(remaining, lastActivityTime + options.stallTimeout * 1000 - now);
+    }
+    return remaining;
+}
+/** The longest delay `setTimeout` honours (2^31-1 ms, ~24.8 days). */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Thrown by {@link readWithinDeadlines} when `--timeout` or `--stall-timeout`
+ * ends a read (Issue #3974). Not an `ApiError` and not a failed poll: the poll
+ * loop goes back to its deadline check, which ends the wait with exit 124.
+ */
+class DeadlineReached extends Error {
+    constructor() {
+        super('--timeout/--stall-timeout reached during a read');
+        this.name = 'DeadlineReached';
+    }
+}
+exports.DeadlineReached = DeadlineReached;
+/**
+ * Runs one read of a poll bounded by `--timeout` / `--stall-timeout`
+ * (Issue #3974): the read gets an `AbortSignal` that fires when the sooner of
+ * the two runs out ({@link msBeforeDeadlines}). With neither set, `read` gets no
+ * signal and runs as before (also when the time left is more than a timer can
+ * hold). With no time left, no read is started.
+ *
+ * A read that was aborted — whether it threw (`ApiClient.get`) or swallowed the
+ * failure (`readNewestPromptAt`) — throws {@link DeadlineReached}, so a ledger
+ * that did not answer is a timeout, not "unreadable". Any other failure is
+ * rethrown as it came.
+ */
+async function readWithinDeadlines(options, startTime, lastActivityTime, read) {
+    const budgetMs = msBeforeDeadlines(options, startTime, lastActivityTime, Date.now());
+    // Beyond what a timer can hold (setTimeout fires at once past 2^31-1 ms) the
+    // read is left unbounded, as with no deadline; a later poll is bounded.
+    if (budgetMs > MAX_TIMER_MS)
+        return read();
+    if (budgetMs <= 0)
+        throw new DeadlineReached();
+    const controller = new AbortController();
+    const abortTimer = setTimeout(() => controller.abort(), budgetMs);
+    try {
+        const result = await read(controller.signal);
+        if (controller.signal.aborted)
+            throw new DeadlineReached();
+        return result;
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new DeadlineReached();
+        throw error;
+    }
+    finally {
+        clearTimeout(abortTimer);
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/cli/commands/wait-turn-boundary.d.ts

@@ -0,0 +1,284 @@
+/**
+ * wait Command - turn boundaries: completion basis, turn adoption, self-resume and the prompt ledger
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+import type { WaitOptions } from '../types';
+import type { CurrentOutputResponse } from '../types/api-responses';
+import type { ApiClient } from '../utils/api-client';
+/**
+ * Why `wait` decided the agent was done, printed on the completion line
+ * (Issue #1839).
+ *
+ * `Completed: <id>` used to be the whole story, which made two very different
+ * situations indistinguishable in a log: the agent's own `Stop` hook arrived, or
+ * nothing but the screen said so. The measurement behind this Issue is exactly
+ * that difference — a 529 storm returns Claude to its composer in ~3 s with the
+ * scraper reporting `ready`/`input_prompt` and no `Stop` ever sent — so the
+ * basis belongs next to the verdict rather than in a triage session afterwards.
+ */
+export declare const COMPLETION_BASIS: {
+    /** The agent reported the turn ended, and the report postdates this wait's turn. */
+    readonly HOOK_STOP: "hook_stop";
+    /** The tmux session went away after we had seen it alive. */
+    readonly SESSION_GONE: "session_gone";
+    /** The terminal frame says the agent is back at its composer. Nothing corroborated it. */
+    readonly SCRAPER_READY: "scraper_ready";
+};
+/**
+ * Structured event types that mean "a turn is under way" (Issue #1839).
+ *
+ * Mirrors AGENT_EVENT_TYPES in src/lib/hooks/agent-event-types.ts; duplicated
+ * rather than imported because the CLI bundle keeps its own copy of the API
+ * shapes (see api-responses.ts).
+ *
+ * `notification` is deliberately absent, and that is the one measured deviation
+ * from the design sketched in Issue #1839. The Issue proposed accepting
+ * `stop` **or** `idle_prompt` as the end of a turn; the live capture of
+ * 2026-08-20 (see docs/design/upstream-fault-turn-boundary-1839.md) shows
+ * Claude 2.1.236 emitting `Notification(idle_prompt)` 62 s into a turn that
+ * ran nothing at all, because the composer had been idle for a minute. Reading
+ * it as a turn boundary would have re-created the false completion this gate
+ * exists to stop, one minute later. Only `Stop` ends a turn.
+ *
+ * Exported for the cross-layer pin in
+ * `tests/unit/session/status-contract-1926.test.ts`. The server opens a turn on
+ * the same three events (`src/lib/session/provisional-turn.ts`
+ * TURN_ACTIVITY_EVENTS), and since Issue #1930 `adoptTurnStart` reads that
+ * turn's `openedAt` rather than this set — so a set that drifted would change
+ * this gate silently. The set is still read here for the pre-#1930 fallback
+ * path, and the CLI cannot import the server module (`tsconfig.cli.json` sets
+ * `"paths": {}`), so the test is the only thing holding the two together.
+ */
+export declare const TURN_OPENING_EVENT_TYPES: ReadonlySet<string>;
+/**
+ * Whether this server publishes a real turn record (Issue #1930).
+ *
+ * `dialogPendingMaxMs` landed with the turn model and is set on every payload a
+ * server of that vintage produces, so its presence is the version probe. A
+ * *value* rather than a version string, for the reason #1924 gives for the
+ * capability block: a payload that has to be interpreted by its sender's
+ * version number is a payload nobody can read forward.
+ *
+ * The probe is needed because the two readings below disagree in exactly the
+ * case that matters. On a #1930 server, `openedAt` being null while
+ * `lastEventType` is `user_prompt_submit` means the turn was fenced off by a
+ * generation or aged out — the server has *decided* it is not this instance's
+ * turn. Falling back to the event on such a payload would put back the stale
+ * adoption the turn record exists to remove.
+ */
+export declare function publishesTurnRecord(data: CurrentOutputResponse): boolean;
+/**
+ * Adopt the turn this wait is about, if this poll shows one (Issue #1839,
+ * moved onto the turn record in #1930).
+ *
+ * ## What changed, and why the grace window is no longer the whole guard
+ *
+ * Before #1930 this read `lastEventType` / `lastEventAt` — the newest event of
+ * any kind — and refused anything older than {@link TURN_ADOPTION_GRACE_MS},
+ * because (in the words of that constant) structured events "are NOT fenced by
+ * generation on the way into `structuredEvents`", so a stale
+ * `user_prompt_submit` from a previous agent process could still be the last
+ * event on the wire. The bound was the only thing keeping such a record from
+ * gating a wait for ever.
+ *
+ * The server fences the turn now, and publishes null when it does. So an **open**
+ * turn is adopted whatever its age — which closes a hole the old reading had:
+ * a turn that opened ten minutes before this `wait` started, and is still
+ * running, used to be adopted only because its *newest* event was fresh. An
+ * agent that goes quiet mid-turn (thinking, a long tool call) has no fresh
+ * event, so the #1839 gate came down at exactly the moment a 529 storm would
+ * exploit it.
+ *
+ * A **closed** turn still has to have opened inside this wait's window, and the
+ * reason is the one the grace constant gives: `wait` does not know when `send`
+ * ran, so the last turn of a session that finished an hour ago must not gate a
+ * wait that has only just started. `commandmate wait` on an already-idle
+ * session therefore adopts nothing and completes on its first poll, exactly as
+ * it did before — #1975 measured that at 234/242/259 ms and it is the
+ * orchestrator's normal path.
+ *
+ * @param previous - the turn start adopted so far, or null
+ * @returns the newest adopted turn start, or `previous` when nothing qualified
+ */
+export declare function adoptTurnStart(data: CurrentOutputResponse, waitStartedAt: number, previous: number | null): number | null;
+/**
+ * `structuredEvents.closedBy`, phrased for a diagnostic line (Issue #1930).
+ *
+ * The server's close-reason vocabulary and {@link COMPLETION_BASIS} answer two
+ * different questions — "why did the turn end" and "what did `wait` decide on"
+ * — and are deliberately printed side by side rather than folded together.
+ * `hook_stop` is the only place they meet: it is `closedBy: 'stop'` seen from
+ * the CLI's end. Everything else (`stale`, `scraper_evidence`, `session_end`,
+ * `generation`, `resync_idle`) is a reason the turn stopped being trusted, which
+ * is precisely what `wait` must NOT read as completion.
+ */
+export declare function describeTurnClose(data: CurrentOutputResponse): string;
+/**
+ * Whether the agent has reported the end of the turn this wait adopted
+ * (Issue #1839).
+ *
+ * True when no turn was adopted at all, which is the whole of the unchanged
+ * path: a session whose agent posts no hooks never adopts one, so every caller
+ * on a machine without hook injection sees precisely the pre-#1839 behaviour.
+ */
+export declare function turnSettled(data: CurrentOutputResponse, turnStartedAt: number | null): boolean;
+/**
+ * How long `wait` will hold a composer frame open for an agent that has been
+ * handed a prompt it has not reported the end of (Issue #1975).
+ *
+ * The hold's *reason* is exact — see {@link outstandingPrompt} — so this is not
+ * a settling window standing in for evidence. It is the bound the contract of
+ * this Issue asks for: hooks are fail-open on every path, so a `Stop` that is
+ * simply lost (the receiver was restarted, the machine-wide
+ * `~/.copilot/settings.json` was rewritten by another server mid-session, the
+ * 4-second curl in the hook timed out) must not turn `wait` into a command that
+ * never returns. After this it completes on the frame alone, exactly as it did
+ * before this Issue, and says so.
+ *
+ * 60s is the same dwell {@link UNCLASSIFIED_DWELL_MS} uses for the same job, and
+ * it is ~55x the widest send-to-turn-open window measured for this Issue
+ * (2026-08-22, copilot 1.0.80 against an isolated server: 0.04s / 0.75s / 0.88s
+ * / 1.10s over four sends, the last of them a cold session start). `--timeout`
+ * and `--stall-timeout` below 60s still win, as they do for the unclassified
+ * dwell: this pre-empts long waits, it does not extend short ones.
+ */
+export declare const PENDING_PROMPT_HOLD_MS = 60000;
+/**
+ * Whether this tool's event source claims it can report both ends of a turn
+ * (Issue #1975).
+ *
+ * The gate that keeps the hold below off every path it has no evidence for.
+ * `structuredEvents.source.capabilities` is #1924's declaration, published to
+ * the CLI already, and the compatibility source a tool with no implementation
+ * gets (`src/lib/hooks/sources/legacy-relay.ts`) declares `supportedEvents: []`
+ * — so a tool that posts no hooks answers `false` here and takes precisely the
+ * pre-#1975 path. So does a server older than #1924, which sends no `source` at
+ * all.
+ *
+ * Both words are required. Without a turn-opening word nothing would ever open
+ * the turn this waits for; without `stop` nothing could ever close it, and the
+ * hold would only ever end at its own bound.
+ */
+export declare function reportsTurnBoundaries(data: CurrentOutputResponse): boolean;
+/**
+ * The `stop` detail meaning "the agent ended its turn with its own background
+ * work still running, and resumes by itself when that work finishes"
+ * (Issue #2614).
+ *
+ * A copy of `SELF_RESUME_PENDING_DETAIL` in `src/lib/hooks/agent-event-types.ts`
+ * for the reason {@link TURN_OPENING_EVENT_TYPES} is a copy: the CLI builds with
+ * `"paths": {}`. `tests/unit/cli/commands/wait-self-resume-2614.test.ts` pins the
+ * two together.
+ */
+export declare const SELF_RESUME_PENDING_DETAIL = "self_resume_pending";
+/**
+ * The capability a source declares when its `stop` can carry
+ * {@link SELF_RESUME_PENDING_DETAIL} (Issue #2614).
+ *
+ * Read by name rather than through the mirrored type in `api-responses.ts`,
+ * which predates it: `structuredEvents.source.capabilities` is published as the
+ * source's whole declaration, so a newer server sends the key and an older one
+ * simply does not.
+ */
+export declare const SELF_RESUME_CAPABILITY = "stopReportsSelfResume";
+/**
+ * How long `wait` holds a `stop` whose agent said it would resume by itself
+ * (Issue #2614).
+ *
+ * Measured 2026-09-17 against antigravity 1.2.4: a `schedule` of 60 s closed the
+ * turn, the agent woke 58 s after its `Stop` and did it again three more times,
+ * and the real end came five minutes after the first `Stop` — which is where
+ * `wait` had already reported `Completed (basis=hook_stop)` and started a
+ * verification against a half-finished worktree. The wake is not something to
+ * time: it is a `post_tool_use` that opens a new turn, and #1839's gate takes
+ * over from there. What needs a bound is only the case where it never comes.
+ *
+ * A timer's own length is not on the wire (the `schedule` arguments reach the
+ * permission receiver and stop there), and a command sent to the background has
+ * no length at all, so the bound is the one the server already uses for the
+ * same question the other way round: how long an open turn is trusted with
+ * nothing heard (`TURN_STALE_AFTER_MS` in `src/lib/session/provisional-turn.ts`,
+ * pinned equal by `wait-self-resume-2614.test.ts`). Every wake starts a new
+ * `stop` and a new hold, so an agent that keeps rescheduling never reaches it.
+ *
+ * A constant, like {@link PENDING_PROMPT_HOLD_MS}: `--timeout` and
+ * `--stall-timeout` below it still win.
+ */
+export declare const SELF_RESUME_HOLD_MS: number;
+/**
+ * The instant of the `stop` this agent said it would resume from, or null
+ * (Issue #2614).
+ *
+ * Non-null only while that `stop` is still the newest thing the agent has said.
+ * The wake is a `post_tool_use` (antigravity reports the timer's own tool call
+ * finishing when it fires), which replaces the displayed event and opens a new
+ * turn, so this answers null from the first poll after it — and a later `stop`
+ * is a different instant, which is how a hold knows it is about a new one.
+ *
+ * On a server that publishes a turn record the `stop` must also be what closed
+ * that turn: a turn ended by `generation` or `session_end` belongs to a process
+ * that is gone, and nothing it scheduled is going to wake anything.
+ */
+export declare function pendingSelfResumeStop(data: CurrentOutputResponse): number | null;
+/** What the chat ledger could tell us about the newest prompt (Issue #1975). */
+export type PromptLedgerRead = 
+/** Epoch ms of the newest prompt sent to this instance, or null if it has had none. */
+{
+    readable: true;
+    submittedAt: number | null;
+}
+/** The ledger could not be read. Not a verdict — see the call site. */
+ | {
+    readable: false;
+};
+/**
+ * When this (worktree, instance) was last handed a prompt (Issue #1975).
+ *
+ * `limit=1&unit=pairs` is "every row at or after the newest user message"
+ * (src/lib/db/chat-db.ts), which is the smallest query that is *guaranteed* to
+ * contain that message: plain `limit=1` returns the newest row of either role,
+ * and for a turn the agent has already answered that row is the assistant's.
+ *
+ * Scoped the same way the poll above is: `--instance` when the caller named one,
+ * otherwise the `cliToolId` the server resolved for that same poll. Asking
+ * unscoped would let a message sent to claude decide a wait on codex.
+ *
+ * Never throws. An unreadable ledger is not evidence that nothing was sent, so
+ * it is reported as such rather than as "nothing was sent" — the call site
+ * degrades to the pre-#1975 behaviour instead of holding on a guess.
+ *
+ * `quietWhenAborted` (Issue #3974): a read aborted by `signal` prints no note,
+ * for a caller that says what an aborted read leads to itself; other failures
+ * print it as before.
+ */
+export declare function readNewestPromptAt(client: ApiClient, worktreeId: string, options: WaitOptions, data: CurrentOutputResponse, signal?: AbortSignal, quietWhenAborted?: boolean): Promise<PromptLedgerRead>;
+/**
+ * Whether the newest prompt this instance was handed is still unanswered
+ * (Issue #1975).
+ *
+ * This is the distinction the whole Issue turns on, and it is a comparison of
+ * two server-stamped facts rather than a timer:
+ *
+ *   - **idle before this wait began** — the agent's `Stop` postdates the newest
+ *     prompt. Nothing is outstanding; `wait` completes on the first poll exactly
+ *     as it always has. An orchestrator waiting on a session that finished long
+ *     ago pays nothing.
+ *   - **`send` a moment ago** — the newest prompt postdates the last `Stop`
+ *     (or there has never been one). The agent has been given work and has not
+ *     reported finishing it, so a composer frame is "it has not started yet",
+ *     not "it is done".
+ *
+ * `wait` could not tell these apart before, because from `current-output` alone
+ * they are the same payload: in both, the last thing the agent said was the
+ * previous turn's `stop`, and `adoptTurnStart` adopts nothing. Measured against
+ * copilot 1.0.80 on 2026-08-22, the window in which that is true after a send is
+ * ~1s wide, and `wait`'s first poll is immediate — which is why the false
+ * completions came back in 0.3s with `basis=scraper_ready`, 3 times in 5.
+ *
+ * The fast-turn case falls out of the same comparison rather than needing a rule
+ * of its own: a turn that opens and closes between two polls leaves
+ * `lastEventType: 'stop'` (so no turn is adopted) but a `stop` that postdates
+ * the prompt — answered, and completed on the spot.
+ */
+export declare function outstandingPrompt(data: CurrentOutputResponse, submittedAt: number): boolean;
+//# sourceMappingURL=wait-turn-boundary.d.ts.map

package/dist/cli/commands/wait-turn-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-turn-boundary.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-turn-boundary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,qBAAqB,EAAyB,MAAM,wBAAwB,CAAC;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB;IAC3B,oFAAoF;;IAEpF,6DAA6D;;IAE7D,0FAA0F;;CAElF,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AAwBH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAExE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,qBAAqB,EAC3B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,MAAM,GAAG,IAAI,CAuBf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAMrE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAI9F;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAO1E;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAkBlD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAShF;AAED,gFAAgF;AAChF,MAAM,MAAM,gBAAgB;AAC1B,uFAAuF;AACrF;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AAChD,uEAAuE;GACrE;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAC;AAExB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,qBAAqB,EAC3B,MAAM,CAAC,EAAE,WAAW,EACpB,gBAAgB,UAAQ,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAgC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAG3F"}