@enderfga/claw-orchestrator 5.1.0 → 6.0.0

package/dist/src/ultraapp/build.js

@@ -4,29 +4,293 @@
  * Default concurrency = 1. Pending builds are FIFO. Subscribers receive every
  * BuildEvent emitted by the worker for any currently-running build.
  *
- * Disk persistence (in-progress + pending lists) is NOT done in v0.2 — if the
- * orchestrator restarts mid-build, the build is marked failed and the user
- * can rerun. Adding restart resilience is later scope.
+ * The queue is durable as of 6.0.0. It used to say so in this comment: "Disk
+ * persistence (in-progress + pending lists) is NOT done in v0.2 — if the
+ * orchestrator restarts mid-build, the build is marked failed and the user can
+ * rerun." In practice a restart did not mark anything: the pending list simply
+ * vanished, along with any queued build the user was waiting on, with no record
+ * that it had ever been asked for.
+ *
+ * Now the pending list and the in-flight run id are written on every change and
+ * restored on construction. A build that was in flight when the process died is
+ * re-queued rather than resumed — each build starts from a fresh council
+ * worktree, so re-running is safe and resuming a half-built tree is not.
+ *
+ * Durability without ownership would be worse than neither: two processes each
+ * restoring the same file would each run the same builds, doing every side
+ * effect twice. So restoring takes a lease on the state file, held by pid and
+ * heartbeated. A queue that cannot take the lease starts empty and leaves the
+ * work to whoever owns it.
  */
+import crypto from 'node:crypto';
 import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+import { withFileLock } from '../kernel/file-lock.js';
