@synapsor/runner 0.1.0-alpha.15 → 0.1.0-alpha.16

package/CHANGELOG.md

@@ -2,13 +2,24 @@
 
 ## Unreleased
 
+No unreleased changes yet.
+
+## 0.1.0-alpha.16
+
 ### Added
 
-- `result_format: 2` for a stable MCP result envelope with
-  `ok`, `summary`, `data`, `proposal`, `error`, `evidence`,
-  `source_database_changed`, and `_meta.canonical_capability`.
+- `synapsor-runner up` for first-session review-mode bring-up. It validates
+  the local config/store, checks active store leases, summarizes model-facing
+  tools, explains direct SQL versus app-owned executor writeback, and prints
+  the next smoke, approval, apply, replay, UI, and doctor commands.
+- Guided app-owned executor setup can now write a starter handler template
+  during `init --wizard` / `start --from-env ... --mode review`.
+- `result_format: 2` for a stable MCP result envelope with `ok`, `summary`,
+  `data`, `proposal`, `error`, `evidence`, `source_database_changed`, and
+  `_meta.canonical_capability`.
 - `--result-format v1|v2` for `mcp serve`, `mcp serve --transport
-  streamable-http`, `mcp serve-streamable-http`, and the legacy JSON-RPC bridge.
+  streamable-http`, `mcp serve-streamable-http`, and the legacy JSON-RPC
+  bridge.
 - Capability config fields `description`, per-argument `description`, and
   `returns_hint`; these are surfaced in MCP tool metadata.
 - `tools list` as a first-class alias for `tools preview`, including
@@ -16,16 +27,23 @@
 - `mcp client-config --include-instructions` for Claude/Cursor/OpenAI-style
   client snippets with propose-first agent guidance.
 - `schemas/synapsor.runner.schema.json` for editor validation.
-- `docs/capability-authoring.md` and `docs/result-envelope-v2.md`.
-- RFC source docs under `docs/rfcs/`.
+- `docs/capability-authoring.md`, `docs/result-envelope-v2.md`, and RFC source
+  docs under `docs/rfcs/`.
 
 ### Changed
 
+- Handler templates, template CLI output, app-owned writeback docs, and
+  examples now carry the explicit handler security warning: app handlers own the
+  final business write and must re-check tenant/scope, conflict guards,
+  idempotency, business action, transactions, and safe receipts.
 - OpenAI-safe aliases include the canonical Synapsor capability name in
   descriptions/metadata so model-visible aliases can still be audited against
   dotted capability names.
 - v2 MCP errors redact raw driver/infra strings and map failures to a small
   safe error-code enum.
+- Release policy now keeps the stable channel gated on `up`, review-mode wizard
+  verification, handler warning coverage, clean npm install checks, and at
+  least one external developer following the README without source reading.
 
 ### Compatibility
 

package/README.md

@@ -223,6 +223,21 @@ The end-to-end shape is:
 The generated config is just the safety contract. A small reviewed version
 looks like this:
 
+Bring the generated review-mode workspace up with one command:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner up \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --dry-run
+```
+
+`up` validates the config/store, summarizes model-facing tools, shows whether
+proposal tools use direct SQL writeback or app-owned executors, checks active
+store leases, and prints the next smoke, approve, apply, replay, UI, and doctor
+commands. Use `--transport streamable-http` when you want `up` to start the
+standard HTTP MCP server.
+
 ```json
 {
   "version": 1,
@@ -588,6 +603,14 @@ Use direct guarded DB writeback for simple local/staging single-row updates. If
 your application service already owns business writes, configure an
 `http_handler` or `command_handler` executor. Approval still happens outside
 MCP, and the handler returns an applied/conflict/failed receipt for replay.
+
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 Starter handlers are included under `examples/app-owned-writeback`.
 The packaged app-owned billing example also includes a bundled
 `synapsor-handler.mjs` helper shim; `@synapsor/handler` is not published as a

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAqG,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAmB3P,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAoS3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkD1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA6OjB;AA4uDD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAqG,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAmB3P,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA4U3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmD1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA+RjB;AAivDD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}

package/dist/runner.mjs

@@ -4525,15 +4525,18 @@ function generateRunnerConfigFromSpec(spec) {
   const lookupArg = spec.lookup_arg ?? `${objectName}_id`;
   const inspectToolName = spec.inspect_tool_name ?? `${spec.namespace}.inspect_${objectName}`;
   const proposalToolName = spec.proposal_tool_name ?? `${spec.namespace}.propose_${objectName}_update`;
+  const objectLabel = objectName.replace(/_/g, " ");
   const visibleColumns = unique([spec.primary_key, spec.tenant_key, spec.conflict_column, ...spec.visible_columns].filter((value) => Boolean(value)));
   const readCapability = {
     name: inspectToolName,
     kind: "read",
+    description: spec.inspect_description ?? `Inspect one ${objectLabel} in trusted tenant scope before answering or proposing a change.`,
+    returns_hint: spec.inspect_returns_hint ?? `Returns reviewed ${objectLabel} fields, evidence handle, query audit, and source_database_changed:false.`,
     source: sourceName,
     context: "local_operator",
     target: target(spec),
     args: {
-      [lookupArg]: { type: "string", required: true, max_length: 128 }
+      [lookupArg]: { type: "string", required: true, max_length: 128, description: `${capitalize(objectLabel)} id from the user request or trusted app context.` }
     },
     lookup: { id_from_arg: lookupArg },
     visible_columns: visibleColumns,
@@ -4546,6 +4549,8 @@ function generateRunnerConfigFromSpec(spec) {
     capabilities.push({
       name: proposalToolName,
       kind: "proposal",
+      description: spec.proposal_description ?? `Create a review-required proposal to update one ${objectLabel}. The source database remains unchanged until approval and writeback.`,
+      returns_hint: spec.proposal_returns_hint ?? "Returns a proposal id, exact before/after diff, evidence handle, approval status, and source_database_changed:false.",
       source: sourceName,
       context: "local_operator",
       ...writeback2.executor !== "sql_update" ? { executor: writeback2.executorName } : {},
@@ -4569,6 +4574,7 @@ function generateRunnerConfigFromSpec(spec) {
   const config = {
     version: 1,
     mode,
+    ...spec.result_format ? { result_format: spec.result_format } : {},
     storage: { sqlite_path: "./.synapsor/local.db" },
     sources: {
       [sourceName]: {
@@ -5017,6 +5023,7 @@ function validateSelectionSpec(spec) {
   if (spec.version !== void 0 && spec.version !== 1) throw new Error("onboarding selection version must be 1.");
   if (spec.engine !== "postgres" && spec.engine !== "mysql") throw new Error("selection engine must be postgres or mysql.");
   if (!["read_only", "shadow", "review", void 0].includes(spec.mode)) throw new Error("selection mode must be read_only, shadow, or review.");
+  if (spec.result_format !== void 0 && spec.result_format !== 1 && spec.result_format !== 2) throw new Error("selection result_format must be 1 or 2.");
   if (spec.writeback?.executor && !["sql_update", "http_handler", "command_handler"].includes(spec.writeback.executor)) {
     throw new Error("selection writeback.executor must be sql_update, http_handler, or command_handler.");
   }
@@ -5121,6 +5128,10 @@ function singularize(value) {
 function safeName(value) {
   return value.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "") || "record";
 }
+function capitalize(value) {
+  if (!value) return value;
+  return `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}`;
+}
 function assertSafeIdentifier(identifier) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
     throw new Error(`unsafe identifier in selection: ${identifier}`);
@@ -6573,6 +6584,19 @@ var defaultConfigPath = "synapsor.runner.json";
 var defaultStorePath = "./.synapsor/local.db";
 var quickDemoStorePath = "./.synapsor/quick-demo.db";
 var generatedSmokeInputPath = "./.synapsor/smoke-input.json";
+var handlerSecurityWarning = [
+  "IMPORTANT: your app handler owns the final business write.",
+  "Runner creates the proposal and calls your handler only after approval, but your handler must still enforce:",
+  "- tenant/scope check;",
+  "- expected-version or conflict guard;",
+  "- idempotency key;",
+  "- allowed business action;",
+  "- transaction/rollback;",
+  "- safe error receipt.",
+  "",
+  "If you skip those checks, you can reintroduce cross-tenant writes, lost updates, or duplicate writes.",
+  "Use the generated template/helper pattern and keep handler credentials out of MCP."
+].join("\n");
 var handlerTemplateDefinitions = {
   "node-fastify": {
     aliases: ["node", "fastify"],
@@ -6608,6 +6632,15 @@ app.post("/synapsor/writeback", async (request, reply) => {
   }
 
   /*
+   * IMPORTANT: your app handler owns the final business write.
+   * Runner creates the proposal and calls your handler only after approval,
+   * but your handler must still enforce tenant/scope, expected-version or
+   * conflict guard, idempotency key, allowed business action,
+   * transaction/rollback, and safe error receipt.
+   *
+   * If you skip those checks, you can reintroduce cross-tenant writes,
+   * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+   *
    * Put your app-owned transaction here.
    *
    * Examples:
@@ -6665,6 +6698,15 @@ async def synapsor_writeback(body: dict, authorization: str | None = Header(defa
 
     # Put your app-owned transaction here.
     #
+    # IMPORTANT: your app handler owns the final business write.
+    # Runner creates the proposal and calls your handler only after approval,
+    # but your handler must still enforce tenant/scope, expected-version or
+    # conflict guard, idempotency key, allowed business action,
+    # transaction/rollback, and safe error receipt.
+    #
+    # If you skip those checks, you can reintroduce cross-tenant writes,
+    # lost updates, or duplicate writes. Keep handler credentials out of MCP.
+    #
     # Examples:
     # - insert a refund_review row;
     # - insert an account_credit row;
@@ -6716,6 +6758,15 @@ if (request.dry_run) {
 }
 
 /*
+ * IMPORTANT: your app handler owns the final business write.
+ * Runner creates the proposal and calls your handler only after approval,
+ * but your handler must still enforce tenant/scope, expected-version or
+ * conflict guard, idempotency key, allowed business action,
+ * transaction/rollback, and safe error receipt.
+ *
+ * If you skip those checks, you can reintroduce cross-tenant writes,
+ * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+ *
  * Put your app-owned command transaction here.
  *
  * Examples:
@@ -6784,6 +6835,7 @@ ${cliCommandName()} --help
   if (command === "propose") return propose(rest);
   if (command === "audit") return audit(rest);
   if (command === "start") return start(rest);
+  if (command === "up") return up(rest);
   if (command === "runner") return runnerCommand(rest);
   if (command === "cloud") return cloud(rest);
   if (command === "mcp") return mcp(rest);
@@ -6987,8 +7039,32 @@ async function runInitWizard(args, options = {}) {
   const objectName = await askDefault(ask, "Business object name", optionalArg(args, "--object-name") ?? recipeSpec?.object_name ?? safeObjectName(table.name));
   const lookupArg = await askDefault(ask, "Model-visible object id argument", optionalArg(args, "--lookup-arg") ?? recipeSpec?.lookup_arg ?? `${objectName}_id`);
   const smokeObjectId = await askDefault(ask, "Optional real object id for a first smoke call", optionalArg(args, "--smoke-id") ?? "");
+  const objectLabel = objectName.replace(/_/g, " ");
+  const inspectDescription = await askDefault(
+    ask,
+    "Read capability description",
+    optionalArg(args, "--inspect-description") ?? `Inspect one ${objectLabel} in trusted tenant scope before answering or proposing a change.`
+  );
+  const inspectReturnsHint = await askDefault(
+    ask,
+    "Read capability returns hint",
+    optionalArg(args, "--inspect-returns-hint") ?? `Returns reviewed ${objectLabel} fields, evidence handle, query audit, and source_database_changed:false.`
+  );
+  const proposalDescription = mode === "read_only" ? void 0 : await askDefault(
+    ask,
+    "Proposal capability description",
+    optionalArg(args, "--proposal-description") ?? `Create a review-required proposal to update one ${objectLabel}. The source database remains unchanged until approval and writeback.`
+  );
+  const proposalReturnsHint = mode === "read_only" ? void 0 : await askDefault(
+    ask,
+    "Proposal capability returns hint",
+    optionalArg(args, "--proposal-returns-hint") ?? "Returns a proposal id, exact before/after diff, evidence handle, approval status, and source_database_changed:false."
+  );
+  const resultFormatAnswer = await askChoice(ask, "MCP result envelope", optionalArg(args, "--result-format") ? normalizeResultFormatAnswer(optionalArg(args, "--result-format")) : "default", ["default", "v1", "v2"]);
+  const resultFormat = resultFormatAnswer === "v1" ? 1 : resultFormatAnswer === "v2" ? 2 : void 0;
   let writeUrlEnv = optionalArg(args, "--write-url-env");
   let writeback2;
+  let generatedHandlerTemplate;
   if (mode === "review") {
     const writebackPath = await askChoice(
       ask,
@@ -7011,6 +7087,12 @@ async function runInitWizard(args, options = {}) {
         ...signingSecretEnv ? { handler_signing_secret_env: signingSecretEnv } : {},
         timeout_ms: positiveIntegerOption(args, "--handler-timeout-ms")
       };
+      const writeTemplate = await askChoice(ask, "Write starter app-owned handler template", args.includes("--skip-handler-template") ? "no" : "yes", ["yes", "no"]);
+      if (writeTemplate === "yes") {
+        const template = await askChoice(ask, "Handler template", optionalArg(args, "--handler-template") ?? "node-fastify", ["node-fastify", "python-fastapi"]);
+        const output = await askDefault(ask, "Handler template output", optionalArg(args, "--handler-template-output") ?? handlerTemplateDefinitions[template].fileName);
+        generatedHandlerTemplate = { name: template, output };
+      }
     } else {
       const commandEnv = await askEnvName(ask, "App-owned command handler env var", optionalArg(args, "--handler-command-env") ?? "SYNAPSOR_APP_WRITEBACK_COMMAND");
       writeback2 = {
@@ -7019,6 +7101,11 @@ async function runInitWizard(args, options = {}) {
         handler_command_env: commandEnv,
         timeout_ms: positiveIntegerOption(args, "--handler-timeout-ms")
       };
+      const writeTemplate = await askChoice(ask, "Write starter app-owned handler template", args.includes("--skip-handler-template") ? "no" : "yes", ["yes", "no"]);
+      if (writeTemplate === "yes") {
+        const output = await askDefault(ask, "Handler template output", optionalArg(args, "--handler-template-output") ?? handlerTemplateDefinitions.command.fileName);
+        generatedHandlerTemplate = { name: "command", output };
+      }
     }
   }
   const approvalRole = mode === "read_only" ? "local_reviewer" : await askDefault(ask, "Required approval role", optionalArg(args, "--approval-role") ?? recipeSpec?.approval?.required_role ?? "local_reviewer");
@@ -7039,7 +7126,12 @@ async function runInitWizard(args, options = {}) {
     object_name: objectName,
     inspect_tool_name: recipeSpec?.inspect_tool_name,
     proposal_tool_name: recipeSpec?.proposal_tool_name,
+    inspect_description: inspectDescription,
+    inspect_returns_hint: inspectReturnsHint,
+    proposal_description: proposalDescription,
+    proposal_returns_hint: proposalReturnsHint,
     lookup_arg: lookupArg,
+    result_format: resultFormat,
     visible_columns: visibleColumns,
     allowed_columns: allowedColumns,
     patch,
@@ -7065,16 +7157,29 @@ async function runInitWizard(args, options = {}) {
   stdout.write(`  source: ${inspection.engine} ${table.schema}.${table.name}
 `);
   stdout.write(`  mode: ${mode}
