@miller-tech/uap 1.161.24 → 1.162.1

package/dist/cli/deliver.d.ts

@@ -217,6 +217,37 @@ export declare function hasExplicitAidFlags(options: DeliverOptions): boolean;
  * filling only fields the user left unset. Exported for tests.
  */
 export declare function applyAutoPlan(options: DeliverOptions, plan: AutoPlan): void;
+/**
+ * Default wedge timeout (seconds). Override with UAP_DELIVER_WEDGE_TIMEOUT.
+ * Deliberately generous (30 min): the heartbeat only advances between
+ * convergence iterations, and one turn on a slow local model (generation + the
+ * full gate ladder) can legitimately take many minutes. The timeout must sit
+ * comfortably above the worst-case single-turn latency so a healthy-but-slow
+ * run is never mistaken for a wedged one and reclaimed out from under itself.
+ */
+export declare const DEFAULT_WEDGE_TIMEOUT_S = 1800;
+/** Resolve the wedge timeout in seconds (env override, else the default). */
+export declare function wedgeTimeoutS(): number;
+/**
+ * Stamp the current epoch-seconds into `.uap/deliver.heartbeat`, ATOMICALLY
+ * (write a temp file then rename over the target). A plain truncate-in-place
+ * write leaves the file momentarily empty, and a concurrent reader would parse
+ * `""` as 0 (epoch 1970) and wrongly conclude the holder is wedged. Best-effort.
+ */
+export declare function updateDeliverHeartbeat(projectRoot: string): void;
+/**
+ * Read the heartbeat epoch-seconds, or null if absent/unreadable/non-positive.
+ * Rejecting non-positive values guards against a torn read (empty file parses
+ * to 0) being treated as a real 1970 timestamp.
+ */
+export declare function readDeliverHeartbeat(projectRoot: string): number | null;
+/**
+ * True when the lock holder is alive but WEDGED — its heartbeat is older than
+ * the wedge timeout. A MISSING heartbeat is not wedged (the holder may be
+ * starting up), so this returns false in that case and the caller keeps
+ * deferring to PID-liveness.
+ */
+export declare function isDeliverHolderWedged(projectRoot: string, nowS?: number): boolean;
 /**
  * Project-level deliver concurrency lock. Prevents a fan-out where an impatient
  * caller (e.g. a model that launched `uap deliver` for some work, didn't wait

package/dist/cli/deliver.d.ts.map

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

package/dist/cli/deliver.js

@@ -7,8 +7,8 @@
  */
 import chalk from 'chalk';
 import { spawnSync } from 'child_process';
-import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeSync, closeSync } from 'fs';
-import { join, resolve } from 'path';
+import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeSync, closeSync, renameSync } from 'fs';
+import { join, resolve, relative } from 'path';
 import { ConvergenceLoop, composeIterationHooks } from '../delivery/convergence-loop.js';
 import { createModelJudge } from '../delivery/judge.js';
 import { createModelCritic } from '../delivery/critic.js';
