@nanobpm/urban 0.77.2 → 0.77.4

package/dist/runtime/core/modules/scheduler.d.ts

@@ -4,6 +4,14 @@ export interface SchedulerDeps {
     clearTimer: (handle: unknown) => void;
     /** Current wall-clock time in ms since epoch. */
     now: () => number;
+    /** Optional shutdown signal. When it aborts, a pending {@link schedulerClock} `wait()` clears its
+     *  armed timer and rejects, so a handler parked on the (virtual) clock unwinds at teardown instead
+     *  of wedging whoever awaits it. Under the test kit this is the engine's shutdown signal: a worker
+     *  handler parked on `app.wait()` sits on a virtual timer that no `advanceTime` will fire during
+     *  `engine.close()`, so without this its promise never settles and `close()` hangs (the issue #446
+     *  follow-up — the virtual-timer sibling of the real-time use-after-free). Absent on the live
+     *  scheduler, where real timers always fire on wall-clock time, so `wait()` never rejects there. */
+    readonly signal?: AbortSignal;
 }
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
 export declare const MAX_TIMER_DELAY_MS = 2147483647;

package/dist/runtime/core/modules/scheduler.js

@@ -3,6 +3,13 @@
 // worker handlers. Keeping one definition here — rather than a copy per module — means a
 // test's fake scheduler drives them all the same way, and the "clamp a far-future delay to
 // setTimeout's 32-bit range" rule has a single home.
