@enderfga/claw-orchestrator 5.0.0 → 6.0.0

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>;

package/dist/src/ultraapp/fix-on-failure.js

@@ -1,76 +1,60 @@
 /**
- * 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 { spawn } from 'node:child_process';
-const DEFAULT_STEPS = [
+import path from 'node:path';
+import os from 'node:os';
+import { runContract } from '../verify/runner.js';
+const TEN_MIN = 10 * 60_000;
+export const DEFAULT_STEPS = [
     { cmd: 'npm', args: ['install'] },
     { cmd: 'npm', args: ['run', 'build'] },
     { cmd: 'npm', args: ['test'] },
     { cmd: 'docker', args: ['build', '-t', 'ultraapp-fix:test', '.'] },
 ];
-const TAIL_LINES = 200;
-export async function runFixOnFailure(args) {
-    const shell = args.shell ?? realShell;
-    const spawnFixer = args.spawnFixer ?? defaultSpawnFixer;
-    const steps = args.steps ?? DEFAULT_STEPS;
-    let rounds = 0;
-    while (true) {
-        const failure = await runPipelineOnce(shell, args.worktreePath, steps);
-        if (failure === null)
-            return { ok: true, rounds };
-        if (rounds >= args.maxRounds) {
-            return {
-                ok: false,
-                rounds,
-                lastError: failure.lastError,
-                failingCommand: failure.failingCommand,
-            };
-        }
-        rounds++;
-        await spawnFixer({
-            worktreePath: args.worktreePath,
-            failingCommand: failure.failingCommand,
-            tail: failure.tail,
-        });
-    }
+/** Translate the legacy step list into contract checks, `required` included this time. */
+export function stepsToContract(steps, fixOnFailureRounds) {
+    const checks = steps.map((s, i) => ({
+        id: `${s.cmd}-${i + 1}`,
+        spec: { type: 'command', cmd: s.cmd, args: s.args, timeoutMs: s.timeoutMs ?? TEN_MIN },
+        required: s.required !== false,
+    }));
+    return { id: 'fix-on-failure', checks, fixOnFailureRounds };
 }
