@prohost/cli 0.2.3 → 0.3.0

package/dist/agent/contract.js

@@ -13,6 +13,7 @@
  * Server-side sources of truth:
  *   - payload shape — `shared/events/payloads/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/complete` — `api_public/routers/agent_runs.py`
+ *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
@@ -28,6 +29,23 @@ export const RUN_STATUS_SUCCEEDED = 'succeeded';
 export const RUN_STATUS_FAILED = 'failed';
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export const MAX_ERROR_CHARS = 1000;
+/**
+ * The completion `error` that means "a person asked for this run to stop".
+ *
+ * A magic string on purpose, and it must be sent **exactly**: the server
+ * matches on it to word the notice it drops in the thread ("cancelled" rather
+ * than "failed"). Prefixing it with a reason, or sending
+ * `cancelled_by_user: …`, makes a deliberate stop read as a crash.
+ */
+export const RUN_ERROR_CANCELLED_BY_USER = 'cancelled_by_user';
+/**
+ * Cap on the `progress` string sent with a heartbeat.
+ *
+ * Progress is a hint for the UI — "using Bash", the first line of what the
+ * agent is drafting — not a transcript. Bounded here so a brain that emits one
+ * enormous block of text can't turn a keep-alive into a payload.
+ */
+export const MAX_PROGRESS_CHARS = 200;
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export const REDEEM_PATH = '/v1/agent-pairing/redeem';
 /** `POST` — send a message into a conversation as the paired agent. */
@@ -38,6 +56,35 @@ export function conversationMessagesPath(conversationId) {
 export function agentRunCompletePath(runId) {
     return `/v1/agent-runs/${encodeURIComponent(runId)}/complete`;
 }
+/**
+ * `POST` — say a run is still alive, and hear back whether it was cancelled.
+ *
+ * The server holds a lease on every running row and reaps the ones that stop
+ * being heard from; a run that legitimately takes four hours has to say so on a
+ * cadence or it is reaped mid-work. The response also carries
+ * `cancel_requested`, which is the only way a laptop behind NAT learns that
+ * somebody pressed stop.
+ */
+export function agentRunHeartbeatPath(runId) {
+    return `/v1/agent-runs/${encodeURIComponent(runId)}/heartbeat`;
+}
+/**
+ * Where this run's heartbeats go.
+ *
+ * Derived from the server-supplied completion path rather than rebuilt from the
+ * run id, on the same reasoning the rest of this module prefers server-supplied
+ * paths: the two calls are the same resource, so a server that moves its
+ * agent-run routes moves both together and this CLI follows without a release.
+ * The documented path is the fallback for a completion path shaped in some way
+ * we don't recognise.
+ */
+export function heartbeatPathFor(run) {
+    const completion = run.completion_path;
+    const suffix = '/complete';
+    return completion.endsWith(suffix)
+        ? `${completion.slice(0, -suffix.length)}/heartbeat`
+        : agentRunHeartbeatPath(run.run_id);
+}
 /**
  * Ceiling on how many context entries are kept from one payload.
  *

package/dist/agent/exec.d.ts

@@ -17,12 +17,36 @@ export interface ExecOptions {
     command: string;
     /** Prompt written to the child's stdin. */
     prompt: string;
-    /** Hard cap on wall-clock runtime. */
+    /**
+     * Hard cap on wall-clock runtime.
+     *
+     * ``0`` disables it: the child then runs until it exits on its own, until
+     * {@link cancelSignal} fires, or until the server gives up on the run. That
+     * is a real configuration (`--timeout 0`), not a degenerate one — some work
+     * genuinely takes hours and a local clock is the wrong thing to bound it by.
+     */
     timeoutMs: number;
     /** Working directory for the child. Defaults to the CLI's cwd. */
     cwd?: string;
     /** Extra environment for the child, merged over ``process.env``. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Ends the run early — a person pressed stop, or the server closed the run.
+     *
+     * Terminated through exactly the same SIGTERM → grace → SIGKILL path a
+     * timeout uses, because the problem is identical: the thing being stopped is
+     * a process *group* that may be ignoring polite signals.
+     */
+    cancelSignal?: AbortSignal;
+    /**
+     * Each stdout chunk, as it arrives.
+     *
+     * The captured ``stdout`` is still returned in full; this exists for the
+     * things that cannot wait for the process to exit — reading a session id out
+     * of the first event, tracking what the agent is doing for the heartbeat, and
+     * having *something* to salvage from a run that gets killed.
+     */
+    onStdout?: (chunk: string) => void;
     /** Injectable spawn — tests substitute a fake process. */
     spawnImpl?: typeof spawn;
 }
