@nanobpm/urban 0.48.0 → 0.49.0

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

@@ -1,7 +1,19 @@
-// deploy — resolve the manifest `models` patterns and deploy the resources to the engine,
-// substituting any `{{name}}` templates into each resource first (see templates.ts).
-import { expandPatterns } from "../glob.js";
-import { applyTemplates, resolveTemplates } from "./templates.js";
+// deploy — resolve the app's deployable resources and send them to the engine.
+//
+// Resources are found by ONE of two paths:
+//   1. Convention (the default, ADR 0062): when the manifest declares no `models`, deployables are
+//      discovered by walking `resources/` — shallow, one level deep. `resources/` is deploy-only:
+//      everything under it (and nothing outside it) is deployed. Docs (`docs/`, `AGENTS.md`,
+//      top-level `*.md`) live outside `resources/` and are never swept in.
+//   2. Explicit override: when the manifest declares `models` globs, those are used exactly (the
+//      convention walk is skipped) — the escape hatch for a non-convention layout.
+//
+// Either way the deploy dedupe key is the resource's basename (filename only), so a basename
+// collision — two files with the same name in different directories — would silently clobber one
+// resource with another at the engine. We detect that up front and fail loudly instead.
+import { discoverResources, expandPatterns } from "../glob.js";
+/** The convention directory: deploy-only, walked one level deep when no `models` are declared. */
+export const RESOURCES_DIR = "resources";
 function contentTypeFor(path) {
     if (path.endsWith(".bpmn"))
         return "text/xml";
@@ -15,45 +27,65 @@ function baseName(path) {
     const i = path.lastIndexOf("/");
     return i >= 0 ? path.slice(i + 1) : path;
 }
-/** Deploy all processes, decisions and forms declared under `models`. Each resource has its
- *  `{{name}}` placeholders substituted (manifest `models.templates`, then the programmatic
- *  `ctx.templates`, the latter winning) before it is sent to the engine. */
+/** Fail loudly when two resolved files share a basename (the deploy dedupe key), naming the
+ *  colliding paths so the author can rename or relocate one. */
+function assertNoBasenameCollisions(files) {
+    const byName = new Map();
+    for (const path of files) {
+        const name = baseName(path);
+        const list = byName.get(name);
+        if (list)
+            list.push(path);
+        else
+            byName.set(name, [path]);
+    }
+    const collisions = [...byName.entries()].filter(([, paths]) => paths.length > 1);
+    if (collisions.length === 0)
+        return;
+    const detail = collisions
+        .map(([name, paths]) => `  ${name}: ${paths.slice().sort().join(", ")}`)
+        .join("\n");
+    throw new Error("deploy: basename collision — resources are deployed keyed by filename, so two files with " +
+        `the same name would clobber each other. Rename or relocate one of:\n${detail}`);
+}
+/**
+ * Deploy the app's processes, decisions and forms.
+ *
+ * With no manifest `models`, deployables are discovered by convention under `resources/` (shallow,
+ * one level deep). With `models` globs declared, those are used verbatim. Basename collisions are a
+ * hard error in either mode.
+ */
 export async function deployModels(ctx) {
-    const models = ctx.manifest.models ?? {};
+    const models = ctx.manifest.models;
     const patterns = [
-        ...(models.processes ?? []),
-        ...(models.decisions ?? []),
-        ...(models.forms ?? []),
+        ...(models?.processes ?? []),
+        ...(models?.decisions ?? []),
+        ...(models?.forms ?? []),
     ];
-    const files = await expandPatterns(ctx.host, ctx.root, patterns);
+    // Convention is keyed off the *absence* of the `models` block, not an empty pattern set: a
+    // declared `models` (even one resolving to zero files) is an explicit override that must NOT
+    // silently fall back to the `resources/` walk (ADR 0062: "no `models` block → convention;
+    // `models` present → exact override").
+    const byConvention = models === undefined;
+    const files = byConvention
+        ? await discoverResources(ctx.host, ctx.root, RESOURCES_DIR)
+        : await expandPatterns(ctx.host, ctx.root, patterns);
     if (files.length === 0) {
-        ctx.host.log("info", "deploy: no model files matched", { patterns });
+        if (byConvention) {
+            ctx.host.log("info", "deploy: no resources found by convention", { dir: RESOURCES_DIR });
+        }
+        else {
+            ctx.host.log("info", "deploy: no model files matched", { patterns });
+        }
         return { deployed: 0, files: [] };
     }
-    // Resolve templates once (manifest globs/dirs, then the programmatic deploy option). An empty
-    // map makes substitution a no-op, so apps that use no templates are unaffected.
-    const templates = await resolveTemplates(ctx.host, ctx.root, [models.templates, ctx.templates]);
-    const hasTemplates = Object.keys(templates).length > 0;
-    const resources = await Promise.all(files.map(async (path) => {
-        const contentType = contentTypeFor(path);
-        let content = await ctx.host.readTextFile(path);
-        // Only substitute into the model content types we know how to escape (XML for .bpmn/.dmn,
-        // JSON for .form). Unknown extensions map to application/octet-stream; running the default
-        // XML escaper over them could deterministically corrupt a non-XML/JSON resource that a
-        // manifest pattern matched by accident, so leave those files untouched.
-        if (hasTemplates && contentType !== "application/octet-stream") {
-            const applied = applyTemplates(content, contentType, templates);
-            content = applied.content;
-            if (applied.unresolved.length > 0) {
-                ctx.host.log("warn", "deploy: unresolved template placeholders", {
-                    file: path,
-                    unresolved: applied.unresolved,
-                });
-            }
-        }
-        return { name: baseName(path), content, contentType };
-    }));
+    assertNoBasenameCollisions(files);
+    const resources = await Promise.all(files.map(async (path) => ({
+        name: baseName(path),
+        content: await ctx.host.readTextFile(path),
+        contentType: contentTypeFor(path),
+    })));
     const { deployed } = await ctx.engine.deployResources(resources);
-    ctx.host.log("info", "deploy: models deployed", { deployed, files });
+    ctx.host.log("info", "deploy: resources deployed", { deployed, files, byConvention });
     return { deployed, files };
 }

package/dist/runtime/core/modules/instance-tracking.d.ts

@@ -1,5 +1,5 @@
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
-import type { InstanceTracking } from "../manifest.ts";
+import { type InstanceTracking } from "../manifest.ts";
 import { type SchedulerDeps } from "./scheduler.ts";
 /** Default poll interval when a binding does not set `pollMs`. */
 export declare const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15000;

package/dist/runtime/core/modules/instance-tracking.js

@@ -12,6 +12,7 @@
 // — and never on `COMPLETED`, whose terminal row-write the app's own finalize worker owns
 // (reconciling it here would race that worker and could clobber a legitimately-completed
 // row). The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
+import { isConfiguredStatusSelector } from "../manifest.js";
 import { defaultScheduler, MAX_TIMER_DELAY_MS } from "./scheduler.js";
 /** Default poll interval when a binding does not set `pollMs`. */
 export const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15_000;
@@ -44,13 +45,27 @@ export async function reconcileTerminatedKey(api, bindings, processInstanceKey)
  *  scanned and how many rows were reconciled this tick. */
 async function reconcileOnce(api, binding) {
     const table = api.data.table(binding.table, binding.keyField);
-    // Select the rows worth polling. With a statusField + activeStatuses, only rows in an
-    // active status are candidates, so a row already in a terminal status is skipped; without
-    // them every row is polled and a terminal instance's row is idempotently re-patched (the
-    // engine query returns only TERMINATED instances and the patch is a no-op once applied).
+    // Select the rows worth polling. Three modes, in precedence order:
+    //  - `terminalStatuses` (fail-open exclusion): poll every row whose `statusField` is NOT
+    //    a terminal value. A newly-added non-terminal status is polled by default, so it can't
+    //    silently fall out of reconciliation; only already-terminal rows are excluded (bounded).
+    //  - `activeStatuses` (fail-closed allow-list): poll only rows in an enumerated active status.
+    //  - neither: poll every row; a terminal instance's row is idempotently re-patched (the engine
+    //    query returns only TERMINATED instances and the patch is a no-op once applied).
+    // `terminalStatuses` and `activeStatuses` are mutually exclusive per binding (validation rejects
+    // both); if both are somehow present, `terminalStatuses` wins (the fail-open selector). Each
+    // selector is gated through the shared `isConfiguredStatusSelector` predicate (a non-empty array
+    // of non-empty strings) — the same one validation uses — so a malformed value (a bare string, an
+    // empty array) degrades to the fail-open poll-all path here instead of `new Set("abandoned")`
+    // silently filtering by character, or a non-array crashing `activeStatuses.map(...)`.
     let candidates;
     const statusField = binding.statusField;
-    if (statusField && binding.activeStatuses && binding.activeStatuses.length > 0) {
+    if (statusField && isConfiguredStatusSelector(binding.terminalStatuses)) {
+        const terminal = new Set(binding.terminalStatuses);
+        const all = await table.all();
+        candidates = all.filter((row) => !terminal.has(String(row[statusField])));
+    }
+    else if (statusField && isConfiguredStatusSelector(binding.activeStatuses)) {
         const perStatus = await Promise.all(binding.activeStatuses.map((s) => table.find({ [statusField]: s })));
         candidates = perStatus.flat();
     }

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

@@ -513,6 +513,9 @@ table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
 .pc-badge-warn { background:var(--nano-warn); color:#3a2a00; }
 .pc-badge-ok { background:var(--nano-ok); }
 .pc-badge-info { background:var(--nano-info); }
+/* Live row-count pill (dataGrid showCount): a subtle, neutral count distinct from
+   the coloured status badges, legible in the collapse header while collapsed. */
+.pc-count-badge { color:var(--nano-text); background:var(--nano-inset); border:1px solid var(--nano-edge); font-weight:600; }
 :root[data-appearance="light"] .pc-badge-warn { color:#fff; }
 @media (prefers-color-scheme: light) { :root:not([data-appearance]) .pc-badge-warn { color:#fff; } }
 .pc-child { margin:.6rem 0; }
@@ -1214,10 +1217,25 @@ function renderActionForm(node) {
   return card;
 }
 
+// Accessible name for the row-count badge. The visible text is just a number, so an
+// aria-label would override it with a bare "row count" (the count — the important part —
+// is dropped). Instead name it "N row(s)" and keep it in sync with the text on refresh.
+// Single source of truth for both the initial render and every refresh below.
+function rowCountLabel(n) { return n + (n === 1 ? " row" : " rows"); }
+
 function renderDataGrid(node) {
   const p = node.props;
   const card = el("section", { class: "pc-card" });
-  if (p.title) card.append(el("h2", {}, p.title));
+  // Opt-in live row-count badge ("showCount"). Rendered inside the <h2> so a plain
+  // (non-collapsible) grid surfaces it beside the title; makeCollapsible re-homes it
+  // into the collapse header so it stays visible — and refresh-updated — while the
+  // section is collapsed. refresh() below rewrites its text on every poll/pc:refresh.
+  const countBadge = p.showCount ? el("span", { class: "pc-badge pc-count-badge", "aria-label": rowCountLabel(0) }, "0") : null;
+  if (p.title || countBadge) {
+    const h2 = el("h2", {}, p.title || "");
+    if (countBadge) { if (p.title) h2.append(" "); h2.append(countBadge); }
+    card.append(h2);
+  }
   const cols = p.columns || [];
   const tabs = p.tabs || [];
   const rowActions = p.rowActions || [];
@@ -1535,6 +1553,10 @@ function renderDataGrid(node) {
       const { rows } = paramScoped && PARAM === ""
         ? { rows: [] }
         : await getJSON(dataUrl(p.data.source, p.data.table, activeFilter, p.data.orderBy));
+      // Live row-count badge: reflect the currently-fetched, filtered (active-tab)
+      // set — exactly what the body renders — on every refresh (poll + pc:refresh),
+      // whether the section is expanded or collapsed.
+      if (countBadge) { countBadge.textContent = String(rows.length); countBadge.setAttribute("aria-label", rowCountLabel(rows.length)); }
       // Forget expansion / cached detail nodes for rows no longer present so the maps
       // don't grow without bound and a stale answer can't resurface on a key reuse.
       if (p.rowKey) {
@@ -1703,7 +1725,16 @@ function makeCollapsible(node, card) {
   const isCard = card.tagName === "SECTION";
   const container = isCard ? card : el("section", { class: "pc-card" });
   const h2 = isCard && card.querySelector ? card.querySelector("h2") : null;
-  const titleText = props.title || (h2 ? h2.textContent : "") || "Section";
+  // A dataGrid with "showCount" renders a live count badge inside its <h2>. Lift it
+  // out before deriving the title (so the count doesn't leak into the label text),
+  // then re-home it in the header alongside the title so it stays visible — and
+  // refresh-updated by the grid's own refresh() — while the section is collapsed.
+  const countBadge = h2 && h2.querySelector ? h2.querySelector(".pc-count-badge") : null;
+  if (countBadge) countBadge.remove();
+  // Trim the derived label: after the badge is lifted out, the leftover " " whitespace
+  // node from h2.append(" ", countBadge) would otherwise make a title-less section's
+  // header a lone space (and leak whitespace into the storage key). Fall back to "Section".
+  const titleText = props.title || (h2 ? h2.textContent.trim() : "") || "Section";
   if (h2) h2.remove();
   const body = el("div", { class: "pc-card-body" });
   if (isCard) {
@@ -1718,6 +1749,7 @@ function makeCollapsible(node, card) {
     chevron,
     el("span", { class: "pc-collapse-title" }, titleText),
   );
+  if (countBadge) header.append(countBadge);
   const storageKey = "pc:collapsed:" + CURRENT + ":" + (node.id || titleText);
   let collapsed = readCollapsed(storageKey, !!props.defaultCollapsed);
   function apply() {

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

@@ -1,8 +1,13 @@
 // surfaces — the hosted human surfaces (ADR 0026). Implements the `taskInbox` surface: a
-// small JSON+HTML task list backed by the engine's user-task search, that renders the
-// linked `.form` and posts completion back. The `chat` surface is stubbed as a mount point
-// (LLM wiring is a separate concern). Surfaces contribute routes to the shared server.
-import { html, json, normalizeRoutePath } from "../router.js";
+// small JSON+HTML task list backed by the engine's user-task search. Each open task links to
+// its deployed `.form` via the engine-resolved `formKey`; the list fetches that form's form-js
+// schema (`GET base/api/form`), renders its fields client-side with a minimal built-in
+// renderer, and posts the entered field values as the completion `variables` (`POST
+// base/api/complete`). A task with no linked form keeps the bare key-list + raw-complete
+// behavior. The `chat` surface is stubbed as a mount point (LLM wiring is a separate concern).
+// Surfaces contribute routes to the shared server.
+import { presentFormIdentifier } from "../host.js";
+import { html, json, noContent, normalizeRoutePath } from "../router.js";
 import { mountActions } from "./actions.js";
 import { mountApi } from "./api.js";
 import { mountPages } from "./pages.js";
@@ -10,23 +15,169 @@ import { mountPages } from "./pages.js";
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 }
-function inboxPage(basePath) {
+function inboxPage() {
+    // Reverse-proxy safe: the client derives its API base from location.pathname
+    // (where THIS page was actually served) rather than an embedded absolute
+    // route base. A hardcoded "/tasks" would escape the Nano console's
+    // path-prefixed proxy (/console/app-view/<name>/tasks) — the API fetches must
+    // inherit that prefix. Deriving from location also removes the manifest→
+    // <script> injection surface entirely: nothing manifest-supplied is embedded.
+    // All task/form values are rendered via textContent / setAttribute — never
+    // innerHTML — so nothing the engine returns can inject markup.
     return `<!doctype html><meta charset="utf-8"><title>Task inbox</title>
 <style>body{font:14px system-ui,sans-serif;margin:2rem;max-width:52rem}
-li{margin:.4rem 0}code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px}</style>
+ul{list-style:none;padding:0}li{margin:.4rem 0;display:flex;align-items:center;gap:.5rem}
+code{background:#f4f4f4;padding:.1rem .3rem;border-radius:3px}
+button{font:inherit;padding:.2rem .6rem;cursor:pointer}
+form label{display:block;margin:.6rem 0 .2rem;font-weight:600}
+form .field input,form .field textarea,form .field select{font:inherit;padding:.3rem;width:100%;box-sizing:border-box;max-width:24rem}
+form .field input[type=checkbox],form .field input[type=radio]{width:auto}
+#form{margin-top:1.5rem;border-top:1px solid #ddd;padding-top:1rem}
+.muted{color:#666}</style>
 <h1>Task inbox</h1><ul id="tasks"><li>loading…</li></ul>
+<div id="form"></div>
 <script>
-fetch(${JSON.stringify(basePath)}+'/api/tasks').then(r=>r.json()).then(ts=>{
-  const ul=document.getElementById('tasks');
-  ul.replaceChildren();
-  if(!ts.length){const li=document.createElement('li');li.textContent='No open tasks.';ul.appendChild(li);return;}
-  for(const t of ts){const li=document.createElement('li');
-    const code=document.createElement('code');
-    code.textContent=t.elementId||t.userTaskKey;
-    li.appendChild(code);
-    li.appendChild(document.createTextNode(' — key '+t.userTaskKey));
-    ul.appendChild(li);}
-});
+const BASE=location.pathname.replace(/\/+$/,'');
+const tasksEl=document.getElementById('tasks');
+const formEl=document.getElementById('form');
+
+function api(path,opts){return fetch(BASE+path,opts).then(r=>{if(!r.ok)return r.text().then(t=>{throw new Error(t||r.status)});if(r.status===204)return null;return r.json();});}
+
+function loadTasks(){
+  formEl.replaceChildren();
+  tasksEl.replaceChildren(el('li',{},'loading…'));
+  return api('/api/tasks').then(ts=>{
+    tasksEl.replaceChildren();
+    if(!ts.length){tasksEl.appendChild(el('li',{},'No open tasks.'));return;}
+    for(const t of ts){
+      const li=document.createElement('li');
+      const code=el('code',{},t.elementId||t.userTaskKey);
+      li.appendChild(code);
+      li.appendChild(document.createTextNode(' — key '+t.userTaskKey));
+      if(t.formKey){
+        li.appendChild(btn('Open',()=>openForm(t)));
+      }else{
+        li.appendChild(btn('Complete',()=>complete(t.userTaskKey,{})));
+      }
+      tasksEl.appendChild(li);
+    }
+  }).catch(err=>tasksEl.replaceChildren(el('li',{class:'muted'},'Failed to load tasks: '+err.message)));
+}
+
+function openForm(t){
+  formEl.replaceChildren(el('p',{class:'muted'},'loading form…'));
+  const q='formKey='+encodeURIComponent(t.formKey);
+  api('/api/form?'+q).then(f=>{
+    formEl.replaceChildren();
+    if(!f||!f.schema){renderNoForm(t);return;}
+    renderForm(t,f.schema);
+  }).catch(err=>{formEl.replaceChildren(el('p',{class:'muted'},'Failed to load form: '+err.message));});
+}
+
+function renderNoForm(t){
+  formEl.appendChild(el('p',{class:'muted'},'This task has no renderable form.'));
+  const bar=el('div',{});
+  bar.appendChild(btn('Complete',()=>complete(t.userTaskKey,{})));
+  bar.appendChild(btn('Cancel',loadTasks));
+  formEl.appendChild(bar);
+}
+
+function renderForm(t,schema){
+  const form=document.createElement('form');
+  form.appendChild(el('h2',{},'Task '+(t.elementId||t.userTaskKey)));
+  const components=Array.isArray(schema.components)?schema.components:[];
+  const inputs=[];
+  for(const c of components){
+    const built=buildField(c);
+    if(!built)continue;
+    form.appendChild(built.field);
+    if(built.read)inputs.push(built.read);
+  }
+  const submit=btn('Submit',null);submit.type='submit';
+  const bar=el('div',{});bar.appendChild(submit);bar.appendChild(btn('Cancel',loadTasks));
+  form.appendChild(bar);
+  form.addEventListener('submit',e=>{
+    e.preventDefault();
+    // Null-prototype: field keys come from the engine-supplied form schema. A component
+    // keyed '__proto__'/'constructor' must land as a plain own property (and round-trip
+    // through JSON), never mutate a prototype — no prototype pollution in the page runtime.
+    const variables=Object.create(null);
+    for(const read of inputs){const kv=read();if(kv)variables[kv.key]=kv.value;}
+    submit.disabled=true;
+    complete(t.userTaskKey,variables).catch(()=>{submit.disabled=false;});
+  });
+  formEl.appendChild(form);
+}
+
+function buildField(c){
+  const type=c&&c.type;
+  // Static (keyless) components: show text as a paragraph, ignore layout-only ones.
+  if(type==='text'){return {field:el('p',{class:'muted'},typeof c.text==='string'?c.text:'')};}
+  const key=c&&c.key;
+  if(!key)return null;
+  const wrap=el('div',{class:'field'});
+  const label=typeof c.label==='string'&&c.label?c.label:key;
+  if(type==='checkbox'){
+    const input=document.createElement('input');input.type='checkbox';
+    const lab=el('label',{});lab.appendChild(input);lab.appendChild(document.createTextNode(' '+label));
+    wrap.appendChild(lab);
+    return {field:wrap,read:()=>({key,value:input.checked})};
+  }
+  const labelEl=el('label',{},label);
+  wrap.appendChild(labelEl);
+  let input;
+  if(type==='textarea'){input=document.createElement('textarea');}
+  else if(type==='select'){
+    input=document.createElement('select');
+    input.appendChild(el('option',{value:''},'—'));
+    for(const o of (Array.isArray(c.values)?c.values:[])){
+      input.appendChild(el('option',{value:String(o.value)},String(o.label!=null?o.label:o.value)));
+    }
+  }
+  else if(type==='radio'){
+    const name='r'+Math.random().toString(36).slice(2);
+    const group=el('div',{});
+    for(const o of (Array.isArray(c.values)?c.values:[])){
+      const rlab=el('label',{});
+      const r=document.createElement('input');r.type='radio';r.name=name;r.value=String(o.value);
+      rlab.appendChild(r);rlab.appendChild(document.createTextNode(' '+String(o.label!=null?o.label:o.value)));
+      group.appendChild(rlab);
+    }
+    wrap.appendChild(group);
+    return {field:wrap,read:()=>{const sel=group.querySelector('input:checked');return sel?{key,value:sel.value}:null;}};
+  }
+  else{
+    input=document.createElement('input');
+    input.type=(type==='number')?'number':(type==='datetime'?'datetime-local':'text');
+  }
+  // Associate the label with the input (for/id) so screen readers announce it on focus.
+  const fieldId='f'+Math.random().toString(36).slice(2);
+  input.id=fieldId;labelEl.setAttribute('for',fieldId);
+  wrap.appendChild(input);
+  const isNumber=type==='number';
+  return {field:wrap,read:()=>{
+    const raw=input.value;
+    if(raw===''||raw==null)return null;
+    if(isNumber){
+      const n=Number(raw);
+      // A non-numeric value in a number field is only reachable via tampering (the browser
+      // blanks invalid type=number input). Treat it as absent rather than silently submitting
+      // NaN, which JSON.stringify serializes as null — quietly changing the submitted value.
+      return Number.isFinite(n)?{key,value:n}:null;
+    }
+    return {key,value:raw};
+  }};
+}
+
+function complete(userTaskKey,variables){
+  return api('/api/complete',{method:'POST',headers:{'content-type':'application/json'},
+    body:JSON.stringify({userTaskKey,variables})}).then(loadTasks);
+}
+
+function el(tag,attrs,text){const e=document.createElement(tag);for(const k in attrs)e.setAttribute(k,attrs[k]);if(text!=null)e.textContent=text;return e;}
+function btn(label,onClick){const b=document.createElement('button');b.type='button';b.textContent=label;if(onClick)b.addEventListener('click',onClick);return b;}
+
+loadTasks();
 </script>`;
 }
 /** Mount the enabled surfaces and return their routes. */
@@ -42,7 +193,7 @@ export function mountSurfaces(ctx, app) {
             method: "GET",
             path: base,
             source: "surface:taskInbox",
-            handler: () => html(inboxPage(base)),
+            handler: () => html(inboxPage()),
         });
         routes.push({
             method: "GET",
@@ -54,6 +205,29 @@ export function mountSurfaces(ctx, app) {
                 return json(tasks);
             },
         });
+        routes.push({
+            method: "GET",
+            path: `${base}/api/form`,
+            source: "surface:taskInbox",
+            handler: async (req) => {
+                const formKey = req.query.get("formKey") ?? undefined;
+                const formId = req.query.get("formId") ?? undefined;
+                // Reject only when *neither* identifier is present. Presence follows getForm's
+                // canonical rule (`presentFormIdentifier`: empty/whitespace = absent) so a
+                // whitespace-only `?formKey=   ` request 400s here instead of slipping past a raw
+                // truthiness check and returning a spurious 204. The raw values are still passed
+                // through unchanged — resolving a blank key to its `formId` fallback is getForm's
+                // single responsibility.
+                if (!presentFormIdentifier(formKey) && !presentFormIdentifier(formId))
+                    return json({ error: "formKey or formId required" }, 400);
+                const form = await app.engine.getForm({ formKey, formId });
+                // A task whose form can't be resolved returns 204: the client renders the
+                // no-form fallback rather than erroring.
+                if (!form)
+                    return noContent();
+                return json(form);
+            },
+        });
         routes.push({
             method: "POST",
             path: `${base}/api/complete`,

package/dist/runtime/core/router.d.ts

@@ -11,6 +11,13 @@ export interface Route {
 export declare function json(body: unknown, status?: number): HttpResponse;
 export declare function html(body: string, status?: number): HttpResponse;
 export declare function text(body: string, status?: number): HttpResponse;
+/**
+ * A `204 No Content` response: an empty body and no `content-type`. Use this
+ * instead of `json(null, 204)` — the latter emits a `"null"` body that both
+ * violates the no-body semantics of 204 and makes a client that parses the
+ * body throw. Any client that short-circuits 204 receives no payload here.
+ */
+export declare function noContent(): HttpResponse;
 /**
  * Normalize a manifest-supplied route path: collapse leading slashes to exactly
  * one, drop trailing slashes. Incoming request paths always start with "/", so a

package/dist/runtime/core/router.js

@@ -10,6 +10,15 @@ export function html(body, status = 200) {
 export function text(body, status = 200) {
     return { status, headers: { "content-type": "text/plain; charset=utf-8" }, body };
 }
+/**
+ * A `204 No Content` response: an empty body and no `content-type`. Use this
+ * instead of `json(null, 204)` — the latter emits a `"null"` body that both
+ * violates the no-body semantics of 204 and makes a client that parses the
+ * body throw. Any client that short-circuits 204 receives no payload here.
+ */
+export function noContent() {
+    return { status: 204, headers: {}, body: "" };
+}
 /**
  * Normalize a manifest-supplied route path: collapse leading slashes to exactly
  * one, drop trailing slashes. Incoming request paths always start with "/", so a

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

@@ -1,6 +1,5 @@
 import type { EngineClient, HostContext } from "./host.ts";
 import { type AppManifest } from "./manifest.ts";
-import type { TemplateSource } from "./modules/templates.ts";
 import { DataLayer } from "./modules/datasource.ts";
 import { type Logger } from "./logger.ts";
 import type { SchedulerDeps } from "./modules/scheduler.ts";
@@ -32,10 +31,6 @@ export interface CreateUrbanAppOptions {
     port?: number;
     /** Which modules to mount (all true by default). */
     mount?: MountFlags;
-    /** Programmatic `{{name}}` template source for deploy-time substitution (globs or a
-     *  `name → content` map). Merged over the manifest's `models.templates` (this wins on
-     *  collision). See `deployModels`. */
-    templates?: TemplateSource;
     /**
      * Injectable timer + clock seam driving every background loop (the cron trigger loops
      * and the instance-tracking reconciler). Defaults to the live scheduler (real timers,

package/dist/runtime/core/runtime.js

@@ -2,7 +2,7 @@
 // materializes the app by mounting each module. Hosts (CLI/IDE/console/bare process) call
 // this the same way; a host may mount a subset via `mount` flags (e.g. the console mounts
 // its own surfaces but reuses deploy + workers + datasource).
-import { loadManifest } from "./manifest.js";
+import { loadManifest, resolveBindMode, bindModeToHost } from "./manifest.js";
 import { validateManifest } from "./validate.js";
 import { makeRouter } from "./router.js";
 import { deployModels } from "./modules/deploy.js";
@@ -48,7 +48,7 @@ export async function createUrbanApp(opts) {
         security: opts.mount?.security ?? true,
         instanceTracking: opts.mount?.instanceTracking ?? true,
     };
-    const ctx = { manifest, host, engine, root, templates: opts.templates };
+    const ctx = { manifest, host, engine, root };
     // One app-level structured logger over the host sink, shared by the entrypoint (exposed as
     // `app.log`) and the per-invocation `AppApi.log` (workers/route delegates `child()` it with their
     // correlation context).
@@ -65,6 +65,12 @@ export async function createUrbanApp(opts) {
     let started = false;
     let httpPort;
     const port = resolvePort(opts.port, host.env("PORT"));
+    // Which interface the HTTP server binds to (issue #235). Secure by default: loopback unless
+    // the manifest's `network.bind` (or the `URBAN_BIND` env override) opts into all interfaces.
+    // Derive the host address from the already-resolved mode so the two can never diverge (and we
+    // consult the env exactly once) — a second `resolveBindHost` call would re-read the override.
+    const bindMode = resolveBindMode(manifest, (n) => host.env(n));
+    const bindHost = bindModeToHost(bindMode);
     // Release every mounted resource and reset internal state so a subsequent
     // start() begins clean. Used by stop() and by start()'s failure path.
     const teardown = async () => {
@@ -181,9 +187,26 @@ export async function createUrbanApp(opts) {
                             body: JSON.stringify({ ok: true, app: manifest.id }),
                         }),
                     });
-                    server = await host.serveHttp(port, makeRouter(routes));
+                    server = await host.serveHttp(port, makeRouter(routes), bindHost);
                     httpPort = server.port;
-                    host.log("info", "urban app serving surfaces/triggers", { port: httpPort, routes: routes.length });
+                    host.log("info", "urban app serving surfaces/triggers", {
+                        port: httpPort,
+                        routes: routes.length,
+                        bind: bindMode,
+                        bindHost,
+                    });
+                    // Binding to all interfaces exposes the app (and its token-gated capability
+                    // hooks) on the LAN. That is the explicit opt-in this setting exists for, but a
+                    // non-loopback bind must not serve any LOCAL-mode "well-known localhost token"
+                    // credential (issue #235) — consumers that mint one (e.g. the agentic channel's
+                    // LOCAL mode) must gate it on a loopback bind. Surface the exposure so it is never
+                    // silent.
+                    if (bindMode === "all") {
+                        host.log("warn", "urban app bound to all interfaces — reachable off-box on the LAN", {
+                            port: httpPort,
+                            bindHost,
+                        });
+                    }
                     // ADR 0057 boot handshake: under a supervising host (the nano-bpm
                     // Studio sets NANOBPMN_APP_HANDSHAKE), announce the port we actually
                     // bound on a machine-readable stdout control line so the host can