-async function runPipelineOnce(shell, cwd, steps) {
-    for (const step of steps) {
-        const r = await shell(step.cmd, step.args, { cwd });
-        if (!r.ok) {
-            const cmdline = `${step.cmd} ${step.args.join(' ')}`;
-            const tail = lastN(r.stderr || r.stdout, TAIL_LINES);
-            return { failingCommand: cmdline, lastError: tail.slice(0, 500), tail };
-        }
-    }
-    return null;
-}
-function lastN(s, n) {
-    const lines = s.split('\n');
-    return lines.slice(-n).join('\n');
+export async function runFixOnFailure(args) {
+    const contract = args.contract ?? stepsToContract(args.steps ?? DEFAULT_STEPS, args.maxRounds);
+    const spawnFixer = args.spawnFixer
+        ? ({ cwd, failingCheck, tail }) => args.spawnFixer({ worktreePath: cwd, failingCommand: failingCheck, tail })
+        : undefined;
+    const { results, passed, rounds } = await runContract({ ...contract, fixOnFailureRounds: args.maxRounds }, {
+        cwd: args.worktreePath,
+        artifactDir: args.artifactDir ?? path.join(os.tmpdir(), 'clawo-fix-artifacts'),
+        exec: args.shell ? shellToExec(args.shell) : undefined,
+    }, spawnFixer);
+    const failing = results.find((r) => r.required && !r.passed);
+    return {
+        ok: passed,
+        rounds,
+        lastError: failing ? (failing.tail ?? failing.detail).slice(0, 500) : undefined,
+        failingCommand: failing?.detail,
+        results,
+    };
 }
-// Only the tail of build output is ever used (see lastN). Cap each stream so a
-// runaway build (e.g. a watch loop printing forever) can't OOM the process.
-const MAX_CAPTURE_BYTES = 512 * 1024;
-function appendCapped(buf, chunk) {
-    const next = buf + chunk;
-    return next.length > MAX_CAPTURE_BYTES ? next.slice(next.length - MAX_CAPTURE_BYTES) : next;
+/** Keep the injectable `ShellRunner` seam callers already depend on. */
+function shellToExec(shell) {
+    return async (cmd, cmdArgs, opts) => {
+        const r = await shell(cmd, cmdArgs, { cwd: opts.cwd ?? process.cwd() });
+        return { code: r.ok ? 0 : 1, out: r.stdout, err: r.stderr, timedOut: false, durationMs: 0 };
+    };
 }
-const realShell = (cmd, args, opts) => new Promise((resolve) => {
-    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (d) => (stdout = appendCapped(stdout, d.toString())));
-    child.stderr.on('data', (d) => (stderr = appendCapped(stderr, d.toString())));
-    child.on('close', (code) => resolve({ ok: code === 0, stdout, stderr }));
-    child.on('error', (e) => resolve({ ok: false, stdout, stderr: stderr + e.message }));
-});
-const defaultSpawnFixer = async (args) => {
-    const { spawnFixerSession } = await import('./fix-on-failure-session.js');
-    await spawnFixerSession(args);
-};
 //# sourceMappingURL=fix-on-failure.js.map

package/dist/src/ultraapp/fix-on-failure.js.map

@@ -1 +1 @@
-{"version":3,"file":"fix-on-failure.js","sourceRoot":"","sources":["../../../src/ultraapp/fix-on-failure.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAiC3C,MAAM,aAAa,GAA2C;IAC5D,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE;IACjC,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE;IACtC,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE;IAC9B,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,GAAG,CAAC,EAAE;CACnE,CAAC;AAEF,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAsB;IAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC;IACtC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC;IACxD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;IAE1C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QACvE,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAElD,IAAI,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM;gBACN,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,cAAc,EAAE,OAAO,CAAC,cAAc;aACvC,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,CAAC;QACT,MAAM,UAAU,CAAC;YACf,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,IAAI,EAAE,OAAO,CAAC,IAAI;SACnB,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,KAAkB,EAClB,GAAW,EACX,KAA6C;IAE7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACV,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YACrD,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;QAC1E,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,KAAK,CAAC,CAAS,EAAE,CAAS;IACjC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAM,iBAAiB,GAAG,GAAG,GAAG,IAAI,CAAC;AACrC,SAAS,YAAY,CAAC,GAAW,EAAE,KAAa;IAC9C,MAAM,IAAI,GAAG,GAAG,GAAG,KAAK,CAAC;IACzB,OAAO,IAAI,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9F,CAAC;AAED,MAAM,SAAS,GAAgB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CACjD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;IACtB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACrF,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IACtF,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IACtF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACzE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC,CAAC,CAAC;AAEL,MAAM,iBAAiB,GAAiB,KAAK,EAAE,IAAI,EAAE,EAAE;IACrD,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;IAC1E,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC,CAAC"}
+{"version":3,"file":"fix-on-failure.js","sourceRoot":"","sources":["../../../src/ultraapp/fix-on-failure.ts"],"names":[],"mappings":"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"}

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

@@ -1,8 +1,11 @@
 import { type AppSpec } from './spec.js';
-import { type UltraappStore, type ChatEntry } from './store.js';
+import { type UltraappStore, type ChatEntry, type RunMode } from './store.js';
 import { type QuestionEnvelope } from './interview-parser.js';
 import { type PatchOp } from './json-patch.js';
 import type { BuildEvent } from './build-events.js';
+import { RunKernel } from '../kernel/engine.js';
+import type { RunRecord } from '../kernel/types.js';
+import { type AcceptanceContract, type CheckResult } from '../verify/contract.js';
 import { type DeployArgs, type DeployResult } from './deploy.js';
 import type { UltraappRouter } from './router.js';
 export type RunEvent = {
@@ -56,23 +59,69 @@ export interface UltraappManagerOptions {
         `build-complete` (v0.2 behaviour); when present, deploy runs after build
         and the run reaches `done` with a public-but-local URL. */
     router?: UltraappRouter;
+    /**
+     * The run kernel that drives the build pipeline.
+     *
+     * Supplied by SessionManager in production so UltraApp's runs share the one
+     * run store, listing and ownership model as everything else. Left out, a
+     * private kernel is wired up — which keeps the class usable on its own, and
+     * still means there is only one execution model, not two.
+     */
+    kernel?: RunKernel;
     /** Test seam: stub the deploy state machine. */
     deployFn?: (a: DeployArgs) => Promise<DeployResult>;
+    /**
+     * Override the build-stage acceptance contract.
+     *
+     * A caller-supplied contract, never an agent-supplied one — the same rule as
+     * everywhere else in the verification plane. It exists because the default
+     * really does run `npm install && npm run build && npm test` in the generated
+     * codebase, which a unit test has no business doing; tests declare a trivial
+     * contract the way they inject `deployFn`.
+     */
+    buildContract?: AcceptanceContract;
+    /**
+     * Test seam: stub the deploy-stage acceptance checks. The real one drives a
+     * headless browser against the deployed URL, which a stubbed deploy has not
+     * got, so tests inject their own the same way they inject `deployFn`.
+     */
+    runDeployChecksFn?: (contract: AcceptanceContract, cwd: string, artifactDir: string) => Promise<CheckResult[]>;
     /** Runtime mode for build + deploy. 'host' (default) runs the generated
         app as a regular Node process — works anywhere Node works, no extra
         deps. 'docker' uses `docker build` + `docker run` for isolation; only
         use this when you want shared-host hardening. */
     runtimeMode?: 'host' | 'docker';
 }
+/**
+ * The kernel run id for an app's current build.
+ *
+ * Stable rather than per-attempt, so `clawo workflow show ultraapp-<id>` always
+ * names the build that matters; a rebuild deletes the previous run and starts a
+ * new one under the same id, which the incarnation check makes safe.
+ */
+export declare function ultraappKernelRunId(appRunId: string): string;
+/**
+ * UltraApp's `RunMode`, derived from the kernel record.
+ *
+ * The build pipeline no longer has a state machine of its own: this reads the
+ * one the kernel keeps. `interview` and `queued` are not here because they are
+ * not pipeline states — nothing is running yet, and the interview genuinely is
+ * not a workflow.
+ */
+export declare function ultraappModeOf(record: RunRecord): RunMode;
 export declare class UltraappManager {
     private readonly opts;
     private readonly runs;
     private readonly skillContent;
     private readonly buildQueue;
     private readonly narrators;
+    private readonly kernel;
+    /** Per-run serialisation for the mode projection. See {@link projectMode}. */
+    private readonly projectChain;
     private readonly classifierSessions;
     private readonly inflightWork;
     constructor(opts: UltraappManagerOptions);
+    private ultraappNodeDeps;
     get store(): UltraappStore;
     createRun(): Promise<string>;
     submitAnswer(runId: string, answer: {
@@ -94,8 +143,64 @@ export declare class UltraappManager {
     startBuild(runId: string): Promise<void>;
     cancelBuild(runId: string): void;
     buildPosition(runId: string): number;
+    /**
+     * Run the build pipeline as a kernel workflow.
+     *
+     * This used to be a hand-rolled sequence: council, then fix-on-failure, then
+     * deploy, with a mode enum written at each step and nothing checkpointed
+     * between them. It worked, but it meant UltraApp was a second runtime standing
+     * beside the one this release exists to be — its runs were invisible to
+     * `workflow_list` and the Runs tab, and a crash halfway through threw away a
+     * finished council and started it again from nothing.
+     *
+     * Now the sequence is a `WorkflowSpec` and the kernel drives it. What is left
+     * here is the part that is genuinely UltraApp's: turning kernel events into
+     * `BuildEvent`s for the dashboard, and keeping `RunMode` — which the whole
+     * UI and every stored run reads — as a projection of the kernel's state
+     * rather than as a second source of truth.
+     *
+     * The interview and the done-mode conversation are deliberately NOT here.
+     * They are user-driven and open-ended; expressing them as a workflow would
+     * mean a router self-loop fighting the visit bound, or one fake node with a
+     * state machine hidden inside it. That would be unification as theatre.
+     */
     private runBuild;
-    private runDeployStage;
+    /** Best-effort narrator startup; its failure must not sink a build. */
+    private startNarrator;
+    /**
+     * Translate the run's kernel events into build events and mode transitions.
+     *
+     * The mode is recomputed from the record every time rather than stepped
+     * forward, so a handler that arrives late cannot write a stale value over a
+     * newer one — which it otherwise can, because these handlers are async and the
+     * kernel does not wait for them.
+     */
+    private subscribeKernel;
+    private onKernelEvent;
+    /**
+     * Write UltraApp's mode as it is implied by the kernel record, right now.
+     *
+     * Serialised per run, and that is the whole mechanism. These are fired from
+     * async event handlers, so two of them can read the record at different
+     * moments and still write in the opposite order — which showed up as a run
+     * that had already failed reverting to `building`. Chaining read-compute-write
+     * makes the last write the one computed last, and the kernel record only ever
+     * moves forward, so the last computed value is the current one.
+     */
+    private projectMode;
+    private projectModeNow;
+    /** Emit the terminal build event and settle the mode from the final record. */
+    private settleBuild;
+    /**
+     * Deploy the built codebase and check the deployed thing.
+     *
+     * Returns an outcome rather than writing modes: the mode is projected from the
+     * kernel now, and a stage that also wrote it would put the two back out of
+     * step. The acceptance verdict comes back with the outcome because it is the
+     * run's terminal verdict — §7g screenshots are taken against a URL that does
+     * not exist until this has run, so the contract cannot sit in the spec.
+     */
+    private deployStage;
     startContainer(runId: string): Promise<{
         ok: boolean;
         error?: string;