+`);
+  stdout.write(`  result envelope: ${resultFormat ? `v${resultFormat}` : "default"}
 `);
   stdout.write(`  writeback path: ${writeback2?.executor ?? (mode === "review" ? "sql_update" : "none")}
 `);
   stdout.write(`  exposed tools: ${tools2.join(", ")}
 `);
   stdout.write("  not exposed: execute_sql, approval tools, commit tools, database URLs, write credentials, model-controlled tenant authority\n");
+  if (generatedHandlerTemplate) {
+    stdout.write(`  handler template: ${generatedHandlerTemplate.output}
+`);
+    stdout.write(`${handlerSecurityWarning}
+`);
+  }
   const confirmed = await askDefault(ask, "Write generated config and MCP snippets? Type yes to continue", "no");
   if (confirmed.toLowerCase() !== "yes") throw new Error("guided init canceled before writing files");
   const outputPath = outputArg(args) ?? "synapsor.runner.json";
   await writeGeneratedOnboardingFiles(outputPath, generated, args.includes("--force"), { printNext: false });
+  if (generatedHandlerTemplate) {
+    await writeHandlerTemplateFile(generatedHandlerTemplate.name, generatedHandlerTemplate.output, args.includes("--force"));
+    stdout.write(`created ${generatedHandlerTemplate.output}
+`);
+  }
   if (smokeObjectId) {
     await writeGeneratedSmokeInputFile(lookupArg, smokeObjectId, args.includes("--force"));
     stdout.write(`created ${generatedSmokeInputPath}