@@ -32,17 +56,31 @@ export interface ExecResult {
     stderr: string;
     exitCode: number | null;
     timedOut: boolean;
+    /** The run was stopped through {@link ExecOptions.cancelSignal}. */
+    cancelled: boolean;
     /** Populated when the process could not be started at all. */
     error?: string;
     durationMs: number;
 }
 /** Cap on captured output (in characters) so a runaway agent can't exhaust memory. */
 export declare const MAX_OUTPUT_CHARS: number;
+/** ``error`` on a result the caller stopped deliberately. */
+export declare const CANCELLED_ERROR = "cancelled";
+/**
+ * What a timed-out run reports.
+ *
+ * Ends with the way out, because this string does not stay in `agent.log`: the
+ * server echoes a failed run's error into the thread, so the person who was
+ * waiting reads it. Told "timed out after 7200000ms" they learn only that
+ * something broke; told how to raise the ceiling they can fix it themselves.
+ * Kept to one line for the same reason.
+ */
+export declare function timeoutMessage(timeoutMs: number): string;
 /**
  * Execute the agent command with ``prompt`` on stdin and return its stdout.
  *
- * Never throws: a spawn failure, a non-zero exit, and a timeout all come back
- * as ``ok: false`` with the detail filled in, because the caller must report
- * *some* outcome to the server for every run.
+ * Never throws: a spawn failure, a non-zero exit, a timeout, and a cancellation
+ * all come back as ``ok: false`` with the detail filled in, because the caller
+ * must report *some* outcome to the server for every run.
  */
 export declare function execAgent(options: ExecOptions): Promise<ExecResult>;

package/dist/agent/exec.js

@@ -11,11 +11,25 @@
  * comes from the host's own flag — but event-derived text never reaches the
  * shell, so a crafted mention cannot inject a command.
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 /** Cap on captured output (in characters) so a runaway agent can't exhaust memory. */
 export const MAX_OUTPUT_CHARS = 512 * 1024;
-/** Grace period between SIGTERM and SIGKILL when a run overruns its timeout. */
+/** Grace period between SIGTERM and SIGKILL when a run is being stopped. */
 const KILL_GRACE_MS = 5_000;
