@matteeh/osq 0.1.0 → 0.2.1

package/dist/watcher/attempt.js

@@ -0,0 +1,94 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveSymbol } from '../core/foundation/logger.js';
+import { parseFrontmatter } from '../core/spec/parser.js';
+import { asRecord } from '../harness/stream.js';
+import { stripAnsi } from './fingerprint.js';
+const ELLIPSIS = '…';
+function truncateToWidth(text, width) {
+    if (width <= 0)
+        return '';
+    if (text.length <= width)
+        return text;
+    if (width === 1)
+        return ELLIPSIS;
+    return `${text.slice(0, width - 1)}${ELLIPSIS}`;
+}
+/** Curated task-started line: prefix plus the title truncated to terminal width. */
+export function formatTaskStartedLine(taskNumber, title, pid, timeoutSeconds, symbols, terminalWidth = process.stderr.columns ?? 80) {
+    const symbol = resolveSymbol('▶', '[task]', symbols);
+    const prefix = `${symbol} task ${taskNumber} started (pid: ${pid ?? 'unknown'}, timeout: ${timeoutSeconds}s): `;
+    return `${prefix}${truncateToWidth(title, Math.max(0, terminalWidth - prefix.length))}`;
+}
+/**
+ * Body after the frontmatter of the dead marker a retry retained, with ANSI
+ * codes stripped. The retained attempt ordinal is one less than the following
+ * execution attempt. A missing marker, as after retrying a regression, yields no
+ * output.
+ */
+async function readRetainedMarkerBody(specFolderPath, taskNumber, attempt) {
+    const markerPath = path.join(specFolderPath, '.run', 'dead', `${taskNumber}.${attempt - 1}.md`);
+    const content = await fs.readFile(markerPath, 'utf8').catch(() => undefined);
+    if (content === undefined)
+        return undefined;
+    return stripAnsi(parseFrontmatter(content).body);
+}
+/**
+ * Reconstruct the target-wide execution attempt, prior failure reason, and
+ * failure output from the append-only event stream. The latest `retry`
+ * transition or requeued `recertification` wins, so a watcher restart loses
+ * neither the attempt nor the failure context. A retry's output is the body of
+ * the dead marker it retained; a requeued recertification keeps its captured
+ * verification output. A passed recertification is not a transition and never
+ * advances attempts. Without either event the target starts at attempt 1.
+ */
+export async function readRetryContext(specFolderPath, taskNumber) {
+    const eventPath = path.join(specFolderPath, '.run', 'events', `${taskNumber}.jsonl`);
+    const content = await fs.readFile(eventPath, 'utf8').catch(() => '');
+    let attempt = 1;
+    let reason;
+    let output;
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const event = asRecord(parsed);
+        if (event?.type === 'retry') {
+            const data = asRecord(event.data);
+            if (typeof data?.attempt === 'number' && Number.isInteger(data.attempt)) {
+                attempt = data.attempt;
+            }
+            if (typeof data?.reason === 'string' && data.reason) {
+                reason = data.reason;
+            }
+            output = await readRetainedMarkerBody(specFolderPath, taskNumber, attempt);
+            continue;
+        }
+        if (event?.type !== 'recertification')
+            continue;
+        const data = asRecord(event.data);
+        if (data?.outcome !== 'requeued')
+            continue;
+        if (typeof data.attempt === 'number' && Number.isInteger(data.attempt)) {
+            attempt = data.attempt;
+        }
+        if (typeof data.reason === 'string' && data.reason) {
+            reason = data.reason;
+        }
+        if (typeof data.output === 'string') {
+            output = data.output;
+        }
+    }
+    return {
+        attempt,
+        ...(reason ? { reason } : {}),
+        ...(output ? { output } : {}),
+    };
+}
+//# sourceMappingURL=attempt.js.map

package/dist/watcher/attempt.js.map

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

package/dist/watcher/auto-retry.d.ts