@@ -7103,6 +7208,8 @@ async function runInitWizard(args, options = {}) {
 `);
   }
   stdout.write(`  3. Serve MCP tools: ${cliCommandName()} mcp serve --config ${outputPath} --store ${defaultStorePath}
+`);
+  stdout.write(`  OpenAI Agents SDK: use ${cliCommandName()} mcp serve-streamable-http --config ${outputPath} --store ${defaultStorePath} --alias-mode openai
 `);
   return 0;
 }
@@ -7179,6 +7286,11 @@ async function initFromInspection(args, inspection, databaseUrlEnv) {
     namespace: optionalArg(args, "--namespace") ?? "source",
     object_name: optionalArg(args, "--object-name"),
     lookup_arg: optionalArg(args, "--lookup-arg"),
+    inspect_description: optionalArg(args, "--inspect-description"),
+    inspect_returns_hint: optionalArg(args, "--inspect-returns-hint"),
+    proposal_description: optionalArg(args, "--proposal-description"),
+    proposal_returns_hint: optionalArg(args, "--proposal-returns-hint"),
+    result_format: resultFormatOption(args),
     visible_columns: visibleColumns,
     allowed_columns: allowedColumns,
     patch,
@@ -9131,9 +9243,202 @@ async function start(args = []) {
   await startPolling(config, adapters, controller.signal);
   return 0;
 }
+async function up(args = []) {
+  const allowed = /* @__PURE__ */ new Set([
+    "--config",
+    "--store",
+    "--transport",
+    "--host",
+    "--port",
+    "--auth-token-env",
+    "--alias-mode",
+    "--tool-name-style",
+    "--openai-tool-aliases",
+    "--result-format",
+    "--handler-check",
+    "--open-ui",
+    "--print-next",
+    "--dry-run",
+    "--dev-no-auth",
+    "--cors-origin",
+    "--allow-concurrent-store"
+  ]);
+  assertKnownOptions(args, allowed, "up");
+  const configPath = optionalArg(args, "--config") ?? defaultConfigPath;
+  const config = await readRuntimeConfig(configPath);
+  const storePath = optionalArg(args, "--store") ?? config.storage?.sqlite_path ?? defaultStorePath;
+  const transport = optionalArg(args, "--transport") ?? "stdio";
+  if (transport !== "stdio" && transport !== "streamable-http") {
+    throw new Error("--transport must be stdio or streamable-http");
+  }
+  const port = Number(optionalArg(args, "--port") ?? "8766");
+  if (transport === "streamable-http" && (!Number.isInteger(port) || port <= 0 || port > 65535)) {
+    throw new Error("--port must be an integer from 1 to 65535");
+  }
+  const aliasMode = toolNameStyleOption(args);
+  const resultFormat = resultFormatOption(args);
+  const validation = validateRunnerCapabilityConfig(config);
+  if (!validation.ok) {
+    throw new Error(`cannot bring Runner up with invalid config: ${validation.errors.map((error) => `${error.path} ${error.code}`).join("; ")}`);
+  }
+  if (storePath !== ":memory:") {
+    await fs3.mkdir(path3.dirname(path3.resolve(storePath)), { recursive: true });
+  }
+  await assertNoActiveStoreLease(storePath, args.includes("--allow-concurrent-store"), "review-mode up");
+  const boundary = await inspectMcpToolBoundary([
+    "--config",
+    configPath,
+    "--store",
+    storePath,
+    "--alias-mode",
+    aliasMode
+  ]);
+  process2.stdout.write(formatReviewModeUp({
+    aliasMode,
+    authTokenEnv: optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
+    boundary,
+    config,
+    configPath,
+    dryRun: args.includes("--dry-run"),
+    host: optionalArg(args, "--host") ?? "127.0.0.1",
+    openUi: args.includes("--open-ui"),
+    port,
+    resultFormat,
+    storePath,
+    transport
+  }));
+  if (args.includes("--handler-check")) {
+    process2.stdout.write("\nHandler check:\n");
+    const doctorCode = await doctor(["--config", configPath, "--store", storePath, "--check-handlers"]);
+    if (doctorCode !== 0) return doctorCode;
+  }
+  if (args.includes("--dry-run") || transport === "stdio") return boundary.ok ? 0 : 1;
+  const serveArgs = [
+    "--config",
+    configPath,
+    "--store",
+    storePath,
+    "--host",
+    optionalArg(args, "--host") ?? "127.0.0.1",
+    "--port",
+    String(port),
+    "--auth-token-env",
+    optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
+    "--alias-mode",
+    aliasMode,
+    ...resultFormat ? ["--result-format", String(resultFormat)] : [],
+    ...args.includes("--dev-no-auth") ? ["--dev-no-auth"] : [],
+    ...optionalArg(args, "--cors-origin") ? ["--cors-origin", optionalArg(args, "--cors-origin")] : [],
+    ...args.includes("--allow-concurrent-store") ? ["--allow-concurrent-store"] : []
+  ];
+  return mcpServeStreamableHttp(serveArgs);
+}
+function formatReviewModeUp(input) {
+  const lines = [
+    "Synapsor Runner review-mode up",
+    "",
+    `Config: ${input.configPath}`,
+    `Store: ${input.storePath}`,
+    `Mode: ${input.config.mode}`,
+    `Transport: ${input.transport}`,
+    `Alias mode: ${input.aliasMode}`,
+    `Result format: ${input.resultFormat ? `v${input.resultFormat}` : configResultFormat(input.config)}`,
+    `Dry run: ${input.dryRun ? "yes" : "no"}`,
+    "",
+    "Model-facing tools:",
+    ...formatUpToolLines(input.boundary),
+    "",
+    "Writeback paths:",
+    ...formatUpWritebackLines(input.config)
+  ];
+  const handlerLines = formatUpHandlerLines(input.config);
+  if (handlerLines.length > 0) {
+    lines.push("", "App-owned handler requirements:", ...handlerLines, "", handlerSecurityWarning);
+  }
+  lines.push("", "Server guidance:");
+  if (input.transport === "stdio") {
+    lines.push(
+      "  stdio mode is launched by an MCP client. This command does not hold a protocol session open.",
+      `  Print client config: ${cliCommandName()} mcp client-config --client claude-desktop --config ${input.configPath} --store ${input.storePath}`,
+      `  Serve command used by clients: ${cliCommandName()} mcp serve --config ${input.configPath} --store ${input.storePath} --alias-mode ${input.aliasMode}`
+    );
+  } else {
+    lines.push(
+      `  Streamable HTTP endpoint: http://${input.host}:${input.port}/mcp`,
+      `  Auth token env: ${input.authTokenEnv} (${process2.env[input.authTokenEnv] ? "set" : "missing"})`,
+      `  Start command: ${cliCommandName()} mcp serve-streamable-http --config ${input.configPath} --store ${input.storePath} --port ${input.port} --auth-token-env ${input.authTokenEnv} --alias-mode ${input.aliasMode}`
+    );
+  }
+  if (input.openUi) {
+    lines.push("", "Local review UI:", `  ${cliCommandName()} ui --open --tour --config ${input.configPath} --store ${input.storePath}`);
+  }
+  lines.push("", "Next commands:", ...formatUpNextCommands(input.config, input.configPath, input.storePath), "");
+  return `${lines.join("\n")}
+`;
+}
+function formatUpToolLines(boundary) {
+  if (boundary.exposures.length === 0) return ["  - (none)"];
+  return boundary.exposures.map((item) => item.isAlias ? `  - ${item.exposedName} -> ${item.canonicalName}` : `  - ${item.exposedName}`);
+}
+function formatUpWritebackLines(config) {
+  const proposals2 = (config.capabilities ?? []).filter((capability) => capability.kind === "proposal");
+  if (proposals2.length === 0) return ["  - no proposal capabilities; this config is read-only from Runner's perspective"];
+  return proposals2.map((capability) => {
+    const executorName = capability.executor ?? "sql_update";
+    if (executorName === "sql_update") {
+      const source = config.sources?.[capability.source];
+      const envName = source?.write_url_env ?? "SYNAPSOR_DATABASE_URL";
+      return `  - ${capability.name}: direct guarded one-row UPDATE via ${envName} (${process2.env[envName] ? "set" : "missing"})`;
+    }
+    const executor = config.executors?.[executorName];
+    return `  - ${capability.name}: app-owned ${String(executor?.type ?? "executor")} ${executorName}`;
+  });
+}
+function formatUpHandlerLines(config) {
+  const lines = [];
+  for (const [name, executor] of Object.entries(config.executors ?? {})) {
+    if (!isRecord6(executor)) continue;
+    if (executor.type === "http_handler") {
+      const urlEnv = typeof executor.url_env === "string" ? executor.url_env : "";
+      const auth = isRecord6(executor.auth) ? executor.auth : void 0;
+      const tokenEnv = typeof auth?.token_env === "string" ? auth.token_env : void 0;
+      const signingSecretEnv = typeof executor.signing_secret_env === "string" ? executor.signing_secret_env : void 0;
+      lines.push(`  - ${name}: http_handler`);
+      if (urlEnv) lines.push(`    url env: ${urlEnv} (${process2.env[urlEnv] ? "set" : "missing"})`);
+      if (tokenEnv) lines.push(`    bearer token env: ${tokenEnv} (${process2.env[tokenEnv] ? "set" : "missing"})`);
+      if (signingSecretEnv) lines.push(`    signing secret env: ${signingSecretEnv} (${process2.env[signingSecretEnv] ? "set" : "missing"})`);
+      if (!signingSecretEnv) lines.push("    signing secret env: not configured (recommended unless loopback-only)");
+    } else if (executor.type === "command_handler") {
+      const commandEnv = typeof executor.command_env === "string" ? executor.command_env : "";
+      lines.push(`  - ${name}: command_handler`);
+      if (commandEnv) lines.push(`    command env: ${commandEnv} (${process2.env[commandEnv] ? "set" : "missing"})`);
+    }
+  }
+  return lines;
+}
+function configResultFormat(config) {
+  return config.result_format === 2 ? "v2" : config.result_format === 1 ? "v1" : "default";
+}
+function formatUpNextCommands(config, configPath, storePath) {
+  const firstTool = (config.capabilities ?? [])[0]?.name ?? "<capability>";
+  const hasHandlers = Object.keys(config.executors ?? {}).length > 0;
+  return [
+    `  - Preview tools: ${cliCommandName()} tools preview --config ${configPath} --store ${storePath}`,
+    `  - Smoke call: ${cliCommandName()} smoke call ${firstTool} --sample --config ${configPath} --store ${storePath}`,
+    `  - List proposals: ${cliCommandName()} proposals list --store ${storePath}`,
+    `  - Show proposal: ${cliCommandName()} proposals show latest --store ${storePath}`,
+    `  - Approve proposal: ${cliCommandName()} proposals approve latest --yes --store ${storePath}`,
+    `  - Apply approved proposal: ${cliCommandName()} apply latest --config ${configPath} --store ${storePath}`,
+    `  - Replay: ${cliCommandName()} replay show latest --store ${storePath}`,
+    `  - Tail events: ${cliCommandName()} events tail --store ${storePath}`,
+    `  - Direct writeback doctor: ${cliCommandName()} doctor --config ${configPath} --check-writeback`,
+    ...hasHandlers ? [`  - Handler doctor: ${cliCommandName()} doctor --config ${configPath} --check-handlers`] : []
+  ];
+}
 async function runnerCommand(args) {
   const [subcommand, ...rest] = args;
   if (subcommand === "start") return start(rest);
+  if (subcommand === "up") return up(rest);
   if (subcommand === "doctor") return doctor(rest);
   usage();
   return 2;
@@ -9172,7 +9477,7 @@ async function cloudConnect(args) {
     return 1;
   }
   const runnerId = String(parsed.cloud.runner_id || process2.env.SYNAPSOR_RUNNER_ID || "synapsor_runner_local").trim();
-  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.15").trim();
+  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.16").trim();
   const engines = normalizeEngines(parsed.cloud.engines);
   const capabilities = normalizeCapabilities(parsed.cloud.capabilities);
   const client = new ControlPlaneClient({
@@ -9277,21 +9582,28 @@ async function handlerTemplate(args) {
     return 0;
   }
   const output = outputArg(args) ?? definition.fileName;
-  await writeFileGuarded(output, content, args.includes("--force"));
-  if (name === "command" || output.endsWith(".mjs") || output.endsWith(".js")) {
-    await fs3.chmod(path3.resolve(output), 493).catch(() => void 0);
-  }
+  await writeHandlerTemplateFile(name, output, args.includes("--force"));
   process2.stdout.write(`created ${output}
 `);
-  process2.stdout.write("Review the template and add your app-owned transaction, authorization, idempotency, and conflict checks before using it with approved proposals.\n");
+  process2.stdout.write(`${handlerSecurityWarning}
+`);
   return 0;
 }
+async function writeHandlerTemplateFile(name, output, force) {
+  const definition = handlerTemplateDefinitions[name];
+  await writeFileGuarded(output, definition.content, force);
+  if (name === "command" || output.endsWith(".mjs") || output.endsWith(".js")) {
+    await fs3.chmod(path3.resolve(output), 493).catch(() => void 0);
+  }
+}
 function formatHandlerTemplateList() {
   return [
     "Synapsor app-owned writeback handler templates",
     "",
     ...Object.entries(handlerTemplateDefinitions).map(([name, definition]) => `- ${name}: ${definition.description}`),
     "",
+    handlerSecurityWarning,
+    "",
     "Examples:",
     `  ${cliCommandName()} handler template node-fastify --output ./synapsor-writeback-handler.mjs`,
     `  ${cliCommandName()} handler template python-fastapi --output ./synapsor_writeback_handler.py`,
@@ -10040,7 +10352,7 @@ async function assertNoActiveStoreLease(storePath, force, operation) {
     await fs3.rm(storeLeasePath(resolved), { force: true });
     return;
   }
-  const message = `Local store appears active for ${lease.mode}/${lease.transport} (pid ${lease.pid}, started ${lease.started_at}). Refusing ${operation}. Stop the server or rerun with --force if you have verified it is safe.`;
+  const message = `Local store appears active for ${lease.mode}/${lease.transport} (pid ${lease.pid}, started ${lease.started_at}). Refusing ${operation}. Stop the server or rerun with --allow-concurrent-store/--force if you have verified it is safe.`;
   if (!force) throw new Error(message);
   process2.stderr.write(`Warning: ${message}
 `);
@@ -10104,6 +10416,12 @@ function resultFormatOption(args) {
   if (requested === "2" || requested === "v2") return 2;
   throw new Error("--result-format must be v1, 1, v2, or 2");
 }
+function normalizeResultFormatAnswer(value) {
+  if (value === "1" || value === "v1") return "v1";
+  if (value === "2" || value === "v2") return "v2";
+  if (value === "default") return "default";
+  throw new Error("--result-format must be default, v1, 1, v2, or 2");
+}
 async function mcpAudit(args) {
   const format = optionalArg(args, "--format") ?? (args.includes("--json") ? "json" : "text");
   if (!["text", "json", "markdown"].includes(format)) {
@@ -12231,8 +12549,8 @@ async function prepareReferenceDemo(args) {
   ].join("\n"));
   const down = spawnSync("docker", ["compose", "-f", composePath, "down", "-v", "--remove-orphans"], { stdio: "inherit", env: process2.env });
   if (down.status !== 0) return down.status ?? 1;
-  const up = spawnSync("docker", ["compose", "-f", composePath, "up", "-d"], { stdio: "inherit", env: process2.env });
-  if (up.status !== 0) return up.status ?? 1;
+  const up2 = spawnSync("docker", ["compose", "-f", composePath, "up", "-d"], { stdio: "inherit", env: process2.env });
+  if (up2.status !== 0) return up2.status ?? 1;
   await waitForReferenceDemoDatabase();
   await fs3.copyFile(path3.join(demoDir, "synapsor.runner.json"), configPath);
   process2.stdout.write([
@@ -13311,7 +13629,7 @@ function starterCloudConfig() {
       base_url_env: "SYNAPSOR_CLOUD_BASE_URL",
       runner_token_env: "SYNAPSOR_RUNNER_TOKEN",
       runner_id: "synapsor_runner_local",
-      runner_version: "0.1.0-alpha.15",
+      runner_version: "0.1.0-alpha.16",
       project_id: "token_scope",
       adapter_id: "mcp.your_adapter",
       source_id: "src_replace_me",
@@ -13346,6 +13664,7 @@ function isKnownTopLevelCommand(command) {
     "propose",
     "audit",
     "start",
+    "up",
     "runner",
     "cloud",
     "mcp",
@@ -13388,6 +13707,7 @@ Usage:
 Commands:
   inspect      Inspect a Postgres/MySQL schema
   start        Start guided own-database setup, or no-arg legacy worker polling
+  up           Bring up local review mode guidance/server
   init         Generate a Synapsor capability contract
   mcp          Serve safe semantic tools over MCP
   onboard      One-command own-database setup
@@ -13411,6 +13731,7 @@ Commands:
 
 Examples:
   ${cmd} start --from-env DATABASE_URL
+  ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db --dry-run
   ${cmd} onboard db --from-env DATABASE_URL
   ${cmd} inspect --from-env DATABASE_URL
   ${cmd} init --wizard --from-env DATABASE_URL
@@ -13420,6 +13741,26 @@ Examples:
   ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} propose billing.propose_late_fee_waiver --sample
   ${cmd} audit ./synapsor.runner.json
+`,
+    up: `Usage:
+  ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db [--transport stdio|streamable-http]
+  ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db --transport streamable-http --port 8766 --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+  ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db --handler-check --dry-run
+
+Validate the local Runner config and store, summarize model-facing tools,
+explain direct SQL versus app-owned executor writeback, and print the next
+smoke/approve/apply/replay commands.
+
+With --transport stdio, \`${cmd} up\` prints MCP client wiring because stdio is
+launched by the client. With --transport streamable-http and without --dry-run,
+it starts the standard Streamable HTTP MCP server.
+
+Options:
+  --alias-mode canonical|openai|both
+  --result-format v1|v2
+  --handler-check
+  --open-ui
+  --dry-run
 `,
     start: `Usage:
   ${cmd} start --from-env DATABASE_URL [--schema public] [--mode read_only|shadow|review]

package/docs/app-owned-executors.md

@@ -17,6 +17,13 @@ The model-facing MCP tool only creates a proposal. Approval happens outside MCP.
 After approval, Runner calls your `http_handler` or `command_handler`, records
 the receipt, and includes the result in replay.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 A handler is your application endpoint or script. It is not a second Synapsor
 package that users need to install. Install `@synapsor/runner`, then generate
 or copy a handler template only when your approved write needs app-owned

package/docs/handler-helper.md

@@ -17,6 +17,13 @@ The model-facing MCP tool still creates a proposal only. A human/operator
 approves outside MCP. After approval, Runner sends the structured writeback
 request to your handler.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 ## Scope
 
 Current alpha scope:

package/docs/release-notes.md

@@ -11,6 +11,40 @@ npx -y -p @synapsor/runner@alpha synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 0.1.0-alpha.16
+
+### Review-Mode Bring-Up
+
+- Added `synapsor-runner up` as the local review-mode orientation command. It
+  validates the config/store, checks active store leases, summarizes
+  model-facing tools, identifies direct SQL versus app-owned executor writeback
+  paths, and prints the next smoke, approval, apply, replay, UI, and doctor
+  commands.
+- `up --dry-run` gives the full checklist without starting a server.
+- `up --transport streamable-http` starts the standard MCP Streamable HTTP
+  server after the same validation and guidance.
+- `up --handler-check` runs the redacted handler env/reachability doctor path
+  before serving.
+- The guided wizard now writes model-facing capability descriptions,
+  per-argument descriptions, returns hints, and can opt into
+  `result_format: 2`.
+- `result_format: 2` gives MCP clients a stable envelope with `ok`, `summary`,
+  `data`, `proposal`, `error`, `evidence`, `source_database_changed`, and
+  `_meta.canonical_capability`.
+- `tools list`, `tools list --aliases`, and
+  `mcp client-config --include-instructions` help users inspect exposed tools
+  and generate client snippets without source reading.
+
+### Handler Security
+
+- Generated handler templates, template-list output, app-owned writeback docs,
+  and examples now explicitly warn that the app handler owns the final business
+  write. Handlers must re-check tenant/scope, expected-version or conflict
+  guard, idempotency, allowed business action, transaction/rollback, and safe
+  error receipts before mutating application state.
+- The guided review-mode wizard can now write a starter handler template when
+  the app-owned HTTP or command handler path is selected.
+
 ## 0.1.0-alpha.15
 
 ### Handler Wording Clarification
@@ -217,5 +251,5 @@ After publishing an alpha, verify the public package from a clean temporary
 directory:
 
 ```bash
-./scripts/verify-published-alpha.sh 0.1.0-alpha.15
+./scripts/verify-published-alpha.sh 0.1.0-alpha.16
 ```

package/docs/release-policy.md

@@ -5,7 +5,7 @@ or an exact version:
 
 ```bash
 npx -y -p @synapsor/runner@alpha synapsor-runner demo --quick
-npm install -g @synapsor/runner@0.1.0-alpha.15
+npm install -g @synapsor/runner@0.1.0-alpha.16
 ```
 
 Do not rely on the untagged `latest` dist-tag until a stable release is
@@ -38,12 +38,26 @@ A stable `0.1.0` release should only be tagged after:
 - npm README commands match the published package;
 - `synapsor-runner demo --quick` works from a clean directory;
 - own-database onboarding works from a clean directory;
+- one-command review-mode `synapsor-runner up` is verified from a clean
+  directory and clearly prints model-facing tools, writeback path, handler
+  requirements, and next commands;
+- review-mode wizard output is verified for one read capability plus one
+  proposal capability;
+- handler template security warnings are verified in docs, CLI output, and
+  generated templates;
 - stdio MCP and Streamable HTTP MCP are both verified;
 - OpenAI alias mode is verified;
 - direct SQL writeback requirements are documented and tested;
 - app-owned executor requirements are documented and tested;
 - local evidence/proposal/receipt/replay inspection works;
 - current limitations are accurate.
+- at least one external developer can follow the README without reading source;
+- there are no known docs/code mismatches around transport, credentials,
+  receipt tables, or handler expectations.
+
+Serious alpha users should pin an exact alpha version in package.json, CI, and
+MCP client snippets. Use `@alpha` only when intentionally testing the moving
+preview channel.
 
 ## Result Envelope Migration
 

package/docs/writeback-executors.md

@@ -115,6 +115,13 @@ The handler receives proposal fields, the exact patch, evidence metadata,
 guards, and an idempotency key. It does not receive arbitrary model SQL or DB
 credentials from Synapsor Runner.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 When `signing_secret_env` is set, Runner signs the exact JSON body with HMAC
 SHA-256 and sends:
 
@@ -220,6 +227,12 @@ npx -y -p @synapsor/runner@alpha synapsor-runner handler template command \
 The command receives the same structured JSON request on stdin and should print
 a JSON receipt body on stdout.
 
+> **Important:** command handlers have the same responsibility as HTTP
+> handlers. Re-check tenant/scope, expected-version or conflict guard,
+> idempotency, allowed business action, transaction/rollback, and safe error
+> receipt before mutating state. Otherwise the script can reintroduce
+> cross-tenant writes, lost updates, or duplicate writes.
+
 Use `examples/app-owned-writeback/command-handler.mjs` as a starting point when
 your safest apply path is an app script or job runner.
 

package/examples/app-owned-writeback/README.md

@@ -14,6 +14,13 @@ The model-facing MCP tool still only creates a proposal. Approval happens
 outside MCP. After approval, `synapsor-runner apply` sends a structured request
 to your handler, and the handler returns an execution receipt for replay.
 
+> **Important:** your app handler owns the final business write. Runner creates
+> the proposal and calls your handler only after approval, but your handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If you skip those checks, you can reintroduce cross-tenant
+> writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
+
 ## Config Snippet
 
 Add an executor and point one proposal capability at it:

package/examples/app-owned-writeback/command-handler.mjs

@@ -26,6 +26,15 @@ if (request.dry_run) {
 }
 
 /*
+ * IMPORTANT: your app handler owns the final business write.
+ * Runner creates the proposal and calls your handler only after approval,
+ * but your handler must still enforce tenant/scope, expected-version or
+ * conflict guard, idempotency key, allowed business action,
+ * transaction/rollback, and safe error receipt.
+ *
+ * If you skip those checks, you can reintroduce cross-tenant writes,
+ * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+ *
  * Put your app-owned command transaction here.
  *
  * Examples:

package/examples/app-owned-writeback/node-fastify-handler.mjs

@@ -28,6 +28,15 @@ app.post("/synapsor/writeback", async (request, reply) => {
   }
 
   /*
+   * IMPORTANT: your app handler owns the final business write.
+   * Runner creates the proposal and calls your handler only after approval,
+   * but your handler must still enforce tenant/scope, expected-version or
+   * conflict guard, idempotency key, allowed business action,
+   * transaction/rollback, and safe error receipt.
+   *
+   * If you skip those checks, you can reintroduce cross-tenant writes,
+   * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+   *
    * Put your app-owned transaction here.
    *
    * Examples:

package/examples/app-owned-writeback/python-fastapi-handler.py

@@ -36,6 +36,15 @@ def writeback(request: HandlerRequest, authorization: str | None = Header(defaul
             "details": {"dry_run": True},
         }
 
+    # IMPORTANT: your app handler owns the final business write.
+    # Runner creates the proposal and calls your handler only after approval,
+    # but your handler must still enforce tenant/scope, expected-version or
+    # conflict guard, idempotency key, allowed business action,
+    # transaction/rollback, and safe error receipt.
+    #
+    # If you skip those checks, you can reintroduce cross-tenant writes,
+    # lost updates, or duplicate writes. Keep handler credentials out of MCP.
+    #
     # Put your app-owned transaction here.
     #
     # Examples:

package/examples/mcp-postgres-billing-app-handler/README.md

@@ -26,6 +26,13 @@ App-owned rich writeback:
 The model never receives `execute_sql`, approval tools, commit/apply tools,
 database URLs, or write credentials.
 
+> **Important:** the app handler owns the final business write. Runner creates
+> the proposal and calls the handler only after approval, but the handler must
+> still enforce tenant/scope checks, expected-version or conflict guards,
+> idempotency keys, allowed business actions, transaction/rollback, and safe
+> error receipts. If those checks are skipped, the app can reintroduce
+> cross-tenant writes, lost updates, or duplicate writes.
+
 ## Run
 
 From the repository root:

package/examples/mcp-postgres-billing-app-handler/app-handler.mjs

@@ -54,6 +54,12 @@ async function shutdown() {
 }
 
 async function applyAccountCredit(job, tx) {
+  /*
+   * IMPORTANT: this app handler owns the final business write.
+   * The helper has already verified auth, tenant scope, expected version,
+   * idempotency, and transaction wrapping before this function runs. Keep that
+   * pattern if you replace the helper or move this logic into your app.
+   */
   const amountCents = Number(job.patch.credit_requested_cents);
   const reason = String(job.patch.credit_reason || "approved account credit");
   if (!Number.isInteger(amountCents) || amountCents <= 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.16",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",

package/schemas/onboarding-selection.v1.schema.json

@@ -24,7 +24,12 @@
     "object_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
     "inspect_tool_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
     "proposal_tool_name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$" },
+    "inspect_description": { "type": "string", "minLength": 1 },
+    "proposal_description": { "type": "string", "minLength": 1 },
+    "inspect_returns_hint": { "type": "string", "minLength": 1 },
+    "proposal_returns_hint": { "type": "string", "minLength": 1 },
     "lookup_arg": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+    "result_format": { "enum": [1, 2] },
     "visible_columns": {
       "type": "array",
       "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },