@miller-tech/uap 2.1.7 → 2.11.1

package/dist/supervise/loop.d.ts

@@ -0,0 +1,78 @@
+import { type ClassifierLike } from './assess.js';
+import type { Decision, Observation, SupervisorAction, SupervisorConfig, SupervisorState } from './types.js';
+export declare const SUPERVISE_STATE_VERSION = 1;
+/** Consecutive unanswered ESCALATEs before the watcher gives up. */
+export declare const MAX_SUPPRESSED_ESCALATIONS = 20;
+export interface SupervisorEvent {
+    v: 1;
+    ts: string;
+    runId: string;
+    kind: 'assessment' | 'action';
+    action: SupervisorAction;
+    reason: string;
+    /** True when the action was a repeat of the last one and side effects were skipped. */
+    suppressed?: boolean;
+    evidence: Record<string, unknown>;
+    /** Dimension name → value AND who asserted it (heuristic | classifier). */
+    dimensions: Record<string, {
+        value: boolean | number;
+        source: 'heuristic' | 'classifier';
+    }>;
+}
+export declare function superviseDir(projectRoot: string, runId: string): string;
+export declare function supervisorStatePath(projectRoot: string, runId: string): string;
+export declare function supervisorEventsPath(projectRoot: string, runId: string): string;
+export declare function freshSupervisorState(runId: string, nowIso: string): SupervisorState;
+/**
+ * Load persisted supervisor state, or a fresh one. A MISSING file is normal
+ * (first watch); a file that EXISTS but is unparseable or invalid is not —
+ * warn loudly, then recover fresh (fail closed means never silently dropping
+ * the retry/verify budgets a previous watcher already spent).
+ */
+export declare function loadSupervisorState(projectRoot: string, runId: string, nowIso: string, warn?: (message: string) => void): SupervisorState;
+/**
+ * Persist state atomically (tmp + rename), mode 0600 — the embedded
+ * lastDecision can carry log-tail evidence. Fail-soft (false) on ordinary IO
+ * errors; SupervisorError (path discipline) always propagates.
+ */
+export declare function saveSupervisorState(projectRoot: string, state: SupervisorState): boolean;
+/** Append one v-stamped event record (file created mode 0600). Fail-soft, except SupervisorError. */
+export declare function appendSupervisorEvent(projectRoot: string, runId: string, event: SupervisorEvent): boolean;
+/**
+ * The assessment cadence, PURE: a state change may trigger an assessment once
+ * the debounce has elapsed; a heartbeat forces one once the interval has.
+ */
+export declare function shouldAssess(args: {
+    changed: boolean;
+    sinceLastMs: number;
+    debounceMs: number;
+    intervalMs: number;
+}): boolean;
+export interface RunSupervisorOpts {
+    projectRoot: string;
+    /** Run id or 'latest'. */
+    runId: string;
+    once?: boolean;
+    classifier?: ClassifierLike;
+    /** Injected config (tests); defaults to the packaged reviewed policy. */
+    config?: SupervisorConfig;
+    /** CLI --interval-ms override; clamped to >= debounceMs. */
+    intervalOverrideMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Sink for ESCALATE/STOP warnings; defaults to console.warn. */
+    warn?: (message: string) => void;
+    /** Called after every cycle (CLI prints); not called for suppressed repeats. */
+    onDecision?: (decision: Decision, obs: Observation) => void;
+    /** Safety bound for tests; default unlimited. */
+    maxCycles?: number;
+}
+export interface SupervisorResult {
+    runId: string;
+    decision: Decision;
+    cycles: number;
+    statePath: string;
+    eventsPath: string;
+}
+export declare function runSupervisor(opts: RunSupervisorOpts): Promise<SupervisorResult>;
+//# sourceMappingURL=loop.d.ts.map

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

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

package/dist/supervise/loop.js