@@ -0,0 +1,11 @@
+import type { OsqConfig } from '../core/foundation/config.js';
+import { type Logger } from '../core/foundation/logger.js';
+export declare const ELIGIBLE_AUTO_RETRY_REASONS: readonly ["verify_red", "change_verify_red", "undeclared_test_change", "verify_path_missing", "no_result", "crashed", "timeout"];
+export type EligibleAutoRetryReason = (typeof ELIGIBLE_AUTO_RETRY_REASONS)[number];
+/**
+ * Decide, per active dead task in an approved change, whether to retry it. Runs
+ * from disk every cycle so a watcher restart between a death and its retry
+ * neither loses nor repeats the action. Returns the number of retries made.
+ */
+export declare function runAutomaticRetries(projectRoot: string, folderPath: string, config: OsqConfig, logger?: Logger): Promise<number>;
+//# sourceMappingURL=auto-retry.d.ts.map

package/dist/watcher/auto-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-retry.d.ts","sourceRoot":"","sources":["../../src/watcher/auto-retry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,8BAA8B,CAAC;AAU1E,eAAO,MAAM,2BAA2B,kIAQ9B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AA6KnF;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/watcher/auto-retry.js

@@ -0,0 +1,180 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import { resolveSymbol } from '../core/foundation/logger.js';
+import { retrySpec } from '../core/lifecycle/retry.js';
+import { parseFrontmatter } from '../core/spec/parser.js';
+import { appendHarnessEvent } from '../harness/types.js';
+import { markerFingerprint } from './fingerprint.js';
+// Automatic retry spends one agent attempt on a dead task when a fresh run
+// could plausibly fix it. The decision is re-derived from disk every cycle; the
+// retry transition itself (renaming the active marker) is the commit point.
+export const ELIGIBLE_AUTO_RETRY_REASONS = [
+    'verify_red',
+    'change_verify_red',
+    'undeclared_test_change',
+    'verify_path_missing',
+    'no_result',
+    'crashed',
+    'timeout',
+];
+const ELIGIBLE = new Set(ELIGIBLE_AUTO_RETRY_REASONS);
+const ACTIVE_DEAD = /^\d+\.md$/;
+const RETAINED_DEAD = /^(\d+)\.(\d+)\.md$/;
+async function readStream(folderPath, taskNumber) {
+    const raw = await fs
+        .readFile(path.join(folderPath, '.run', 'events', `${taskNumber}.jsonl`), 'utf8')
+        .catch(() => '');
+    const events = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // A malformed line never blocks the decision.
+        }
+    }
+    return events;
+}
+function dataOf(event) {
+    return event.data !== null && typeof event.data === 'object'
+        ? event.data
+        : {};
+}
+function laterOf(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return a > b ? a : b;
+}
+function lastManualRetryAt(events) {
+    let latest;
+    for (const event of events) {
+        if (event.type !== 'retry' || dataOf(event).automatic === true)
+            continue;
+        if (typeof event.timestamp !== 'string')
+            continue;
+        latest = laterOf(latest, event.timestamp);
+    }
+    return latest;
+}
+function automaticRetriesSince(events, cutoff) {
+    let count = 0;
+    for (const event of events) {
+        if (event.type !== 'retry' || dataOf(event).automatic !== true)
+            continue;
+        if (cutoff !== undefined && typeof event.timestamp === 'string' && event.timestamp < cutoff) {
+            continue;
+        }
+        count += 1;
+    }
+    return count;
+}
+async function readApprovedAt(runDir) {
+    const raw = await fs.readFile(path.join(runDir, 'manifest.json'), 'utf8').catch(() => '');
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.approvedAt === 'string' ? parsed.approvedAt : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Stored fingerprint, falling back to a content-derived one for legacy markers. */
+function fingerprintOf(content, projectRoot) {
+    const stored = parseFrontmatter(content).data.fingerprint;
+    return typeof stored === 'string' && stored ? stored : markerFingerprint(content, projectRoot);
+}
+async function highestRetained(deadDir, taskNumber, projectRoot) {
+    const entries = await fs.readdir(deadDir).catch(() => []);
+    let bestOrdinal = -1;
+    let best;
+    for (const entry of entries) {
+        const match = entry.match(RETAINED_DEAD);
+        if (!match || match[1] !== taskNumber)
+            continue;
+        const ordinal = Number.parseInt(match[2], 10);
+        if (ordinal > bestOrdinal) {
+            bestOrdinal = ordinal;
+            best = entry;
+        }
+    }
+    if (best === undefined)
+        return undefined;
+    const content = await fs.readFile(path.join(deadDir, best), 'utf8').catch(() => '');
+    return fingerprintOf(content, projectRoot);
+}
+function shortFingerprint(fingerprint) {
+    const hex = fingerprint.startsWith('sha256:') ? fingerprint.slice(7) : fingerprint;
+    return hex.slice(0, 12);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Mark the active marker stuck once, preserving the body after its frontmatter. */
+async function markStuck(folderPath, specId, taskNumber, deadPath, fingerprint, logger) {
+    const content = await fs.readFile(deadPath, 'utf8');
+    const { data, body } = parseFrontmatter(content);
+    if (data.stuck === true)
+        return;
+    await fs.writeFile(deadPath, `---\n${YAML.stringify({ ...data, stuck: true })}---\n${body}`, 'utf8');
+    await appendHarnessEvent(folderPath, taskNumber, {
+        type: 'stuck',
+        timestamp: new Date().toISOString(),
+        data: { task: taskNumber, fingerprint },
+    });
+    logger?.info(`${resolveSymbol('■', '[stuck]', logger?.symbols === true)} task ${taskNumber} of ${specId} stuck: same failure twice (${shortFingerprint(fingerprint)})`);
+}
+async function decideDeadTask(projectRoot, folderPath, specId, taskNumber, deadPath, config, limit, logger) {
+    const content = await fs.readFile(deadPath, 'utf8').catch(() => '');
+    const reason = parseFrontmatter(content).data.reason;
+    if (typeof reason !== 'string' || !ELIGIBLE.has(reason))
+        return 'none';
+    const runDir = path.join(folderPath, '.run');
+    const events = await readStream(folderPath, taskNumber);
+    const fingerprint = fingerprintOf(content, projectRoot);
+    const previous = await highestRetained(path.join(runDir, 'dead'), taskNumber, projectRoot);
+    if (previous !== undefined && previous === fingerprint) {
+        await markStuck(folderPath, specId, taskNumber, deadPath, fingerprint, logger);
+        return 'stuck';
+    }
+    const cutoff = laterOf(await readApprovedAt(runDir), lastManualRetryAt(events));
+    if (automaticRetriesSince(events, cutoff) >= limit)
+        return 'none';
+    try {
+        const result = await retrySpec(projectRoot, specId, taskNumber, config, { automatic: true });
+        logger?.info(`${resolveSymbol('↻', '[retry]', logger?.symbols === true)} task ${taskNumber} of ${specId} retried automatically after ${result.reason} (attempt ${result.attempt})`);
+        return 'retried';
+    }
+    catch (err) {
+        logger?.warn(`task ${taskNumber} of ${specId} automatic retry failed: ${errorMessage(err)}`);
+        return 'none';
+    }
+}
+/**
+ * Decide, per active dead task in an approved change, whether to retry it. Runs
+ * from disk every cycle so a watcher restart between a death and its retry
+ * neither loses nor repeats the action. Returns the number of retries made.
+ */
+export async function runAutomaticRetries(projectRoot, folderPath, config, logger) {
+    const limit = config.gates?.autoRetries ?? 1;
+    if (limit <= 0)
+        return 0;
+    const folderName = path.basename(folderPath);
+    const specId = folderName.match(/^(\d+)/)?.[1] ?? folderName;
+    const deadDir = path.join(folderPath, '.run', 'dead');
+    const entries = (await fs.readdir(deadDir).catch(() => []))
+        .filter((entry) => ACTIVE_DEAD.test(entry))
+        .sort();
+    let retried = 0;
+    for (const entry of entries) {
+        const decision = await decideDeadTask(projectRoot, folderPath, specId, entry.replace(/\.md$/, ''), path.join(deadDir, entry), config, limit, logger);
+        if (decision === 'retried')
+            retried += 1;
+    }
+    return retried;
+}
+//# sourceMappingURL=auto-retry.js.map

package/dist/watcher/auto-retry.js.map

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

package/dist/watcher/build-project.d.ts

@@ -0,0 +1,11 @@
+/** Short HEAD commit for `cwd`, or null when git is missing / not a repo. */
+export declare function readGitCommit(cwd: string): Promise<string | null>;
+/** Top of the git work tree containing `cwd`, or null when not in a repo. */
+export declare function readGitTopLevel(cwd: string): Promise<string | null>;
+/**
+ * Short HEAD commit of the project root, or null when it is not inside a git
+ * repository. Unlike osq's own identity this may resolve to an enclosing work
+ * tree, which is exactly what the project commit means for an installed osq.
+ */
+export declare function resolveProjectCommit(projectRoot: string): Promise<string | null>;
+//# sourceMappingURL=build-project.d.ts.map

package/dist/watcher/build-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-project.d.ts","sourceRoot":"","sources":["../../src/watcher/build-project.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWjE;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWnE;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEtF"}

package/dist/watcher/build-project.js

@@ -0,0 +1,36 @@
+import { execFile } from 'node:child_process';
+/** Short HEAD commit for `cwd`, or null when git is missing / not a repo. */
+export function readGitCommit(cwd) {
+    return new Promise((resolve) => {
+        execFile('git', ['rev-parse', '--short', 'HEAD'], { cwd }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const commit = String(stdout).trim();
+            resolve(commit.length > 0 ? commit : null);
+        });
+    });
+}
+/** Top of the git work tree containing `cwd`, or null when not in a repo. */
+export function readGitTopLevel(cwd) {
+    return new Promise((resolve) => {
+        execFile('git', ['rev-parse', '--show-toplevel'], { cwd }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            const top = String(stdout).trim();
+            resolve(top.length > 0 ? top : null);
+        });
+    });
+}
+/**
+ * Short HEAD commit of the project root, or null when it is not inside a git
+ * repository. Unlike osq's own identity this may resolve to an enclosing work
+ * tree, which is exactly what the project commit means for an installed osq.
+ */
+export async function resolveProjectCommit(projectRoot) {
+    return readGitCommit(projectRoot);
+}
+//# sourceMappingURL=build-project.js.map

