@matteeh/osq 0.1.0 → 0.2.0

package/dist/watcher/dev.d.ts

@@ -0,0 +1,51 @@
+import { type ChildProcess } from 'node:child_process';
+export declare const DEV_WORKER_ENV = "OSQ_DEV_WORKER";
+export declare const EXIT_SIGINT = 130;
+/**
+ * Options accepted by `osq watch`. Declared here, in the watcher tier, so the
+ * CLI can consume them without the watcher importing from `src/cli`.
+ */
+export interface WatchCommandOptions {
+    once?: boolean;
+    dir?: string;
+    harness?: string;
+    verbose?: boolean;
+    quiet?: boolean;
+    symbols?: boolean;
+    allowStale?: boolean;
+    dev?: boolean;
+}
+/** Command used to (re)spawn the watcher worker through `tsx`. */
+export interface DevWorkerSpec {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Build the worker invocation for dev mode: execute the CLI's TypeScript entry
+ * through `tsx` so editing `src/` is picked up on restart. `--dev` itself is not
+ * forwarded, and `OSQ_DEV_WORKER` tells `watchCommand` it is already inside a
+ * supervised worker so it starts the loop instead of the supervisor again.
+ */
+export declare function buildWorkerInvocation(options: WatchCommandOptions, packageRoot?: string): DevWorkerSpec;
+export interface DevWatchHandle {
+    close: () => unknown;
+}
+/** Injection seams so the supervisor's restart state machine is testable. */
+export interface DevSupervisorOverrides {
+    packageRoot?: string;
+    spawnWorker?: (spec: DevWorkerSpec) => ChildProcess;
+    watchSource?: (sourceDir: string, onChange: () => void) => DevWatchHandle;
+    onSignal?: (handler: () => void) => () => void;
+    exit?: (code: number) => void;
+    logError?: (message: string) => void;
+}
+/**
+ * Dev-mode supervisor: runs the watcher as a child process through `tsx` from
+ * `src/` and watches `src/` with chokidar. A source change only signals the
+ * worker (SIGINT); the worker's own SIGINT handler finishes the running task
+ * before exiting, after which the supervisor spawns a fresh worker that loads
+ * the updated code. A user SIGINT shuts both down without restarting.
+ */
+export declare function runDevSupervisor(options: WatchCommandOptions, overrides?: DevSupervisorOverrides): Promise<void>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/watcher/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/watcher/dev.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAM9D,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAKD,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,mBAAmB,EAC5B,WAAW,GAAE,MAAqB,GACjC,aAAa,CAWf;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,OAAO,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,YAAY,CAAC;IACpD,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,cAAc,CAAC;IAC1E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IAC/C,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAiBD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,EAC5B,SAAS,GAAE,sBAA2B,GACrC,OAAO,CAAC,IAAI,CAAC,CA+Ef"}

package/dist/watcher/dev.js

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { watch } from 'chokidar';
+export const DEV_WORKER_ENV = 'OSQ_DEV_WORKER';
+export const EXIT_SIGINT = 130;
+/** Package root of the running osq build: `src/watcher/` or `dist/watcher/`. */
+const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL('../../', import.meta.url)));
+/**
+ * Build the worker invocation for dev mode: execute the CLI's TypeScript entry
+ * through `tsx` so editing `src/` is picked up on restart. `--dev` itself is not
+ * forwarded, and `OSQ_DEV_WORKER` tells `watchCommand` it is already inside a
+ * supervised worker so it starts the loop instead of the supervisor again.
+ */
+export function buildWorkerInvocation(options, packageRoot = PACKAGE_ROOT) {
+    const args = ['--import', 'tsx', path.join(packageRoot, 'src', 'cli', 'bin.ts'), 'watch'];
+    if (options.once)
+        args.push('--once');
+    if (options.verbose)
+        args.push('--verbose');
+    if (options.quiet)
+        args.push('--quiet');
+    if (options.allowStale)
+        args.push('--allow-stale');
+    return {
+        command: process.execPath,
+        args,
+        env: { ...process.env, [DEV_WORKER_ENV]: '1' },
+    };
+}
+function defaultSpawnWorker(spec) {
+    return spawn(spec.command, spec.args, { env: spec.env, stdio: 'inherit' });
+}
+function defaultWatchSource(sourceDir, onChange) {
+    const handle = watch(sourceDir, { ignoreInitial: true });
+    handle.on('all', onChange);
+    return { close: () => handle.close() };
+}
+function defaultOnSignal(handler) {
+    process.on('SIGINT', handler);
+    return () => process.removeListener('SIGINT', handler);
+}
+/**
+ * Dev-mode supervisor: runs the watcher as a child process through `tsx` from
+ * `src/` and watches `src/` with chokidar. A source change only signals the
+ * worker (SIGINT); the worker's own SIGINT handler finishes the running task
+ * before exiting, after which the supervisor spawns a fresh worker that loads
+ * the updated code. A user SIGINT shuts both down without restarting.
+ */
+export async function runDevSupervisor(options, overrides = {}) {
+    const packageRoot = overrides.packageRoot ?? PACKAGE_ROOT;
+    const sourceDir = path.join(packageRoot, 'src');
+    const exit = overrides.exit ?? ((code) => process.exit(code));
+    const logError = overrides.logError ?? ((message) => console.error(message));
+    const sourceStat = await fs.stat(sourceDir).catch(() => null);
+    if (!sourceStat?.isDirectory()) {
+        logError(`osq --dev requires a source checkout with src/ (looked in ${sourceDir}).`);
+        exit(1);
+        return;
+    }
+    const spawnWorker = overrides.spawnWorker ?? defaultSpawnWorker;
+    const watchSource = overrides.watchSource ?? defaultWatchSource;
+    const onSignal = overrides.onSignal ?? defaultOnSignal;
+    let currentWorker = null;
+    let restartPending = false;
+    let shuttingDown = false;
+    let finalized = false;
+    let watcherHandle = null;
+    let detachSignal = () => { };
+    let resolveDone = () => { };
+    const done = new Promise((resolve) => {
+        resolveDone = resolve;
+    });
+    const finalize = (code) => {
+        if (finalized)
+            return;
+        finalized = true;
+        detachSignal();
+        watcherHandle?.close();
+        resolveDone();
+        exit(code);
+    };
+    const startWorker = () => {
+        const spec = buildWorkerInvocation(options, packageRoot);
+        const worker = spawnWorker(spec);
+        currentWorker = worker;
+        worker.on('exit', (code) => {
+            currentWorker = null;
+            if (shuttingDown) {
+                finalize(EXIT_SIGINT);
+                return;
+            }
+            if (restartPending) {
+                restartPending = false;
+                startWorker();
+                return;
+            }
+            finalize(typeof code === 'number' ? code : 0);
+        });
+    };
+    const requestRestart = () => {
+        if (shuttingDown || restartPending)
+            return;
+        restartPending = true;
+        currentWorker?.kill('SIGINT');
+    };
+    const handleSigint = () => {
+        if (shuttingDown || finalized)
+            return;
+        shuttingDown = true;
+        restartPending = false;
+        if (!currentWorker) {
+            finalize(EXIT_SIGINT);
+            return;
+        }
+        currentWorker.kill('SIGINT');
+    };
+    detachSignal = onSignal(handleSigint);
+    startWorker();
+    watcherHandle = watchSource(sourceDir, requestRestart);
+    await done;
+}
+//# sourceMappingURL=dev.js.map