@@ -0,0 +1,311 @@
+/**
+ * The supervisor loop: observe → assess → decide → persist, debounced and
+ * periodic.
+ *
+ * Assessments run AT MOST every debounceMs (state-change triggered) and AT
+ * LEAST every intervalMs (heartbeat). State persists per run at
+ * `.uap/supervise/<runId>/state.json` (atomic tmp+rename, mode 0600) and every
+ * cycle appends a v-stamped record to `events.jsonl` (mode 0600).
+ *
+ * Action side effects are deliberately minimal — the supervisor watches, it
+ * does not drive:
+ *   STOP      → requestStop(): the cooperative STOP file the deliver loop
+ *               already polls. NEVER a signal, never a kill.
+ *   RETRY     → consumes one retry from the budget (recorded).
+ *   ESCALATE  → event + console warning only, once per streak; after
+ *               MAX_SUPPRESSED_ESCALATIONS unanswered repeats the loop gives
+ *               up with a final 'escalation unanswered' event.
+ *   VERIFY    → recorded; bounded by cfg.maxVerify (policy-side).
+ *   FINISH/CONTINUE → recorded, nothing else.
+ *
+ * Path discipline: every directory the supervisor writes through is lstat'd
+ * and realpath-checked first — a symlinked `.uap/supervise/<runId>` or
+ * `.uap/deliver-runs/<runId>` (a planted redirect) throws SupervisorError
+ * instead of writing outside the project.
+ */
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync, } from 'fs';
+import { join, sep } from 'path';
+import { deliverRunsDir, requestStop } from '../delivery/run-state.js';
+import { assessAll } from './assess.js';
+import { loadSupervisorConfig, SupervisorError } from './config.js';
+import { collectObservation, runStateMtimeMs } from './observe.js';
+import { decide, effectiveMaxMinutes } from './policy.js';
+export const SUPERVISE_STATE_VERSION = 1;
+/** Consecutive unanswered ESCALATEs before the watcher gives up. */
+export const MAX_SUPPRESSED_ESCALATIONS = 20;
+const TERMINAL_STATUSES = new Set(['delivered', 'failed', 'interrupted']);
+export function superviseDir(projectRoot, runId) {
+    return join(projectRoot, '.uap', 'supervise', runId);
+}
+export function supervisorStatePath(projectRoot, runId) {
+    return join(superviseDir(projectRoot, runId), 'state.json');
+}
+export function supervisorEventsPath(projectRoot, runId) {
+    return join(superviseDir(projectRoot, runId), 'events.jsonl');
+}
+/**
+ * Refuse to write through anything but a plain directory INSIDE baseDir.
+ * lstat (not stat) so symlinks are seen as symlinks — including broken ones,
+ * which existsSync reports as missing. Throws SupervisorError.
+ */
+function ensureContainedDir(baseDir, dir, label) {
+    for (const p of [baseDir, dir]) {
+        let st;
+        try {
+            st = lstatSync(p);
+        }
+        catch {
+            st = undefined; // absent — will be created below
+        }
+        if (st && (st.isSymbolicLink() || !st.isDirectory())) {
+            throw new SupervisorError(`${label}: refusing non-plain-directory path ${p}`);
+        }
+    }
+    mkdirSync(dir, { recursive: true });
+    const realBase = realpathSync(baseDir);
+    const realDir = realpathSync(dir);
+    if (realDir !== realBase && !realDir.startsWith(realBase + sep)) {
+        throw new SupervisorError(`${label}: ${dir} escapes ${baseDir}`);
+    }
+}
+function ensureSuperviseDir(projectRoot, runId) {
+    ensureContainedDir(join(projectRoot, '.uap', 'supervise'), superviseDir(projectRoot, runId), 'supervisor state');
+}
+function ensureDeliverRunDir(projectRoot, runId) {
+    ensureContainedDir(deliverRunsDir(projectRoot), join(deliverRunsDir(projectRoot), runId), 'deliver run');
+}
+export function freshSupervisorState(runId, nowIso) {
+    return {
+        version: SUPERVISE_STATE_VERSION,
+        runId,
+        startedAt: nowIso,
+        updatedAt: nowIso,
+        assessments: 0,
+        retries: 0,
+        verifyCount: 0,
+        suppressedEscalations: 0,
+        lastAction: null,
+        lastActionAt: null,
+    };
+}
+/**
+ * Load persisted supervisor state, or a fresh one. A MISSING file is normal
+ * (first watch); a file that EXISTS but is unparseable or invalid is not —
+ * warn loudly, then recover fresh (fail closed means never silently dropping
+ * the retry/verify budgets a previous watcher already spent).
+ */
+export function loadSupervisorState(projectRoot, runId, nowIso, warn = () => { }) {
+    const path = supervisorStatePath(projectRoot, runId);
+    if (!existsSync(path))
+        return freshSupervisorState(runId, nowIso);
+    const fresh = () => {
+        warn(`supervisor: ${path} exists but is invalid — starting fresh (budgets reset); investigate the corrupt file`);
+        return freshSupervisorState(runId, nowIso);
+    };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return fresh();
+    }
+    if (!parsed || parsed.version !== SUPERVISE_STATE_VERSION || typeof parsed.retries !== 'number') {
+        return fresh();
+    }
+    parsed.runId = runId; // directory name is the identity, never the payload
+    // Fields added after the first shipped state shape default, never reject.
+    if (typeof parsed.verifyCount !== 'number')
+        parsed.verifyCount = 0;
+    if (typeof parsed.suppressedEscalations !== 'number')
+        parsed.suppressedEscalations = 0;
+    return parsed;
+}
+/**
+ * Persist state atomically (tmp + rename), mode 0600 — the embedded
+ * lastDecision can carry log-tail evidence. Fail-soft (false) on ordinary IO
+ * errors; SupervisorError (path discipline) always propagates.
+ */
+export function saveSupervisorState(projectRoot, state) {
+    try {
+        ensureSuperviseDir(projectRoot, state.runId);
+        const path = supervisorStatePath(projectRoot, state.runId);
+        const tmp = `${path}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        renameSync(tmp, path);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof SupervisorError)
+            throw err;
+        return false;
+    }
+}
+/** Append one v-stamped event record (file created mode 0600). Fail-soft, except SupervisorError. */
+export function appendSupervisorEvent(projectRoot, runId, event) {
+    try {
+        ensureSuperviseDir(projectRoot, runId);
+        appendFileSync(supervisorEventsPath(projectRoot, runId), JSON.stringify(event) + '\n', {
+            encoding: 'utf-8',
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch (err) {
+        if (err instanceof SupervisorError)
+            throw err;
+        return false;
+    }
+}
+/**
+ * The assessment cadence, PURE: a state change may trigger an assessment once
+ * the debounce has elapsed; a heartbeat forces one once the interval has.
+ */
+export function shouldAssess(args) {
+    if (args.sinceLastMs >= args.intervalMs)
+        return true;
+    return args.changed && args.sinceLastMs >= args.debounceMs;
+}
+export async function runSupervisor(opts) {
+    const baseCfg = opts.config ?? loadSupervisorConfig();
+    const cfg = opts.intervalOverrideMs !== undefined
+        ? (() => {
+            if (!Number.isFinite(opts.intervalOverrideMs) || opts.intervalOverrideMs <= 0) {
+                throw new SupervisorError(`--interval-ms must be a positive number (got ${opts.intervalOverrideMs})`);
+            }
+            return { ...baseCfg, intervalMs: Math.max(baseCfg.debounceMs, Math.floor(opts.intervalOverrideMs)) };
+        })()
+        : baseCfg;
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const warn = opts.warn ?? ((m) => console.warn(m));
+    const tickMs = Math.min(cfg.debounceMs, 1000);
+    // Resolve 'latest' and fail fast when there is nothing to watch.
+    const first = collectObservation(opts.projectRoot, opts.runId, now);
+    if (!first) {
+        throw new SupervisorError(`no deliver run '${opts.runId}' under ${opts.projectRoot}`);
+    }
+    const runId = first.runId;
+    const state = loadSupervisorState(opts.projectRoot, runId, new Date(now()).toISOString(), warn);
+    let lastAssessAt = 0;
+    let lastMtime = runStateMtimeMs(opts.projectRoot, runId);
+    let cycles = 0;
+    let decision;
+    let lastStatus = first.status;
+    const applyDecision = (d, dims) => {
+        const ts = new Date(now()).toISOString();
+        const firstOfStreak = d.action !== state.lastAction;
+        const suppressed = !firstOfStreak && (d.action === 'ESCALATE' || d.action === 'FINISH');
+        if (!suppressed) {
+            if (d.action === 'STOP') {
+                ensureDeliverRunDir(opts.projectRoot, runId);
+                requestStop(opts.projectRoot, runId);
+                if (firstOfStreak)
+                    warn(`supervisor: STOP ${runId} — ${d.reason} (cooperative stop file written; no signals sent)`);
+            }
+            else if (d.action === 'RETRY') {
+                state.retries += 1;
+            }
+            else if (d.action === 'VERIFY') {
+                state.verifyCount += 1;
+            }
+            else if (d.action === 'ESCALATE') {
+                warn(`supervisor: ESCALATE ${runId} — ${d.reason}`);
+            }
+        }
+        // Budget bookkeeping: verifyCount resets when test evidence reappears;
+        // the unanswered-escalation streak counts consecutive suppressed repeats.
+        if (!dims.some((x) => x.name === 'verification-pending' && x.value === true)) {
+            state.verifyCount = 0;
+        }
+        if (suppressed && d.action === 'ESCALATE') {
+            state.suppressedEscalations += 1;
+        }
+        else {
+            state.suppressedEscalations = 0;
+        }
+        state.assessments += 1;
+        state.lastAction = d.action;
+        state.lastActionAt = ts;
+        state.lastDecision = d;
+        state.updatedAt = ts;
+        saveSupervisorState(opts.projectRoot, state);
+        const dimensions = {};
+        for (const dim of dims) {
+            dimensions[dim.name] = { value: dim.value, source: dim.source };
+        }
+        appendSupervisorEvent(opts.projectRoot, runId, {
+            v: 1,
+            ts,
+            runId,
+            kind: d.action === 'CONTINUE' ? 'assessment' : 'action',
+            action: d.action,
+            reason: d.reason,
+            ...(suppressed ? { suppressed: true } : {}),
+            evidence: d.evidence,
+            dimensions,
+        });
+    };
+    const cycle = () => {
+        const obs = collectObservation(opts.projectRoot, runId, now);
+        if (!obs)
+            throw new SupervisorError(`deliver run '${runId}' vanished mid-supervision`);
+        const dims = assessAll(obs, cfg, opts.classifier);
+        // An operator-raised deliver budget outranks the static policy number.
+        const policyCfg = {
+            ...cfg,
+            maxMinutes: effectiveMaxMinutes(cfg, opts.projectRoot),
+        };
+        const d = decide(obs, dims, state, policyCfg);
+        applyDecision(d, dims);
+        cycles += 1;
+        lastAssessAt = now();
+        lastStatus = obs.status;
+        opts.onDecision?.(d, obs);
+        return d;
+    };
+    for (;;) {
+        const mtime = runStateMtimeMs(opts.projectRoot, runId);
+        const changed = mtime !== lastMtime;
+        if (changed)
+            lastMtime = mtime;
+        const sinceLast = lastAssessAt === 0 ? Number.POSITIVE_INFINITY : now() - lastAssessAt;
+        if (shouldAssess({ changed, sinceLastMs: sinceLast, debounceMs: cfg.debounceMs, intervalMs: cfg.intervalMs })) {
+            decision = cycle();
+            if (opts.once)
+                break;
+            if (decision.action === 'STOP' || decision.action === 'FINISH')
+                break;
+            if (TERMINAL_STATUSES.has(lastStatus))
+                break;
+            if (state.suppressedEscalations >= MAX_SUPPRESSED_ESCALATIONS) {
+                // The escalation went unanswered for the whole bound — stop watching
+                // rather than filling the ledger forever. The final event says why.
+                appendSupervisorEvent(opts.projectRoot, runId, {
+                    v: 1,
+                    ts: new Date(now()).toISOString(),
+                    runId,
+                    kind: 'action',
+                    action: 'ESCALATE',
+                    reason: 'escalation unanswered',
+                    evidence: { suppressedEscalations: state.suppressedEscalations },
+                    dimensions: {},
+                });
+                warn(`supervisor: ESCALATE ${runId} unanswered after ${MAX_SUPPRESSED_ESCALATIONS} repeats — detaching watcher`);
+                break;
+            }
+            if (opts.maxCycles !== undefined && cycles >= opts.maxCycles)
+                break;
+        }
+        await sleep(tickMs);
+    }
+    if (!decision)
+        throw new SupervisorError('supervisor exited without assessing');
+    return {
+        runId,
+        decision,
+        cycles,
+        statePath: supervisorStatePath(opts.projectRoot, runId),
+        eventsPath: supervisorEventsPath(opts.projectRoot, runId),
+    };
+}
+//# sourceMappingURL=loop.js.map

package/dist/supervise/loop.js.map

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

package/dist/supervise/observe.d.ts

@@ -0,0 +1,31 @@
+import type { Observation } from './types.js';
+/** Log tail budget — enough for error signatures, small enough to be safe. */
+export declare const LOG_TAIL_BYTES = 8192;
+/** `git diff --stat` cap; a monorepo diff can list thousands of files. */
+export declare const DIFF_STAT_MAX_CHARS = 4000;
+export declare const GIT_TIMEOUT_MS = 5000;
+/**
+ * Read at most the last `maxBytes` of a file. Fail-soft: undefined on any
+ * error, and silently for anything that is not a plain regular file (a
+ * symlinked log or a FIFO must never be followed into a blocking read).
+ */
+export declare function tailFile(path: string, maxBytes?: number): string | undefined;
+/**
+ * Newest log plausibly belonging to a run. Run ids embed the launch stamp
+ * (`run-<YYYYMMDDTHHMMSS>-<hex>`) and the detached wrapper names its log
+ * `deliver-<YYYYMMDDTHHMMSS>.log` moments earlier, so the right log is the
+ * newest stamped at-or-before the run's stamp; absent any stamped match, the
+ * newest log by mtime. Undefined when there are no logs at all.
+ */
+export declare function newestLogForRun(projectRoot: string, runId: string): string | undefined;
+export declare function gitDirtyFileCount(projectRoot: string): number | undefined;
+export declare function gitDiffStat(projectRoot: string): string | undefined;
+/** mtime of the run's state.json — the change signal the debounce watches. */
+export declare function runStateMtimeMs(projectRoot: string, runId: string): number;
+/**
+ * Collect one bounded observation for a run. `runId` may be 'latest'
+ * (resolved by run-state). Returns null for invalid ids and unknown runs —
+ * the caller decides how loud to be. `now` is injectable for tests.
+ */
+export declare function collectObservation(projectRoot: string, runId: string, now?: () => number): Observation | null;
+//# sourceMappingURL=observe.d.ts.map

package/dist/supervise/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/supervise/observe.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,8EAA8E;AAC9E,eAAO,MAAM,cAAc,OAAO,CAAC;AACnC,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,cAAc,OAAO,CAAC;AAcnC;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAuB,GAAG,MAAM,GAAG,SAAS,CAqB5F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA6BtF;AAiBD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIzE;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM1E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,MAAiB,GAC3B,WAAW,GAAG,IAAI,CAyBpB"}

package/dist/supervise/observe.js

@@ -0,0 +1,172 @@
+/**
+ * Observation collection — the ONLY impure step in the supervisor.
+ *
+ * Everything read here is bounded and fail-soft:
+ *  - run state comes from run-state.ts's sanitizing loader (never trusted raw)
+ *  - log tails are read with an fd seek of the last N bytes, never a whole-file
+ *    readFileSync (a multi-GB mission log must not be slurped)
+ *  - git runs via execFileSync ARG ARRAYS (no shell, no interpolation), piped
+ *    stdio, 5s timeout — and any failure degrades to `undefined`, never throws
+ */
+import { execFileSync } from 'child_process';
+import { closeSync, fstatSync, lstatSync, openSync, readSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { deliverRunsDir, isValidRunId, loadRunState } from '../delivery/run-state.js';
+/** Log tail budget — enough for error signatures, small enough to be safe. */
+export const LOG_TAIL_BYTES = 8192;
+/** `git diff --stat` cap; a monorepo diff can list thousands of files. */
+export const DIFF_STAT_MAX_CHARS = 4000;
+export const GIT_TIMEOUT_MS = 5000;
+/** Defeat fsmonitor/untracked-cache shims: observation must see the real tree. */
+const GIT_ARGS_PREFIX = ['-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false'];
+/** True only for a plain regular file — symlinks/FIFOs/devices are skipped. */
+function isRegularFile(path) {
+    try {
+        const st = lstatSync(path);
+        return !st.isSymbolicLink() && st.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read at most the last `maxBytes` of a file. Fail-soft: undefined on any
+ * error, and silently for anything that is not a plain regular file (a
+ * symlinked log or a FIFO must never be followed into a blocking read).
+ */
+export function tailFile(path, maxBytes = LOG_TAIL_BYTES) {
+    if (!isRegularFile(path))
+        return undefined;
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const size = fstatSync(fd).size;
+        const start = Math.max(0, size - maxBytes);
+        const buf = Buffer.alloc(size - start);
+        readSync(fd, buf, 0, buf.length, start);
+        return buf.toString('utf-8');
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    }
+}
+/**
+ * Newest log plausibly belonging to a run. Run ids embed the launch stamp
+ * (`run-<YYYYMMDDTHHMMSS>-<hex>`) and the detached wrapper names its log
+ * `deliver-<YYYYMMDDTHHMMSS>.log` moments earlier, so the right log is the
+ * newest stamped at-or-before the run's stamp; absent any stamped match, the
+ * newest log by mtime. Undefined when there are no logs at all.
+ */
+export function newestLogForRun(projectRoot, runId) {
+    const dir = join(projectRoot, '.uap', 'deliver-logs');
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter((f) => f.endsWith('.log'))
+            .filter((f) => isRegularFile(join(dir, f)));
+    }
+    catch {
+        return undefined;
+    }
+    if (files.length === 0)
+        return undefined;
+    const runStamp = /^run-(\d{8}T\d{6})/.exec(runId)?.[1];
+    if (runStamp) {
+        const eligible = files
+            .map((f) => ({ f, stamp: /^deliver-(\d{8}T\d{6})\.log$/.exec(f)?.[1] }))
+            .filter((x) => x.stamp !== undefined && x.stamp <= runStamp)
+            .sort((a, b) => b.stamp.localeCompare(a.stamp));
+        if (eligible.length > 0)
+            return join(dir, eligible[0].f);
+    }
+    let best;
+    for (const f of files) {
+        try {
+            const mtime = statSync(join(dir, f)).mtimeMs;
+            if (!best || mtime > best.mtime)
+                best = { f, mtime };
+        }
+        catch {
+            /* vanished between readdir and stat */
+        }
+    }
+    return best ? join(dir, best.f) : undefined;
+}
+/** git, fail-soft: undefined on any error (not a repo, timeout, no binary). */
+function git(projectRoot, args) {
+    try {
+        const out = execFileSync('git', [...GIT_ARGS_PREFIX, ...args], {
+            cwd: projectRoot,
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            maxBuffer: 1024 * 1024,
+        });
+        return out.toString('utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+export function gitDirtyFileCount(projectRoot) {
+    const out = git(projectRoot, ['status', '--porcelain']);
+    if (out === undefined)
+        return undefined;
+    return out.split('\n').filter((l) => l.trim().length > 0).length;
+}
+export function gitDiffStat(projectRoot) {
+    const out = git(projectRoot, ['diff', '--stat']);
+    return out === undefined ? undefined : out.slice(0, DIFF_STAT_MAX_CHARS);
+}
+/** mtime of the run's state.json — the change signal the debounce watches. */
+export function runStateMtimeMs(projectRoot, runId) {
+    try {
+        return statSync(join(deliverRunsDir(projectRoot), runId, 'state.json')).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Collect one bounded observation for a run. `runId` may be 'latest'
+ * (resolved by run-state). Returns null for invalid ids and unknown runs —
+ * the caller decides how loud to be. `now` is injectable for tests.
+ */
+export function collectObservation(projectRoot, runId, now = Date.now) {
+    if (runId !== 'latest' && !isValidRunId(runId))
+        return null;
+    const state = loadRunState(projectRoot, runId);
+    if (!state)
+        return null;
+    const nowMs = now();
+    const created = Date.parse(state.createdAt);
+    const updated = Date.parse(state.updatedAt);
+    const elapsedMinutes = Number.isFinite(created) ? Math.max(0, (nowMs - created) / 60_000) : 0;
+    const minutesSinceUpdate = Number.isFinite(updated) ? Math.max(0, (nowMs - updated) / 60_000) : elapsedMinutes;
+    const cp = state.checkpoint;
+    const failures = cp?.history?.filter((h) => !h.passed).length ?? 0;
+    const logPath = newestLogForRun(projectRoot, state.runId);
+    return {
+        runId: state.runId,
+        status: state.status,
+        instruction: state.instruction,
+        elapsedMinutes,
+        minutesSinceUpdate,
+        turnsCompleted: cp?.turn ?? 0,
+        failures,
+        hasCheckpoint: cp !== undefined,
+        recentLogTail: (logPath && tailFile(logPath)) || '',
+        gitDirtyFiles: gitDirtyFileCount(projectRoot),
+        diffStat: gitDiffStat(projectRoot),
+    };
+}
+//# sourceMappingURL=observe.js.map

package/dist/supervise/observe.js.map

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

package/dist/supervise/policy.d.ts

@@ -0,0 +1,16 @@
+import type { Decision, DimensionAssessment, Observation, SupervisorConfig, SupervisorState } from './types.js';
+/** The policy state it needs: retry/verify budgets + the oscillation guard's memory. */
+export type PolicyState = Pick<SupervisorState, 'retries' | 'lastAction' | 'verifyCount'>;
+/**
+ * The budget the STOP branch enforces: the LARGER of the supervisor policy
+ * and the deliver run's own budget (`UAP_DELIVER_MAX_MINUTES` /
+ * `.uap.json delivery.maxRunMinutes` / the calibrated default). An
+ * operator-raised deliver budget must not be overruled by the supervisor's
+ * static policy number; a LOWER operator budget makes the deliver loop stop
+ * itself first anyway, so taking the max never extends a mission past what
+ * its owner granted. Impure (reads env/config) — callers pass the result in
+ * via an adjusted cfg so decide() itself stays pure.
+ */
+export declare function effectiveMaxMinutes(cfg: SupervisorConfig, projectRoot: string): number;
+export declare function decide(obs: Observation, dims: DimensionAssessment[], state: PolicyState, cfg: SupervisorConfig): Decision;
+//# sourceMappingURL=policy.d.ts.map

package/dist/supervise/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/supervise/policy.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAehH,wFAAwF;AACxF,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,YAAY,GAAG,aAAa,CAAC,CAAC;AAE1F;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtF;AAgBD,wBAAgB,MAAM,CACpB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,mBAAmB,EAAE,EAC3B,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,gBAAgB,GACpB,QAAQ,CAiGV"}