package/dist/watcher/build-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-project.js","sourceRoot":"","sources":["../../src/watcher/build-project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YAC3E,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO;YACT,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YAC3E,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO;YACT,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YAClC,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,WAAmB;IAC5D,OAAO,aAAa,CAAC,WAAW,CAAC,CAAC;AACpC,CAAC"}

package/dist/watcher/build.d.ts

@@ -0,0 +1,27 @@
+/** Identity of the osq build currently executing: package version plus commit. */
+export interface BuildInfo {
+    version: string;
+    commit: string;
+}
+/**
+ * Resolve the active osq build identity from an optional osq package root,
+ * defaulting to the running package. Version comes from that root's
+ * `package.json`; the commit is the short git SHA only when the root is the top
+ * of a git work tree, otherwise a hash of that root's `dist/`, otherwise
+ * `unknown`. The project's `package.json` and HEAD are never consulted here;
+ * an installed osq must not report the consumer's identity. The result is
+ * cached per resolved root so the watcher pays the git spawn at most once.
+ */
+export declare function resolveBuildInfo(packageRoot?: string): Promise<BuildInfo>;
+export interface CheckStaleBuildOptions {
+    allowStale?: boolean;
+    packageRoot?: string;
+}
+/**
+ * Refuse to run a compiled osq build whose `dist/` is older than `src/` when
+ * started from a repository checkout. An installed package carries no `src/`
+ * and is never considered stale. Prints exactly one error line and exits with
+ * code 1 when stale, so a developer rebuilds instead of debugging a phantom.
+ */
+export declare function checkStaleBuild(options?: CheckStaleBuildOptions): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/watcher/build.ts"],"names":[],"mappings":"AAOA,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AA8FD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAe/E;AA0BD,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BzF"}

