@akanjs/devkit 3.2.0-rc.7 → 3.2.0-rc.8

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 ### Minor Changes
 
+- e973831: A CLI failure carries a code and the exit status its family takes, so a script branches on either instead of the message.
+
+  - Exit 2 (`usage`, `unknownTarget`): a flag, argument or command commander refuses, a value outside an option's choices, an argument left out where no terminal can ask for it, a run outside the workspace root, and an app, lib, package or module the workspace does not have. These exited 1 before, except for `akan migrate`, `akan pipeline` and `akan verify <name>`, which already exited 2.
+  - Exit 2 (`refused`) stays what it was: a pack that needs a new store build, and a release the Akan Cloud project rejected.
+  - Exit 3 (`checkFailed`): `akan verify`, `akan typecheck` and the typecheck of `akan build`, `akan preview` and `akan agent install --check` when they found problems. These exited 1 before.
+  - Exit 130 (`interrupted`) for a prompt closed with Ctrl+C, which exited 1.
+  - Exit 1 (`failed`, or an `AkanError`'s own code) for anything else, as before.
+  - `akan pack-update`, `akan push-update` and `akan register-binary` keep exiting 1 for a usage or unknown-target failure, so their 2 still means only the store-build verdict or the project's refusal. `akan agent` exits 1 for one too, and `akan agent hook` never exits 2, saying on stderr why the hook failed: Claude Code reads a hook's exit 2 as a block.
+
+  With `--json` or `--format json`, a failure now ends stdout with one line, `{"ok":false,"error":"<message>","code":"<code>"}`, and the message goes to stderr instead of stdout. An NDJSON stream (`akan code --json`, `akan logs --json`) ends with that line too. A command whose own JSON report says it failed, as `akan verify`'s does, adds no line. `akan migrate --json` answers `usage` or `notFound` for a command line or an app it cannot take before the app runs, matching its exit 2.
+
+  Upgrade: a script that tested for exit 1 after a usage error, a failed check or a closed prompt tests for non-zero, or for 2, 3 and 130. A CI step that branches on exit 2 from the OTA commands needs no change. `@akanjs/devkit/commandDecorators` exports `CliError(code, message, { exitCode })`, `ExitCodeError` is now one coded from its exit status (2 as `refused`, 3 as `checkFailed`), and a target's `usageExitCode` now also sets the exit of a `usage` or `unknownTarget` failure thrown while it runs.
+
 - 29756e1: `akan lint`, `akan lint-all` and `akan verify` now hold each package under a workspace's `pkgs/` to a structure budget, as they already hold apps and libs: a file up to 800 lines, a function up to 150 lines (`akan.size.function`) and a class up to 60 members (`akan.size.class`). Tests and their fixtures (`*.test`, `*.spec`, `*.fixture`, `*.instance` and `*.bench` files, and `test/`, `tests/`, `__tests__/`, `__fixtures__/` and `__mocks__/` folders), `.d.ts` files, re-export barrels and a package's `examples/` are left out, and a package in a git repository is listed through git, so ignored files are never measured. Each package keeps its own `akan.baseline.json`; `akan quality baseline` now seeds one for each package too, `akan quality scan` reports its exceptions, and packing a package that would publish one fails.
 
   A baseline only shrinks from the default branch's copy. Where the default branch has none, an app's, lib's or package's baseline may hold only the breaches the default branch's code already has, so a new one starts empty instead of skipping the check. A file's line count no longer includes the newline ending its last line, so a recorded size may drop by one on the next `akan lint`.
@@ -138,6 +151,15 @@
 
   **Behavior change:** where the shell exports a value the workspace `.env` also sets, such as `AKAN_PUBLIC_ENV`, `AKAN_PUBLIC_REPO_NAME` or `AKAN_PUBLIC_SERVE_DOMAIN`, `akan` now takes the shell's. Unset it, or match the `.env`, to build what you built before.
 
+- af7c411: The five child-process restart loops now share one restart schedule, `RestartSchedule` from `akanjs/common`: the gateway's replicas, the RSC worker, the incremental builder, and `akan start`'s backend and builder recovery. It counts failed restarts, waits before the next one and cancels a pending one on stop. Each loop keeps its own delays (200ms–30s for the RSC worker, 2s–60s for `akan start`'s builder recovery, 1s–30s for the rest), its own give-up rule and its own log lines.
+
+  Two stop races in those loops are fixed:
+
+  - A replica whose restart timer had fired no longer respawns after the gateway stops.
+  - A builder `akan start` was still creating or booting when it stopped is now stopped too, instead of being started or retried after its ready timeout.
+
+  In `@akanjs/devkit`, `shouldAbandonBackendRecovery` is replaced by `backendRecoveryPolicy`, which gives up after five failed backend restarts as before.
+
 - e65172d: The CLI refreshes a cloud sign-in once less than an hour, or half the token's lifetime, is left, whichever is shorter. Before, a token that lived an hour or less read as due the moment it arrived, so every command rotated the refresh token and then called the cloud unsigned. Any unexpired token is now sent with the request, except the refresh call, which carries none. `akan login` signs in again when a session is due for refresh and has no refresh token left.
 - c3b5b3c: The framework no longer puts `@akanjs/native/core` on a web page. `isNativeApp()` and the other host checks read the platform the shell writes before the bundle runs, and a native shell still starts core with the page. A file that imports `akanjs/client/native` statically still brings core to every page that reaches it. On the minimal app this takes 15 KB raw (5.6 KB brotli) off the vendor floor and 20 KB raw (6.6 KB brotli) off every route entry. `akan build` also resolves the `production` export condition for the browser, SSR-client, CSR and MCP App view bundles, so a package such as Lexical ships its production build alone. On the minimal app the Agent editor chunk drops from 91 KB to 63 KB brotli. `akan start` is unchanged.
 - 6d5b544: A database service now has `create<Model>Many(rows)`. It creates the rows on the same path as `create<Model>`: `_preCreate` and `_postCreate`, the document's save and create hooks, and the live and pubsub events each row's commit fires. Every row's `_preCreate` and document pre hooks run first, so a check there that queries the table does not see the batch's own rows. The rows are then written in one transaction, joining the caller's when one is open, with one multi-row INSERT per 500 rows instead of one statement per row; if the database refuses one row, none is written. Every row's `_postCreate` runs once the transaction commits, as `create<Model>`'s runs once its row is stored, so a `_postCreate` that throws leaves the rows written. A service that already declares a method of that name, itself or in a lib service it extends, keeps its own at runtime, but its signature no longer typechecks against the generated one: rename it.
@@ -370,6 +392,30 @@
   - **`BuilderRpc.isUnavailable(error)`** tells such a failure apart, as `BuilderRpc.isTimeout` does for a request that times out. A bare, empty or unknown `/_akan/studio` view then lands on Runtime, and a view asked for by name still answers 503 with the reason.
   - **Mixed versions keep working.** A server reading a reply from an older dev host, with no kind, answers 503 as before, and an older server ignores the new field.
 
+- 3b7247e: A failed tool call now names a code a client or a model can branch on, beside the text it already sent, which is unchanged. No upgrade step is needed: `AgentWireToolResult` and `use-agentic`'s `ToolCallResult` only gain an optional `code`, and `akanjs/common` adds `MCP_FAILURE_META`, `McpFailure` and `FailureCode`.
+
+  Every code is a bounded token, a dictionary key (`<module>.error.<key>`) or one camelCase identifier, never prose, so no text can pass for one.
+
+  - **An app's `/mcp`:**
+    - A tool error carries `_meta["akanjs/failure"]: { code, statusCode }`, beside the server's own `_meta` for a 2026-07-28 client. The code is the one an HTTP caller gets:
+      - a domain `Err` by its dictionary key, such as `base.error.documentNotFound`;
+      - an `AkanError` by its code, such as `invalidArgument` for an argument the call got wrong;
+      - a 401 or 403 by its status alone (`unauthorized`, `forbidden`);
+      - a 5xx by a dictionary key or this server's own `AkanError` code, else by its status (`internalError`, `serviceUnavailable`), never by a code a duck-typed error put in its body.
+    - A JSON-RPC error carries `data.code`, which tells apart what `-32602` covers:
+      - `unknownTool`, `unknownPrompt` (an unlisted page prompt included) and `unknownResource`;
+      - `invalidArgument` for bad arguments or a missing tool name, prompt name or resource uri;
+      - a refused screen's `forbidden` or `notFound`.
+        A rate-limited call names `tooManyRequests` and the catch-all names `internalError`.
+    - An MCP Apps view's call that fails without a domain `Err` restores as an error with that status and code, where it used to be a plain `Error`. A tool the view itself serves to the host names its code in the same `_meta` entry, without a `statusCode`.
+  - **`akan mcp`:** a tool error carries the same `_meta["akanjs/failure"]`, with one of these codes:
+    - `unknownTool` for a name no mode lists;
+    - `toolUnavailable` for a tool outside the server's mode;
+    - `invalidArgument` for a missing argument, an unknown guideline name, or a workflow path outside `.akan/workflows/`;
+    - `toolFailed` for anything else, with `statusCode` 500. A coded `AkanError` keeps its own code.
+  - **The code agent:** an MCP server's tool result keeps the code it named, from `_meta["akanjs/failure"]` or a JSON-RPC error's `data.code`, in the call's `details`.
+  - **The in-page agent:** a `toolResults` entry whose tool threw carries `code` beside `error` (see `use-agentic`'s WIRE.md): a dictionary `Err`'s key, else the thrown error's own `code`. A `taint: "source"` tool's result carries none, since its code would travel outside the page-content fence. The bundled Anthropic and OpenAI adaptors send `code` to the model inside the tool result, beside `error`.
+
 - 44149b1: A module named in a library that lacks it, such as `akan create-view util:nope`, is refused at once, as one named in an app is. Before, it fell through to the module picker in a terminal, and without one it failed as if no module had been named. Both are now refused, terminal or not, with the modules there are and the line to rerun: `` Unknown module 'util:nope': util has no such module, so rerun it as `akan create-view <sys:module>` (choices: pokedex:card, util:photo). `` An app's used to say only `Invalid module name: nope`.
 - 0d7294c: Narrowed vendor entries hold up during a rolling deploy and on very large builds.
 
@@ -391,6 +437,7 @@
     - The rule's own rewrite is removed. Under `--unsafe` it renamed a `#field` where it was called but not where it was declared.
   - **A raw `Error` in an `srvkit/` adapter names its fix.** `akan verify` prints the `Err` import path from that file, and where the key goes: the app's or lib's own service dictionary, `lib/_<name>/<name>.dictionary.ts`, as `<name>.error.<key>`.
 
+- d4d84c6: `akan workflow validate` exits 0 when the only failures left are known baseline blockers (`overallStatus` `passed-with-baseline-blockers`); any other failed validation still exits 1. Over MCP, a passing `apply_workflow` dry run names `apply_workflow` with the same `planPath` and no `dryRun` as `next`, where it named `run_validation`, which had nothing to validate. A failed `akan workflow apply` reports no generated files queued for sync, no recommended validation command and no `akan verify` next action, and a failed field, mutation or slice write (`akan add-field` and its siblings) lists no generated file, validation command or next action; both used to list them as if the write had passed. With `-o json`, `akan workflow plan`, `apply`, `validate` and `report` print only the JSON report on stdout and send their log lines (`File Create:`, sync's warnings) to stderr; `create-module` and `create-scalar` applies used to print them before the report, so stdout did not parse. The text output is unchanged. `add-field` (the workflow and `akan add-field`) imports the type it writes: a scalar of the target from `../__scalar/<scalar>/<scalar>.constant`, a model from `../<model>/<model>.constant`, and `ID`, `Any` and the other `akanjs/base` types from `akanjs/base`, where it imported only `Int` and `Float` and wrote `field(Address)` with no import. A type that is not built in, not imported by the constant and not a scalar or model of the target is refused with `primitive-field-type-unknown`, at plan time and again at apply, before anything is written.
 - d2b2291: A failed workflow no longer reports success to its caller. `akan workflow plan` exits 1 when the plan has an error, `akan workflow apply` when the apply or its `--dry-run` fails, and `akan workflow validate` when its status is `failed` (which includes `passed-with-baseline-blockers`); all three exited 0 before. A dry run of a plan with an error, such as `add-field --type Number`, reports `failed` and lists no changed or generated files, where it used to list the plan's edits under "Automatically Modified". Over MCP, `plan_workflow` names `apply_workflow` in `next` and `approval.canApplyWith` only for a plan without an error, and `apply_workflow` names `run_validation` only when the apply did not fail; a refused plan also drops its "apply this plan" and "validate the apply report" recommendations. The workflows that write into an existing module (`add-field`, `add-enum-field`, `add-mutation`, `add-slice`, `create-ui`, `rename-key`) now refuse a service module, or any folder without its `<module>.constant.ts`, at plan time and again at apply. The `workflow-module-not-database` error lists the target's database modules and points at `create-module`, and for a field at `create-scalar`. Before, `add-field` on a service module passed its plan and dry run and failed only at apply, and `create-ui` wrote a misnamed `_<service>.View.tsx` into it. The `workflow-module-missing` error now lists only database modules too, says a name that matches a service module (with or without its `_`) is one instead of asking "Did you mean \_<service>?", and points at another app or library only when it holds a database module of that name.
 - adcdf3b: `akan workflow plan` and the `plan_workflow` MCP tool refuse a module the target app or library lacks, for every workflow that writes into an existing module (`add-field`, `add-enum-field`, `add-mutation`, `add-slice`, `create-ui`, `rename-key`). The `workflow-module-missing` error names the module, lists the modules the target has, and points at the module whose name differs only in case or by a leading `_`, at a scalar of that name, or at the app or library that holds it; only when none exists does it point at `create-module`. Before, the plan passed and its dry run reported `passed`. `add-mutation` used to plan a missing module with a warning so that a `create-module` plan could precede it; it now refuses too, so plan it after applying `create-module`. Every workflow now refuses an unknown `app` at plan time, listing the workspace's apps and libraries. `apply` and `--dry-run` check the target again before anything else, so a plan written earlier for a module that is gone fails instead of passing. `plan_workflow` now inspects the MCP server's workspace rather than the process directory.
 - Updated dependencies [bd198af]
@@ -414,8 +461,10 @@
 - Updated dependencies [ddd3d96]
 - Updated dependencies [3f231a7]
 - Updated dependencies [96f9ff6]
+- Updated dependencies [af7c411]
 - Updated dependencies [1ebc57a]
 - Updated dependencies [c3b5b3c]
+- Updated dependencies [dcb7e61]
 - Updated dependencies [6d5b544]
 - Updated dependencies [73f8830]
 - Updated dependencies [958f175]
@@ -427,6 +476,7 @@
 - Updated dependencies [e143263]
 - Updated dependencies [e4f7876]
 - Updated dependencies [cb0fd5b]
+- Updated dependencies [256b6e3]
 - Updated dependencies [c48d780]
 - Updated dependencies [3537448]
 - Updated dependencies [c882491]
@@ -448,6 +498,7 @@
 - Updated dependencies [9a9e1fa]
 - Updated dependencies [9055634]
 - Updated dependencies [3537448]
+- Updated dependencies [a373d51]
 - Updated dependencies [6c3a303]
 - Updated dependencies [27440aa]
 - Updated dependencies [e3de9ef]
@@ -470,6 +521,7 @@
 - Updated dependencies [e4c7e5c]
 - Updated dependencies [6291fec]
 - Updated dependencies [0c480c6]
+- Updated dependencies [3b7247e]
 - Updated dependencies [e4c3009]
 - Updated dependencies [0d7294c]
 - Updated dependencies [d9eaacc]

package/akanApp/akanApp.host.test.ts

@@ -194,3 +194,79 @@ describe("a builder request while no builder is running", () => {
     }
   });
 });
+
+describe("a stop while the builder is starting", () => {
+  isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "local" });
+  const track = tempRoots();
+  const fakeBuilder = (onStart: (options: { onReady?: () => void; onExit?: () => void }) => void = () => undefined) => {
+    const builder = {
+      status: "starting",
+      patcherOff: false,
+      started: 0,
+      stopped: 0,
+      start: (options: { onReady?: () => void; onExit?: () => void }) => {
+        builder.started += 1;
+        onStart(options);
+      },
+      send: () => false,
+      stop: () => {
+        builder.stopped += 1;
+      },
+    };
+    return builder;
+  };
+
+  test("stops a builder created after the stop, and never starts it", async () => {
+    const { app } = track(await createTempApp("demo"));
+    const builder = fakeBuilder();
+    const created = Promise.withResolvers<IncrementalBuilderHost>();
+    const create = IncrementalBuilderHost.create;
+    let creates = 0;
+    IncrementalBuilderHost.create = async () => {
+      creates += 1;
+      return await created.promise;
+    };
+    const host = new AkanAppHost(app, { env: { ...process.env } as Record<string, string> });
+    try {
+      const starting = host.start();
+      await Bun.sleep(50);
+      await host.stop();
+      created.resolve(builder as unknown as IncrementalBuilderHost);
+      await expect(starting).rejects.toThrow("dev server stopped before the builder started");
+      expect({ creates, started: builder.started, stopped: builder.stopped }).toEqual({
+        creates: 1,
+        started: 0,
+        stopped: 1,
+      });
+    } finally {
+      IncrementalBuilderHost.create = create;
+    }
+  });
+
+  test("gives up a builder still booting at once instead of retrying after its ready timeout", async () => {
+    const { app } = track(await createTempApp("demo"));
+    let exitLate: (() => void) | undefined;
+    const builder = fakeBuilder(({ onExit }) => {
+      exitLate = onExit;
+    });
+    const create = IncrementalBuilderHost.create;
+    let creates = 0;
+    IncrementalBuilderHost.create = async () => {
+      creates += 1;
+      return builder as unknown as IncrementalBuilderHost;
+    };
+    const host = new AkanAppHost(app, { env: { ...process.env } as Record<string, string> });
+    try {
+      const starting = host.start();
+      await Bun.sleep(50);
+      expect(builder.started).toBe(1);
+      await host.stop();
+      await expect(starting).rejects.toThrow("dev server stopped before the builder was ready");
+      exitLate?.();
+      await Bun.sleep(50);
+      expect({ creates, stopped: builder.stopped }).toEqual({ creates: 1, stopped: 1 });
+    } finally {
+      IncrementalBuilderHost.create = create;
+    }
+  });
+});

