amalgm 0.1.144 → 0.1.145

package/runtime/scripts/amalgm-mcp/browser/delta.js

@@ -0,0 +1,254 @@
+'use strict';
+
+/**
+ * Action-result deltas — the evidence contract behind "every action reports
+ * its own result".
+ *
+ * Success must mean the intended browser state changed, not that a command
+ * was dispatched. So around each mutating verb the wrapper measures:
+ *   before — the facts that decide whether the action CAN work (target
+ *            enabled, current field value, keyboard-event baseline), using
+ *            agent-browser's own target resolution (@ref/CSS), never a
+ *            second resolver;
+ *   after  — what actually changed (URL/title, field value, key events,
+ *            blocking dialog), one settle window later.
+ *
+ * The result is a typed delta object (buildable and testable without a
+ * browser) rendered to compact text. Every field is a measured fact or
+ * absent — no confidence scores, no interpretation, no model calls. Probe
+ * failures degrade to absent fields and never fail the action they decorate.
+ */
+
+const attach = require('./attach');
+
+/** One in-page round trip: url + title. Same probe engine.js batches. */
+const STATE_PROBE = ['eval', 'JSON.stringify({url: location.href, title: document.title})'];
+
+/** Idempotent capture-phase keydown counter; returns the current count.
+ * Navigation resets it — probes just degrade to absent. */
+const KEY_COUNTER_PROBE = ['eval', `(() => {
+  if (!window.__amalgmKeyGuard) {
+    window.__amalgmKeyGuard = { count: 0 };
+    document.addEventListener('keydown', () => { window.__amalgmKeyGuard.count += 1; }, true);
+  }
+  return window.__amalgmKeyGuard.count;
+})()`];
+
+/** Brief settle so the page reacts (handlers run, sync navigations start)
+ * before we look. Not a load wait — deltas must stay cheap. */
+const SETTLE_MS = 150;
+
+const PROBE_TIMEOUT_MS = 5_000;
+
+/** A press dispatching more events than this is not a keypress — re-check
+ * after a pause and call out a runaway input flood (a real stress-test P0:
+ * 34K+ synthetic keydowns/minute after one modifier combo). */
+const KEY_FLOOD_THRESHOLD = 15;
+const KEY_FLOOD_RECHECK_MS = 200;
+
+/** session -> { url, title } as of the last probe or verb that knew it. */
+const lastStates = new Map();
+
+function parseProbe(result) {
+  // Batch entries wrap as {result: {origin, result}}, single runs as
+  // {data: {origin, result}} — .result must win, same as engine.parseState.
+  const data = result?.result ?? result?.data ?? result;
+  const raw = data && typeof data === 'object' && 'result' in data ? data.result : data;
+  try {
+    const { url = '', title = '' } = JSON.parse(String(raw));
+    return { url, title };
+  } catch {
+    return null;
+  }
+}
+
+/** Unwrap a single value out of an agent-browser command result. */
+function unwrap(entry, key) {
+  const data = entry?.result ?? entry?.data ?? entry;
+  if (data && typeof data === 'object') {
+    if (key !== undefined && key in data) return data[key];
+    if ('result' in data) return data.result;
+  }
+  return data;
+}
+
+/** Verbs that already learned the page state (open/snapshot) record it here
+ * so the next action's delta has a real "before". */
+function remember(session, state) {
+  if (state && state.url) lastStates.set(session, { url: state.url, title: state.title || '' });
+}
+
+/** text= targets go through find, which agent-browser's get/is commands
+ * don't take — element probes are skipped for them, fields stay absent. */
+function probeable(target) {
+  return typeof target === 'string' && target.length > 0 && !target.startsWith('text=');
+}
+
+async function tryRun(session, command, context) {
+  try {
+    return await attach.run(session, command, { timeoutMs: PROBE_TIMEOUT_MS, context });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Measure the facts that decide whether the action can work. One extra
+ * round trip; every failure degrades to absent fields.
+ */
+async function beforeAction(session, { action, target } = {}, context) {
+  const before = { page: lastStates.get(session) || null };
+  if ((action === 'click' || action === 'select') && probeable(target)) {
+    const enabled = await tryRun(session, ['is', 'enabled', target], context);
+    if (enabled) before.enabled = Boolean(unwrap(enabled, 'enabled'));
+  }
+  if (action === 'fill' && probeable(target)) {
+    const entries = await tryRun(session, ['get', 'value', target], context);
+    if (entries) {
+      before.value = String(unwrap(entries, 'value') ?? '');
+      const enabled = await tryRun(session, ['is', 'enabled', target], context);
+      if (enabled) before.enabled = Boolean(unwrap(enabled, 'enabled'));
+    }
+  }
+  if (action === 'press') {
+    const count = await tryRun(session, KEY_COUNTER_PROBE, context);
+    if (count) before.keyCount = Number(unwrap(count)) || 0;
+  }
+  return before;
+}
+
+/**
+ * Measure what changed and assemble the typed delta. Never throws.
+ * `expected` is the value a fill asked for, so a field that silently kept
+ * or mangled its content gets called out.
+ */
+async function afterAction(session, { action, target, before = {}, expected } = {}, context) {
+  await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+  const delta = { action: action || null, target: target || null, page: {}, warnings: [] };
+  if (typeof before.enabled === 'boolean') delta.targetEnabled = before.enabled;
+  if (before.enabled === false) {
+    delta.warnings.push(`Target ${target} was disabled when ${action || 'the action'} ran — it likely had no effect.`);
+  }
+
+  // One batched round trip for the after-facts; a pending dialog fails the
+  // batch with a message that says so — that IS the delta then.
+  const commands = [];
+  if ((action === 'fill' || action === 'select') && probeable(target)) commands.push(['get', 'value', target]);
+  if (action === 'press') commands.push(KEY_COUNTER_PROBE);
+  commands.push(STATE_PROBE);
+
+  let entries = null;
+  try {
+    entries = await attach.runBatch(session, commands, { timeoutMs: PROBE_TIMEOUT_MS, context });
+  } catch (err) {
+    const message = String(err?.message || '');
+    if (/dialog/i.test(message)) {
+      delta.page.dialog = message;
+      return delta;
+    }
+    return delta; // probe failure: facts stay absent, action result stands
+  }
+
+  let index = 0;
+  if ((action === 'fill' || action === 'select') && probeable(target)) {
+    const after = String(unwrap(entries[index], 'value') ?? '');
+    index += 1;
+    delta.value = { after };
+    if (typeof before.value === 'string') {
+      delta.value.before = before.value;
+      delta.value.changed = before.value !== after;
+    }
+    if (typeof expected === 'string' && after !== expected) {
+      delta.warnings.push(`Field value is "${clip(after, 80)}", not the requested "${clip(expected, 80)}".`);
+    }
+  }
+  if (action === 'press') {
+    const count = Number(unwrap(entries[index])) || 0;
+    index += 1;
+    if (typeof before.keyCount === 'number') {
+      const dispatched = Math.max(0, count - before.keyCount);
+      delta.keys = { dispatched };
+      if (dispatched > KEY_FLOOD_THRESHOLD) {
+        await new Promise((resolve) => setTimeout(resolve, KEY_FLOOD_RECHECK_MS));
+        const again = await tryRun(session, KEY_COUNTER_PROBE, context);
+        const later = Number(unwrap(again)) || count;
+        if (later > count) {
+          delta.keys.flood = true;
+          delta.warnings.push(`Runaway keyboard input: ${later - before.keyCount} keydown events and still firing. Reload the page to stop it.`);
+        }
+      }
+    }
+  }
+
+  const state = parseProbe(entries[index]);
+  if (state && state.url) {
+    delta.page.url = state.url;
+    delta.page.title = state.title || '';
+    const prior = before.page;
+    if (prior && prior.url) delta.page.urlChanged = prior.url !== state.url;
+    remember(session, state);
+  }
+  return delta;
+}
+
+function clip(value, max) {
+  const text = String(value ?? '');
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** Render the delta as compact lines: warnings first, then facts. */
+function render(delta) {
+  if (!delta) return '';
+  const lines = delta.warnings.map((warning) => `⚠ ${warning}`);
+  if (delta.page.dialog) {
+    lines.push(`⚠ ${delta.page.dialog}`);
+    return lines.join('\n');
+  }
+  if (delta.value && delta.value.before !== undefined) {
+    lines.push(`→ Value: "${clip(delta.value.before, 80)}" → "${clip(delta.value.after, 80)}"`);
+  }
+  if (delta.keys && delta.keys.dispatched === 0) {
+    lines.push('→ No keydown events reached the page — the key may not have been delivered.');
+  }
+  if (delta.page.url) {
+    const label = delta.page.title ? `${delta.page.url} ("${delta.page.title}")` : delta.page.url;
+    if (delta.page.urlChanged) {
+      lines.push(`→ Navigated to ${label}`);
+      lines.push('Refs from the previous page are stale — re-run snapshot.');
+    } else {
+      lines.push(`→ Page: ${label}${delta.page.urlChanged === false ? ' (no navigation)' : ''}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Page-facts-only delta for verbs with no element target (dialog, tab, cua
+ * clicks). Returns rendered text; kept for those callers' simplicity.
+ */
+async function describeAfter(session, context, action = null) {
+  const delta = await afterAction(session, { action, before: { page: lastStates.get(session) || null } }, context);
+  return render(delta);
+}
+
+/**
+ * Cap tool output at `max` chars with an explicit truncation marker — silent
+ * truncation reads as "that was everything" when it wasn't.
+ */
+function clipOutput(text, max, hint = '') {
+  const value = String(text ?? '');
+  if (value.length <= max) return value;
+  const marker = `\n\n[Output truncated: showing ${max.toLocaleString()} of ${value.length.toLocaleString()} chars.${hint ? ` ${hint}` : ''}]`;
+  return value.slice(0, max) + marker;
+}
+
+module.exports = {
+  afterAction,
+  beforeAction,
+  clipOutput,
+  describeAfter,
+  lastStates,
+  parseProbe,
+  remember,
+  render,
+};

package/runtime/scripts/amalgm-mcp/browser/tools.js

@@ -3,13 +3,18 @@
 /**
  * Browser core actions — the thin surface.
  *
- * Eleven verbs built on the agent-browser CLI (vercel-labs/agent-browser).
+ * Verbs built on the agent-browser CLI (vercel-labs/agent-browser).
  * The loop is: open → snapshot (@refs) → click/fill/select (@ref) →
  * re-snapshot.
  * Everything else agent-browser can do (scroll, hover, cookies, network
  * mocking, traces, diffs, React inspection, ...) is reachable through `cli`
  * without widening this schema.
  *
+ * Every mutating verb reports its own result: after acting it probes the
+ * page once (delta.js) and answers in the same response what the agent
+ * would otherwise ask next — did we navigate, is a dialog blocking, where
+ * are we now. All large outputs carry explicit truncation markers.
+ *
  * Action names are short verbs — the toolbox layer prefixes them, so agents
  * see toolbox__browser_open, toolbox__browser_snapshot, and so on.
  *
@@ -20,6 +25,34 @@
 
 const { textResult, errorResult } = require('../lib/tool-result');
 const engine = require('./engine');
+const delta = require('./delta');
+
+const SNAPSHOT_MAX_CHARS = 12_000;
+const OUTPUT_MAX_CHARS = 15_000;
+
+/** Action text + the post-action delta, in one response. */
+function actionResult(text, deltaText) {
+  return textResult([text, deltaText].filter(Boolean).join('\n'));
+}
+
+/** Rendered text for the agent + the typed delta object as metadata for
+ * anything programmatic (tests, UIs, validators). */
+function evidenceResult(text, deltaObject) {
+  const result = actionResult(text, delta.render(deltaObject));
+  return { ...result, metadata: { browserDelta: deltaObject } };
+}
+
+/**
+ * The before → act → after evidence pipeline shared by the element verbs.
+ * `act` runs the engine verb; measurement never fails the action.
+ */
+async function withEvidence({ action, args, ctx, expected, act, describe }) {
+  const session = engine.sessionFor(args, ctx);
+  const before = await delta.beforeAction(session, { action, target: args.target }, ctx);
+  const result = await act();
+  const deltaObject = await delta.afterAction(session, { action, target: args.target, before, expected }, ctx);
+  return evidenceResult(describe(result), deltaObject);
+}
 
 const sessionProperty = {
   session: {
@@ -54,6 +87,14 @@ module.exports = [
       if (!args.url) return errorResult('url is required');
       try {
         const result = await engine.open(args, ctx);
+        delta.remember(result.session, result);
+        // The audit contract for open: requested URL, final URL, error page
+        // or not. A chrome-error page means the navigation failed and the
+        // previous page is gone — success text here would be a lie.
+        if (/^chrome-error:/.test(result.url || '')) {
+          return errorResult(`Open failed: the browser is on an error page (${result.url}) after requesting ${args.url}. `
+            + 'The previous page is gone — open a working URL to continue.');
+        }
         return textResult(line(result, `Opened: ${result.title || args.url}`)
           + '\n\nNext: snapshot lists interactive elements as @refs.');
       } catch (err) {
@@ -68,8 +109,11 @@ module.exports = [
     async handler(args, ctx) {
       try {
         const result = await engine.snapshot(args, ctx);
+        delta.remember(result.session, result);
         const header = `Page: ${result.title || ''}\nURL: ${result.url || ''}\n\n`;
-        return textResult(header + (result.snapshotText || '(empty page)').slice(0, 12_000));
+        const body = delta.clipOutput(result.snapshotText || '(empty page)', SNAPSHOT_MAX_CHARS,
+          'Elements past the cutoff have no refs here — scope with cli ["get","html","<css>"] or ["find","role","<role>","click","--name","<label>"].');
+        return textResult(header + body);
       } catch (err) {
         return errorResult(`Snapshot failed: ${err.message}`);
       }
@@ -110,8 +154,13 @@ module.exports = [
     async handler(args, ctx) {
       if (!args.target) return errorResult('target is required (e.g. "@e3", "#submit", "text=Sign in")');
       try {
-        const result = await engine.click(args, ctx);
-        return textResult(`Clicked ${args.target}\nSession: ${result.session}\n\nRe-run snapshot if the page changed.`);
+        return await withEvidence({
+          action: 'click',
+          args,
+          ctx,
+          act: () => engine.click(args, ctx),
+          describe: () => `Clicked ${args.target}`,
+        });
       } catch (err) {
         return errorResult(`Click failed: ${err.message}`);
       }
@@ -133,8 +182,16 @@ module.exports = [
     async handler(args, ctx) {
       if (!args.target || typeof args.text !== 'string') return errorResult('target and text are required');
       try {
-        const result = await engine.fill(args, ctx);
-        return textResult(`Filled ${args.target}${result.submitted ? ' and pressed Enter' : ''}\nSession: ${result.session}`);
+        return await withEvidence({
+          action: 'fill',
+          args,
+          ctx,
+          // A submit navigates away — comparing the next page's field against
+          // the requested text would be a false warning.
+          expected: args.submit ? undefined : args.text,
+          act: () => engine.fill(args, ctx),
+          describe: (result) => `Filled ${args.target}${result.submitted ? ' and pressed Enter' : ''}`,
+        });
       } catch (err) {
         return errorResult(`Fill failed: ${err.message}`);
       }
@@ -151,8 +208,13 @@ module.exports = [
     async handler(args, ctx) {
       if (!args.key) return errorResult('key is required');
       try {
-        const result = await engine.press(args, ctx);
-        return textResult(`Pressed ${args.key}\nSession: ${result.session}`);
+        return await withEvidence({
+          action: 'press',
+          args,
+          ctx,
+          act: () => engine.press(args, ctx),
+          describe: () => `Pressed ${args.key}`,
+        });
       } catch (err) {
         return errorResult(`Press failed: ${err.message}`);
       }
@@ -173,8 +235,13 @@ module.exports = [
     async handler(args, ctx) {
       if (!args.target || typeof args.value !== 'string') return errorResult('target and value are required');
       try {
-        const result = await engine.select(args, ctx);
-        return textResult(`Selected "${args.value}" in ${args.target}\nSession: ${result.session}`);
+        return await withEvidence({
+          action: 'select',
+          args,
+          ctx,
+          act: () => engine.select(args, ctx),
+          describe: () => `Selected "${args.value}" in ${args.target}`,
+        });
       } catch (err) {
         return errorResult(`Select failed: ${err.message}`);
       }
@@ -193,7 +260,8 @@ module.exports = [
       try {
         const { result } = await engine.evaluate(args, ctx);
         const output = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
-        return textResult(output.slice(0, 15_000) || '(no result)');
+        return textResult(delta.clipOutput(output, OUTPUT_MAX_CHARS,
+          'Return less from the script — slice/filter/count in-page instead.') || '(no result)');
       } catch (err) {
         return errorResult(`Eval failed: ${err.message}`);
       }
@@ -237,12 +305,98 @@ module.exports = [
       try {
         const { result } = await engine.passthrough(args, ctx);
         const output = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
-        return textResult(output.slice(0, 15_000) || 'ok');
+        return textResult(delta.clipOutput(output, OUTPUT_MAX_CHARS) || 'ok');
       } catch (err) {
         return errorResult(`cli failed: ${err.message}`);
       }
     },
   },
+  {
+    name: 'dialog',
+    description: 'Resolve a JavaScript dialog (alert/confirm/prompt) that is blocking the page: accept or dismiss, with optional text for prompts. Action results warn when a dialog appears — resolve it here before any other action will work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['accept', 'dismiss'], description: 'accept = OK, dismiss = Cancel' },
+        text: { type: 'string', description: 'Text to enter into a prompt() before accepting' },
+        ...sessionProperty,
+      },
+      required: ['action'],
+    },
+    async handler(args, ctx) {
+      if (args.action !== 'accept' && args.action !== 'dismiss') return errorResult('action must be "accept" or "dismiss"');
+      try {
+        const command = ['dialog', args.action];
+        if (typeof args.text === 'string' && args.action === 'accept') command.push(args.text);
+        const result = await engine.passthrough({ ...args, args: command }, ctx);
+        return actionResult(
+          `Dialog ${args.action === 'accept' ? 'accepted' : 'dismissed'}${args.text ? ` with text "${args.text}"` : ''}`,
+          await delta.describeAfter(result.session, ctx),
+        );
+      } catch (err) {
+        return errorResult(`dialog failed: ${err.message}`);
+      }
+    },
+  },
+  {
+    name: 'tab',
+    description: 'Manage the session\'s browser tabs: list them (stable ids like "t2"), switch to one, open a new one, or close one. Links with target=_blank and window.open popups become tabs automatically and are auto-focused.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'switch', 'new', 'close'], description: 'What to do' },
+        id: { type: 'string', description: 'Tab id from list, e.g. "t2" — required for switch, optional for close (defaults to the active tab)' },
+        ...sessionProperty,
+      },
+      required: ['action'],
+    },
+    async handler(args, ctx) {
+      try {
+        let command;
+        // Bare `tab` lists — and stays allowed in the desktop app, where
+        // switching targets is refused (a session IS its surface there).
+        if (args.action === 'list') command = ['tab'];
+        else if (args.action === 'new') command = ['tab', 'new'];
+        else if (args.action === 'switch') {
+          if (!args.id) return errorResult('id is required for switch (run {action: "list"} first)');
+          command = ['tab', args.id];
+        } else if (args.action === 'close') command = ['tab', 'close', ...(args.id ? [args.id] : [])];
+        else return errorResult('action must be one of: list, switch, new, close');
+        const { result, session } = await engine.passthrough({ ...args, args: command }, ctx);
+        const output = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+        if (args.action === 'list') return textResult(delta.clipOutput(output, OUTPUT_MAX_CHARS) || 'ok');
+        return actionResult(output || `tab ${args.action} ok`, await delta.describeAfter(session, ctx));
+      } catch (err) {
+        return errorResult(`tab failed: ${err.message}`);
+      }
+    },
+  },
+  {
+    name: 'console',
+    description: 'Read the page\'s console logs and uncaught errors captured for this session. Check this after actions that misbehave — a page that looks stuck is often throwing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        clear: { type: 'boolean', description: 'Clear the captured logs and errors after reading' },
+        ...sessionProperty,
+      },
+    },
+    async handler(args, ctx) {
+      try {
+        const flags = args.clear ? ['--clear'] : [];
+        const logs = await engine.passthrough({ ...args, args: ['console', ...flags] }, ctx);
+        const errors = await engine.passthrough({ ...args, args: ['errors', ...flags] }, ctx);
+        const asText = (value) => (typeof value === 'object' ? JSON.stringify(value, null, 2) : String(value ?? ''));
+        const body = [
+          `Console:\n${delta.clipOutput(asText(logs.result), 8_000) || '(empty)'}`,
+          `Page errors:\n${delta.clipOutput(asText(errors.result), 6_000) || '(none)'}`,
+        ].join('\n\n');
+        return textResult(body);
+      } catch (err) {
+        return errorResult(`console failed: ${err.message}`);
+      }
+    },
+  },
   {
     name: 'close',
     description: 'End the browser session. Headless browsers shut down; the visible desktop surface stays open for the user. A fresh session starts on the next browser call.',

package/runtime/scripts/amalgm-mcp/lib/tool-result.js

@@ -77,6 +77,13 @@ function buildActionDescriptor(toolName, args = {}) {
       return `Browser CLI${quoteIfPresent(Array.isArray(args.args) ? args.args.join(' ') : '')}`;
     case 'browser_close':
       return 'Close browser';
+    case 'cua':
+    case 'browser_cua': {
+      const action = String(args.action || '');
+      if (action === 'screenshot') return 'Take visible browser screenshot';
+      if (action === 'type') return args.text ? `Type ${clipText(args.text, 40)} in browser` : 'Type in browser';
+      return action ? `Browser ${action.replace(/_/g, ' ')} (coordinates)` : 'Browser computer-use action';
+    }
     case 'cua_click':
       return 'Click browser coordinates';
     case 'cua_double_click':
@@ -93,6 +100,12 @@ function buildActionDescriptor(toolName, args = {}) {
       return 'Drag in browser';
     case 'cua_screenshot':
       return 'Take visible browser screenshot';
+    case 'browser_dialog':
+      return args.action === 'dismiss' ? 'Dismiss browser dialog' : 'Accept browser dialog';
+    case 'browser_tab':
+      return `Browser tab ${clipText(String(args.action || 'list'), 20)}`;
+    case 'browser_console':
+      return 'Read browser console';
     case 'record_start':
       return `Start browser recording${quoteIfPresent(args.name)}`;
     case 'record_stop':

package/runtime/scripts/amalgm-mcp/tests/apps-crash-loop.test.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-app-crash-loop-'));
+process.env.AMALGM_DIR = path.join(tempRoot, 'user');
+process.env.AMALGM_HOME = path.join(tempRoot, 'home');
+process.env.AMALGM_RUNTIME_LABEL = 'test';
+process.env.AMALGM_WORKSPACES_DIR = path.join(process.env.AMALGM_DIR, 'workspaces');
+
+const { getApp, saveApps } = require('../apps/store');
+const { APP_RESTART_POLICY, startApp, stopApp } = require('../apps/supervisor');
+const { APPS_DIR } = require('../config');
+
+function waitFor(predicate, label, timeoutMs = 10_000) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const tick = async () => {
+      try {
+        if (await predicate()) return resolve();
+      } catch {}
+      if (Date.now() >= deadline) return reject(new Error(`Timed out waiting for ${label}`));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+test('a crash-looping app is parked as degraded instead of restarting forever', async (t) => {
+  APP_RESTART_POLICY.initialDelayMs = 50;
+  APP_RESTART_POLICY.maxDelayMs = 100;
+  APP_RESTART_POLICY.maxCrashes = 3;
+
+  const appCwd = fs.mkdtempSync(path.join(tempRoot, 'crasher-'));
+  const script = path.join(appCwd, 'crash.js');
+  fs.writeFileSync(script, "console.log('boom before dying'); process.exit(1);\n");
+
+  saveApps({
+    version: 1,
+    apps: [{
+      id: 'app-crash-loop',
+      kind: 'app',
+      name: 'Crash Loop',
+      cwd: appCwd,
+      port: 0,
+      startCommand: `"${process.execPath}" "${script}"`,
+      appRef: 'crashloop',
+      publicUrl: 'https://crashloop.apps.amalgm.ai/',
+      dnsConnected: false,
+      autostart: true,
+      keepAlive: true,
+      desiredState: 'running',
+      status: 'registered',
+      pid: null,
+    }],
+  });
+
+  t.after(() => stopApp('app-crash-loop').catch(() => {}));
+
+  await startApp('app-crash-loop');
+  await waitFor(() => getApp('app-crash-loop')?.status === 'degraded', 'degraded status');
+
+  const app = getApp('app-crash-loop');
+  assert.equal(app.status, 'degraded');
+  assert.equal(app.pid, null);
+  assert.match(app.error, /automatic restarts paused/);
+
+  // Degraded means parked: no further restarts should happen on their own.
+  await new Promise((resolve) => setTimeout(resolve, 400));
+  assert.equal(getApp('app-crash-loop').status, 'degraded');
+
+  // App output landed in the app's own log file, not the runtime log.
+  const logFile = path.join(APPS_DIR, 'logs', 'app-crash-loop.log');
+  await waitFor(() => fs.existsSync(logFile), 'app log file');
+  assert.match(fs.readFileSync(logFile, 'utf8'), /boom before dying/);
+
+  // An explicit start resets the crash budget and tries again.
+  await startApp('app-crash-loop');
+  const restarted = getApp('app-crash-loop');
+  assert.equal(restarted.status, 'running');
+});