+/** ``error`` on a result the caller stopped deliberately. */
+export const CANCELLED_ERROR = 'cancelled';
+/**
+ * What a timed-out run reports.
+ *
+ * Ends with the way out, because this string does not stay in `agent.log`: the
+ * server echoes a failed run's error into the thread, so the person who was
+ * waiting reads it. Told "timed out after 7200000ms" they learn only that
+ * something broke; told how to raise the ceiling they can fix it themselves.
+ * Kept to one line for the same reason.
+ */
+export function timeoutMessage(timeoutMs) {
+    return `timed out after ${timeoutMs}ms — raise the ceiling with --timeout <seconds> (0 = no limit)`;
+}
 function clamp(text) {
     if (text.length <= MAX_OUTPUT_CHARS)
         return text;
@@ -24,9 +38,9 @@ function clamp(text) {
 /**
  * Execute the agent command with ``prompt`` on stdin and return its stdout.
  *
- * Never throws: a spawn failure, a non-zero exit, and a timeout all come back
- * as ``ok: false`` with the detail filled in, because the caller must report
- * *some* outcome to the server for every run.
+ * Never throws: a spawn failure, a non-zero exit, a timeout, and a cancellation
+ * all come back as ``ok: false`` with the detail filled in, because the caller
+ * must report *some* outcome to the server for every run.
  */
 export async function execAgent(options) {
     const spawnImpl = options.spawnImpl ?? spawn;
@@ -35,7 +49,23 @@ export async function execAgent(options) {
         let stdout = '';
         let stderr = '';
         let timedOut = false;
+        let cancelled = false;
         let settled = false;
+        // Nothing to stop if the stop already happened: a run cancelled while it
+        // sat in the queue must not spawn the agent at all.
+        if (options.cancelSignal?.aborted) {
+            resolve({
+                ok: false,
+                stdout: '',
+                stderr: '',
+                exitCode: null,
+                timedOut: false,
+                cancelled: true,
+                error: CANCELLED_ERROR,
+                durationMs: Date.now() - started,
+            });
+            return;
+        }
         const spawnOptions = {
             shell: true,
             cwd: options.cwd,
@@ -58,27 +88,52 @@ export async function execAgent(options) {
                 stderr: '',
                 exitCode: null,
                 timedOut: false,
+                cancelled: false,
                 error: err instanceof Error ? err.message : String(err),
                 durationMs: Date.now() - started,
             });
             return;
         }
+        let timer;
         let killTimer;
+        /** Why the run ended, when it ended because we ended it. */
+        const stopReason = () => cancelled ? CANCELLED_ERROR : timedOut ? timeoutMessage(options.timeoutMs) : undefined;
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
-            clearTimeout(timer);
+            if (timer !== undefined)
+                clearTimeout(timer);
             if (killTimer !== undefined)
                 clearTimeout(killTimer);
+            options.cancelSignal?.removeEventListener('abort', onAbort);
             resolve({ ...result, durationMs: Date.now() - started });
         };
         /**
-         * Signal the child's whole process group, falling back to the child alone
-         * when there is no group (Windows, or a spawn that never got a pid).
+         * Signal the child's whole process tree.
+         *
+         * POSIX: the child has its own process group (see `detached` above), so one
+         * signal reaches the shell and everything it started.
+         *
+         * Windows has no process groups to signal, and `shell: true` means the
+         * child is `cmd.exe` — killing it alone leaves the agent it launched
+         * running, which is a run reported as stopped that carries on acting with
+         * the operator's credentials. `taskkill /T` walks the tree instead, with
+         * `/F` as the SIGKILL half of the escalation. It is best-effort: if
+         * `taskkill` is missing or refuses, the fallback below still kills the
+         * shell, which is exactly what this did before.
          */
         const signalTree = (signal) => {
             const pid = child.pid;
+            if (pid !== undefined && process.platform === 'win32') {
+                try {
+                    const args = ['/pid', String(pid), '/T', ...(signal === 'SIGKILL' ? ['/F'] : [])];
+                    spawnSync('taskkill', args, { windowsHide: true });
+                }
+                catch {
+                    // Fall through — the child itself is still signalled below.
+                }
+            }
             try {
                 if (pid !== undefined && spawnOptions.detached)
                     process.kill(-pid, signal);
@@ -89,11 +144,18 @@ export async function execAgent(options) {
                 // ESRCH — the group is already gone, which is the outcome we wanted.
             }
         };
-        const timer = setTimeout(() => {
-            timedOut = true;
+        /**
+         * End the run: ask politely, then insist.
+         *
+         * The single path for both reasons a run is stopped from outside. They need
+         * identical handling — an agent that ignores SIGTERM ignores it whoever
+         * sent it — and having one caller escalate and the other not is how a
+         * cancelled run wedges the queue behind a child that never died.
+         */
+        const terminate = () => {
+            if (settled || killTimer !== undefined)
+                return;
             signalTree('SIGTERM');
-            // Escalate if the agent ignores SIGTERM, so a wedged child can't hold
-            // the harness open past its timeout.
             killTimer = setTimeout(() => {
                 signalTree('SIGKILL');
                 // A descendant can still hold the pipes open after the group is
@@ -104,14 +166,36 @@ export async function execAgent(options) {
                     stdout: clamp(stdout),
                     stderr: clamp(stderr),
                     exitCode: null,
-                    timedOut: true,
-                    error: `timed out after ${options.timeoutMs}ms`,
+                    timedOut,
+                    cancelled,
+                    error: stopReason(),
                 });
             }, KILL_GRACE_MS);
-        }, options.timeoutMs);
+        };
+        function onAbort() {
+            cancelled = true;
+            terminate();
+        }
+        if (options.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                terminate();
+            }, options.timeoutMs);
+        }
+        options.cancelSignal?.addEventListener('abort', onAbort, { once: true });
         child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString();
+            // Capture is bounded; the callback is not. A parser that stops being fed
+            // at 512 KB would report stale progress and salvage the wrong text for
+            // the rest of a long run — and the callback keeps nothing per chunk.
             if (stdout.length < MAX_OUTPUT_CHARS)