package/dist/watcher/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/watcher/dev.ts"],"names":[],"mappings":"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"}

package/dist/watcher/failure-reason.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Every terminal reason a task attempt can be recorded as dead under. Kept in
+ * its own module so `outcome.ts` stays within the strict runner line budget as
+ * the reason set grows.
+ */
+export type RunTaskFailureReason = 'spec_conflict' | 'already_running' | 'no_result' | 'verify_red' | 'verify_precondition' | 'verify_path_missing' | 'change_verify_red' | 'crashed' | 'timeout' | 'undeclared_test_change' | 'regressed';
+//# sourceMappingURL=failure-reason.d.ts.map

package/dist/watcher/failure-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-reason.d.ts","sourceRoot":"","sources":["../../src/watcher/failure-reason.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B,eAAe,GACf,iBAAiB,GACjB,WAAW,GACX,YAAY,GACZ,qBAAqB,GACrB,qBAAqB,GACrB,mBAAmB,GACnB,SAAS,GACT,SAAS,GACT,wBAAwB,GACxB,WAAW,CAAC"}

package/dist/watcher/failure-reason.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=failure-reason.js.map

package/dist/watcher/failure-reason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-reason.js","sourceRoot":"","sources":["../../src/watcher/failure-reason.ts"],"names":[],"mappings":""}

package/dist/watcher/fingerprint.d.ts