@@ -65,7 +65,7 @@ export function resolveEvaluatorPreset(opts) {
 export { resolveAcceptanceVerdict } from '../delivery/mission-acceptance.js';
 import { createAgenticExecutor, noopApplier, selectExecutorMode, lockContractFiles } from '../delivery/agentic-executor.js';
 import { createRepairEscalation } from '../delivery/repair-escalation.js';
-import { clearStop, isStopRequested, loadRunState, newRunId, saveRunState, MAX_PERSISTED_PHASES } from '../delivery/run-state.js';
+import { clearStop, isStopRequested, requestStop, loadRunState, newRunId, saveRunState, MAX_PERSISTED_PHASES } from '../delivery/run-state.js';
 import { planDeliveryPhases, shouldDecompose } from '../delivery/decompose.js';
 import { initLedger, markItem } from '../delivery/completion-ledger.js';
 import { loadUapConfigRaw } from '../utils/config-loader.js';
@@ -263,6 +263,73 @@ export function applyAutoPlan(options, plan) {
     if (plan.deployDev && options.deployDev === undefined)
         options.deployDev = true;
 }
+// ─── Deliver wedge detection (P0 reliability) ────────────────────────────────
+// A deliver can wedge (alive PID, but stuck making no progress — e.g. a
+// plan-check re-plan loop or a hung upstream). The lock alone can't tell a
+// healthy long run from a wedged one, so the running deliver stamps a heartbeat
+// on every iteration and the lock path reclaims a holder whose heartbeat has
+// gone stale. Language-agnostic contract: `.uap/deliver.heartbeat` = one integer
+// (unix epoch seconds), rewritten each turn; also read by deliver_autoroute.py.
+/**
+ * Default wedge timeout (seconds). Override with UAP_DELIVER_WEDGE_TIMEOUT.
+ * Deliberately generous (30 min): the heartbeat only advances between
+ * convergence iterations, and one turn on a slow local model (generation + the
+ * full gate ladder) can legitimately take many minutes. The timeout must sit
+ * comfortably above the worst-case single-turn latency so a healthy-but-slow
+ * run is never mistaken for a wedged one and reclaimed out from under itself.
+ */
+export const DEFAULT_WEDGE_TIMEOUT_S = 1800;
+/** Resolve the wedge timeout in seconds (env override, else the default). */
+export function wedgeTimeoutS() {
+    const raw = process.env.UAP_DELIVER_WEDGE_TIMEOUT;
+    const n = raw !== undefined ? Number(raw) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_WEDGE_TIMEOUT_S;
+}
+/**
+ * Stamp the current epoch-seconds into `.uap/deliver.heartbeat`, ATOMICALLY
+ * (write a temp file then rename over the target). A plain truncate-in-place
+ * write leaves the file momentarily empty, and a concurrent reader would parse
+ * `""` as 0 (epoch 1970) and wrongly conclude the holder is wedged. Best-effort.
+ */
+export function updateDeliverHeartbeat(projectRoot) {
+    try {
+        const dir = join(projectRoot, '.uap');
+        mkdirSync(dir, { recursive: true });
+        const hbPath = join(dir, 'deliver.heartbeat');
+        const tmp = `${hbPath}.${process.pid}.tmp`;
+        const fd = openSync(tmp, 'w');
+        writeSync(fd, String(Math.floor(Date.now() / 1000)));
+        closeSync(fd);
+        renameSync(tmp, hbPath);
+    }
+    catch { /* non-fatal — lock path falls back to PID-liveness only */ }
+}
+/**
+ * Read the heartbeat epoch-seconds, or null if absent/unreadable/non-positive.
+ * Rejecting non-positive values guards against a torn read (empty file parses
+ * to 0) being treated as a real 1970 timestamp.
+ */
+export function readDeliverHeartbeat(projectRoot) {
+    try {
+        const v = Number(readFileSync(join(projectRoot, '.uap', 'deliver.heartbeat'), 'utf8').trim());
+        return Number.isFinite(v) && v > 0 ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when the lock holder is alive but WEDGED — its heartbeat is older than
+ * the wedge timeout. A MISSING heartbeat is not wedged (the holder may be
+ * starting up), so this returns false in that case and the caller keeps
+ * deferring to PID-liveness.
+ */
+export function isDeliverHolderWedged(projectRoot, nowS = Math.floor(Date.now() / 1000)) {
+    const hb = readDeliverHeartbeat(projectRoot);
+    if (hb === null)
+        return false;
+    return nowS - hb > wedgeTimeoutS();
+}
 /**
  * Project-level deliver concurrency lock. Prevents a fan-out where an impatient
  * caller (e.g. a model that launched `uap deliver` for some work, didn't wait
@@ -291,8 +358,9 @@ export function acquireDeliverLock(projectRoot) {
         // Reclaim a stale lock (holder no longer alive).
         if (existsSync(lockPath)) {
             const held = Number((readFileSync(lockPath, 'utf8').split('|')[0] || '').trim());
-            if (held && held !== process.pid && pidAlive(held))
-                return null; // live holder
+            // Defer only to a live holder that is NOT wedged; reclaim a stuck one.
+            if (held && held !== process.pid && pidAlive(held) && !isDeliverHolderWedged(projectRoot))
+                return null;
             try {
                 rmSync(lockPath);
             }
@@ -308,6 +376,10 @@ export function acquireDeliverLock(projectRoot) {
         }
         writeSync(fd, `${process.pid}|${new Date().toISOString()}`);
         closeSync(fd);
+        // Stamp a fresh heartbeat immediately so this brand-new holder is never
+        // classified as wedged in the window before its first iteration (and so a
+        // reclaim overwrites the previous holder's stale heartbeat).
+        updateDeliverHeartbeat(projectRoot);
     }
     catch {
         // Lock machinery unavailable — fail OPEN (don't block a legitimate run).
@@ -413,7 +485,7 @@ async function runDeliver(instruction, options) {
         if (releaseLock === null) {
             let holder = '';
             try {
-                holder = readFileSync(join(projectRoot, '.uap', 'deliver.lock'), 'utf8').split('|')[0];
+                holder = stripControl(readFileSync(join(projectRoot, '.uap', 'deliver.lock'), 'utf8').split('|')[0]);
             }
             catch { /* gone already */ }
             console.log(chalk.yellow(`↩ deliver already running for this project${holder ? ` (pid ${holder.trim()})` : ''} — ` +
@@ -424,6 +496,14 @@ async function runDeliver(instruction, options) {
     }
     // The lock is released via acquireDeliverLock's process-exit handler (the
     // deliver CLI is a one-shot process), and explicitly on early returns below.
+    // ── Wedge handling (P0 reliability) ─────────────────────────────────────
+    // A stuck deliver (e.g. a plan-check re-plan loop) no longer blocks future
+    // runs: the heartbeat is refreshed on every iteration (see the loop hook
+    // below) and acquireDeliverLock PASSIVELY reclaims a holder whose heartbeat
+    // has gone stale past the wedge timeout. We deliberately do NOT self-abort via
+    // process.exit here — an abrupt teardown skips snapshot/worktree disposal
+    // (re-opening the known tmpfs-leak class), and a merely-slow turn must never
+    // kill a healthy run. Passive reclaim frees the lock without either hazard.
     // Durable runs: `--resume <id|latest>` restores an interrupted mission —
     // instruction, phase cursor, and the loop checkpoint — and continues it.
     let resumeState = null;
@@ -974,10 +1054,16 @@ async function runDeliver(instruction, options) {
     // read-only for later epics. Mutable by reference — the epic controller
     // grows it between epics; the executor reads it live on every tool call.
     const contractLock = new Set();
+    // ORIGINAL-cased locked contract paths (contractLock stores lowercased match
+    // keys, which are NOT valid FS paths on a case-sensitive filesystem — reading
+    // those back would silently drop PascalCase files like Config.ts). P1 reads
+    // these for verbatim injection.
+    const contractPaths = [];
     const executor = agentic
         ? createAgenticExecutor(model, {
             projectRoot,
             endpoint: agenticEndpoint,
+            onToolProgress: () => updateDeliverHeartbeat(projectRoot), // #2a per-tool-call heartbeat
             temperature,
             contextTokenBudget: sessionBudget,
             contractFiles: contractLock,
@@ -998,6 +1084,7 @@ async function runDeliver(instruction, options) {
         ? createAgenticExecutor(repairModel, {
             projectRoot,
             endpoint: agenticEndpoint,
+            onToolProgress: () => updateDeliverHeartbeat(projectRoot), // #2a per-tool-call heartbeat
             temperature: 0.2,
             contextTokenBudget: sessionBudget,
             contractFiles: contractLock,
@@ -1286,7 +1373,12 @@ async function runDeliver(instruction, options) {
                     errorTail),
             })
             : undefined;
-        return composeIterationHooks((record) => printProgress(record), (record) => {
+        return composeIterationHooks((record) => printProgress(record), (_record) => {
+            // P0 wedge watchdog: each iteration is real progress — refresh the
+            // heartbeat so the watchdog + lock wedge-reclaim only fire on a true stall.
+            updateDeliverHeartbeat(projectRoot);
+            return undefined;
+        }, (record) => {
             // Feed the acceptance breaker's zero-diff guard.
             specs.recordWrites(evidenceRoot, record.filesApplied.length);
             return undefined;
@@ -1363,6 +1455,32 @@ async function runDeliver(instruction, options) {
     };
     // ---- Durable run + optional mission decomposition (fable-style) ----
     const runId = resumeState?.runId ?? newRunId();
+    // #2b: safe cooperative wedge watchdog. If this run stops making tool progress
+    // (heartbeat goes stale past the wedge timeout — #2a stamps it per tool call),
+    // request a COOPERATIVE stop rather than process.exit: the convergence loop's
+    // shouldStop picks it up at the next turn boundary and unwinds through the
+    // normal finally (snapshot/worktree/lock cleanup all run). This lets a
+    // genuinely-wedged run free its lock and exit instead of lingering as an idle
+    // zombie, WITHOUT the abrupt-teardown resource leak the earlier process.exit
+    // watchdog risked. Off-switch rides the existing UAP_DELIVER_NO_LOCK=1.
+    let wedgeWatchdog = null;
+    if (!options.dryRun && process.env.UAP_DELIVER_NO_LOCK !== '1') {
+        // Fresh baseline at arm time so the watchdog never fires on a run that just
+        // started but hasn't stamped yet — critically on --resume (which does NOT
+        // acquire the lock, so acquireDeliverLock's stamp never ran and the on-disk
+        // heartbeat still holds the PRIOR interrupted run's timestamp).
+        updateDeliverHeartbeat(projectRoot);
+        const wedgeS = wedgeTimeoutS();
+        wedgeWatchdog = setInterval(() => {
+            if (isDeliverHolderWedged(projectRoot) && !isStopRequested(projectRoot, runId)) {
+                console.error(chalk.yellow(`⏱ wedge watchdog: no tool progress for ${wedgeS}s — requesting a clean stop so the lock is released.`));
+                requestStop(projectRoot, runId);
+            }
+        }, Math.min(30_000, Math.max(1000, wedgeS * 1000)));
+        wedgeWatchdog.unref();
+        process.once('exit', () => { if (wedgeWatchdog)
+            clearInterval(wedgeWatchdog); });
+    }
     let phases = resumeState?.phases;
     let phaseIndex = resumeState?.phaseIndex ?? 0;
     const phaseSummaries = [...(resumeState?.phaseSummaries ?? [])];
@@ -1645,6 +1763,12 @@ async function runDeliver(instruction, options) {
                     ? createAgenticExecutor(model, {
                         projectRoot: root,
                         endpoint: agenticEndpoint,
+                        // #2a per-tool-call heartbeat. Stamp projectRoot (NOT the
+                        // per-task `root`): the deliver heartbeat is a project-global
+                        // wedge signal the watchdog + lock reclaim read at projectRoot;
+                        // stamping `root` here would leave projectRoot's advancing only
+                        // per-turn, re-opening the false-wedge window for isolated tasks.
+                        onToolProgress: () => updateDeliverHeartbeat(projectRoot),
                         temperature,
                         contextTokenBudget: sessionBudget,
                         contractFiles: contractLock,
@@ -1822,7 +1946,31 @@ async function runDeliver(instruction, options) {
             ledgerInit: (items) => initLedger(projectRoot, instruction, items.map((i) => ({ ...i, kind: 'epic' }))),
             ledgerMark: (id, status, noteText) => markItem(projectRoot, id, status, noteText),
             lockedContracts: () => [...contractLock],
-            lockContracts: (files) => lockContractFiles(contractLock, projectRoot, files),
+            lockContracts: (files) => {
+                const locked = lockContractFiles(contractLock, projectRoot, files);
+                for (const p of locked)
+                    if (!contractPaths.includes(p))
+                        contractPaths.push(p);
+                return locked;
+            },
+            // P1: concatenate the locked contract files' CONTENTS (original-cased
+            // paths) for verbatim injection into later epics (build against the EXACT
+            // shared surface). Reads are contained to the project root.
+            readContractFiles: () => {
+                if (contractPaths.length === 0)
+                    return null;
+                const parts = [];
+                for (const rel of contractPaths) {
+                    const abs = resolve(projectRoot, rel);
+                    if (relative(projectRoot, abs).startsWith('..'))
+                        continue; // never read outside the project
+                    try {
+                        parts.push(`// ===== ${rel} =====\n${readFileSync(abs, 'utf8')}`);
+                    }
+                    catch { /* a locked path that vanished — skip it */ }
+                }
+                return parts.length > 0 ? parts.join('\n\n') : null;
+            },
             maxAttemptsPerEpic: Number(process.env.UAP_DELIVER_EPIC_ATTEMPTS ?? 3), // (#4b) 2→3
             // (#4c) Recursive split depth: a huge epic that still can't land after
             // a split is split again, one level shallower — bounded.
@@ -1894,7 +2042,7 @@ async function runDeliver(instruction, options) {
                 redetectRungs: true,
                 redetectFilter: loopConfig.redetectFilter,
                 protectTests: options.protectTests,
-                onIteration: (record) => printProgress(record),
+                onIteration: (record) => { updateDeliverHeartbeat(projectRoot); printProgress(record); },
             }, executor, seams);
             const lazyResult = await lazyLoop.deliver(instruction);
             if (lazyResult.success) {
@@ -2060,6 +2208,13 @@ async function runDeliver(instruction, options) {
         // The loop is over: from here a normal exit is expected, so stop treating a
         // signal as a mystery death.
         disposeExitRecorder();
+        // Stop the wedge watchdog on the normal completion path too (not only on
+        // process exit) — avoids a stray requestStop on a finished runId and, for
+        // repeated in-process callers, interval/listener accumulation.
+        if (wedgeWatchdog) {
+            clearInterval(wedgeWatchdog);
+            wedgeWatchdog = null;
+        }
     }
     // --keep-best: if deliver left the project worse than it started (by real
     // gate score), roll back to the snapshot so the run is never a regression.