-                stdout += chunk.toString();
+                stdout += text;
+            try {
+                options.onStdout?.(text);
+            }
+            catch {
+                // A broken observer must not cost the run its output.
+            }
         });
         child.stderr?.on('data', (chunk) => {
             if (stderr.length < MAX_OUTPUT_CHARS)
@@ -124,17 +208,19 @@ export async function execAgent(options) {
                 stderr: clamp(stderr),
                 exitCode: null,
                 timedOut,
+                cancelled,
                 error: err.message,
             });
         });
         child.on('close', (code) => {
             finish({
-                ok: !timedOut && code === 0,
+                ok: !timedOut && !cancelled && code === 0,
                 stdout: clamp(stdout),
                 stderr: clamp(stderr),
                 exitCode: code,
                 timedOut,
-                error: timedOut ? `timed out after ${options.timeoutMs}ms` : undefined,
+                cancelled,
+                error: stopReason(),
             });
         });
         // stdin may already be closed if the command failed to start.

package/dist/agent/heartbeat.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Keeps long runs alive, and is how a laptop hears "stop".
+ *
+ * The server holds a lease on every `running` agent-run row and reaps the ones
+ * that go quiet, because the alternative — trusting a laptop to always report —
+ * leaves rows spinning forever whenever someone closes a lid. A run that
+ * legitimately takes four hours therefore has to say so on a cadence.
+ *
+ * The response is the other half: this CLI dials *out* over a websocket and
+ * accepts no inbound connections, so the heartbeat's `cancel_requested` flag is
+ * the only channel by which "somebody pressed stop in the UI" can reach a
+ * machine behind NAT.
+ *
+ * Two properties this module is written around:
+ *
+ * * **Every accepted run beats, not just the executing one.** Runs are
+ *   serialized, so a run queued behind a four-hour job sits `running`
+ *   server-side for four hours without a single line of work being done on it.
+ *   Beating only for the executing run would have the server reap the queue.
+ * * **It never takes the daemon down.** A heartbeat is bookkeeping. Every
+ *   failure mode — an old server that 404s, a dropped network, a handler that
+ *   throws — costs at most the beat it happened on.
+ */
+import type { ApiOptions } from './api.js';
+/**
+ * How often each open run is reported.
+ *
+ * Well inside any sane server-side lease so a run survives losing a beat or
+ * two to a flaky link, and long enough that a queue of runs is a trickle of
+ * requests rather than a load source.
+ */
+export declare const HEARTBEAT_INTERVAL_MS = 60000;
+/** A cancelled timer. Returned by {@link Scheduler} implementations. */
+export interface ScheduledTick {
+    cancel(): void;
+}
+/**
+ * Deferred execution, injectable so tests drive the loop rather than wait it
+ * out. The default unrefs its timer: a heartbeat loop must never be the reason
+ * a process refuses to exit.
+ */
+export type Scheduler = (run: () => void, ms: number) => ScheduledTick;
+/** One run the loop is beating for. */
+export interface HeartbeatTarget {
+    /** Where the heartbeat POSTs — see `heartbeatPathFor`. */
+    path: string;
+    /**
+     * Latest one-line description of what the agent is doing, read fresh at each
+     * beat. Absent for a queued run, and for brains whose output we don't stream.
+     */
+    progress?: () => string | undefined;
+    /**
+     * The server wants this run stopped. Called at most once, and never again
+     * beaten for.
+     */
+    onCancelRequested: () => void | Promise<void>;
+    /**
+     * The server has already closed this run out (409) — reaped, or resolved by
+     * someone else. Called at most once. The work in flight is now pointless:
+     * whatever it produces has nowhere to go.
+     */
+    onResolved: () => void | Promise<void>;
+}
+export interface HeartbeatLoopOptions {
+    api: ApiOptions;
+    log: (line: string) => void;
+    /** Defaults to {@link HEARTBEAT_INTERVAL_MS}. */
+    intervalMs?: number;
+    /** Defaults to an unref'd `setTimeout`. */
+    scheduler?: Scheduler;
+}
+/**
+ * Beats for every open run on a fixed cadence.
+ *
+ * Idle when nothing is tracked — no timer is armed at all — so a harness that
+ * never receives a run makes no requests, and the first {@link track} starts
+ * the cadence.
+ */
+export declare class HeartbeatLoop {
+    private readonly options;
+    private readonly targets;
+    private readonly intervalMs;
+    private readonly scheduler;
+    private pending;
+    private stopped;
+    /** A tick in flight. Ticks never overlap; a slow one delays the next. */
+    private ticking;
+    constructor(options: HeartbeatLoopOptions);
+    /** Begin beating for a run. Idempotent on ``runId``. */
+    track(runId: string, target: HeartbeatTarget): void;
+    /** Stop beating for a run — it reached a terminal state, one way or another. */
+    untrack(runId: string): void;
+    /** Runs currently being beaten for. Exposed for assertions and logging. */
+    tracked(): string[];
+    /** Stop the loop for good. Called once, when the harness is shutting down. */
+    stop(): void;
+    /**
+     * Beat once for every tracked run.
+     *
+     * Public so tests can drive the cadence directly instead of waiting on a
+     * timer. Beats are issued concurrently: they are independent requests, and
+     * doing them in series would make one slow response delay every run behind it.
+     */
+    tick(): Promise<void>;
+    private arm;
+    private runTick;
+    /**
+     * One run's heartbeat, and what its answer means.
+     *
+     * Wrapped so that a throwing handler — or a fetch implementation that rejects
+     * rather than resolving — costs this run's beat and nothing else.
+     */
+    private beat;
+}