+/** The rejection surfaced to a `wait()` cancelled by a shutdown {@link SchedulerDeps.signal}: the
+ *  signal's `reason` when it is an {@link Error}, else a generic teardown error. Reusing the reason
+ *  keeps a caller's fail-loud message (e.g. "WasmEngineClient closing") intact. */
+function schedulerAbortError(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new Error("app.wait aborted: scheduler shutting down");
+}
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 function isTimerHandle(handle) {
@@ -32,9 +39,48 @@ export function defaultScheduler() {
 export function schedulerClock(sched) {
     return {
         now: () => sched.now(),
-        wait: (ms) => new Promise((resolve) => {
+        wait: (ms) => new Promise((resolve, reject) => {
+            const signal = sched.signal;
+            // Already shutting down: reject immediately rather than arm a timer that would outlive the
+            // teardown (and, under the virtual clock, never fire).
+            if (signal?.aborted) {
+                reject(schedulerAbortError(signal));
+                return;
+            }
             const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
-            sched.setTimer(() => resolve(), delay);
+            let settled = false;
+            let onAbort;
+            const handle = sched.setTimer(() => {
+                settled = true;
+                if (onAbort && signal)
+                    signal.removeEventListener("abort", onAbort);
+                resolve();
+            }, delay);
+            // When a shutdown signal is present, a mid-wait abort disarms the timer and rejects, so a
+            // handler parked here unwinds at teardown instead of wedging its awaiter. Inert (no listener,
+            // no behaviour change) on the live scheduler, which supplies no signal.
+            //
+            // `settled` guards the synchronous-timer case: this seam permits `setTimer` to invoke its
+            // callback synchronously (the test `capturingScheduler` does exactly that), which resolves
+            // the wait *before* we get here. Installing an abort listener on that already-settled promise
+            // would leak its closure until the signal fires (and have shutdown clear an already-fired
+            // handle), so skip it entirely when the callback already ran.
+            if (signal && !settled) {
+                onAbort = () => {
+                    sched.clearTimer(handle);
+                    reject(schedulerAbortError(signal));
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+                // Re-entrant seam: `setTimer` above is injectable and may abort `signal` *synchronously*
+                // without firing the timer callback (so `settled` is still false). An abort event is not
+                // replayed to a listener added after the fact, so the listener just registered would never
+                // run and the wait would hang until the runner timeout. Re-check and drive the abort path
+                // by hand — removing the (now-inert) listener first so it cannot also fire and double-reject.
+                if (signal.aborted && !settled) {
+                    signal.removeEventListener("abort", onAbort);
+                    onAbort();
+                }
+            }
         }),
     };
 }

package/dist/toolkit/addConnector.js

@@ -12,6 +12,7 @@
 // package (a subprocess) is the CLI's job, so this stays runtime-agnostic and
 // unit-testable.
 import { errorMessage, isRecord } from "../runtime/core/guards.js";
+import { detectJsonIndent } from "./scaffold.js";
 const MANIFEST_FILE = "nano-ide.ext.json";
 function joinPath(a, b) {
     // Trim both slash styles (as toolkit/gen.ts joinPath does) so a Windows-style
@@ -61,9 +62,11 @@ export async function addConnector(opts) {
     if (!(await io.exists(appManifestPath))) {
         throw new Error(`no ${manifestFile} at ${appManifestPath} — run this inside an Urban app.`);
     }
+    let appRaw;
     let app;
     try {
-        app = JSON.parse(await io.readText(appManifestPath));
+        appRaw = await io.readText(appManifestPath);
+        app = JSON.parse(appRaw);
     }
     catch (err) {
         throw new Error(`failed to parse ${appManifestPath}: ${errorMessage(err)}`);
@@ -161,7 +164,10 @@ export async function addConnector(opts) {
         workers.push(entry);
         wired.push({ taskType: spec.type, alreadyPresent: false });
     }
-    await io.writeText(appManifestPath, JSON.stringify(app, null, 2) + "\n");
+    // Preserve the manifest's own indentation (default tab, matching the scaffold's Biome config)
+    // so enabling a connector never reformats nano.app.json out from under `npm run lint` — the same
+    // fidelity `urban gen` gives via detectJsonIndent, kept as the single source of truth.
+    await io.writeText(appManifestPath, `${JSON.stringify(app, null, detectJsonIndent(appRaw))}\n`);
     return {
         packId: pack.id,
         wired,

package/dist/toolkit/scaffold/operations.js

@@ -29,16 +29,21 @@ export function renderOperationStub(operationId, dir = DEFAULT_OPERATIONS_DIR) {
         `// (ADR 0059). This file is yours to edit — \`urban gen\` will never overwrite it. The\n` +
         `// generated controller (nano-generated/controller.ts) imports this default export and\n` +
         `// type-checks it against the spec, so the signature cannot drift. Implement the body below\n` +
-        `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`) and delete the throw.\n` +
+        `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`), replacing the\n` +
+        `// guard warn + throw.\n` +
         `import { NotImplemented } from "@nanobpm/urban";\n` +
         `import { defineOperation } from ${JSON.stringify(`${up}nano-generated/operations.ts`)};\n` +
         `\n` +
         `export default defineOperation(${key}, async (input, app) => {\n` +
-        `  // \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
-        `  // through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
-        `  // auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
-        `  // Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
-        `  throw new NotImplemented(${key});\n` +
+        `\t// \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
+        `\t// through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
+        `\t// auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
+        `\t// Return \`{ status?, headers?, body? }\` (or nothing → 204). Replace the two lines below.\n` +
+        `\tapp.log.warn("operation not implemented", {\n` +
+        `\t\toperationId: ${key},\n` +
+        `\t\tmethod: input.req.method,\n` +
+        `\t});\n` +
+        `\tthrow new NotImplemented(${key});\n` +
         `});\n`);
 }
 /**

package/dist/toolkit/scaffold/workers.js

@@ -38,21 +38,26 @@ export function renderWorkerStub(taskType, typedIn, typedOut) {
     else if (typedOut)
         generic = `<Record<string, unknown>, WorkerOutputs[${key}]>`;
     const varsNote = typedIn
-        ? `  // \`job.variables\` is typed as WorkerInputs[${key}].`
-        : `  // \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
+        ? `\t// \`job.variables\` is typed as WorkerInputs[${key}].`
+        : `\t// \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
+    // The stub arrives lint-clean under the scaffold's own Biome config: tab-indented, and
+    // referencing both `job` and `app` (via the warn line) so `noUnusedFunctionParameters`
+    // does not fire before the author has filled in the body.
     return (`// Handler stub for the \`${taskType}\` service task, scaffolded from the model (ADR 0056).\n` +
         `// This file is yours to edit — \`urban gen\` will never overwrite it. Implement the body\n` +
-        `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
+        `// below (use \`app.data.table(...)\` for state), replacing the guard warn + throw so the\n` +
+        `// "worker not implemented" warning does not survive into a working handler.\n` +
         `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
         generatedImport +
         `\n` +
         `const handler: AppJobHandler${generic} = async (job, app) => {\n` +
         varsNote +
         `\n` +
-        `  // Reach app state and services through the injected \`app\` API.\n` +
-        `  // Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
-        `  // { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
-        `  throw new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
+        `\t// Reach app state and services through the injected \`app\` API.\n` +
+        `\t// Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
+        `\t// { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
+        `\tapp.log.warn("worker not implemented", { jobKey: job.jobKey });\n` +
+        `\tthrow new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
         `};\n` +
         `\n` +
         `export default handler;\n`);

package/dist/toolkit/scaffold.d.ts

@@ -1,5 +1,17 @@
 import type { GenIO } from "./gen.ts";
 import { type SkippedWorker, type StubManifestEntry } from "./scaffold/workers.ts";
+/**
+ * Detect the indentation of a JSON document from its first indented line, so a rewrite can
+ * reuse it (`"\t"` or an N-space string) instead of hard-coding one style. Falls back to a tab
+ * — the scaffold's Biome default — when the file is empty/single-line or uses no indentation.
+ *
+ * Any indent — spaces or tabs — is clamped to 10 characters because `JSON.stringify` silently
+ * truncates a string `space` argument to 10; returning a wider prefix would promise a fidelity the
+ * serializer cannot honor (e.g. an 11+-tab manifest would be rewritten at a different width than
+ * its input). Tab indentation (the scaffold default) and any realistic width (2/4 spaces) are
+ * unaffected.
+ */
+export declare function detectJsonIndent(json: string): string;
 export interface ScaffoldOptions {
     root: string;
     io: GenIO;

package/dist/toolkit/scaffold.js

@@ -6,13 +6,38 @@ import { joinPath, readModels } from "./gen.js";
 import { planWorkerScaffold, } from "./scaffold/workers.js";
 import { planOperationScaffold } from "./scaffold/operations.js";
 import { parseSpec } from "../openapi/spec.js";
+/**
+ * Detect the indentation of a JSON document from its first indented line, so a rewrite can
+ * reuse it (`"\t"` or an N-space string) instead of hard-coding one style. Falls back to a tab
+ * — the scaffold's Biome default — when the file is empty/single-line or uses no indentation.
+ *
+ * Any indent — spaces or tabs — is clamped to 10 characters because `JSON.stringify` silently
+ * truncates a string `space` argument to 10; returning a wider prefix would promise a fidelity the
+ * serializer cannot honor (e.g. an 11+-tab manifest would be rewritten at a different width than
+ * its input). Tab indentation (the scaffold default) and any realistic width (2/4 spaces) are
+ * unaffected.
+ */
+export function detectJsonIndent(json) {
+    // Anchor on any line terminator, not just `\n`, so the width is detected regardless of the
+    // manifest's line endings: LF (`\n`), CRLF (`\r\n`, where `\n` already precedes the indent),
+    // bare-CR old-Mac (`\r`), and LFCR (`\n\r`) all resolve to the indentation that follows.
+    const m = json.match(/[\r\n]([ \t]+)\S/);
+    if (!m)
+        return "\t";
+    const indent = m[1];
+    return indent.length > 10 ? indent.slice(0, 10) : indent;
+}
 /** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
 export async function scaffoldWorkers(opts) {
     const { root, io } = opts;
     const write = opts.write ?? false;
     const manifestFile = opts.manifestFile ?? "nano.app.json";
     const manifestPath = joinPath(root, manifestFile);
-    const manifest = JSON.parse(await io.readText(manifestPath));
+    const manifestRaw = await io.readText(manifestPath);
+    const manifest = JSON.parse(manifestRaw);
+    // Preserve the manifest's own indentation when we patch it back (default tab, matching the
+    // scaffold's Biome config), so wiring a worker never reformats the file out from under lint.
+    const manifestIndent = detectJsonIndent(manifestRaw);
     const models = await readModels(root, io, manifest);
     const declaredTypeIds = Object.keys(manifest.types ?? {});
     const { plans, skipped } = planWorkerScaffold(models, manifest.workers ?? [], declaredTypeIds, manifest.externalTaskTypes ?? []);
@@ -49,7 +74,7 @@ export async function scaffoldWorkers(opts) {
             ...manifest,
             workers: [...(manifest.workers ?? []), ...wired],
         };
-        await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, 2)}\n`);
+        await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, manifestIndent)}\n`);
         manifestPatched = true;
     }
     return { outcomes, skipped, wired, manifestPatched, write };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.77.2",
+	"version": "0.77.4",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -103,7 +103,7 @@
 		"@nanobpm/nano-sdk": "^1.2.5",
 		"@nanobpm/workflow": "^0.14.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
-		"create-urban-app": "^0.15.1",
+		"create-urban-app": "^0.15.2",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

package/src/runtime/core/modules/scheduler.test.ts

@@ -42,3 +42,108 @@ test("schedulerClock.wait clamps non-positive / non-finite delays to the current
   await schedulerClock(sched).wait(Number.POSITIVE_INFINITY);
   assert.deepEqual(sched.delays, [0, 0, 0]);
 });
+
+// Regression (issue #446 follow-up): a handler parked on `app.wait()` sits on a (virtual) timer that
+// no clock advance fires during teardown, so whoever awaits it — the test kit's `engine.close()` —
+// hangs forever. `schedulerClock().wait()` now honours an optional shutdown `signal`: a mid-wait
+// abort disarms the armed timer and rejects, so the parked handler unwinds at teardown. The live
+// scheduler supplies no signal, so this is wholly inert in production.
+test("schedulerClock.wait disarms its timer and rejects when the shutdown signal aborts mid-wait", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  let armed: (() => void) | undefined;
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: (fn) => {
+      armed = fn;
+      return 42;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  const waiting = schedulerClock(sched).wait(10_000);
+  assert.equal(typeof armed, "function", "wait must arm a timer while not aborted");
+  controller.abort(new Error("engine shutting down"));
+  await assert.rejects(waiting, /engine shutting down/, "an aborted wait must reject with the signal's reason");
+  assert.deepEqual(cleared, [42], "the armed timer must be cleared on abort so it cannot fire later");
+});
+
+test("schedulerClock.wait rejects immediately (arming no timer) when the signal is already aborted", async () => {
+  const controller = new AbortController();
+  controller.abort(new Error("already shutting down"));
+  let armedCount = 0;
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => {
+      armedCount += 1;
+      return 0;
+    },
+    clearTimer: () => {},
+  };
+  await assert.rejects(schedulerClock(sched).wait(1000), /already shutting down/);
+  assert.equal(armedCount, 0, "an already-aborted signal must reject without arming a timer");
+});
+
+// Regression (PR #447 review, scheduler.ts): this seam permits `setTimer` to fire its callback
+// SYNCHRONOUSLY (the `capturingScheduler` above does). When it does — and a shutdown `signal` is
+// present — the wait resolves before we would install the abort listener, so we must NOT install
+// one: attaching a listener to an already-settled promise leaks its closure until the signal fires
+// and later has shutdown clear an already-fired timer handle. A synchronously-resolved wait must
+// leave zero listeners on the signal and must not clear its (already-fired) handle on a later abort.
+test("schedulerClock.wait installs no abort listener when a signalled wait resolves synchronously", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: (fn) => {
+      fn(); // fire synchronously — the wait resolves before any listener could be installed
+      return 7;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  await schedulerClock(sched).wait(0);
+  // A leaked listener would fire here and clear the stale handle; the fix installs none.
+  controller.abort(new Error("shutting down"));
+  assert.deepEqual(cleared, [], "a synchronously-resolved wait must not install an abort listener");
+});
+// The abort reason is attacker/caller-controlled: guard the case where it is a bare value rather
+// than an Error so `wait()` still rejects with a generic teardown error instead of leaking it.
+test("schedulerClock.wait rejects with a generic teardown error when the abort reason is not an Error", async () => {
+  const controller = new AbortController();
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => 0,
+    clearTimer: () => {},
+  };
+  const waiting = schedulerClock(sched).wait(1000);
+  controller.abort("not-an-error");
+  await assert.rejects(waiting, /scheduler shutting down/);
+});
+
+// Regression (PR #447 review, scheduler.ts:108): `setTimer` is an injectable seam that may abort the
+// shutdown `signal` SYNCHRONOUSLY while arming, WITHOUT firing its callback (a re-entrant scheduler).
+// An abort event is not replayed to a listener added after the fact, so a wait that merely installed
+// its listener would hang forever — never rejecting, never clearing the armed timer. `wait()` must
+// re-check `signal.aborted` after installing the listener and drive the abort path by hand.
+test("schedulerClock.wait rejects (and clears its timer) when setTimer aborts the signal synchronously", async () => {
+  const controller = new AbortController();
+  const cleared: unknown[] = [];
+  const sched: SchedulerDeps = {
+    now: () => 0,
+    signal: controller.signal,
+    setTimer: () => {
+      controller.abort(new Error("aborted during setTimer"));
+      return 99;
+    },
+    clearTimer: (h) => cleared.push(h),
+  };
+  await assert.rejects(
+    schedulerClock(sched).wait(1000),
+    /aborted during setTimer/,
+    "a synchronous mid-arm abort must reject the wait, not leave it hanging",
+  );
+  assert.deepEqual(cleared, [99], "the armed timer must be cleared when the synchronous abort is handled");
+});

package/src/runtime/core/modules/scheduler.ts

@@ -10,6 +10,22 @@ export interface SchedulerDeps {
   clearTimer: (handle: unknown) => void;
   /** Current wall-clock time in ms since epoch. */
   now: () => number;
+  /** Optional shutdown signal. When it aborts, a pending {@link schedulerClock} `wait()` clears its
+   *  armed timer and rejects, so a handler parked on the (virtual) clock unwinds at teardown instead
+   *  of wedging whoever awaits it. Under the test kit this is the engine's shutdown signal: a worker
+   *  handler parked on `app.wait()` sits on a virtual timer that no `advanceTime` will fire during
+   *  `engine.close()`, so without this its promise never settles and `close()` hangs (the issue #446
+   *  follow-up — the virtual-timer sibling of the real-time use-after-free). Absent on the live
+   *  scheduler, where real timers always fire on wall-clock time, so `wait()` never rejects there. */
+  readonly signal?: AbortSignal;
+}
+
+/** The rejection surfaced to a `wait()` cancelled by a shutdown {@link SchedulerDeps.signal}: the
+ *  signal's `reason` when it is an {@link Error}, else a generic teardown error. Reusing the reason
+ *  keeps a caller's fail-loud message (e.g. "WasmEngineClient closing") intact. */
+function schedulerAbortError(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason;
+  return reason instanceof Error ? reason : new Error("app.wait aborted: scheduler shutting down");
 }
 
 /** Max delay a single `setTimeout` honours before its 32-bit signed overflow (~24.8 days). */
@@ -58,9 +74,47 @@ export function schedulerClock(sched: SchedulerDeps): AppClock {
   return {
     now: () => sched.now(),
     wait: (ms) =>
-      new Promise<void>((resolve) => {
+      new Promise<void>((resolve, reject) => {
+        const signal = sched.signal;
+        // Already shutting down: reject immediately rather than arm a timer that would outlive the
+        // teardown (and, under the virtual clock, never fire).
+        if (signal?.aborted) {
+          reject(schedulerAbortError(signal));
+          return;
+        }
         const delay = Number.isFinite(ms) && ms > 0 ? Math.min(ms, MAX_TIMER_DELAY_MS) : 0;
-        sched.setTimer(() => resolve(), delay);
+        let settled = false;
+        let onAbort: (() => void) | undefined;
+        const handle = sched.setTimer(() => {
+          settled = true;
+          if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+          resolve();
+        }, delay);
+        // When a shutdown signal is present, a mid-wait abort disarms the timer and rejects, so a
+        // handler parked here unwinds at teardown instead of wedging its awaiter. Inert (no listener,
+        // no behaviour change) on the live scheduler, which supplies no signal.
+        //
+        // `settled` guards the synchronous-timer case: this seam permits `setTimer` to invoke its
+        // callback synchronously (the test `capturingScheduler` does exactly that), which resolves
+        // the wait *before* we get here. Installing an abort listener on that already-settled promise
+        // would leak its closure until the signal fires (and have shutdown clear an already-fired
+        // handle), so skip it entirely when the callback already ran.
+        if (signal && !settled) {
+          onAbort = () => {
+            sched.clearTimer(handle);
+            reject(schedulerAbortError(signal));
+          };
+          signal.addEventListener("abort", onAbort, { once: true });
+          // Re-entrant seam: `setTimer` above is injectable and may abort `signal` *synchronously*
+          // without firing the timer callback (so `settled` is still false). An abort event is not
+          // replayed to a listener added after the fact, so the listener just registered would never
+          // run and the wait would hang until the runner timeout. Re-check and drive the abort path
+          // by hand — removing the (now-inert) listener first so it cannot also fire and double-reject.
+          if (signal.aborted && !settled) {
+            signal.removeEventListener("abort", onAbort);
+            onAbort();
+          }
+        }
       }),
   };
 }

package/src/toolkit/addConnector.test.ts

@@ -67,6 +67,24 @@ test("addConnector wires a pack-backed worker + a connection into nano.app.json"
   });
 });
 
+test("addConnector preserves the manifest's existing indentation (no lint reformat)", async () => {
+  // Regression (nano-ide#454): the scaffold's Biome config formats nano.app.json with tabs, so a
+  // hard-coded 2-space rewrite here would turn `npm run lint` red the moment a connector is
+  // enabled in a fresh app. addConnector must round-trip the manifest's own indentation, like
+  // `urban gen` does via detectJsonIndent.
+  const tabManifest = `${JSON.stringify({ schemaVersion: 1, id: "t", name: "T" }, null, "\t")}\n`;
+  const io = memIO({ ...baseFiles(), "app/nano.app.json": tabManifest });
+  await addConnector({ root: "app", pkg: PKG, io });
+  const written = io.files["app/nano.app.json"];
+  assert.match(written, /\n\t"workers"/, "tab indentation is preserved");
+  assert.doesNotMatch(written, /\n {2}"workers"/, "no 2-space indentation was introduced");
+
+  const twoSpace = `${JSON.stringify({ schemaVersion: 1, id: "t", name: "T" }, null, 2)}\n`;
+  const io2 = memIO({ ...baseFiles(), "app/nano.app.json": twoSpace });
+  await addConnector({ root: "app", pkg: PKG, io: io2 });
+  assert.match(io2.files["app/nano.app.json"], /\n {2}"workers"/, "2-space indentation is preserved");
+});
+
 test("addConnector is idempotent — re-running does not duplicate entries", async () => {
   const io = memIO(baseFiles());
   await addConnector({ root: "app", pkg: PKG, io });

package/src/toolkit/addConnector.ts

@@ -14,6 +14,7 @@
 
 import type { GenIO } from "./gen.ts";
 import { errorMessage, isRecord } from "../runtime/core/guards.ts";
+import { detectJsonIndent } from "./scaffold.ts";
 
 /** A config field a pack declares (subset of ext-types `ConfigField`). */
 interface PackConfigField {
@@ -116,13 +117,15 @@ export async function addConnector(opts: AddConnectorOptions): Promise<AddConnec
   if (!(await io.exists(appManifestPath))) {
     throw new Error(`no ${manifestFile} at ${appManifestPath} — run this inside an Urban app.`);
   }
+  let appRaw: string;
   let app: {
     workers?: { taskType?: string; connector?: string; connection?: string; handler?: string; llm?: string }[];
     connections?: Record<string, Record<string, unknown>>;
     [k: string]: unknown;
   };
   try {
-    app = JSON.parse(await io.readText(appManifestPath));
+    appRaw = await io.readText(appManifestPath);
+    app = JSON.parse(appRaw);
   } catch (err) {
     throw new Error(`failed to parse ${appManifestPath}: ${errorMessage(err)}`);
   }
@@ -223,7 +226,10 @@ export async function addConnector(opts: AddConnectorOptions): Promise<AddConnec
     wired.push({ taskType: spec.type, alreadyPresent: false });
   }
 
-  await io.writeText(appManifestPath, JSON.stringify(app, null, 2) + "\n");
+  // Preserve the manifest's own indentation (default tab, matching the scaffold's Biome config)
+  // so enabling a connector never reformats nano.app.json out from under `npm run lint` — the same
+  // fidelity `urban gen` gives via detectJsonIndent, kept as the single source of truth.
+  await io.writeText(appManifestPath, `${JSON.stringify(app, null, detectJsonIndent(appRaw))}\n`);
 
   return {
     packId: pack.id,

package/src/toolkit/derivers/generated-lint.test.ts

@@ -149,7 +149,7 @@ function lintUnderScaffold(
   biomeBin: string,
   dirs: string[],
 ): { status: number | null; stdout: string; stderr: string } {
-  const templateBiome = JSON.parse(readFileSync(join(templateDir, "biome.json"), "utf8"));
+  const templateBiome = JSON.parse(readFileSync(join(templateDir, "_biome.json"), "utf8"));
   // Copy the scaffold's GritQL plugin (bans `as` assertions) next to the config so its relative
   // path resolves, then reuse the template's exact ruleset — force-scoped to the generated dirs so
   // the guard tracks the scaffold standard without depending on the template's own `includes`.
@@ -320,7 +320,7 @@ function lintWithTemplateConfigVerbatim(
   templateDir: string,
   biomeBin: string,
 ): { status: number | null; stdout: string; stderr: string } {
-  const templateBiome = JSON.parse(readFileSync(join(templateDir, "biome.json"), "utf8"));
+  const templateBiome = JSON.parse(readFileSync(join(templateDir, "_biome.json"), "utf8"));
   cpSync(join(templateDir, "plugins"), join(work, "plugins"), { recursive: true });
   const config = { ...templateBiome, $schema: undefined, root: true };
   writeFileSync(join(work, "biome.json"), `${JSON.stringify(config, null, "\t")}\n`);

package/src/toolkit/scaffold/operations.test.ts

@@ -34,6 +34,49 @@ test("renderOperationStub adjusts the generated-import depth for a nested api.di
   assert.match(stub, /import \{ defineOperation \} from "\.\.\/\.\.\/nano-generated\/operations\.ts";/);
 });
 
+test("operation stub is lint-clean under the scaffold config: tab-indented, both params referenced", () => {
+  // Guards the same two failure modes as the worker stub (nano-ide#454): the scaffold's Biome
+  // config formats with tabs and enables correctness/noUnusedFunctionParameters, so a
+  // space-indented body or an unused `input`/`app` makes a freshly generated operation fail the
+  // app's own `biome check`. Body lines must be tab-indented and both params read before the
+  // author fills in the body.
+  const stub = renderOperationStub("getInvoice");
+  const bodyLines = stub
+    .split("\n")
+    .filter((l) => l.startsWith(" ") || l.startsWith("\t"));
+  assert.ok(bodyLines.length > 0, "the stub has an indented body");
+  for (const line of bodyLines) {
+    assert.ok(line.startsWith("\t"), `body line is tab-indented, not space-indented: ${line}`);
+  }
+  assert.match(
+    stub,
+    /app\.log\.warn\("operation not implemented", \{\n\t\toperationId: "getInvoice",\n\t\tmethod: input\.req\.method,\n\t\}\);/,
+  );
+  // Guard the same Biome-width defect class the reviewer flagged (nano-ide#454): the generated
+  // stub is linted by the scaffold's `operations/**/*.ts` include at Biome's default 80-column
+  // width (tab = 2 columns), so a single-line log call that overruns 80 makes `urban gen` emit a
+  // file `biome check` immediately reports as needing formatting. Assert every non-comment code
+  // line fits, so any future template change that reintroduces an over-wide line fails here.
+  for (const line of stub.split("\n")) {
+    if (line.trim().startsWith("//")) continue;
+    const leadingTabs = line.length - line.replace(/^\t+/, "").length;
+    const width = leadingTabs * 2 + (line.length - leadingTabs);
+    assert.ok(width <= 80, `generated code line exceeds Biome's 80-column width (${width}): ${line}`);
+  }
+  // Guard the PII/credential-leak defect class (nano-ide#454): the stub must reference a
+  // non-sensitive identifier, never serialize the whole validated `input` (which carries
+  // params/query/body/req) into the NDJSON log line.
+  assert.doesNotMatch(stub, /app\.log\.warn\([^)]*,\s*input\s*\}/);
+});
+
+test("operation stub logs a non-sensitive identifier, not the raw input payload", () => {
+  // Red/Green guard for the operation-stub log-leak: an unedited 501 handler must not emit the
+  // validated request body/params/query (potential credentials or PII) to structured logs.
+  const stub = renderOperationStub("createInvoice");
+  assert.doesNotMatch(stub, /,\s*input\s*\}\)/);
+  assert.match(stub, /method: input\.req\.method/);
+});
+
 test("planOperationScaffold plans one stub per declared operationId", () => {
   const plans = planOperationScaffold(doc);
   const byId = Object.fromEntries(plans.map((p) => [p.operationId, p.handlerPath]));

package/src/toolkit/scaffold/operations.ts

@@ -44,16 +44,21 @@ export function renderOperationStub(operationId: string, dir: string = DEFAULT_O
     `// (ADR 0059). This file is yours to edit — \`urban gen\` will never overwrite it. The\n` +
     `// generated controller (nano-generated/controller.ts) imports this default export and\n` +
     `// type-checks it against the spec, so the signature cannot drift. Implement the body below\n` +
-    `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`) and delete the throw.\n` +
+    `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`), replacing the\n` +
+    `// guard warn + throw.\n` +
     `import { NotImplemented } from "@nanobpm/urban";\n` +
     `import { defineOperation } from ${JSON.stringify(`${up}nano-generated/operations.ts`)};\n` +
     `\n` +
     `export default defineOperation(${key}, async (input, app) => {\n` +
-    `  // \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
-    `  // through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
-    `  // auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
-    `  // Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
-    `  throw new NotImplemented(${key});\n` +
+    `\t// \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
+    `\t// through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
+    `\t// auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
+    `\t// Return \`{ status?, headers?, body? }\` (or nothing → 204). Replace the two lines below.\n` +
+    `\tapp.log.warn("operation not implemented", {\n` +
+    `\t\toperationId: ${key},\n` +
+    `\t\tmethod: input.req.method,\n` +
+    `\t});\n` +
+    `\tthrow new NotImplemented(${key});\n` +
     `});\n`
   );
 }

package/src/toolkit/scaffold/workers.test.ts

@@ -7,7 +7,7 @@ import {
   type ScaffoldWorker,
 } from "./workers.ts";
 import type { ModelSource } from "../derivers/worker-io.ts";
-import { scaffoldWorkers } from "../scaffold.ts";
+import { detectJsonIndent, scaffoldWorkers } from "../scaffold.ts";
 import type { GenIO } from "../gen.ts";
 
 // A service task with a data-envelope in/out contract; `type` is the taskType, and the
@@ -53,6 +53,43 @@ test("untyped stub imports no generated types and uses bare AppJobHandler", () =
   assert.match(stub, /const handler: AppJobHandler = async \(job, app\) =>/);
 });
 
+test("stub is lint-clean under the scaffold config: tab-indented, both params referenced", () => {
+  // Guards the two ways `urban gen`'s stub used to fail a fresh scaffold's own `biome check`
+  // (nano-ide#451): space indentation (Biome defaults to tabs) and unused `job`/`app` params
+  // (correctness/noUnusedFunctionParameters). Body lines must be tab-indented and both params
+  // must be read before the author fills in the body.
+  const stub = renderWorkerStub("greet.hello", false, false);
+  const bodyLines = stub.split("\n").filter((l) => l.startsWith(" ") || l.startsWith("\t"));
+  assert.ok(bodyLines.length > 0, "the stub has an indented body");
+  for (const line of bodyLines) {
+    assert.ok(line.startsWith("\t"), `body line is tab-indented, not space-indented: ${line}`);
+  }
+  assert.match(stub, /app\.log\.warn\("worker not implemented", \{ jobKey: job\.jobKey \}\)/);
+});
+
+test("detectJsonIndent reuses tab/space width but clamps to JSON.stringify's 10-char cap", () => {
+  assert.equal(detectJsonIndent('{\n\t"a": 1\n}'), "\t");
+  assert.equal(detectJsonIndent('{\n  "a": 1\n}'), "  ");
+  assert.equal(detectJsonIndent("{}"), "\t", "no indentation falls back to a tab");
+  // JSON.stringify silently truncates a string `space` to 10 chars, so a wider space indent must
+  // be clamped rather than promising a fidelity the serializer cannot honor.
+  const wide = `{\n${" ".repeat(12)}"a": 1\n}`;
+  const indent = detectJsonIndent(wide);
+  assert.equal(indent, " ".repeat(10));
+  assert.equal(JSON.stringify({ a: 1 }, null, indent), JSON.stringify({ a: 1 }, null, wide.match(/\n( +)/)?.[1]));
+  // The 10-char cap is not space-only: an overlong *tab* indent must clamp too, or the rewrite
+  // would silently differ from an 11+-tab input (JSON.stringify truncates any string `space`).
+  const wideTabs = `{\n${"\t".repeat(12)}"a": 1\n}`;
+  const tabIndent = detectJsonIndent(wideTabs);
+  assert.equal(tabIndent, "\t".repeat(10));
+  assert.equal(JSON.stringify({ a: 1 }, null, tabIndent), JSON.stringify({ a: 1 }, null, wideTabs.match(/\n(\t+)/)?.[1]));
+  // Line-ending agnostic: the width must be detected regardless of terminator, or a space-indented
+  // Windows/old-Mac manifest would be rewritten at the tab fallback width instead of preserved.
+  assert.equal(detectJsonIndent('{\r\n  "a": 1\r\n}'), "  ", "CRLF space indent preserved");
+  assert.equal(detectJsonIndent('{\r  "a": 1\r}'), "  ", "bare-CR space indent preserved");
+  assert.equal(detectJsonIndent('{\n\r  "a": 1\n\r}'), "  ", "LFCR space indent preserved");
+});
+
 test("typed-out-only stub fills In with the open default", () => {
   const stub = renderWorkerStub("demo.out", false, true);
   assert.match(stub, /import type \{ WorkerOutputs \} from/);
@@ -183,6 +220,21 @@ test("scaffoldWorkers --write creates the stub and patches the manifest once", a
   assert.ok(io.files["/app/nano.app.json"].endsWith("\n"), "manifest ends with newline");
 });
 
+test("scaffoldWorkers preserves the manifest's own indentation when wiring (nano-ide#451)", async () => {
+  // `urban gen` used to reserialize nano.app.json with a hard-coded 2-space indent, clobbering
+  // the tab-indented scaffold and breaking its own `biome check`. The patch must round-trip the
+  // file's existing indentation instead.
+  for (const indent of ["\t", "  "]) {
+    const files = appFixture();
+    files["/app/nano.app.json"] = `${JSON.stringify(JSON.parse(files["/app/nano.app.json"]), null, indent)}\n`;
+    const io = memIO(files);
+    await scaffoldWorkers({ root: "/app", io, write: true });
+    const patched = io.files["/app/nano.app.json"];
+    const firstIndent = patched.match(/\n([ \t]+)\S/)?.[1];
+    assert.equal(firstIndent, indent, `indentation preserved (${JSON.stringify(indent)})`);
+  }
+});
+
 test("scaffoldWorkers never clobbers an existing stub (keeps it), still wires it", async () => {
   const files = appFixture();
   files["/app/workers/t-new/worker.ts"] = "// hand-edited, do not touch\n";

package/src/toolkit/scaffold/workers.ts

@@ -87,23 +87,28 @@ export function renderWorkerStub(
   else if (typedOut) generic = `<Record<string, unknown>, WorkerOutputs[${key}]>`;
 
   const varsNote = typedIn
-    ? `  // \`job.variables\` is typed as WorkerInputs[${key}].`
-    : `  // \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
+    ? `\t// \`job.variables\` is typed as WorkerInputs[${key}].`
+    : `\t// \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
 
+  // The stub arrives lint-clean under the scaffold's own Biome config: tab-indented, and
+  // referencing both `job` and `app` (via the warn line) so `noUnusedFunctionParameters`
+  // does not fire before the author has filled in the body.
   return (
     `// Handler stub for the \`${taskType}\` service task, scaffolded from the model (ADR 0056).\n` +
     `// This file is yours to edit — \`urban gen\` will never overwrite it. Implement the body\n` +
-    `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
+    `// below (use \`app.data.table(...)\` for state), replacing the guard warn + throw so the\n` +
+    `// "worker not implemented" warning does not survive into a working handler.\n` +
     `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
     generatedImport +
     `\n` +
     `const handler: AppJobHandler${generic} = async (job, app) => {\n` +
     varsNote +
     `\n` +
-    `  // Reach app state and services through the injected \`app\` API.\n` +
-    `  // Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
-    `  // { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
-    `  throw new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
+    `\t// Reach app state and services through the injected \`app\` API.\n` +
+    `\t// Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
+    `\t// { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
+    `\tapp.log.warn("worker not implemented", { jobKey: job.jobKey });\n` +
+    `\tthrow new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
     `};\n` +
     `\n` +
     `export default handler;\n`

package/src/toolkit/scaffold.ts

@@ -14,6 +14,27 @@ import {
 import { planOperationScaffold } from "./scaffold/operations.ts";
 import { parseSpec } from "../openapi/spec.ts";
 
+/**
+ * Detect the indentation of a JSON document from its first indented line, so a rewrite can
+ * reuse it (`"\t"` or an N-space string) instead of hard-coding one style. Falls back to a tab
+ * — the scaffold's Biome default — when the file is empty/single-line or uses no indentation.
+ *
+ * Any indent — spaces or tabs — is clamped to 10 characters because `JSON.stringify` silently
+ * truncates a string `space` argument to 10; returning a wider prefix would promise a fidelity the
+ * serializer cannot honor (e.g. an 11+-tab manifest would be rewritten at a different width than
+ * its input). Tab indentation (the scaffold default) and any realistic width (2/4 spaces) are
+ * unaffected.
+ */
+export function detectJsonIndent(json: string): string {
+  // Anchor on any line terminator, not just `\n`, so the width is detected regardless of the
+  // manifest's line endings: LF (`\n`), CRLF (`\r\n`, where `\n` already precedes the indent),
+  // bare-CR old-Mac (`\r`), and LFCR (`\n\r`) all resolve to the indentation that follows.
+  const m = json.match(/[\r\n]([ \t]+)\S/);
+  if (!m) return "\t";
+  const indent = m[1];
+  return indent.length > 10 ? indent.slice(0, 10) : indent;
+}
+
 /** The manifest fields the scaffolder reads. */
 interface ScaffoldManifest {
   types?: Record<string, unknown>;
@@ -61,7 +82,11 @@ export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRu
   const manifestFile = opts.manifestFile ?? "nano.app.json";
   const manifestPath = joinPath(root, manifestFile);
 
-  const manifest: ScaffoldManifest = JSON.parse(await io.readText(manifestPath));
+  const manifestRaw = await io.readText(manifestPath);
+  const manifest: ScaffoldManifest = JSON.parse(manifestRaw);
+  // Preserve the manifest's own indentation when we patch it back (default tab, matching the
+  // scaffold's Biome config), so wiring a worker never reformats the file out from under lint.
+  const manifestIndent = detectJsonIndent(manifestRaw);
   const models = await readModels(root, io, manifest);
   const declaredTypeIds = Object.keys(manifest.types ?? {});
 
@@ -105,7 +130,7 @@ export async function scaffoldWorkers(opts: ScaffoldOptions): Promise<ScaffoldRu
       ...manifest,
       workers: [...(manifest.workers ?? []), ...wired],
     };
-    await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, 2)}\n`);
+    await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, manifestIndent)}\n`);
     manifestPatched = true;
   }