+/** How long an owner may go without a heartbeat before the queue is up for grabs. */
+const OWNER_TTL_MS = 60_000;
+/** Refresh interval, comfortably inside the TTL. */
+const HEARTBEAT_MS = 15_000;
+function ownerIsLive(owner, selfId) {
+    if (!owner)
+        return false;
+    if (owner.ownerId === selfId)
+        return true;
+    const age = Date.now() - Date.parse(owner.renewedAt);
+    if (Number.isNaN(age) || age > OWNER_TTL_MS)
+        return false;
+    try {
+        process.kill(owner.pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
 export class UltraappBuildQueue {
     emitter = new EventEmitter();
     pending = [];
     currentRunId = null;
     worker;
     concurrency;
+    statePath;
+    heartbeat;
+    /** This queue instance's identity as an owner. Per instance, not per process. */
+    ownerId = `queue-${crypto.randomUUID()}`;
+    /** Consecutive failed dispatch claims, per build. Cleared once it starts. */
+    dispatchRetries = new Map();
     idlePromise = Promise.resolve();
     idleResolve = null;
     constructor(opts) {
         this.worker = opts.worker;
         this.concurrency = opts.concurrency ?? 1;
+        this.statePath = opts.statePath;
+        const restored = this.restore();
+        if (this.statePath && !this.notOwner) {
+            // Independent of any build finishing: a worker that runs for ten minutes
+            // makes no state writes, and must not look abandoned for it.
+            this.heartbeat = setInterval(() => this.persist(), HEARTBEAT_MS);
+            if (typeof this.heartbeat.unref === 'function')
+                this.heartbeat.unref();
+        }
+        if (this.notOwner)
+            opts.onNotOwner?.(this.notOwner);
+        if (restored.length > 0) {
+            opts.onRestore?.(restored);
+            this.markBusy();
+            void this.tryDispatch();
+        }
+    }
+    /** Set when another live queue holds the claim. */
+    notOwner;
+    /**
+     * True when this process is executing the queue.
+     *
+     * Reads the state file rather than answering from the last decision, so a
+     * queue that has been taken over reports it even before its next write finds
+     * out. Advisory only — nothing acts on this answer; `enqueue` and dispatch
+     * re-check under the lock, because a lock-free read is a snapshot and a claim
+     * is not.
+     */
+    ownsQueue() {
+        if (this.notOwner)
+            return false;
+        if (!this.statePath)
+            return true;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.statePath, 'utf8'));
+            if (parsed?.owner && parsed.owner.ownerId !== this.ownerId && ownerIsLive(parsed.owner, this.ownerId)) {
+                return false;
+            }
+        }
+        catch {
+            // No state file yet, or unreadable: nothing says anyone else has it.
+        }
+        return true;
+    }
+    /** Refuse an operation that only the owner may perform. */
+    assertOwner(action) {
+        if (!this.notOwner)
+            return;
+        throw new Error(`Cannot ${action}: this build queue is owned by ${this.notOwner.ownerId} (pid ${this.notOwner.pid}) ` +
+            `(last seen ${this.notOwner.renewedAt}). Running its builds here would execute them twice.`);
+    }
+    /** Release the claim so another process can pick the queue up promptly. */
+    stop() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = undefined;
+    }
+    /**
+     * Read back a queue left by a previous process.
+     *
+     * A build that was in flight goes to the FRONT of the restored queue: it was
+     * asked for first, and the user has been waiting on it longest.
+     */
+    /**
+     * Claim the queue and read back whatever the last owner left.
+     *
+     * Read-then-decide is not a claim. Two processes starting with no state file
+     * both saw "free", both concluded they owned it, and nothing wrote an owner
+     * until the first enqueue — by which time both were running the same builds.
+     * The read and the claim happen inside one `O_EXCL` critical section now.
+     */
+    restore() {
+        if (!this.statePath)
+            return [];
+        let entered = false;
+        const ids = this.withLock(() => {
+            entered = true;
+            return this.claimLocked();
+        }, []);
+        if (!entered && !this.notOwner) {
+            // We never got inside the critical section — someone else is claiming
+            // right now, or the lock file is unusable. Either way we have not taken
+            // the queue, and acting as though we had is how both processes end up
+            // running the same builds.
+            this.notOwner = { ownerId: 'unknown', pid: -1, renewedAt: new Date().toISOString() };
+        }
+        return ids ?? [];
+    }
+    /**
+     * Run `fn` inside the queue's lock, waiting briefly for it.
+     *
+     * Shared with the run store, and for the same reason: a lock that is merely
+     * busy must not be reported the same way as a claim that has moved on.
+     */
+    withLock(fn, onContended) {
+        if (!this.statePath)
+            return undefined;
+        const result = withFileLock(`${this.statePath}.lock`, fn, { staleMs: OWNER_TTL_MS, createParent: true });
+        return result.ok ? result.value : onContended;
+    }
+    /** The critical section of `restore`: inspect the owner and take it, or step aside. */
+    claimLocked() {
+        if (!this.statePath)
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(this.statePath, 'utf8'));
+        }
+        catch {
+            parsed = { pending: [], current: null };
+        }
+        if (ownerIsLive(parsed.owner, this.ownerId)) {
+            // Someone else is running these. Taking them would execute every build
+            // twice; the honest move is to start empty and say so.
+            this.notOwner = parsed.owner;
+            return [];
+        }
+        const ids = [
+            ...(parsed.current ? [parsed.current] : []),
+            ...(Array.isArray(parsed.pending) ? parsed.pending.filter((x) => typeof x === 'string') : []),
+        ];
+        for (const runId of ids)
+            this.pending.push({ runId });
+        // Stake the claim before releasing the lock, so a racer that gets in next
+        // sees an owner rather than an empty file.
+        this.writeStateUnchecked();
+        return ids;
+    }
+    /**
+     * Persist the queue, if we still own it.
+     *
+     * Best-effort about I/O, not about ownership: the check happens inside the
+     * lock, in the same critical section as the write. Taking the claim at
+     * construction and then writing unconditionally forever was not ownership — a
+     * queue whose heartbeat had lapsed and been taken over would quietly stamp
+     * itself back in as owner on its next persist, clobbering the new owner's
+     * pending list and running its builds a second time.
+     */
+    persist() {
+        if (!this.statePath)
+            return 'ephemeral';
+        if (this.notOwner)
+            return 'superseded';
+        return this.withLock(() => this.writeStateLocked(), 'blocked') ?? 'blocked';
+    }
+    /** Caller must hold the lock. Steps aside — permanently — if the claim moved on. */
+    writeStateLocked() {
+        if (!this.statePath)
+            return 'ephemeral';
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(this.statePath, 'utf8'));
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (parsed?.owner && parsed.owner.ownerId !== this.ownerId && ownerIsLive(parsed.owner, this.ownerId)) {
+            this.standDown(parsed.owner);
+            return 'superseded';
+        }
+        this.writeStateUnchecked();
+        return 'committed';
+    }
+    /**
+     * Hand the queue over: stop heartbeating and drop the pending list.
+     *
+     * Keeping the list would be worse than losing it — every entry now belongs to
+     * the new owner, who has its own copy, and dispatching from ours is the double
+     * execution the claim exists to prevent. A build already in flight cannot be
+     * recalled; it finishes, and nothing further starts.
+     */
+    standDown(owner) {
+        this.notOwner = owner;
+        this.stop();
+        this.pending.length = 0;
+        if (this.currentRunId === null)
+            this.markIdle();
+    }
+    writeStateUnchecked() {
+        if (!this.statePath)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.statePath), { recursive: true });
+            const state = {
+                pending: this.pending.map((p) => p.runId),
+                current: this.currentRunId,
+                // Every write is also the heartbeat, so a queue that stops making
+                // progress stops holding the claim.
+                owner: { ownerId: this.ownerId, pid: process.pid, renewedAt: new Date().toISOString() },
+            };
+            const tmp = `${this.statePath}.tmp.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
+            fs.writeFileSync(tmp, JSON.stringify(state));
+            fs.renameSync(tmp, this.statePath);
+        }
+        catch {
+            // A queue that cannot be persisted still works for this process.
+        }
     }
     /**
      * Enqueue a build. Resolves immediately after the run is appended to the
      * pending list. Use {@link idle} to wait for the queue to drain.
      */
     async enqueue(runId) {
+        // Refusing at construction is not enough: `ownsQueue()` returning false
+        // while `enqueue` cheerfully ran the build — and rewrote the owner to
+        // ourselves — is exactly the double execution the claim exists to stop.
+        this.assertOwner('enqueue');
         this.pending.push({ runId });
+        // The claim is re-checked inside the same critical section the write happens
+        // in. Owning the queue at construction says nothing about owning it now: the
+        // heartbeat can have lapsed and someone else can have taken over, and an
+        // `enqueue` that only consulted the construction-time answer would run their
+        // builds a second time.
+        //
+        // Three outcomes, not two. `superseded` refuses. `blocked` — we could not
+        // even get into the critical section — also refuses, because an enqueue that
+        // cannot be recorded may be an enqueue into a queue somebody else now owns;
+        // the earlier version returned a bare `false` here and carried on, and ran a
+        // build whose queue state on disk already belonged to another process.
+        const persisted = this.persist();
+        if (persisted === 'superseded')
+            this.assertOwner('enqueue');
+        if (persisted === 'blocked') {
+            this.pending.pop();
+            throw new Error(`Cannot enqueue: the build queue state file is locked by another process, so this build cannot be ` +
+                `recorded. Retry in a moment.`);
+        }
         this.markBusy();
         const pos = this.position(runId);
         if (pos > 0) {
@@ -38,6 +302,7 @@ export class UltraappBuildQueue {
         const idx = this.pending.findIndex((p) => p.runId === runId);
         if (idx >= 0) {
             this.pending.splice(idx, 1);
+            this.persist();
             this.emit({ type: 'build-cancelled', runId });
             if (this.pending.length === 0 && this.currentRunId === null)
                 this.markIdle();
@@ -65,6 +330,8 @@ export class UltraappBuildQueue {
         return this.idlePromise;
     }
     async tryDispatch() {
+        if (this.notOwner)
+            return;
         if (this.currentRunId !== null)
             return;
         if (this.concurrency !== 1)
@@ -75,6 +342,25 @@ export class UltraappBuildQueue {
             return;
         }
         this.currentRunId = next.runId;
+        // Same check before starting work as before recording it, and with the same
+        // three outcomes: only `committed` (or an ephemeral queue, which owns
+        // nothing and persists nothing) may dispatch. Dispatching on `blocked` is
+        // how a superseded queue ran a build whose state on disk already named
+        // another owner.
+        const persisted = this.persist();
+        if (persisted === 'superseded') {
+            this.currentRunId = null;
+            this.markIdle();
+            return;
+        }
+        if (persisted === 'blocked') {
+            // Transient: put the build back at the front and try again shortly.
+            this.currentRunId = null;
+            this.pending.unshift(next);
+            this._retryDispatch(next.runId);
+            return;
+        }
+        this.dispatchRetries.delete(next.runId);
         try {
             await this.worker(next.runId, (e) => this.emit(e));
         }
@@ -88,9 +374,39 @@ export class UltraappBuildQueue {
         }
         finally {
             this.currentRunId = null;
+            this.persist();
             void this.tryDispatch();
         }
     }
+    /**
+     * Re-attempt a dispatch that could not claim the state file.
+     *
+     * Bounded: a queue that cannot record what it is doing must eventually say so
+     * rather than spinning, and the build is failed with the reason instead of
+     * quietly never starting.
+     */
+    _retryDispatch(runId) {
+        const attempts = (this.dispatchRetries.get(runId) ?? 0) + 1;
+        this.dispatchRetries.set(runId, attempts);
+        if (attempts > 8) {
+            this.dispatchRetries.delete(runId);
+            const idx = this.pending.findIndex((p) => p.runId === runId);
+            if (idx >= 0)
+                this.pending.splice(idx, 1);
+            this.emit({
+                type: 'build-failed',
+                runId,
+                phase: 'orchestrator',
+                reason: 'the build queue state file stayed locked by another process; the build was not started',
+            });
+            if (this.pending.length === 0 && this.currentRunId === null)
+                this.markIdle();
+            return;
+        }
+        const timer = setTimeout(() => void this.tryDispatch(), 100 * attempts);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+    }
     emit(e) {
         this.emitter.emit('event', e);
     }

package/dist/src/ultraapp/build.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/ultraapp/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAc3C,MAAM,OAAO,kBAAkB;IACZ,OAAO,GAAG,IAAI,YAAY,EAAE,CAAC;IAC7B,OAAO,GAAkB,EAAE,CAAC;IACrC,YAAY,GAAkB,IAAI,CAAC;IAC1B,MAAM,CAAS;IACf,WAAW,CAAS;IAC7B,WAAW,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/C,WAAW,GAAwB,IAAI,CAAC;IAEhD,YAAY,IAA+B;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,KAAa;QACzB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7B,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACZ,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;IAC1B,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QAC7D,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;YAC9C,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI;gBAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC/E,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;YAChC,gEAAgE;YAChE,kEAAkE;YAClE,+CAA+C;YAC/C,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,KAAa;QACpB,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK;YAAE,OAAO,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QAC7D,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,SAAS,CAAC,QAAiC;QACzC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAEO,KAAK,CAAC,WAAW;QACvB,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI;YAAE,OAAO;QACvC,IAAI,IAAI,CAAC,WAAW,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACvF,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,IAAI,CAAC;gBACR,IAAI,EAAE,cAAc;gBACpB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,cAAc;gBACrB,MAAM,EAAG,CAAW,CAAC,OAAO;aAC7B,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC;IAEO,IAAI,CAAC,CAAa;QACxB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IAEO,QAAQ;QACd,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;YAC9B,IAAI,CAAC,WAAW,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;YAC7B,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,QAAQ;QACd,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAC1B,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/ultraapp/build.ts"],"names":[],"mappings":"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"}

package/dist/src/ultraapp/contract.d.ts

@@ -0,0 +1,52 @@
+/**
+ * UltraApp's acceptance contracts — the only mode whose contract is on by default.
+ *
+ * It earns that because it already ran most of these commands, and because its
+ * own documentation has claimed two gates that the code never enforced:
+ *
+ *  1. `conventions.ts` §4 states "fix-on-failure runs `npm run smoke` and gates
+ *     build-success on its passing". It did not — the step list was install /
+ *     build / test / docker-build, with no smoke anywhere. The claim is now true.
+ *  2. `ultraapp.md` recorded, as a known limitation since 4.0.0, that the §7g
+ *     frontend gate "relies on per-agent honesty about running the screenshot
+ *     capture", with a follow-up promised to make it structural. The capture is
+ *     now performed by the runtime against the deployed URL and stored as
+ *     evidence, so whether it happened is no longer an agent's word.
+ *
+ * What §7g still does not do is judge the pixels. A human or an agent still
+ * decides whether the render is acceptable; the runtime guarantees only that the
+ * images exist and are of the deployed app. Calling that visual regression would
+ * be the same overclaim this module exists to remove.
+ */
+import type { AcceptanceContract } from '../verify/contract.js';
+/** §7g's two viewports, unchanged from the convention text agents were given. */
+export declare const UI_VIEWPORTS: {
+    width: number;
+    height: number;
+    label: string;
+}[];
+export interface BuildContractOptions {
+    useDocker: boolean;
+    fixRounds?: number;
+}
+/**
+ * Build-stage checks, run in the council's worktree. The order is the old
+ * `DEFAULT_STEPS` order, plus the smoke step the docs already promised.
+ */
+export declare function ultraappBuildContract(opts: BuildContractOptions): AcceptanceContract;
+/**
+ * Whether a missing/failed screenshot capture should fail the deploy.
+ *
+ * Default is lenient: capture and store, record a failure, but do not sink a
+ * working app because the host has no Chrome. `CLAWO_ULTRAAPP_VISUAL_GATE=strict`
+ * makes it binding for setups that want §7g fully enforced.
+ */
+export declare function visualGateIsStrict(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Deploy-stage checks, run against the live URL.
+ *
+ * No health probe here on purpose: `deployArtifact` already polls `/health` and
+ * refuses to report success without it, so re-probing would be a second source
+ * of truth for a question that is already settled.
+ */
+export declare function ultraappDeployContract(url: string, env?: NodeJS.ProcessEnv): AcceptanceContract;

package/dist/src/ultraapp/contract.js

@@ -0,0 +1,83 @@
+/**
+ * UltraApp's acceptance contracts — the only mode whose contract is on by default.
+ *
+ * It earns that because it already ran most of these commands, and because its
+ * own documentation has claimed two gates that the code never enforced:
+ *
+ *  1. `conventions.ts` §4 states "fix-on-failure runs `npm run smoke` and gates
+ *     build-success on its passing". It did not — the step list was install /
+ *     build / test / docker-build, with no smoke anywhere. The claim is now true.
+ *  2. `ultraapp.md` recorded, as a known limitation since 4.0.0, that the §7g
+ *     frontend gate "relies on per-agent honesty about running the screenshot
+ *     capture", with a follow-up promised to make it structural. The capture is
+ *     now performed by the runtime against the deployed URL and stored as
+ *     evidence, so whether it happened is no longer an agent's word.
+ *
+ * What §7g still does not do is judge the pixels. A human or an agent still
+ * decides whether the render is acceptable; the runtime guarantees only that the
+ * images exist and are of the deployed app. Calling that visual regression would
+ * be the same overclaim this module exists to remove.
+ */
+/** §7g's two viewports, unchanged from the convention text agents were given. */
+export const UI_VIEWPORTS = [
+    { width: 1440, height: 900, label: 'desktop' },
+    { width: 375, height: 812, label: 'mobile' },
+];
+const TEN_MIN = 10 * 60_000;
+/**
+ * Build-stage checks, run in the council's worktree. The order is the old
+ * `DEFAULT_STEPS` order, plus the smoke step the docs already promised.
+ */
+export function ultraappBuildContract(opts) {
+    const checks = [
+        { id: 'install', spec: { type: 'command', cmd: 'npm', args: ['install'], timeoutMs: TEN_MIN }, required: true },
+        { id: 'build', spec: { type: 'command', cmd: 'npm', args: ['run', 'build'], timeoutMs: TEN_MIN }, required: true },
+        { id: 'test', spec: { type: 'command', cmd: 'npm', args: ['test'], timeoutMs: TEN_MIN }, required: true },
+    ];
+    if (opts.useDocker) {
+        checks.push({
+            id: 'docker-build',
+            spec: { type: 'command', cmd: 'docker', args: ['build', '-t', 'ultraapp-fix:test', '.'], timeoutMs: TEN_MIN },
+            required: true,
+        });
+    }
+    // Required, because §4 of the conventions makes `scripts.smoke` mandatory and
+    // tells the council the gate is binding. A codebase without it has not met the
+    // brief it was given.
+    checks.push({
+        id: 'smoke',
+        spec: { type: 'command', cmd: 'npm', args: ['run', 'smoke'], timeoutMs: TEN_MIN },
+        required: true,
+    });
+    return { id: 'ultraapp-build', checks, fixOnFailureRounds: opts.fixRounds ?? 5 };
+}
+/**
+ * Whether a missing/failed screenshot capture should fail the deploy.
+ *
+ * Default is lenient: capture and store, record a failure, but do not sink a
+ * working app because the host has no Chrome. `CLAWO_ULTRAAPP_VISUAL_GATE=strict`
+ * makes it binding for setups that want §7g fully enforced.
+ */
+export function visualGateIsStrict(env = process.env) {
+    return (env.CLAWO_ULTRAAPP_VISUAL_GATE || '').toLowerCase() === 'strict';
+}
+/**
+ * Deploy-stage checks, run against the live URL.
+ *
+ * No health probe here on purpose: `deployArtifact` already polls `/health` and
+ * refuses to report success without it, so re-probing would be a second source
+ * of truth for a question that is already settled.
+ */
+export function ultraappDeployContract(url, env = process.env) {
+    return {
+        id: 'ultraapp-deploy',
+        checks: [
+            {
+                id: 'frontend-gate',
+                spec: { type: 'screenshot', url, viewports: UI_VIEWPORTS },
+                required: visualGateIsStrict(env),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/src/ultraapp/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/ultraapp/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE;IAC9C,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE;CAC7C,CAAC;AAEF,MAAM,OAAO,GAAG,EAAE,GAAG,MAAM,CAAC;AAO5B;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAA0B;IAC9D,MAAM,MAAM,GAAoB;QAC9B,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC/G,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;QAClH,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;KAC1G,CAAC;IACF,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,cAAc;YAClB,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE;YAC7G,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;IACL,CAAC;IACD,8EAA8E;IAC9E,+EAA+E;IAC/E,sBAAsB;IACtB,MAAM,CAAC,IAAI,CAAC;QACV,EAAE,EAAE,OAAO;QACX,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE;QACjF,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IAEH,OAAO,EAAE,EAAE,EAAE,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC;AACnF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC;AAC3E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,MAAyB,OAAO,CAAC,GAAG;IACtF,OAAO;QACL,EAAE,EAAE,iBAAiB;QACrB,MAAM,EAAE;YACN;gBACE,EAAE,EAAE,eAAe;gBACnB,IAAI,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE;gBAC1D,QAAQ,EAAE,kBAAkB,CAAC,GAAG,CAAC;aAClC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/src/ultraapp/conventions.js

@@ -92,8 +92,9 @@ internally. ENTRYPOINT runs the production server. Build args:
 Smoke test: package.json must expose "scripts.smoke" that drives ONE complete
 job using AppSpec.inputs[].examples[0].ref files copied into the image at
 build time under $DATA_DIR/_smoke/. The smoke test asserts pipeline completes and
-output matches AppSpec.outputs[].type. fix-on-failure runs "npm run smoke" and
-gates build-success on its passing.
+output matches AppSpec.outputs[].type. The orchestrator runs "npm run smoke"
+itself as part of the build acceptance contract and gates build-success on its
+exit code — a codebase without a working "scripts.smoke" does not build.
 
 Smoke test must complete in < 90 seconds for the reference-trace inputs
 provided. If your pipeline genuinely takes longer, design the smoke test to
@@ -205,6 +206,12 @@ tags, class names, and \`@media\` queries don't tell you what the page
 actually looks like. You MUST capture screenshots and look at the pixels
 before voting.
 
+Note on who checks what: after deployment the orchestrator captures both
+viewports against the live URL itself and stores the PNGs as run evidence,
+so whether a capture happened is no longer taken on trust. It does not
+judge the rendering — that is still your job, and it is why the steps
+below are yours to perform in your own worktree before you vote.
+
 Before voting [CONSENSUS: YES], EVERY agent MUST:
 
 1. Start the dev/preview server in their worktree (\`npm run preview\` or

package/dist/src/ultraapp/conventions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../../src/ultraapp/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+OxC,CAAC,IAAI,EAAE,CAAC"}
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../../src/ultraapp/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsPxC,CAAC,IAAI,EAAE,CAAC"}

package/dist/src/ultraapp/fix-on-failure.d.ts

@@ -1,10 +1,18 @@
 /**
- * Purpose-built helper: run the standard verification pipeline in a worktree,
- * spawn a Claude session to fix mechanical errors on red, retry up to N rounds.
+ * Run the verification pipeline in a worktree, spawn a session to fix mechanical
+ * errors on red, retry up to N rounds.
+ *
+ * As of 6.0.0 this is an adapter over `src/verify/`, not its own runner. The
+ * logic it used to own — ordered steps, exit-code gating, byte-capped tails, the
+ * fix loop — moved out to become mode-agnostic, and came back with the two
+ * things it was missing: a per-step timeout (a wedged `npm test` used to hang
+ * the pipeline forever) and an honoured `required` flag (the field was declared
+ * here and never read, so every step was fatal).
  *
  * Not to be confused with src/autoloop/, which is a planner/coder/reviewer
  * message-bus orchestrator for a different problem shape.
  */
+import type { AcceptanceContract, CheckResult } from '../verify/contract.js';
 export interface ShellResult {
     ok: boolean;
     stdout: string;
@@ -24,16 +32,27 @@ export interface FixOnFailureArgs {
     maxRounds: number;
     shell?: ShellRunner;
     spawnFixer?: FixerSpawner;
+    /** Legacy step list. Each entry becomes a `command` check. */
     steps?: Array<{
         cmd: string;
         args: string[];
         required?: boolean;
+        timeoutMs?: number;
     }>;
+    /** Full acceptance contract. Takes precedence over `steps`. */
+    contract?: AcceptanceContract;
+    /** Where screenshot-style checks drop files. Defaults to a temp dir. */
+    artifactDir?: string;
 }
 export interface FixOnFailureResult {
     ok: boolean;
     rounds: number;
     lastError?: string;
     failingCommand?: string;
+    /** Per-check outcomes, for an evidence bundle. Absent on stubbed results. */
+    results?: CheckResult[];
 }
+export declare const DEFAULT_STEPS: NonNullable<FixOnFailureArgs['steps']>;
+/** Translate the legacy step list into contract checks, `required` included this time. */
+export declare function stepsToContract(steps: NonNullable<FixOnFailureArgs['steps']>, fixOnFailureRounds: number): AcceptanceContract;
 export declare function runFixOnFailure(args: FixOnFailureArgs): Promise<FixOnFailureResult>;