package/dist/agent/heartbeat.js

@@ -0,0 +1,165 @@
+/**
+ * Keeps long runs alive, and is how a laptop hears "stop".
+ *
+ * The server holds a lease on every `running` agent-run row and reaps the ones
+ * that go quiet, because the alternative — trusting a laptop to always report —
+ * leaves rows spinning forever whenever someone closes a lid. A run that
+ * legitimately takes four hours therefore has to say so on a cadence.
+ *
+ * The response is the other half: this CLI dials *out* over a websocket and
+ * accepts no inbound connections, so the heartbeat's `cancel_requested` flag is
+ * the only channel by which "somebody pressed stop in the UI" can reach a
+ * machine behind NAT.
+ *
+ * Two properties this module is written around:
+ *
+ * * **Every accepted run beats, not just the executing one.** Runs are
+ *   serialized, so a run queued behind a four-hour job sits `running`
+ *   server-side for four hours without a single line of work being done on it.
+ *   Beating only for the executing run would have the server reap the queue.
+ * * **It never takes the daemon down.** A heartbeat is bookkeeping. Every
+ *   failure mode — an old server that 404s, a dropped network, a handler that
+ *   throws — costs at most the beat it happened on.
+ */
+import { heartbeatRun } from './api.js';
+/**
+ * How often each open run is reported.
+ *
+ * Well inside any sane server-side lease so a run survives losing a beat or
+ * two to a flaky link, and long enough that a queue of runs is a trickle of
+ * requests rather than a load source.
+ */
+export const HEARTBEAT_INTERVAL_MS = 60_000;
+const defaultScheduler = (run, ms) => {
+    const timer = setTimeout(run, ms);
+    // `unref` exists on Node/Bun timers and not in the DOM lib's typing.
+    timer.unref?.();
+    return { cancel: () => clearTimeout(timer) };
+};
+/**
+ * Beats for every open run on a fixed cadence.
+ *
+ * Idle when nothing is tracked — no timer is armed at all — so a harness that
+ * never receives a run makes no requests, and the first {@link track} starts
+ * the cadence.
+ */
+export class HeartbeatLoop {
+    options;
+    targets = new Map();
+    intervalMs;
+    scheduler;
+    pending;
+    stopped = false;
+    /** A tick in flight. Ticks never overlap; a slow one delays the next. */
+    ticking = false;
+    constructor(options) {
+        this.options = options;
+        this.intervalMs = options.intervalMs ?? HEARTBEAT_INTERVAL_MS;
+        this.scheduler = options.scheduler ?? defaultScheduler;
+    }
+    /** Begin beating for a run. Idempotent on ``runId``. */
+    track(runId, target) {
+        if (this.stopped)
+            return;
+        this.targets.set(runId, { ...target, runId });
+        this.arm();
+    }
+    /** Stop beating for a run — it reached a terminal state, one way or another. */
+    untrack(runId) {
+        this.targets.delete(runId);
+    }
+    /** Runs currently being beaten for. Exposed for assertions and logging. */
+    tracked() {
+        return [...this.targets.keys()];
+    }
+    /** Stop the loop for good. Called once, when the harness is shutting down. */
+    stop() {
+        this.stopped = true;
+        this.targets.clear();
+        this.pending?.cancel();
+        this.pending = undefined;
+    }
+    /**
+     * Beat once for every tracked run.
+     *
+     * Public so tests can drive the cadence directly instead of waiting on a
+     * timer. Beats are issued concurrently: they are independent requests, and
+     * doing them in series would make one slow response delay every run behind it.
+     */
+    async tick() {
+        const targets = [...this.targets.values()];
+        await Promise.all(targets.map((target) => this.beat(target)));
+    }
+    arm() {
+        if (this.stopped || this.pending || this.ticking || this.targets.size === 0)
+            return;
+        this.pending = this.scheduler(() => {
+            this.pending = undefined;
+            void this.runTick();
+        }, this.intervalMs);
+    }
+    async runTick() {
+        this.ticking = true;
+        try {
+            await this.tick();
+        }
+        catch (err) {
+            // `tick` already contains every beat's failure; reaching here means the
+            // bookkeeping around them broke. Say so and keep the cadence — a harness
+            // that stops beating because of a bug here silently loses every long run.
+            this.options.log(`    ! heartbeat loop error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            this.ticking = false;
+            this.arm();
+        }
+    }
+    /**
+     * One run's heartbeat, and what its answer means.
+     *
+     * Wrapped so that a throwing handler — or a fetch implementation that rejects
+     * rather than resolving — costs this run's beat and nothing else.
+     */
+    async beat(target) {
+        try {
+            const outcome = await heartbeatRun(this.options.api, target.path, target.progress?.());
+            // The run may have finished while its own heartbeat was in flight; acting
+            // on a stale answer would cancel a run that is already reporting itself.
+            if (!this.targets.has(target.runId))
+                return;
+            if (outcome.kind === 'alive') {
+                if (!outcome.cancelRequested)
+                    return;
+                this.untrack(target.runId);
+                this.options.log(`    ⏹ run ${target.runId.slice(0, 12)} was cancelled from ProhostAI — stopping it`);
+                await target.onCancelRequested();
+                return;
+            }
+            if (outcome.kind === 'unknown') {
+                // Said once per run, then silence: on a server that predates
+                // heartbeats this is the answer for every run forever, and a line a
+                // minute per run would bury the log that operators actually read.
+                this.untrack(target.runId);
+                this.options.log(`    ◦ run ${target.runId.slice(0, 12)} cannot be kept alive (HTTP 404) — this ProhostAI ` +
+                    'server has no heartbeat endpoint, or no longer knows this run. Long runs may be ' +
+                    'reaped while they are still working.');
+                return;
+            }
+            if (outcome.kind === 'resolved') {
+                this.untrack(target.runId);
+                this.options.log(`    ⏹ run ${target.runId.slice(0, 12)} was already closed server-side — abandoning it`);
+                await target.onResolved();
+                return;
+            }
+            // Transient by assumption: keep the cadence rather than give up on the
+            // run. A run whose beats all fail is reaped server-side eventually, which
+            // is the correct end state for a machine that cannot reach the API.
+            this.options.log(`    ! heartbeat for run ${target.runId.slice(0, 12)} failed (HTTP ${outcome.status})` +
+                `${outcome.detail ? ` ${outcome.detail}` : ''}`);
+        }
+        catch (err) {
+            this.options.log(`    ! heartbeat for run ${target.runId.slice(0, 12)} threw: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/agent/prompt.d.ts

@@ -39,6 +39,17 @@ export interface PromptContext {
      * decline work it is perfectly able to do.
      */
     toolsGated?: boolean;
+    /**
+     * How long this run may take before it is killed, in milliseconds. ``0`` is
+     * `--timeout 0`: no local cap at all.
+     *
+     * Threaded in from the harness rather than assumed, because the prompt used
+     * to say "this run has a hard time limit" without ever naming it — which an
+     * agent reads as "hurry", whatever the number happens to be. An agent given
+     * five minutes should triage; an agent given two hours should do the work.
+     * They cannot tell those apart from a sentence that says neither.
+     */
+    timeoutMs?: number;
 }
 /** Build the stdin prompt for one run. */
 export declare function buildPrompt(run: AgentRunRequest, context: PromptContext): string;