@@ -0,0 +1,19 @@
+/** Strip ANSI escape sequences (CSI and OSC) from terminal text. */
+export declare function stripAnsi(text: string): string;
+/**
+ * Normalize a dead marker body for fingerprinting: drop ANSI codes, replace the
+ * project root, timestamps, durations, and PIDs with fixed placeholders, and
+ * leave every other byte untouched.
+ */
+export declare function normalizeFailureBody(body: string, projectRoot?: string): string;
+/**
+ * `sha256:<hex>` over the frontmatter `reason`, a newline, and the normalized
+ * body after the frontmatter. Content without frontmatter has an empty reason.
+ */
+export declare function markerFingerprint(content: string, projectRoot?: string): string;
+/**
+ * Insert `fingerprint: sha256:<hex>` inside the marker's frontmatter. Content
+ * without frontmatter gains a minimal block; every other byte is preserved.
+ */
+export declare function addFingerprint(content: string, projectRoot?: string): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/watcher/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/watcher/fingerprint.ts"],"names":[],"mappings":"AAcA,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAS/E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAO/E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5E"}

package/dist/watcher/fingerprint.js

@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto';
+import { parseFrontmatter } from '../core/spec/parser.js';
+// Built from a char code so the escape byte never appears as a regex control
+// character literal.
+const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[ -/]*[@-~]|${String.fromCharCode(27)}\\][^\\u0007]*(?:\\u0007|${String.fromCharCode(27)}\\\\)`, 'g');
+const ISO_TIMESTAMP = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g;
+const DURATION = /\(?\b\d+(?:\.\d+)?(?:ms|s|m|h)\b\)?/g;
+const PID = /\bpid\s*[:=]?\s*\d+/gi;
+/** Strip ANSI escape sequences (CSI and OSC) from terminal text. */
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, '');
+}
+/**
+ * Normalize a dead marker body for fingerprinting: drop ANSI codes, replace the
+ * project root, timestamps, durations, and PIDs with fixed placeholders, and
+ * leave every other byte untouched.
+ */
+export function normalizeFailureBody(body, projectRoot) {
+    let normalized = stripAnsi(body);
+    if (projectRoot) {
+        normalized = normalized.split(projectRoot).join('<root>');
+    }
+    return normalized
+        .replace(ISO_TIMESTAMP, '<time>')
+        .replace(DURATION, '<duration>')
+        .replace(PID, 'pid <pid>');
+}
+/**
+ * `sha256:<hex>` over the frontmatter `reason`, a newline, and the normalized
+ * body after the frontmatter. Content without frontmatter has an empty reason.
+ */
+export function markerFingerprint(content, projectRoot) {
+    const { data, body } = parseFrontmatter(content);
+    const reason = typeof data.reason === 'string' ? data.reason : '';
+    const digest = createHash('sha256')
+        .update(`${reason}\n${normalizeFailureBody(body, projectRoot)}`)
+        .digest('hex');
+    return `sha256:${digest}`;
+}
+/**
+ * Insert `fingerprint: sha256:<hex>` inside the marker's frontmatter. Content
+ * without frontmatter gains a minimal block; every other byte is preserved.
+ */
+export function addFingerprint(content, projectRoot) {
+    const fingerprint = markerFingerprint(content, projectRoot);
+    const match = content.match(/^(---\r?\n(?:[\s\S]*?\r?\n)?)(---)/);
+    if (!match) {
+        return `---\nfingerprint: ${fingerprint}\n---\n${content}`;
+    }
+    const head = match[1];
+    return `${head}fingerprint: ${fingerprint}\n${content.slice(head.length)}`;
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/watcher/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/watcher/fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,6EAA6E;AAC7E,qBAAqB;AACrB,MAAM,YAAY,GAAG,IAAI,MAAM,CAC7B,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,0BAA0B,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,4BAA4B,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,OAAO,EACrI,GAAG,CACJ,CAAC;AAEF,MAAM,aAAa,GAAG,uEAAuE,CAAC;AAC9F,MAAM,QAAQ,GAAG,sCAAsC,CAAC;AACxD,MAAM,GAAG,GAAG,uBAAuB,CAAC;AAEpC,oEAAoE;AACpE,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,WAAoB;IACrE,IAAI,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,WAAW,EAAE,CAAC;QAChB,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,UAAU;SACd,OAAO,CAAC,aAAa,EAAE,QAAQ,CAAC;SAChC,OAAO,CAAC,QAAQ,EAAE,YAAY,CAAC;SAC/B,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,WAAoB;IACrE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;SAChC,MAAM,CAAC,GAAG,MAAM,KAAK,oBAAoB,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;SAC/D,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,OAAO,UAAU,MAAM,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,WAAoB;IAClE,MAAM,WAAW,GAAG,iBAAiB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAClE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,qBAAqB,WAAW,UAAU,OAAO,EAAE,CAAC;IAC7D,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,OAAO,GAAG,IAAI,gBAAgB,WAAW,KAAK,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;AAC7E,CAAC"}

package/dist/watcher/heartbeat.d.ts

@@ -0,0 +1,33 @@
+import { relativizeToolSummary } from '../core/run/summary.js';
+export { relativizeToolSummary };
+export interface TaskHeartbeatStats {
+    elapsedSeconds: number;
+    eventCount: number;
+    totalTokens: number;
+    toolCount: number;
+    cost?: number;
+    lastToolSummary?: string;
+}
+/**
+ * Snapshot of task progress. Counters are maintained in memory and advanced
+ * with only the bytes appended since the previous poll; tool summaries are
+ * stored relativized to `projectRoot` for display.
+ */
+export declare function computeTaskHeartbeatStats(specFolderPath: string, taskNumber: string, startTime: number, projectRoot?: string): Promise<TaskHeartbeatStats>;
+/** Drop the in-memory counters for a finished task so the map does not grow. */
+export declare function clearTaskHeartbeatStats(specFolderPath: string, taskNumber: string): void;
+/**
+ * Compact token count for the live status row and the heartbeat line: below
+ * 1000 as an integer, below 1M as `X.Xk`, at or above 1M as `X.XM`. A value
+ * that rounds up to `1000.0k` rolls over to `1.0M` so the suffix never grows.
+ */
+export declare function formatTokens(tokens: number): string;
+/**
+ * Single-line running status row. The logger owns the animated spinner and
+ * terminal-width truncation, so this assembles the full row and leaves fitting
+ * to the sink.
+ */
+export declare function formatTaskStatusRow(taskNumber: string, stats: TaskHeartbeatStats): string;
+/** Periodic heartbeat line shared by the 1s TTY row and the non-TTY log. */
+export declare function formatTaskHeartbeatLine(taskNumber: string, stats: TaskHeartbeatStats): string;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/watcher/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/watcher/heartbeat.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAK/D,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAuBD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,CAAC,CA0E7B;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAGxF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAYnD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAgBzF;AAED,4EAA4E;AAC5E,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAE7F"}

package/dist/watcher/heartbeat.js

@@ -0,0 +1,135 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { relativizeToolSummary } from '../core/run/summary.js';
+import { asRecord } from '../harness/stream.js';
+// Re-exported from core so existing watcher/status consumers keep importing it
+// from the heartbeat module.
+export { relativizeToolSummary };
+const heartbeatAccumulators = new Map();
+function createHeartbeatAccumulator() {
+    return { byteOffset: 0, eventCount: 0, totalTokens: 0, toolCount: 0, cost: 0, hasCost: false };
+}
+/**
+ * Snapshot of task progress. Counters are maintained in memory and advanced
+ * with only the bytes appended since the previous poll; tool summaries are
+ * stored relativized to `projectRoot` for display.
+ */
+export async function computeTaskHeartbeatStats(specFolderPath, taskNumber, startTime, projectRoot) {
+    const elapsedSeconds = Number(((Date.now() - startTime) / 1000).toFixed(1));
+    const eventFilePath = path.join(specFolderPath, '.run', 'events', `${taskNumber}.jsonl`);
+    let content = '';
+    try {
+        content = await fs.readFile(eventFilePath, 'utf8');
+    }
+    catch {
+        heartbeatAccumulators.delete(eventFilePath);
+        return { elapsedSeconds, eventCount: 0, totalTokens: 0, toolCount: 0 };
+    }
+    let accumulator = heartbeatAccumulators.get(eventFilePath);
+    if (!accumulator || accumulator.byteOffset > content.length) {
+        accumulator = createHeartbeatAccumulator();
+    }
+    const fresh = content.slice(accumulator.byteOffset);
+    const lastNewline = fresh.lastIndexOf('\n');
+    if (lastNewline !== -1) {
+        const complete = fresh.slice(0, lastNewline);
+        accumulator.byteOffset += lastNewline + 1;
+        for (const line of complete.split('\n')) {
+            if (!line.trim()) {
+                continue;
+            }
+            accumulator.eventCount += 1;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                // Ignore malformed lines rather than losing the whole heartbeat.
+                continue;
+            }
+            const event = asRecord(parsed);
+            if (!event) {
+                continue;
+            }
+            const data = asRecord(event.data);
+            if (event.type === 'tokens') {
+                accumulator.totalTokens += Number(data?.totalTokens ?? 0) || 0;
+                const cost = Number(data?.cost);
+                if (Number.isFinite(cost)) {
+                    accumulator.cost += cost;
+                    accumulator.hasCost = true;
+                }
+            }
+            else if (event.type === 'tool') {
+                accumulator.toolCount += 1;
+                const summary = data?.summary;
+                if (typeof summary === 'string') {
+                    accumulator.lastToolSummary = relativizeToolSummary(summary, projectRoot);
+                }
+            }
+        }
+    }
+    heartbeatAccumulators.set(eventFilePath, accumulator);
+    const stats = {
+        elapsedSeconds,
+        eventCount: accumulator.eventCount,
+        totalTokens: accumulator.totalTokens,
+        toolCount: accumulator.toolCount,
+    };
+    if (accumulator.hasCost) {
+        stats.cost = accumulator.cost;
+    }
+    if (accumulator.lastToolSummary !== undefined) {
+        stats.lastToolSummary = accumulator.lastToolSummary;
+    }
+    return stats;
+}
+/** Drop the in-memory counters for a finished task so the map does not grow. */
+export function clearTaskHeartbeatStats(specFolderPath, taskNumber) {
+    const eventFilePath = path.join(specFolderPath, '.run', 'events', `${taskNumber}.jsonl`);
+    heartbeatAccumulators.delete(eventFilePath);
+}
+/**
+ * Compact token count for the live status row and the heartbeat line: below
+ * 1000 as an integer, below 1M as `X.Xk`, at or above 1M as `X.XM`. A value
+ * that rounds up to `1000.0k` rolls over to `1.0M` so the suffix never grows.
+ */
+export function formatTokens(tokens) {
+    if (tokens < 1000) {
+        return tokens.toString();
+    }
+    if (tokens < 1_000_000) {
+        const k = (tokens / 1000).toFixed(1);
+        if (k === '1000.0') {
+            return '1.0M';
+        }
+        return `${k}k`;
+    }
+    return `${(tokens / 1_000_000).toFixed(1)}M`;
+}
+/**
+ * Single-line running status row. The logger owns the animated spinner and
+ * terminal-width truncation, so this assembles the full row and leaves fitting
+ * to the sink.
+ */
+export function formatTaskStatusRow(taskNumber, stats) {
+    const segments = [
+        `task ${taskNumber}`,
+        `${stats.elapsedSeconds}s`,
+        `${stats.toolCount} tools`,
+        `${formatTokens(stats.totalTokens)} tokens`,
+    ];
+    if (typeof stats.cost === 'number' && Number.isFinite(stats.cost)) {
+        segments.push(`$${stats.cost.toFixed(4)}`);
+    }
+    const base = segments.join(' · ');
+    if (!stats.lastToolSummary) {
+        return base;
+    }
+    return `${base} · ${stats.lastToolSummary}`;
+}
+/** Periodic heartbeat line shared by the 1s TTY row and the non-TTY log. */
+export function formatTaskHeartbeatLine(taskNumber, stats) {
+    return `task ${taskNumber} heartbeat (elapsed: ${stats.elapsedSeconds}s, events: ${stats.eventCount}, tokens: ${formatTokens(stats.totalTokens)})`;
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/watcher/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../../src/watcher/heartbeat.ts"],"names":[],"mappings":"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"}

package/dist/watcher/lock.d.ts

@@ -0,0 +1,10 @@
+import { type LockResult } from '../core/run/lock.js';
+/**
+ * Acquire the exclusive running lock for a task's `.run` directory. Thin
+ * wrapper over the core lock so the watcher tier owns a single integration
+ * point.
+ */
+export declare function acquireTaskLock(runDir: string, taskNumber: string | number): Promise<LockResult>;
+/** Release the task lock, tolerating an already-absent marker. */
+export declare function releaseTaskLock(runDir: string, taskNumber: string | number): Promise<void>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/watcher/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/watcher/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAA4B,MAAM,qBAAqB,CAAC;AAEhF;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GAAG,MAAM,GAC1B,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,kEAAkE;AAClE,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhG"}

package/dist/watcher/lock.js

@@ -0,0 +1,14 @@
+import { acquireLock, releaseLock } from '../core/run/lock.js';
+/**
+ * Acquire the exclusive running lock for a task's `.run` directory. Thin
+ * wrapper over the core lock so the watcher tier owns a single integration
+ * point.
+ */
+export async function acquireTaskLock(runDir, taskNumber) {
+    return acquireLock(runDir, taskNumber);
+}
+/** Release the task lock, tolerating an already-absent marker. */
+export async function releaseTaskLock(runDir, taskNumber) {
+    await releaseLock(runDir, taskNumber);
+}
+//# sourceMappingURL=lock.js.map

package/dist/watcher/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/watcher/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,WAAW,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEhF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAc,EACd,UAA2B;IAE3B,OAAO,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACzC,CAAC;AAED,kEAAkE;AAClE,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc,EAAE,UAA2B;IAC/E,MAAM,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC"}

package/dist/watcher/loop.d.ts

@@ -1,15 +1,26 @@
-import type { OsqConfig } from '../core/config.js';
-import { type Logger } from '../core/logger.js';
+import type { OsqConfig } from '../core/foundation/config.js';
+import { type Logger } from '../core/foundation/logger.js';
 import type { HarnessAdapter } from '../harness/types.js';
+import { type BuildInfo } from './build.js';
 export interface WatcherSummary {
     tasksRun: number;
+    /** Automatic retries the watcher made; progress even when no task ran. */
+    retried: number;
     specsArchived: number;
+    /** Changes whose pre-dispatch scope audit found newly stale tasks. */
+    blockedByRegression: {
+        readonly id: string;
+        readonly outcome: 'blocked_by_regression';
+        readonly tasks: readonly string[];
+    }[];
 }
 export interface StartWatcherOptions {
     once?: boolean;
     pollIntervalMs?: number;
     signal?: AbortSignal;
     logger?: Logger;
+    allowStale?: boolean;
+    dev?: boolean;
 }
 export interface ArchivedSpecSummary {
     id: string;
@@ -18,11 +29,20 @@ export interface ArchivedSpecSummary {
 }
 export declare function formatAgo(ms: number): string;
 /**
- * Single idle status line: the watched spec directory, how many approved specs
- * are still waiting, and when the last spec was archived. Pure so the exact
- * shape is testable without a watcher.
+ * Single idle status line: the active build identity, the watched spec
+ * directory, how many approved specs are still waiting, and when the last spec
+ * was archived. Pure so the exact shape is testable without a watcher. The
+ * `osq v<version> (<commit>)` prefix is omitted when no build info is supplied.
  */
-export declare function formatIdleStatus(specsDir: string, approvedWaiting: number, lastArchived?: ArchivedSpecSummary, now?: number): string;
+export declare function formatIdleStatus(specsDir: string, approvedWaiting: number, lastArchived?: ArchivedSpecSummary, now?: number, buildInfo?: BuildInfo): string;
+/**
+ * Extract the `## Human steps` section from a change document. osq never
+ * performs these steps itself; they are printed once the change completes so
+ * the human knows which manual actions remain (for the layout cut-over: stop
+ * the watcher, run the migration, restart). Returns an empty string when the
+ * document has no such section or the section is blank.
+ */
+export declare function extractHumanSteps(content: string): string;
 /**
  * Most recently archived spec folder, derived from the archive directory's
  * modification times so the idle status survives a watcher restart.

package/dist/watcher/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/watcher/loop.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,mBAAmB,CAAC;AAG/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAS5C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,mBAAmB,EAClC,GAAG,GAAE,MAAmB,GACvB,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAyB1C;AAUD,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,CAmFzB;AAED,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,CAezB;AAED,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAuFf"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/watcher/loop.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,8BAA8B,CAAC;AAM1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,EAAE,KAAK,SAAS,EAAqC,MAAM,YAAY,CAAC;AAQ/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,mBAAmB,EAAE;QACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;QAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;KACnC,EAAE,CAAC;CACL;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAS5C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,mBAAmB,EAClC,GAAG,GAAE,MAAmB,EACxB,SAAS,CAAC,EAAE,SAAS,GACpB,MAAM,CAMR;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASzD;AAgBD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAyB1C;AAkBD,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,CA6KzB;AAED,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,CA6BzB;AAED,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CA+Ff"}