package/akanApp/akanApp.host.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { Logger } from "akanjs/common";
+import { Logger, RestartSchedule } from "akanjs/common";
 import type { BuilderMessage, BuilderMetrics, BuildPhase, ChangeBatch, DevBuildStatus } from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createTunnel } from "../createTunnel";
@@ -15,6 +15,7 @@ import {
   type BackendLifecycleState,
   type BackendRestartReason,
   BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS,
+  backendRecoveryPolicy,
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
   createBackendBuildStatus,
@@ -35,7 +36,6 @@ import {
   redisTunnelPolicy,
   resolveIdleSuspendMs,
   type SourceFingerprints,
-  shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
   shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
@@ -59,10 +59,6 @@ const BACKEND_RESTART_DEBOUNCE_MS = 120;
 // Above the gateway's ~5s child-shutdown wait: a gateway SIGKILLed mid-shutdown strands orphan replicas.
 const BACKEND_GRACEFUL_TIMEOUT_MS = 8_000;
 
-const BACKEND_RECOVERY_BASE_DELAY_MS = 1_000;
-
-const BACKEND_RECOVERY_MAX_DELAY_MS = 30_000;
-
 const BACKEND_STDERR_TAIL_LIMIT = 40;
 
 const BUILDER_READY_TIMEOUT_MS = 150000;
@@ -77,11 +73,6 @@ const BUILDER_RSS_SETTLE_MS = 20_000;
 
 const PS_RSS_TIMEOUT_MS = 2_000;
 
-// The builder is the file watcher, so unlike the backend its recovery never gives up; it only backs off.
-const BUILDER_RECOVERY_BASE_DELAY_MS = 2_000;
-
-const BUILDER_RECOVERY_MAX_DELAY_MS = 60_000;
-
 interface LastGoodFrontendState {
   pages?: Extract<BuilderMessage, { type: "pages-updated" }>;
   css?: Extract<BuilderMessage, { type: "css-updated" }>;
@@ -101,8 +92,7 @@ export class AkanAppHost {
   #backendReady = false;
   #plannedBackendStops = new WeakSet<Bun.Subprocess<"ignore", "inherit", "inherit">>();
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
-  #backendRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
-  #backendRecoveryAttempts = 0;
+  readonly #backendRecovery = new RestartSchedule(backendRecoveryPolicy);
   #backendGaveUp = false;
   #backendLifecycleState: BackendLifecycleState = "stopped";
   #pendingRestartReason: BackendRestartReason | null = null;
@@ -119,8 +109,9 @@ export class AkanAppHost {
   //? its recovery, reported past the failure's generation so the scan overlay clears.
   #restartFailedAfterApply: number | null = null;
   #stopping = false;
-  #builderRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
-  #builderRecoveryAttempts = 0;
+  //? The builder is the file watcher, so unlike the backend its recovery never gives up; it only backs off.
+  readonly #builderRecovery = new RestartSchedule({ min: 2_000, max: 60_000 });
+  #abandonBuilderStart: ((error: Error) => void) | null = null;
   #backendStartStatus: { generation?: number; files: string[] } | null = null;
   #backendBuildStatusGeneration = 0;
   #backendStderrTail: string[] = [];
@@ -186,6 +177,8 @@ export class AkanAppHost {
     this.#cancelIdleSuspend();
     this.#stopIdleWatcher();
     this.#clearRestartTimers();
+    //? A stopped builder sends no exit: a start waiting for its ready would sit out the ready timeout, then retry.
+    this.#abandonBuilderStart?.(new Error("dev server stopped before the builder was ready"));
     this.#pendingRestartReason = null;
     // Before the backend goes away, while it can still receive the answer.
     this.#failPendingBuilderMessages("dev server is shutting down");
@@ -195,9 +188,10 @@ export class AkanAppHost {
     return this;
   }
   #clearRestartTimers() {
-    for (const timer of [this.#restartTimer, this.#backendRecoveryTimer, this.#builderRecoveryTimer])
-      if (timer) clearTimeout(timer);
-    this.#restartTimer = this.#backendRecoveryTimer = this.#builderRecoveryTimer = null;
+    if (this.#restartTimer) clearTimeout(this.#restartTimer);
+    this.#restartTimer = null;
+    this.#backendRecovery.cancel();
+    this.#builderRecovery.cancel();
   }
   kill() {
     void this.stop();
@@ -239,7 +233,7 @@ export class AkanAppHost {
         if (!msg || typeof msg !== "object") return;
         if (msg.type === "backend-ready") {
           this.#backendReady = true;
-          this.#backendRecoveryAttempts = 0;
+          this.#backendRecovery.reset();
           this.#setBackendLifecycleState("ready", `pid=${msg.pid}`);
           this.#recordBackendReadyStatus();
           this.logger.verbose(`backend ready pid=${msg.pid}`);
@@ -402,10 +396,7 @@ export class AkanAppHost {
       "restart-pending",
       `generation=${pending.generation ?? "(unknown)"} files=${pending.files.length} roles=${pending.roles.join(",") || "(none)"}`,
     );
-    if (this.#backendRecoveryTimer) {
-      clearTimeout(this.#backendRecoveryTimer);
-      this.#backendRecoveryTimer = null;
-    }
+    this.#backendRecovery.cancel();
     if (this.#restartTimer) clearTimeout(this.#restartTimer);
     this.#restartTimer = setTimeout(() => {
       this.#restartTimer = null;
@@ -426,16 +417,16 @@ export class AkanAppHost {
     this.logger.verbose(
       `[backend-reload] restarting backend generation=${reason.generation ?? "(unknown)"} files=${reason.files.length} roles=${reason.roles.join(",") || "(none)"}`,
     );
-    this.#backendRecoveryAttempts = 0;
+    this.#backendRecovery.reset();
     await Promise.all([this.#stopBackend(), this.#backendGraph.refresh()]);
     this.#startBackend({ generation: reason.generation, files: reason.files });
   }
   #scheduleBackendRecovery(reason: string) {
-    if (this.#backendRecoveryTimer || this.#backend) return;
-    if (shouldAbandonBackendRecovery(this.#backendRecoveryAttempts)) {
-      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for an edit or a green build to retry.`;
+    if (this.#backendRecovery.pending || this.#backend) return;
+    if (this.#backendRecovery.exhausted) {
+      const message = `Backend exited ${this.#backendRecovery.attempts} times in a row (${reason}); waiting for an edit or a green build to retry.`;
       this.#backendGaveUp = true;
-      this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecoveryAttempts} recovery attempts`);
+      this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecovery.attempts} recovery attempts`);
       this.logger.error(`[backend-recovery] ${message}`);
       if (this.#backendStderrTail.length > 0) {
         this.logger.error(`[backend-recovery] recent backend stderr:\n${this.#backendStderrTail.join("\n")}`);
@@ -445,9 +436,7 @@ export class AkanAppHost {
       return;
     }
     this.#setBackendLifecycleState("recovering", reason);
-    const attempt = this.#backendRecoveryAttempts;
-    const delay = Math.min(BACKEND_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BACKEND_RECOVERY_MAX_DELAY_MS);
-    this.#backendRecoveryAttempts = attempt + 1;
+    const delay = this.#backendRecovery.next();
     const failureStatus = this.#recordBackendBuildStatus({
       ok: false,
       files: [],
@@ -455,18 +444,17 @@ export class AkanAppHost {
     });
     this.#sendOrQueueBuildStatus(failureStatus);
     this.logger.warn(
-      `[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`,
+      `[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecovery.attempts})`,
     );
     if (this.#backendStderrTail.length > 0) {
       this.logger.warn(`[backend-recovery] recent backend stderr:\n${this.#backendStderrTail.join("\n")}`);
     }
-    this.#backendRecoveryTimer = setTimeout(() => {
-      this.#backendRecoveryTimer = null;
+    this.#backendRecovery.arm(delay, () => {
       if (this.#backend) return;
       void this.#backendGraph.refresh().finally(() => {
         if (!this.#backend) this.#startBackend({ generation: failureStatus.generation, files: failureStatus.files });
       });
-    }, delay);
+    });
   }
   #enqueueBuilderMessage(message: BuilderMessage) {
     this.#builderMessageQueue = this.#builderMessageQueue
@@ -763,8 +751,8 @@ export class AkanAppHost {
       this.#pendingRecycle ||
       this.#restartTimer ||
       this.#backendRestart ||
-      this.#backendRecoveryTimer ||
-      this.#builderRecoveryTimer ||
+      this.#backendRecovery.pending ||
+      this.#builderRecovery.pending ||
       this.#rssRecycleReason
     );
   }
@@ -1024,28 +1012,25 @@ export class AkanAppHost {
     this.#scheduleBuilderRecovery({ generation, files: message.files });
   }
   #scheduleBuilderRecovery(reason: { generation?: number; files: string[] }): void {
-    if (this.#builderRecoveryTimer || this.#builder) return;
-    const attempt = this.#builderRecoveryAttempts;
-    const delay = Math.min(BUILDER_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BUILDER_RECOVERY_MAX_DELAY_MS);
-    this.#builderRecoveryAttempts = attempt + 1;
+    if (this.#stopping || this.#builderRecovery.pending || this.#builder) return;
+    const delay = this.#builderRecovery.schedule(() => {
+      if (this.#stopping || this.#builder) return;
+      void this.#recoverBuilder(reason);
+    });
     this.logger.warn(
-      `[builder-recovery] builder is down; retrying start in ${delay}ms (attempt ${this.#builderRecoveryAttempts})`,
+      `[builder-recovery] builder is down; retrying start in ${delay}ms (attempt ${this.#builderRecovery.attempts})`,
     );
-    this.#builderRecoveryTimer = setTimeout(() => {
-      this.#builderRecoveryTimer = null;
-      if (this.#builder) return;
-      void this.#recoverBuilder(reason);
-    }, delay);
   }
   async #recoverBuilder(reason: { generation?: number; files: string[] }): Promise<void> {
     try {
       await this.#startBuilder();
     } catch (err) {
+      if (this.#stopping) return;
       this.logger.warn(`[builder-recovery] builder start failed: ${err instanceof Error ? err.message : String(err)}`);
       this.#scheduleBuilderRecovery(reason);
       return;
     }
-    this.#builderRecoveryAttempts = 0;
+    this.#builderRecovery.reset();
     this.logger.info("[builder-recovery] builder recovered");
     void this.#restartBackendForGapChanges();
     const failedAfterApply = this.#restartFailedAfterApply;
@@ -1062,14 +1047,14 @@ export class AkanAppHost {
     };
     this.#recordBuildStatus(status);
     this.#sendOrQueueBuildStatus(status);
-    if (!this.#backend && !this.#backendRecoveryTimer) {
+    if (!this.#backend && !this.#backendRecovery.pending) {
       this.#startBackend({ generation: reason.generation, files: reason.files });
     }
   }
   #reviveBackendAfterGreenBuild(status: DevBuildStatus): void {
-    if (!status.ok || !this.#backendGaveUp || this.#backend || this.#backendRecoveryTimer) return;
+    if (!status.ok || !this.#backendGaveUp || this.#backend || this.#backendRecovery.pending) return;
     this.logger.info(`[backend-recovery] build went green (generation=${status.generation}); retrying backend`);
-    this.#backendRecoveryAttempts = 0;
+    this.#backendRecovery.reset();
     this.#startBackend({ generation: status.generation, files: status.files });
   }
   async #restartDevChildren(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<void> {
@@ -1097,7 +1082,7 @@ export class AkanAppHost {
   ): Promise<void> {
     const generation = message.devPlan?.generation ?? message.generation;
     this.#clearRestartTimers();
-    this.#builderRecoveryAttempts = 0;
+    this.#builderRecovery.reset();
     this.#pendingRestartReason = null;
     await this.#backendRestart;
     this.#lastGoodFrontend = {};
@@ -1232,7 +1217,7 @@ export class AkanAppHost {
     this.app.verbose(`[cli] waiting for builder to complete initial base build…`);
     let lastError: unknown;
     for (let attempt = 1; attempt <= BUILDER_START_MAX_ATTEMPTS; attempt++) {
-      this.#builder = await IncrementalBuilderHost.create(
+      const builder = await IncrementalBuilderHost.create(
         this.app,
         this.env,
         (msg) => {
@@ -1244,6 +1229,11 @@ export class AkanAppHost {
           patcherOff: this.#patcherOff,
         },
       );
+      if (this.#stopping) {
+        builder.stop();
+        throw new Error("dev server stopped before the builder started");
+      }
+      this.#builder = builder;
       try {
         await this.#waitForBuilderReady(attempt, { announceBootState });
         this.app.verbose(`[cli] base build ready in ${Date.now() - startTime}ms — starting backend`);
@@ -1251,7 +1241,7 @@ export class AkanAppHost {
       } catch (err) {
         lastError = err;
         this.#stopBuilder();
-        if (attempt >= BUILDER_START_MAX_ATTEMPTS) break;
+        if (attempt >= BUILDER_START_MAX_ATTEMPTS || this.#stopping) break;
         this.app.verbose(`[cli] builder failed before ready; retrying (${attempt + 1}/${BUILDER_START_MAX_ATTEMPTS})`);
       }
     }
@@ -1269,8 +1259,11 @@ export class AkanAppHost {
         if (settled) return;
         settled = true;
         clearTimeout(timeout);
+        if (this.#abandonBuilderStart === abandon) this.#abandonBuilderStart = null;
         fn();
       };
+      const abandon = (error: Error) => settle(() => reject(error));
+      this.#abandonBuilderStart = abandon;
       const timeout = setTimeout(() => {
         settle(() => reject(new Error("[cli] builder timed out before emitting builder-ready")));
       }, BUILDER_READY_TIMEOUT_MS);

package/akanApp/devHostPolicy.test.ts

@@ -1,8 +1,10 @@
 import { describe, expect, test } from "bun:test";
+import { RestartSchedule } from "akanjs/common";
 import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangeAction } from "akanjs/server";
 //? The source itself, not the package: the published akanjs exports no such subpath, and tests are not bundled.
 import { DevBuildRecovery } from "../../../akanjs/server/artifact/devBuildRecovery";
 import {
+  backendRecoveryPolicy,
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
   createBackendBuildStatus,
@@ -18,7 +20,6 @@ import {
   normalizeBackendReportedGeneration,
   redisTunnelPolicy,
   resolveIdleSuspendMs,
-  shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
   shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
@@ -489,16 +490,15 @@ describe("legacy backend graph fallback", () => {
 });
 
 describe("backend recovery abandonment", () => {
-  test("keeps retrying below the attempt ceiling and abandons at it", () => {
-    expect(shouldAbandonBackendRecovery(0)).toBe(false);
-    expect(shouldAbandonBackendRecovery(4)).toBe(false);
-    expect(shouldAbandonBackendRecovery(5)).toBe(true);
-    expect(shouldAbandonBackendRecovery(9)).toBe(true);
-  });
-
-  test("honors a custom attempt ceiling", () => {
-    expect(shouldAbandonBackendRecovery(2, 3)).toBe(false);
-    expect(shouldAbandonBackendRecovery(3, 3)).toBe(true);
+  test("backs off from 1s and gives up after five failed restarts in a row", () => {
+    const recovery = new RestartSchedule(backendRecoveryPolicy);
+    const delays = [1, 2, 3, 4].map(() => recovery.next());
+    expect(recovery.exhausted).toBe(false);
+    delays.push(recovery.next());
+    expect(delays).toEqual([1_000, 2_000, 4_000, 8_000, 16_000]);
+    expect(recovery.exhausted).toBe(true);
+    recovery.reset();
+    expect(recovery.exhausted).toBe(false);
   });
 });
 

package/akanApp/devHostPolicy.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import type { RestartPolicy } from "akanjs/common";
 import type {
   BuilderMessage,
   BuildPhase,
@@ -20,7 +21,7 @@ export const redisTunnelPolicy = ({
 }): "none" | "optional" | "required" =>
   environment === "local" ? "none" : databaseMode === "single" ? "optional" : "required";
 
-const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
+export const backendRecoveryPolicy: RestartPolicy = { min: 1_000, max: 30_000, maxAttempts: 5 };
 
 // A page load asks for several routes, but a builder that never returns must not grow the hold queue unbounded.
 const HELD_BUILDER_REQUEST_LIMIT = 64;
@@ -57,9 +58,6 @@ export const shouldRestartBackendByDevPlan = (
 export const shouldRestartBuilderByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
   message.devPlan?.actions.includes("restart-builder") ?? false;
 
-export const shouldAbandonBackendRecovery = (attempts: number, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS): boolean =>
-  attempts >= maxAttempts;
-
 /** The gateway reports backend failures with `generation: -1`; the host assigns its own counter then. */
 export const normalizeBackendReportedGeneration = (generation: number): number | undefined =>
   generation >= 0 ? generation : undefined;

package/akanMcpContract.ts

@@ -2,6 +2,7 @@ import { lstatSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { isRecord } from "akanjs/common";
 import { AkanContextAnalyzer, type AkanDiagnostic, type AkanModuleContext } from "./akanContext";
+import { AkanMcpToolError } from "./akanMcpToolError";
 import type { Workspace } from "./commandDecorators";
 import type {
   AkanContextEvidence,
@@ -172,7 +173,8 @@ export const workflowArtifactPath = (workspace: Workspace, filePath: string) =>
       ? path.join(root, "runs", `${filePath}.json`)
       : path.resolve(workspace.workspaceRoot, filePath);
   if (!isInside(root, resolved) || !staysInside(workspace.workspaceRoot, root, resolved))
-    throw new Error(
+    throw new AkanMcpToolError(
+      "invalidArgument",
       `MCP workflow files live under ${workflowArtifactDir}/ of the workspace, not ${JSON.stringify(filePath)}.`,
     );
   return resolved;
@@ -213,7 +215,8 @@ export const applyFirstPolicy = {
 
 export const stringArg = (args: Record<string, unknown>, key: string) => {
   const value = args[key];
-  if (typeof value !== "string" || !value) throw new Error(`MCP tool argument "${key}" is required.`);
+  if (typeof value !== "string" || !value)
+    throw new AkanMcpToolError("invalidArgument", `MCP tool argument "${key}" is required.`);
   return value;
 };
 
@@ -226,13 +229,20 @@ export const workflowInputsArg = (args: Record<string, unknown>) => {
 export const inspectAkanContextPropsArg = (args: Record<string, unknown>): InspectAkanContextProps => {
   const question = stringArg(args, "question");
   const review = stringArg(args, "review");
-  if (!isRecord(args.draft)) throw new Error('MCP tool argument "draft" is required.');
-  if (!isRecord(args.request)) throw new Error('MCP tool argument "request" is required.');
+  if (!isRecord(args.draft)) throw new AkanMcpToolError("invalidArgument", 'MCP tool argument "draft" is required.');
+  if (!isRecord(args.request))
+    throw new AkanMcpToolError("invalidArgument", 'MCP tool argument "request" is required.');
   if (!isInspectAkanContextRequestType(args.draft.type)) {
-    throw new Error('MCP tool argument "draft.type" must be a supported inspect_akan_context request type.');
+    throw new AkanMcpToolError(
+      "invalidArgument",
+      'MCP tool argument "draft.type" must be a supported inspect_akan_context request type.',
+    );
   }
   if (!isInspectAkanContextRequestType(args.request.type)) {
-    throw new Error('MCP tool argument "request.type" must be a supported inspect_akan_context request type.');
+    throw new AkanMcpToolError(
+      "invalidArgument",
+      'MCP tool argument "request.type" must be a supported inspect_akan_context request type.',
+    );
   }
   const base = { question, draft: { reason: stringArg(args.draft, "reason"), type: args.draft.type }, review };
   const request = args.request;
@@ -384,7 +394,7 @@ export const applyMcpTools: McpToolDefinition[] = [
   {
     name: "apply_workflow",
     description:
-      "Apply a stored workflow plan before direct edits and return validationTarget, plus next.tool=run_validation unless the apply failed.",
+      "Apply a stored workflow plan before direct edits and return validationTarget. Unless it failed, next.tool is run_validation after an apply and apply_workflow without dryRun after a dry run.",
     inputSchema: {
       type: "object",
       properties: { planPath: stringProperty, dryRun: booleanProperty },

package/akanMcpToolError.ts

@@ -0,0 +1,16 @@
+import { AkanError } from "akanjs/base";
+import type { McpFailure } from "akanjs/common";
+
+export type AkanMcpToolErrorCode = "invalidArgument" | "toolUnavailable" | "unknownTool";
+
+export class AkanMcpToolError extends AkanError<AkanMcpToolErrorCode> {
+  constructor(code: AkanMcpToolErrorCode, message: string) {
+    super(code, message, { statusCode: 400 });
+  }
+
+  static failureOf(error: unknown): McpFailure {
+    return AkanError.is(error)
+      ? { code: error.code, statusCode: error.statusCode }
+      : { code: "toolFailed", statusCode: 500 };
+  }
+}

package/codeAgent/skills/akan-debug/SKILL.md

@@ -9,7 +9,7 @@ description: "Check and debug a running Akan app: akan preview for what a page s
 
 `akan preview <app> [paths]` opens pages of the app's dev server in a headless browser and prints, per page,
 the HTTP status, the title, a slice of the visible text, the uncaught errors and rejections the page reported,
-the server errors logged meanwhile, console errors and warnings, and layout smells. It exits 1 when a page failed.
+the server errors logged meanwhile, console errors and warnings, and layout smells. It exits 3 when a page failed.
 
 - It uses the dev server that answers for this app and checkout. With none, it starts one for the run and
   stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a

package/codeAgent/skills/akan-mcp/SKILL.md

@@ -23,7 +23,8 @@ an endpoint with a real guard is published, one with none is refused, and so is
 - `option.setMcp({ … })` in the app's `lib/option.ts`, never `main.ts`; `AKAN_MCP=false` takes the surface off.
 - `JWT_SECRET` is required outside `local`.
 - Every published entry needs a `.desc()`; model-facing text is English.
-- Never make a refusal message more helpful.
+- Never make a refusal message more helpful. A client branches on the code a failure carries
+  (`_meta["akanjs/failure"]`, or a JSON-RPC error's `data.code`), never on its text.
 
 ## Pages for the host