package/dist/watcher/build.js

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readGitCommit, readGitTopLevel } from './build-project.js';
+const UNKNOWN = 'unknown';
+/**
+ * Package root of the running osq build: `src/watcher/` when executed through
+ * `tsx`, `dist/watcher/` once compiled. Both resolve two levels up.
+ */
+const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL('../../', import.meta.url)));
+/**
+ * Whether this module is being executed from TypeScript source (via `tsx`)
+ * rather than from compiled output. Source execution always reflects the
+ * latest code, so there is no compiled build that could be stale.
+ */
+const RUNNING_FROM_SOURCE = fileURLToPath(import.meta.url).endsWith('.ts');
+const buildInfoCache = new Map();
+/**
+ * Read the `version` field from the osq package root's own `package.json`.
+ * The project being watched is never consulted: an installed osq must report
+ * its own version, not the consumer's.
+ */
+async function readVersion(packageRoot) {
+    try {
+        const raw = await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === 'string' && parsed.version.trim().length > 0) {
+            return parsed.version.trim();
+        }
+    }
+    catch {
+        // Missing or malformed file: report unknown.
+    }
+    return UNKNOWN;
+}
+/**
+ * SHA-256 over every file under `dist/`, first 8 hex characters. Paths are
+ * sorted so the hash is stable across filesystems; the relative path is folded
+ * in so a rename changes the hash even when contents do not. Returns `unknown`
+ * when `dist/` is absent or empty.
+ */
+async function hashDist(projectRoot) {
+    const distDir = path.join(projectRoot, 'dist');
+    const files = [];
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                files.push(full);
+            }
+        }
+    };
+    await walk(distDir);
+    if (files.length === 0) {
+        return UNKNOWN;
+    }
+    files.sort();
+    const hash = createHash('sha256');
+    for (const file of files) {
+        const relative = path.relative(distDir, file).split(path.sep).join('/');
+        hash.update(relative);
+        hash.update('\0');
+        hash.update(await fs.readFile(file));
+        hash.update('\0');
+    }
+    return hash.digest('hex').slice(0, 8);
+}
+/** Whether two paths resolve to the same real location on disk. */
+async function sameRealPath(a, b) {
+    try {
+        const [realA, realB] = await Promise.all([fs.realpath(a), fs.realpath(b)]);
+        return realA === realB;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the active osq build identity from an optional osq package root,
+ * defaulting to the running package. Version comes from that root's
+ * `package.json`; the commit is the short git SHA only when the root is the top
+ * of a git work tree, otherwise a hash of that root's `dist/`, otherwise
+ * `unknown`. The project's `package.json` and HEAD are never consulted here;
+ * an installed osq must not report the consumer's identity. The result is
+ * cached per resolved root so the watcher pays the git spawn at most once.
+ */
+export async function resolveBuildInfo(packageRoot) {
+    const root = path.resolve(packageRoot ?? PACKAGE_ROOT);
+    const cached = buildInfoCache.get(root);
+    if (cached) {
+        return cached;
+    }
+    const [version, gitTopLevel] = await Promise.all([readVersion(root), readGitTopLevel(root)]);
+    const commit = gitTopLevel && (await sameRealPath(gitTopLevel, root))
+        ? ((await readGitCommit(root)) ?? (await hashDist(root)))
+        : await hashDist(root);
+    const info = { version, commit };
+    buildInfoCache.set(root, info);
+    return info;
+}
+/** Newest `mtimeMs` among every file below `dir`, or 0 when none exist. */
+async function newestMtimeMs(dir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    let newest = 0;
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            newest = Math.max(newest, await newestMtimeMs(full));
+        }
+        else if (entry.isFile()) {
+            const stat = await fs.stat(full).catch(() => null);
+            if (stat) {
+                newest = Math.max(newest, stat.mtimeMs);
+            }
+        }
+    }
+    return newest;
+}
+/**
+ * Refuse to run a compiled osq build whose `dist/` is older than `src/` when
+ * started from a repository checkout. An installed package carries no `src/`
+ * and is never considered stale. Prints exactly one error line and exits with
+ * code 1 when stale, so a developer rebuilds instead of debugging a phantom.
+ */
+export async function checkStaleBuild(options = {}) {
+    if (options.allowStale === true) {
+        return;
+    }
+    // Executing from TypeScript source means the running code *is* the latest
+    // source, so there is no compiled output that can be stale. An explicit
+    // `packageRoot` (tests, diagnostics) always performs the comparison.
+    if (options.packageRoot === undefined && RUNNING_FROM_SOURCE) {
+        return;
+    }
+    const packageRoot = options.packageRoot ? path.resolve(options.packageRoot) : PACKAGE_ROOT;
+    const srcDir = path.join(packageRoot, 'src');
+    const srcStat = await fs.stat(srcDir).catch(() => null);
+    if (!srcStat?.isDirectory()) {
+        return;
+    }
+    const srcNewest = await newestMtimeMs(srcDir);
+    const distNewest = await newestMtimeMs(path.join(packageRoot, 'dist'));
+    if (srcNewest > distNewest) {
+        console.error("osq build is stale: src/ is newer than dist/. Run 'npm run build' or pass --allow-stale.");
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=build.js.map

package/dist/watcher/build.js.map

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

package/dist/watcher/change-verify.d.ts

@@ -0,0 +1,25 @@
+import type { OsqConfig } from '../core/foundation/config.js';
+import { type VerificationGateResult } from './verify.js';
+/** Failure evidence for a red change gate; the runner writes it through `fail`. */
+export interface ChangeVerifyFailure {
+    marker: string;
+    error: string;
+    extra?: string;
+}
+export type ChangeVerifyOutcome = {
+    ok: true;
+} | ({
+    ok: false;
+} & ChangeVerifyFailure);
+/** Deterministic marker with reason, command, numeric exit code, timeout, output. */
+export declare function formatChangeVerifyMarker(command: string, result: VerificationGateResult): string;
+/** Marker used when an approved proposal exposes no change-level verify command. */
+export declare function formatMissingChangeVerifyMarker(): string;
+/**
+ * Run the proposal's change-level verify after a passing task verify. Returns a
+ * passing outcome when the gate is disabled or green, otherwise failure
+ * evidence for the runner's single `fail` path. The shared gate entrypoint owns
+ * the single `verify_ran` event, attributed to the established `change` target.
+ */
+export declare function runChangeVerifyGate(projectRoot: string, specFolderPath: string, config: OsqConfig): Promise<ChangeVerifyOutcome>;
+//# sourceMappingURL=change-verify.d.ts.map

package/dist/watcher/change-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-verify.d.ts","sourceRoot":"","sources":["../../src/watcher/change-verify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,KAAK,sBAAsB,EAA6B,MAAM,aAAa,CAAC;AAErF,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,CAAC;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,GAAG,mBAAmB,CAAC,CAAC;AAEvF,qFAAqF;AACrF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAahG;AAED,oFAAoF;AACpF,wBAAgB,+BAA+B,IAAI,MAAM,CAQxD;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,mBAAmB,CAAC,CA4B9B"}