/** * Run activity clock (2026-10-27). * * WHY THIS EXISTS - the data-collector incident. * ---------------------------------------------- * The harness kill-switch was an IDLE timer, but the idle signal was the child * process's stdout/stderr and nothing else. That is wrong for OpenCode V2 in * three ways, and all three are silent: * * 1. V2 is a client/server product. While the SERVICE runs a tool call the * CLI client prints nothing, so one long `execute` looks exactly like a * dead harness. Live case: `navigate` to a LinkedIn job posting never * returned, the console was silent for 60 minutes, and the run was killed * with "the harness went silent" at 60m03s. * 2. Subagent output is relayed by US (`startSubagentRelay`), not printed by * the child, so a working subagent never reset the timer either. * 3. A background shell runs on the service too; its output never reaches the * parent pipe. * * So "silence on the pipe" is not "no work". This module makes the run's * liveness ONE clock fed by every channel we can actually observe: * * stdout - a chunk on the child's stdout/stderr (the old signal) * subagent - a NEW assistant message in a child session * shell - a running background shell in the run's location * mcp - a relayed MCP request from this run (see the daemon's * `/internal/session-activity`) * * The idle kill fires only when EVERY channel has been quiet for the budget. * The decision stays pure so the regression cannot come back unnoticed. */ /** Every observable sign that the run is doing something. */ export type ActivityKind = 'stdout' | 'subagent' | 'shell' | 'mcp'; export interface ActivitySnapshot { /** When this clock was created (the harness was spawned). */ spawnedAt: number; /** Newest activity on ANY channel. */ lastActivityAt: number; /** Newest stdout/stderr chunk, or null when the child never printed. */ lastOutputAt: number | null; /** Channel of the newest activity. */ lastKind: ActivityKind | 'none'; /** Short label: a subagent id, a shell command, an MCP tool name. */ lastDetail: string | null; /** False only when the child has never printed anything at all. */ everOutput: boolean; } /** How long the newest activity has been quiet, in ms. */ export interface IdleVerdict { kill: boolean; /** True when the child produced NOTHING at all (a boot/silent hang). */ cold: boolean; /** How long every channel has been quiet. */ silentMs: number; /** Human label for what spoke last ("mcp (browser_action)"). */ actor: string; } /** One clock per harness invocation. Never shared across runs. */ export declare class ActivityClock { private readonly spawnedAt; private lastActivityAt; private lastOutputAt; private lastKind; private lastDetail; constructor(now?: number); /** * Record activity. `detail` is the thing that spoke, and it is what the idle * kill message names - a bare "no output" is what made the original failure * impossible to diagnose. */ note(kind: ActivityKind, detail?: string | null): void; snapshot(): ActivitySnapshot; } /** Human label for the newest activity ("mcp (browser_action)"). */ export declare function activityActor(snapshot: ActivitySnapshot): string; /** * The idle decision. Pure on purpose: a test can pin every branch without a * child process, a service or a clock. */ export declare function decideIdleKill(input: { snapshot: ActivitySnapshot; now: number; idleMs: number; }): IdleVerdict; /** * "It has been quiet long enough to warn" - the early console line that turns * a 60-minute mystery into a named stall. The caller keeps `lastWarnAt` so a * warning is emitted at most once per window. */ export declare function shouldWarnStall(input: { snapshot: ActivitySnapshot; now: number; warnMs: number; lastWarnAt: number; }): boolean;