@synapsor/runner 0.1.0-alpha.8 → 0.1.0

package/dist/runner.mjs

@@ -444,23 +444,26 @@ function sleep(ms) {
 }
 
 // packages/config/src/index.ts
-var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["version", "mode", "storage", "sources", "trusted_context", "contexts", "executors", "capabilities", "cloud", "strict"]);
+var TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["version", "mode", "storage", "sources", "trusted_context", "contexts", "executors", "capabilities", "cloud", "strict", "result_format"]);
 var STORAGE_KEYS = /* @__PURE__ */ new Set(["sqlite_path"]);
 var CLOUD_KEYS = /* @__PURE__ */ new Set(["base_url_env", "runner_token_env", "runner_id", "runner_version", "project_id", "adapter_id", "source_id", "engines", "capabilities", "session"]);
 var SOURCE_KEYS = /* @__PURE__ */ new Set([
   "engine",
   "read_url_env",
   "write_url_env",
+  "read_only",
   "statement_timeout_ms",
   "ssl"
 ]);
 var TRUSTED_CONTEXT_KEYS = /* @__PURE__ */ new Set(["provider", "values"]);
 var CONTEXT_KEYS = TRUSTED_CONTEXT_KEYS;
-var EXECUTOR_KEYS = /* @__PURE__ */ new Set(["type", "url_env", "method", "auth", "timeout_ms", "command_env"]);
+var EXECUTOR_KEYS = /* @__PURE__ */ new Set(["type", "url_env", "method", "auth", "signing_secret_env", "timeout_ms", "command_env"]);
 var EXECUTOR_AUTH_KEYS = /* @__PURE__ */ new Set(["type", "token_env"]);
 var CAPABILITY_KEYS = /* @__PURE__ */ new Set([
   "name",
   "kind",
+  "description",
+  "returns_hint",
   "source",
   "context",
   "executor",
@@ -480,7 +483,7 @@ var CAPABILITY_KEYS = /* @__PURE__ */ new Set([
 ]);
 var TARGET_KEYS = /* @__PURE__ */ new Set(["schema", "table", "primary_key", "tenant_key", "single_tenant_dev"]);
 var LOOKUP_KEYS = /* @__PURE__ */ new Set(["id_from_arg"]);
-var ARG_KEYS = /* @__PURE__ */ new Set(["type", "required", "max_length", "minimum", "maximum", "enum"]);
+var ARG_KEYS = /* @__PURE__ */ new Set(["type", "description", "required", "max_length", "minimum", "maximum", "enum"]);
 var PATCH_BINDING_KEYS = /* @__PURE__ */ new Set(["fixed", "from_arg"]);
 var NUMERIC_BOUND_KEYS = /* @__PURE__ */ new Set(["minimum", "maximum"]);
 var TRANSITION_GUARD_KEYS = /* @__PURE__ */ new Set(["from_column", "allowed"]);
@@ -549,6 +552,9 @@ function validateRunnerCapabilityConfig(input) {
   if (input.version !== 1) {
     errors.push({ path: "$.version", code: "UNSUPPORTED_CONFIG_VERSION", message: "Runner config version must be 1." });
   }
+  if (input.result_format !== void 0 && input.result_format !== 1 && input.result_format !== 2) {
+    errors.push({ path: "$.result_format", code: "INVALID_RESULT_FORMAT", message: "result_format must be 1 or 2." });
+  }
   if (!isRunnerMode(input.mode)) {
     errors.push({ path: "$.mode", code: "INVALID_MODE", message: "mode must be read_only, shadow, review, or cloud." });
   }
@@ -559,6 +565,7 @@ function validateRunnerCapabilityConfig(input) {
   validateTrustedContext(input.trusted_context, input.contexts, input.capabilities, input.mode, strict, errors, warnings);
   validateExecutors(input.executors, input.mode, strict, errors);
   validateCapabilities(input.capabilities, input.sources, input.contexts, input.executors, input.mode, strict, errors, warnings);
+  validateWritebackReadiness(input.sources, input.capabilities, input.mode, errors, warnings);
   scanForForbiddenFields(input, "$", errors);
   return { ok: errors.length === 0, errors, warnings };
 }
@@ -617,14 +624,37 @@ function validateSources(value, mode, strict, errors, warnings) {
     if (source.statement_timeout_ms !== void 0 && !isPositiveInteger(source.statement_timeout_ms)) {
       errors.push({ path: `${path4}.statement_timeout_ms`, code: "INVALID_TIMEOUT", message: "statement_timeout_ms must be a positive integer." });
     }
+    if (source.read_only !== void 0 && typeof source.read_only !== "boolean") {
+      errors.push({ path: `${path4}.read_only`, code: "INVALID_SOURCE_READ_ONLY", message: "read_only must be true or false when provided." });
+    }
+  }
+}
+function validateWritebackReadiness(sources, capabilities, mode, errors, warnings) {
+  if (mode !== "review" || !isRecord(sources) || !Array.isArray(capabilities)) return;
+  capabilities.forEach((capability, index) => {
+    if (!isRecord(capability) || capability.kind !== "proposal") return;
+    const sourceName = isNonEmptyString(capability.source) ? capability.source : void 0;
+    const source = sourceName ? sources[sourceName] : void 0;
+    if (!sourceName || !isRecord(source)) return;
+    const executor = isNonEmptyString(capability.executor) ? capability.executor : "sql_update";
+    const directSql = executor === "sql_update";
+    if (!directSql) return;
+    if (source.read_only === true) {
+      errors.push({
+        path: `$.capabilities[${index}].executor`,
+        code: "READ_ONLY_SOURCE_DIRECT_WRITEBACK",
+        message: `Proposal capability ${String(capability.name ?? index)} uses direct SQL writeback, but source ${sourceName} is marked read_only.`
+      });
+      return;
+    }
     if (source.write_url_env === void 0) {
       warnings.push({
-        path: `${path4}.write_url_env`,
+        path: `$.sources.${sourceName}.write_url_env`,
         code: "WRITEBACK_DISABLED",
-        message: "No write_url_env is configured; review-mode proposal execution cannot apply external DB changes."
+        message: "No write_url_env is configured; direct SQL review-mode proposal execution cannot apply external DB changes."
       });
     }
-  }
+  });
 }
 function validateCloud(value, mode, strict, errors) {
   if (mode !== "cloud") {
@@ -797,6 +827,9 @@ function validateExecutors(value, mode, strict, errors) {
         errors.push({ path: `${path4}.method`, code: "INVALID_HANDLER_METHOD", message: "http_handler.method must be POST, PUT, or PATCH." });
       }
       validateExecutorAuth(executor.auth, `${path4}.auth`, strict, errors);
+      if (executor.signing_secret_env !== void 0 && !isEnvName(executor.signing_secret_env)) {
+        errors.push({ path: `${path4}.signing_secret_env`, code: "HANDLER_SIGNING_SECRET_ENV_INVALID", message: "http_handler.signing_secret_env must name an environment variable containing the HMAC signing secret." });
+      }
       if (executor.timeout_ms !== void 0 && !isPositiveInteger(executor.timeout_ms)) {
         errors.push({ path: `${path4}.timeout_ms`, code: "INVALID_HANDLER_TIMEOUT", message: "http_handler.timeout_ms must be a positive integer." });
       }
@@ -852,6 +885,12 @@ function validateCapability(value, index, sourceNames, contextNames, executorNam
   if (!isCapabilityKind(value.kind)) {
     errors.push({ path: `${path4}.kind`, code: "INVALID_CAPABILITY_KIND", message: "kind must be read or proposal." });
   }
+  if (value.description !== void 0 && !isNonEmptyString(value.description)) {
+    errors.push({ path: `${path4}.description`, code: "INVALID_CAPABILITY_DESCRIPTION", message: "description must be a non-empty string when provided." });
+  }
+  if (value.returns_hint !== void 0 && !isNonEmptyString(value.returns_hint)) {
+    errors.push({ path: `${path4}.returns_hint`, code: "INVALID_RETURNS_HINT", message: "returns_hint must be a non-empty string when provided." });
+  }
   if (!isNonEmptyString(value.source) || !sourceNames.has(value.source)) {
     errors.push({ path: `${path4}.source`, code: "UNKNOWN_SOURCE", message: "Capability source must reference a configured source." });
   }
@@ -926,6 +965,9 @@ function validateArgs(value, path4, strict, errors) {
     if (!["string", "number", "boolean"].includes(String(arg.type))) {
       errors.push({ path: `${argPath}.type`, code: "INVALID_ARG_TYPE", message: "Argument type must be string, number, or boolean." });
     }
+    if (arg.description !== void 0 && !isNonEmptyString(arg.description)) {
+      errors.push({ path: `${argPath}.description`, code: "INVALID_ARG_DESCRIPTION", message: "Argument description must be a non-empty string when provided." });
+    }
     if (arg.max_length !== void 0 && !isPositiveInteger(arg.max_length)) {
       errors.push({ path: `${argPath}.max_length`, code: "INVALID_MAX_LENGTH", message: "max_length must be a positive integer." });
     }
@@ -1184,6 +1226,8 @@ import { createServer } from "node:http";
 import path from "node:path";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 
 // packages/proposal-store/src/index.ts
 import { DatabaseSync } from "node:sqlite";
@@ -2071,6 +2115,11 @@ var ProposalStore = class {
     const rows = this.db.prepare("SELECT * FROM proposal_events WHERE proposal_id = ? ORDER BY event_id ASC").all(proposalId);
     return rows.map(rowToEvent).filter((event) => event !== void 0);
   }
+  listEvents(filters = {}) {
+    const query = buildEventQuery(filters);
+    const rows = this.db.prepare(query.sql).all(...query.params);
+    return rows.map(rowToEvent).filter((event) => event !== void 0);
+  }
   receipts(proposalId) {
     const rows = this.db.prepare("SELECT * FROM writeback_receipts WHERE proposal_id = ? ORDER BY receipt_id ASC").all(proposalId);
     return rows.map(rowToReceipt).filter((receipt) => receipt !== void 0);
@@ -2385,6 +2434,15 @@ function buildReceiptQuery(filters) {
   addTimeRange(clauses, params, "created_at", filters.from, filters.to);
   return finishQuery("SELECT * FROM writeback_receipts", clauses, params, filters.limit);
 }
+function buildEventQuery(filters) {
+  const clauses = [];
+  const params = [];
+  addEqual(clauses, params, "proposal_id", filters.proposal);
+  addEqual(clauses, params, "kind", filters.kind);
+  addEqual(clauses, params, "actor", filters.actor);
+  addTimeRange(clauses, params, "created_at", filters.from, filters.to);
+  return finishQuery("SELECT * FROM proposal_events", clauses, params, filters.limit);
+}
 function addEqual(clauses, params, column, value) {
   if (!value) return;
   clauses.push(`${column} = ?`);
@@ -2668,74 +2726,118 @@ function loadRuntimeConfigFromFile(configPath = process.env.SYNAPSOR_MCP_CONFIG
 function createMcpRuntime(config, options = {}) {
   assertValidRunnerCapabilityConfig(config);
   const env = options.env ?? process.env;
-  const store = options.store ?? new ProposalStore(options.storePath ?? config.storage?.sqlite_path ?? "./.synapsor/local.db");
+  const storePath = options.storePath ?? config.storage?.sqlite_path ?? "./.synapsor/local.db";
+  const ownsStore = !options.store;
+  const store = options.store ?? new ProposalStore(storePath);
   const readRow = options.readRow ?? readCurrentRow;
   const cloudClient = options.controlPlaneClient ?? (config.mode === "cloud" ? createCloudClient(config, env) : void 0);
   const cloudTools = options.cloudTools ?? [];
+  const resultFormat = options.resultFormat ?? config.result_format ?? 1;
+  const assertStoreAvailable = () => {
+    if (ownsStore) assertPersistentStoreAvailable(storePath);
+  };
   return {
     config,
     store,
     listTools: () => config.mode === "cloud" ? cloudTools : listedLocalCapabilities(config).map((capability) => toolMetadata(capability)),
-    callTool: async (name, args) => callConfiguredTool({ config, env, store, readRow, cloudClient, name, args }),
-    readResource: (uri) => readLocalResource(store, uri),
+    callTool: async (name, args) => {
+      if (resultFormat === 2) {
+        try {
+          assertStoreAvailable();
+          return await callConfiguredToolV2({ config, env, store, readRow, cloudClient, name, args });
+        } catch (error) {
+          const capability = config.mode === "cloud" ? void 0 : localCapabilities(config).find((item) => item.name === name);
+          return errorEnvelopeFromError(error, capability, name);
+        }
+      }
+      assertStoreAvailable();
+      return callConfiguredTool({ config, env, store, readRow, cloudClient, name, args });
+    },
+    readResource: (uri) => {
+      assertStoreAvailable();
+      return readLocalResource(store, uri);
+    },
     close: () => {
       if (!options.store) store.close();
     }
   };
 }
-function createSynapsorMcpServer(runtime) {
+function assertPersistentStoreAvailable(storePath) {
+  if (storePath === ":memory:") return;
+  if (fs.existsSync(storePath)) return;
+  throw new McpRuntimeError(
+    "LOCAL_STORE_UNAVAILABLE",
+    "The local Synapsor store is temporarily unavailable. Restart the runner or recreate the store before retrying."
+  );
+}
+function createSynapsorMcpServer(runtime, options = {}) {
   const server = new McpServer(
-    { name: "synapsor-runner", version: "0.1.0-alpha.8" },
+    { name: "synapsor-runner", version: "0.1.0" },
     { capabilities: { tools: {}, resources: {} } }
   );
+  const toolNameStyle = options.toolNameStyle ?? "canonical";
   if (runtime.config.mode === "cloud") {
-    for (const tool of runtime.listTools()) {
-      server.registerTool(
-        tool.name,
-        {
-          title: tool.title,
-          description: tool.description,
-          inputSchema: zodInputShapeFromJsonSchema(tool.input_schema),
-          annotations: {
-            readOnlyHint: Boolean(tool.annotations.readOnlyHint),
-            destructiveHint: false,
-            idempotentHint: Boolean(tool.annotations.idempotentHint),
-            openWorldHint: false
+    const tools2 = runtime.listTools();
+    const exposedNames = toolNameExposureMap(tools2.map((tool) => tool.name), toolNameStyle);
+    for (const tool of tools2) {
+      for (const exposedName of exposedNames.get(tool.name) ?? [tool.name]) {
+        server.registerTool(
+          exposedName,
+          {
+            title: tool.title,
+            description: toolDescriptionWithCanonical(tool.description, tool.name, exposedName),
+            inputSchema: zodInputShapeFromJsonSchema(tool.input_schema),
+            annotations: {
+              readOnlyHint: Boolean(tool.annotations.readOnlyHint),
+              destructiveHint: false,
+              idempotentHint: Boolean(tool.annotations.idempotentHint),
+              openWorldHint: false
+            },
+            _meta: {
+              ...tool.annotations,
+              "synapsor.cloud_delegated": true,
+              "synapsor.canonical_tool_name": tool.name,
+              "synapsor.exposed_tool_name": exposedName,
+              "synapsor.tool_name_style": toolNameStyle,
+              "synapsor.raw_sql_exposed": false,
+              "synapsor.approval_tool": false
+            }
           },
-          _meta: {
-            ...tool.annotations,
-            "synapsor.cloud_delegated": true,
-            "synapsor.raw_sql_exposed": false,
-            "synapsor.approval_tool": false
-          }
-        },
-        async (args) => toolCallResult(runtime, tool.name, args)
-      );
+          async (args) => toolCallResult(runtime, tool.name, args)
+        );
+      }
     }
   } else {
-    for (const capability of listedLocalCapabilities(runtime.config)) {
-      server.registerTool(
-        capability.name,
-        {
-          title: capability.name,
-          description: capabilityDescription(capability),
-          inputSchema: zodInputShape(capability),
-          annotations: {
-            readOnlyHint: capability.kind === "read",
-            destructiveHint: false,
-            idempotentHint: capability.kind === "read",
-            openWorldHint: false
+    const capabilities = listedLocalCapabilities(runtime.config);
+    const exposedNames = toolNameExposureMap(capabilities.map((capability) => capability.name), toolNameStyle);
+    for (const capability of capabilities) {
+      for (const exposedName of exposedNames.get(capability.name) ?? [capability.name]) {
+        server.registerTool(
+          exposedName,
+          {
+            title: capability.name,
+            description: capabilityDescription(capability, exposedName),
+            inputSchema: zodInputShape(capability),
+            annotations: {
+              readOnlyHint: capability.kind === "read",
+              destructiveHint: false,
+              idempotentHint: capability.kind === "read",
+              openWorldHint: false
+            },
+            _meta: {
+              "synapsor.kind": capability.kind,
+              "synapsor.source": capability.source,
+              "synapsor.target": `${capability.target.schema}.${capability.target.table}`,
+              "synapsor.canonical_tool_name": capability.name,
+              "synapsor.exposed_tool_name": exposedName,
+              "synapsor.tool_name_style": toolNameStyle,
+              "synapsor.raw_sql_exposed": false,
+              "synapsor.approval_tool": false
+            }
           },
-          _meta: {
-            "synapsor.kind": capability.kind,
-            "synapsor.source": capability.source,
-            "synapsor.target": `${capability.target.schema}.${capability.target.table}`,
-            "synapsor.raw_sql_exposed": false,
-            "synapsor.approval_tool": false
-          }
-        },
-        async (args) => toolCallResult(runtime, capability.name, args)
-      );
+          async (args) => toolCallResult(runtime, capability.name, args)
+        );
+      }
     }
   }
   server.registerResource(
@@ -2761,8 +2863,8 @@ function createSynapsorMcpServer(runtime) {
 async function serveStdio(options = {}) {
   const config = options.config ?? loadRuntimeConfigFromFile(options.configPath);
   const cloudTools = config.mode === "cloud" ? await fetchCloudToolMetadata(config, process.env) : void 0;
-  const runtime = createMcpRuntime(config, { storePath: options.storePath, cloudTools });
-  const server = createSynapsorMcpServer(runtime);
+  const runtime = createMcpRuntime(config, { storePath: options.storePath, resultFormat: options.resultFormat, cloudTools });
+  const server = createSynapsorMcpServer(runtime, { toolNameStyle: options.toolNameStyle });
   const transport = new StdioServerTransport();
   await server.connect(transport);
   await new Promise((resolve) => {
@@ -2797,6 +2899,7 @@ async function startHttpMcpServer(options = {}) {
   const runtime = createMcpRuntime(config, {
     env,
     storePath: options.storePath,
+    resultFormat: options.resultFormat,
     readRow: options.readRow,
     cloudTools
   });
@@ -2844,6 +2947,152 @@ async function startHttpMcpServer(options = {}) {
     close: () => closeHttpServer(server, runtime)
   };
 }
+async function startStreamableHttpMcpServer(options = {}) {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? 8766;
+  const authTokenEnv = options.authTokenEnv ?? "SYNAPSOR_RUNNER_HTTP_TOKEN";
+  const env = options.env ?? process.env;
+  const devNoAuth = options.devNoAuth === true;
+  if (devNoAuth && !isLoopbackHost(host)) {
+    throw new McpRuntimeError("HTTP_DEV_NO_AUTH_UNSAFE_HOST", "--dev-no-auth is only allowed with localhost or 127.0.0.1.");
+  }
+  const authToken = devNoAuth ? void 0 : env[authTokenEnv];
+  if (!devNoAuth && !authToken) {
+    throw new McpRuntimeError("HTTP_AUTH_TOKEN_MISSING", `${authTokenEnv} is not set. Streamable HTTP MCP requires bearer auth by default.`);
+  }
+  const config = options.config ?? loadRuntimeConfigFromFile(options.configPath);
+  const cloudTools = config.mode === "cloud" ? await fetchCloudToolMetadata(config, env) : void 0;
+  const sessions = /* @__PURE__ */ new Map();
+  const openSessions = /* @__PURE__ */ new Set();
+  const server = createServer((request, response) => {
+    void handleStreamableHttpMcpRequest({
+      request,
+      response,
+      config,
+      storePath: options.storePath,
+      readRow: options.readRow,
+      cloudTools,
+      env,
+      toolNameStyle: options.toolNameStyle,
+      resultFormat: options.resultFormat,
+      authToken,
+      devNoAuth,
+      corsOrigin: options.corsOrigin,
+      sessions,
+      openSessions
+    });
+  });
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, host, () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+  } catch (error) {
+    await closeStreamableSessions(openSessions);
+    throw error;
+  }
+  const address = server.address();
+  const actualHost = address.address === "::" ? host : address.address;
+  const actualPort = address.port;
+  const url = `http://${actualHost}:${actualPort}/mcp`;
+  if (options.log !== false) {
+    const log = options.log ?? process.stderr;
+    log.write(`Synapsor Runner Streamable HTTP MCP listening on ${url}
+`);
+    log.write(devNoAuth ? "Auth: disabled for localhost development only\n" : `Auth: bearer token from ${authTokenEnv}
+`);
+    log.write(`Config: ${options.configPath ?? "synapsor.runner.json"}
+`);
+    log.write(`Store: ${options.storePath ?? config.storage?.sqlite_path ?? "./.synapsor/local.db"}
+`);
+  }
+  return {
+    host: actualHost,
+    port: actualPort,
+    url,
+    close: () => closeStreamableHttpServer(server, openSessions)
+  };
+}
+async function handleStreamableHttpMcpRequest(input) {
+  const { request, response, config, storePath, readRow, cloudTools, env, toolNameStyle, resultFormat, authToken, devNoAuth, corsOrigin, sessions, openSessions } = input;
+  try {
+    setCorsHeaders(response, corsOrigin);
+    if (request.method === "OPTIONS" && corsOrigin) {
+      response.statusCode = 204;
+      response.end();
+      return;
+    }
+    const url = new URL(request.url ?? "/", "http://localhost");
+    if (request.method === "GET" && url.pathname === "/healthz") {
+      writeJson(response, 200, {
+        ok: true,
+        transport: "streamable-http",
+        sessions: sessions.size,
+        tools: config.mode === "cloud" ? (cloudTools ?? []).length : listedLocalCapabilities(config).length,
+        mode: config.mode
+      });
+      return;
+    }
+    if (url.pathname !== "/mcp") {
+      writeJson(response, 404, { ok: false, error: "not_found" });
+      return;
+    }
+    if (!devNoAuth && !validBearerToken(request.headers.authorization, authToken ?? "")) {
+      writeJson(response, 401, { ok: false, error: "unauthorized" });
+      return;
+    }
+    const sessionId = headerValue(request.headers["mcp-session-id"]);
+    if (sessionId) {
+      const existing = sessions.get(sessionId);
+      if (!existing) {
+        writeJson(response, 404, jsonRpcError(null, -32e3, "MCP session not found."));
+        return;
+      }
+      await existing.transport.handleRequest(request, response);
+      return;
+    }
+    if (request.method !== "POST") {
+      writeJson(response, 400, jsonRpcError(null, -32e3, "MCP initialize request is required before using this Streamable HTTP session."));
+      return;
+    }
+    const parsedBody = JSON.parse(await readRequestBody(request));
+    if (!containsInitializeRequest(parsedBody)) {
+      writeJson(response, 400, jsonRpcError(requestIdFromPayload(parsedBody), -32e3, "First Streamable HTTP MCP request must be initialize."));
+      return;
+    }
+    let session;
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => crypto.randomUUID(),
+      onsessioninitialized: (newSessionId) => {
+        if (session) {
+          session.sessionId = newSessionId;
+          sessions.set(newSessionId, session);
+        }
+      },
+      onsessionclosed: (closedSessionId) => {
+        const closed = sessions.get(closedSessionId);
+        if (closed) {
+          disposeStreamableSession(closed, sessions, openSessions);
+        }
+      }
+    });
+    const runtime = createMcpRuntime(config, { env, storePath, resultFormat, readRow, cloudTools });
+    session = { transport, runtime };
+    openSessions.add(session);
+    transport.onclose = () => {
+      if (session) disposeStreamableSession(session, sessions, openSessions);
+    };
+    await createSynapsorMcpServer(runtime, { toolNameStyle }).connect(transport);
+    await transport.handleRequest(request, response, parsedBody);
+  } catch (error) {
+    const message = sanitizeHttpError(error, authToken);
+    if (!response.headersSent) writeJson(response, 200, jsonRpcError(null, -32e3, message));
+    else response.end();
+  }
+}
 async function handleHttpMcpRequest(input) {
   const { request, response, runtime, authToken, devNoAuth, corsOrigin } = input;
   try {
@@ -2943,6 +3192,71 @@ function validBearerToken(header, expected) {
   const expectedBuffer = Buffer.from(expected);
   return actualBuffer.length === expectedBuffer.length && crypto.timingSafeEqual(actualBuffer, expectedBuffer);
 }
+function headerValue(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+function containsInitializeRequest(payload) {
+  if (Array.isArray(payload)) return payload.some((message) => isInitializeRequest(message));
+  return isInitializeRequest(payload);
+}
+function requestIdFromPayload(payload) {
+  if (Array.isArray(payload)) {
+    const request = payload.find((message) => isRecord3(message) && "id" in message);
+    return isRecord3(request) ? request.id ?? null : null;
+  }
+  return isRecord3(payload) ? payload.id ?? null : null;
+}
+function openaiToolNameAlias(canonicalName) {
+  const sanitized = canonicalName.replace(/[^A-Za-z0-9_-]+/g, "__").replace(/_{3,}/g, "__").replace(/^_+|_+$/g, "");
+  const base = sanitized.length > 0 ? sanitized : `tool_${shortToolHash(canonicalName)}`;
+  if (base.length <= 64) return base;
+  const suffix = shortToolHash(canonicalName);
+  return `${base.slice(0, Math.max(1, 63 - suffix.length)).replace(/_+$/g, "")}_${suffix}`;
+}
+function toolNameExposures(canonicalNames, style) {
+  const exposedNames = toolNameExposureMap(canonicalNames, style);
+  return canonicalNames.flatMap((canonicalName) => {
+    return (exposedNames.get(canonicalName) ?? [canonicalName]).map((exposedName) => ({
+      canonicalName,
+      exposedName,
+      isAlias: exposedName !== canonicalName,
+      style
+    }));
+  });
+}
+function toolNameExposureMap(canonicalNames, style) {
+  const exposedByCanonical = /* @__PURE__ */ new Map();
+  const canonicalByExposed = /* @__PURE__ */ new Map();
+  if (style === "both") {
+    for (const canonical of canonicalNames) canonicalByExposed.set(canonical, canonical);
+  }
+  for (const canonical of canonicalNames) {
+    const names = /* @__PURE__ */ new Set();
+    if (style === "canonical" || style === "both") names.add(canonical);
+    if (style === "openai" || style === "both") {
+      let alias = openaiToolNameAlias(canonical);
+      const existing = canonicalByExposed.get(alias);
+      if (existing && existing !== canonical) {
+        const suffix = shortToolHash(canonical);
+        alias = `${alias.slice(0, Math.max(1, 63 - suffix.length)).replace(/_+$/g, "")}_${suffix}`;
+      }
+      canonicalByExposed.set(alias, canonical);
+      names.add(alias);
+    }
+    exposedByCanonical.set(canonical, [...names]);
+  }
+  return exposedByCanonical;
+}
+function shortToolHash(value) {
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+function setCorsHeaders(response, corsOrigin) {
+  if (corsOrigin) {
+    response.setHeader("access-control-allow-origin", corsOrigin);
+    response.setHeader("access-control-allow-methods", "POST, GET, DELETE, OPTIONS");
+    response.setHeader("access-control-allow-headers", "authorization, content-type, mcp-session-id, mcp-protocol-version, last-event-id");
+  }
+}
 function setCommonHttpHeaders(response, corsOrigin) {
   response.setHeader("content-type", "application/json; charset=utf-8");
   if (corsOrigin) {
@@ -3006,6 +3320,28 @@ async function closeHttpServer(server, runtime) {
     runtime.close();
   });
 }
+async function closeStreamableHttpServer(server, sessions) {
+  await new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  }).finally(() => closeStreamableSessions(sessions));
+}
+async function closeStreamableSessions(sessions) {
+  for (const session of [...sessions]) {
+    sessions.delete(session);
+    await session.transport.close().catch(() => void 0);
+    disposeStreamableSession(session);
+  }
+}
+function disposeStreamableSession(session, sessionMap, openSessions) {
+  if (session.closed) return;
+  session.closed = true;
+  if (session.sessionId) sessionMap?.delete(session.sessionId);
+  openSessions?.delete(session);
+  session.runtime.close();
+}
 async function toolCallResult(runtime, toolName, args) {
   try {
     const structuredContent = await runtime.callTool(toolName, args);
@@ -3081,6 +3417,11 @@ function cloudToolMetadata(tool) {
     }
   };
 }
+function toolDescriptionWithCanonical(description, canonicalName, exposedName) {
+  if (!exposedName || exposedName === canonicalName) return description;
+  return `Canonical Synapsor capability: ${canonicalName}.
+${description}`;
+}
 function zodInputShapeFromJsonSchema(schema) {
   const properties = isRecord3(schema.properties) ? schema.properties : {};
   const required = Array.isArray(schema.required) ? new Set(schema.required.map(String)) : /* @__PURE__ */ new Set();
@@ -3258,6 +3599,135 @@ async function callConfiguredTool(input) {
     source_database_mutated: false
   };
 }
+async function callConfiguredToolV2(input) {
+  const capability = input.config.mode === "cloud" ? void 0 : localCapabilities(input.config).find((item) => item.name === input.name);
+  try {
+    const legacy = await callConfiguredTool(input);
+    return resultEnvelopeFromLegacy(legacy, capability, input.name);
+  } catch (error) {
+    return errorEnvelopeFromError(error, capability, input.name);
+  }
+}
+function resultEnvelopeFromLegacy(legacy, capability, canonicalName) {
+  const action = typeof legacy.action === "string" ? legacy.action : canonicalName;
+  const kind = capability?.kind ?? (typeof legacy.proposal_id === "string" ? "proposal" : "read");
+  const evidenceBundleId = typeof legacy.evidence_bundle_id === "string" ? legacy.evidence_bundle_id : void 0;
+  const sourceChanged = Boolean(legacy.source_database_changed ?? legacy.source_database_mutated ?? false);
+  const context = isRecord3(legacy.trusted_context) ? legacy.trusted_context : void 0;
+  const target2 = isRecord3(legacy.target) ? legacy.target : void 0;
+  if (kind === "proposal") {
+    const proposalId = typeof legacy.proposal_id === "string" ? legacy.proposal_id : "wrp_unknown";
+    const targetType = typeof target2?.type === "string" ? target2.type : capability?.target.table ?? "object";
+    const targetId = target2?.id !== void 0 ? String(target2.id) : "unknown";
+    const executor = writebackExecutorName(legacy.writeback);
+    const writebackMode = executor && executor !== "sql_update" && executor !== "trusted_worker_required" ? "app_handler" : "direct_update";
+    return {
+      ok: true,
+      summary: `Created proposal ${proposalId} for ${targetType} ${targetId}. Source database changed: no.`,
+      action,
+      kind,
+      data: null,
+      proposal: {
+        id: proposalId,
+        state: typeof legacy.status === "string" ? legacy.status : "review_required",
+        target: `${targetType}:${targetId}`,
+        diff: isRecord3(legacy.diff) ? legacy.diff : {},
+        approval_required: legacy.approval_required !== false,
+        writeback: {
+          mode: writebackMode,
+          applied: false
+        },
+        next: "A human must approve outside this model-facing tool surface; nothing is committed yet."
+      },
+      error: null,
+      evidence: evidenceBundleId ? evidenceHandle(evidenceBundleId) : null,
+      source_database_changed: sourceChanged,
+      _meta: {
+        tenant_id: typeof target2?.tenant_id === "string" ? target2.tenant_id : void 0,
+        principal: typeof context?.principal === "string" ? context.principal : void 0,
+        provenance: typeof context?.provenance === "string" ? context.provenance : void 0,
+        canonical_capability: action
+      }
+    };
+  }
+  const businessObject = isRecord3(legacy.business_object) ? legacy.business_object : void 0;
+  const objectType = typeof businessObject?.type === "string" ? businessObject.type : capability?.target.table ?? "record";
+  const objectId = businessObject?.id !== void 0 ? String(businessObject.id) : String(legacy.action ?? action);
+  return {
+    ok: true,
+    summary: `Read ${objectType} ${objectId} through ${action}. Source database changed: no.`,
+    action,
+    kind: "read",
+    data: isRecord3(legacy.data) ? legacy.data : {},
+    proposal: null,
+    error: null,
+    evidence: evidenceBundleId ? evidenceHandle(evidenceBundleId) : null,
+    source_database_changed: sourceChanged,
+    _meta: {
+      tenant_id: typeof context?.tenant_id === "string" ? context.tenant_id : void 0,
+      principal: typeof context?.principal === "string" ? context.principal : void 0,
+      provenance: typeof context?.provenance === "string" ? context.provenance : void 0,
+      canonical_capability: action
+    }
+  };
+}
+function writebackExecutorName(value) {
+  if (!isRecord3(value)) return void 0;
+  return typeof value.executor === "string" ? value.executor : typeof value.mode === "string" ? value.mode : void 0;
+}
+function evidenceHandle(bundleId) {
+  return {
+    bundle_id: bundleId,
+    note: "audit/replay handle; you do not need to act on it during this turn"
+  };
+}
+function errorEnvelopeFromError(error, capability, canonicalName) {
+  const safe = safeToolError(error);
+  const action = capability?.name ?? canonicalName;
+  return {
+    ok: false,
+    summary: safe.message,
+    action,
+    kind: capability?.kind ?? "read",
+    data: null,
+    proposal: null,
+    error: safe,
+    evidence: null,
+    source_database_changed: false,
+    _meta: {
+      canonical_capability: action
+    }
+  };
+}
+function safeToolError(error) {
+  const runtimeCode = error instanceof McpRuntimeError ? error.code : void 0;
+  if (runtimeCode === "ROW_NOT_FOUND") {
+    return { code: "NOT_FOUND_IN_TENANT", message: "No authorized row was found in the trusted tenant scope.", retryable: false };
+  }
+  if (runtimeCode === "MCP_TOOL_NOT_FOUND") {
+    return { code: "CAPABILITY_NOT_FOUND", message: "The requested Synapsor capability is not available.", retryable: false };
+  }
+  if (runtimeCode === "PROPOSALS_DISABLED") {
+    return { code: "APPROVAL_REQUIRED", message: "Proposal tools are disabled for this runner mode.", retryable: false };
+  }
+  if (runtimeCode && (runtimeCode.startsWith("ARGUMENT_") || runtimeCode === "LOOKUP_ARG_MISSING" || runtimeCode === "MODEL_CANNOT_OVERRIDE_BINDING" || runtimeCode === "TRUSTED_BINDING_MISSING" || runtimeCode === "TRUSTED_CONTEXT_MISSING")) {
+    return { code: "INVALID_ARGUMENT", message: "The tool input or trusted context binding is invalid.", retryable: false };
+  }
+  if (runtimeCode && (runtimeCode.startsWith("PATCH_") || runtimeCode === "CONFLICT_GUARD_MISSING")) {
+    return { code: "POLICY_VIOLATION", message: "The requested change is outside the reviewed capability policy.", retryable: false };
+  }
+  if (runtimeCode === "LOCAL_STORE_UNAVAILABLE") {
+    return { code: "TEMPORARILY_UNAVAILABLE", message: "The local runner store is temporarily unavailable. Restart the runner or recreate the store before retrying.", retryable: true };
+  }
+  if (runtimeCode === "SOURCE_CREDENTIAL_MISSING" || looksLikeInfraError(error)) {
+    return { code: "TEMPORARILY_UNAVAILABLE", message: "The database is temporarily unavailable. Retry later.", retryable: true };
+  }
+  return { code: "INTERNAL", message: "The capability failed safely. Check the local runner logs for details.", retryable: false };
+}
+function looksLikeInfraError(error) {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /\b(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|timeout|connect|connection|database|authentication|certificate)\b/i.test(message);
+}
 function buildChangeSet(input) {
   const patch = buildPatch(input.capability, input.args);
   const before = scalarRecord(input.currentRow);
@@ -3459,7 +3929,7 @@ function zodInputShape(capability) {
     if (spec.type === "number" && spec.maximum !== void 0) schema = schema.max(spec.maximum);
     if (spec.enum && spec.enum.length > 0) schema = schema.refine((value) => spec.enum?.includes(value), "value is not allowlisted");
     if (spec.required === false) schema = schema.optional();
-    shape[name] = schema.describe(`${name} business argument`);
+    shape[name] = schema.describe(spec.description ?? `${name} business argument`);
   }
   return shape;
 }
@@ -3472,6 +3942,7 @@ function toolMetadata(capability) {
     input_schema: Object.fromEntries(Object.entries(capability.args).map(([name, spec]) => [name, {
       type: spec.type,
       required: spec.required !== false,
+      ...spec.description !== void 0 ? { description: spec.description } : {},
       ...spec.max_length !== void 0 ? { max_length: spec.max_length } : {},
       ...spec.minimum !== void 0 ? { minimum: spec.minimum } : {},
       ...spec.maximum !== void 0 ? { maximum: spec.maximum } : {},
@@ -3487,11 +3958,23 @@ function toolMetadata(capability) {
     }
   };
 }
-function capabilityDescription(capability) {
-  if (capability.kind === "read") {
-    return `Read ${capability.target.schema}.${capability.target.table} through a reviewed Synapsor capability with trusted tenant context and evidence.`;
+function capabilityDescription(capability, exposedName) {
+  const lines = [];
+  if (exposedName && exposedName !== capability.name) {
+    lines.push(`Canonical Synapsor capability: ${capability.name}.`);
+  }
+  if (capability.description) {
+    lines.push(capability.description);
+  } else if (capability.kind === "read") {
+    lines.push(`Read ${capability.target.schema}.${capability.target.table} through a reviewed Synapsor capability with trusted tenant context and evidence.`);
+  } else {
+    lines.push(`Create an evidence-backed Synapsor proposal for ${capability.target.schema}.${capability.target.table}; the source database is not mutated by this tool.`);
+  }
+  if (capability.returns_hint) {
+    lines.push(capability.returns_hint);
   }
-  return `Create an evidence-backed Synapsor proposal for ${capability.target.schema}.${capability.target.table}; the source database is not mutated by this tool.`;
+  lines.push("Evidence handles are audit/replay handles; the model does not need to call them during this turn.");
+  return lines.join("\n");
 }
 function buildPatch(capability, args) {
   if (!capability.patch) throw new McpRuntimeError("PATCH_REQUIRED", "Proposal capability has no patch mapping.");
@@ -3608,6 +4091,9 @@ function isRecord3(value) {
 }
 function toolErrorPayload(error) {
   if (error instanceof McpRuntimeError) {
+    if (error.code === "LOCAL_STORE_UNAVAILABLE") {
+      return { ok: false, code: "TEMPORARILY_UNAVAILABLE", error: "The local runner store is temporarily unavailable. Restart the runner or recreate the store before retrying." };
+    }
     return { ok: false, code: error.code, error: error.message };
   }
   return { ok: false, code: "MCP_TOOL_FAILED", error: error instanceof Error ? error.message : String(error) };
@@ -4005,6 +4491,7 @@ import { Pool as Pool3 } from "pg";
 var TENANT_COLUMNS = /* @__PURE__ */ new Set(["tenant_id", "account_id", "organization_id", "org_id", "workspace_id", "customer_id"]);
 var CONFLICT_COLUMNS = /* @__PURE__ */ new Set(["updated_at", "modified_at", "row_version", "version", "lock_version", "etag"]);
 var IMMUTABLE_COLUMNS = /* @__PURE__ */ new Set(["id", "uuid", "created_at", "created_by"]);
+var DEFAULT_RESULT_FORMAT = 2;
 var SENSITIVE_PATTERNS = [
   /password/i,
   /password_hash/i,
@@ -4056,22 +4543,26 @@ function generateRunnerConfigFromSpec(spec) {
   const mode = spec.mode ?? "shadow";
   const sourceName = spec.source_name ?? (spec.engine === "postgres" ? "local_postgres" : "local_mysql");
   const readUrlEnv = spec.read_url_env ?? spec.database_url_env ?? "SYNAPSOR_DATABASE_READ_URL";
-  const writeUrlEnv = spec.write_url_env ?? "SYNAPSOR_DATABASE_WRITE_URL";
+  const writeback2 = normalizedWriteback(spec);
+  const writeUrlEnv = writeback2.executor === "sql_update" ? spec.write_url_env ?? "SYNAPSOR_DATABASE_WRITE_URL" : void 0;
   const tenantEnv = spec.trusted_context?.tenant_id_env ?? "SYNAPSOR_TENANT_ID";
   const principalEnv = spec.trusted_context?.principal_env ?? "SYNAPSOR_PRINCIPAL";
   const objectName = spec.object_name ?? singularize(safeName(spec.table));
   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,
@@ -4084,8 +4575,11 @@ 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 } : {},
       target: target(spec),
       args: {
         [lookupArg]: { type: "string", required: true, max_length: 128 },
@@ -4106,12 +4600,14 @@ function generateRunnerConfigFromSpec(spec) {
   const config = {
     version: 1,
     mode,
+    result_format: spec.result_format ?? DEFAULT_RESULT_FORMAT,
     storage: { sqlite_path: "./.synapsor/local.db" },
     sources: {
       [sourceName]: {
         engine: spec.engine,
         read_url_env: readUrlEnv,
-        ...mode === "review" ? { write_url_env: writeUrlEnv } : {},
+        ...mode === "review" && writeUrlEnv ? { write_url_env: writeUrlEnv } : {},
+        ...mode === "review" && writeback2.executor !== "sql_update" && !writeUrlEnv ? { read_only: true } : {},
         statement_timeout_ms: spec.statement_timeout_ms ?? 3e3
       }
     },
@@ -4131,11 +4627,20 @@ function generateRunnerConfigFromSpec(spec) {
         }
       }
     },
+    ...mode === "review" && writeback2.executor !== "sql_update" ? { executors: writeback2.executors } : {},
     capabilities
   };
   return {
     config,
-    envExample: envExample({ readUrlEnv, writeUrlEnv, tenantEnv, principalEnv, mode, engine: spec.engine }),
+    envExample: envExample({
+      readUrlEnv,
+      writeUrlEnv,
+      tenantEnv,
+      principalEnv,
+      mode,
+      engine: spec.engine,
+      extraEnv: writeback2.extraEnv
+    }),
     mcpSnippets: mcpSnippets()
   };
 }
@@ -4450,6 +4955,52 @@ function target(spec) {
     ...spec.tenant_key ? { tenant_key: spec.tenant_key } : { single_tenant_dev: Boolean(spec.single_tenant_dev) }
   };
 }
+function normalizedWriteback(spec) {
+  const executor = spec.writeback?.executor ?? "sql_update";
+  if (executor === "sql_update") {
+    return { executor, extraEnv: [] };
+  }
+  const executorName = spec.writeback?.executor_name ?? `${safeName(spec.namespace)}_${executor === "http_handler" ? "http_handler" : "command_handler"}`;
+  if (executor === "http_handler") {
+    const urlEnv = spec.writeback?.handler_url_env ?? "SYNAPSOR_APP_WRITEBACK_URL";
+    const tokenEnv = spec.writeback?.handler_token_env;
+    const signingSecretEnv = spec.writeback?.handler_signing_secret_env;
+    return {
+      executor,
+      executorName,
+      executors: {
+        [executorName]: {
+          type: "http_handler",
+          url_env: urlEnv,
+          method: "POST",
+          ...tokenEnv ? { auth: { type: "bearer_env", token_env: tokenEnv } } : {},
+          ...signingSecretEnv ? { signing_secret_env: signingSecretEnv } : {},
+          timeout_ms: spec.writeback?.timeout_ms ?? 5e3
+        }
+      },
+      extraEnv: [
+        { name: urlEnv, value: "http://127.0.0.1:8787/synapsor/writeback", comment: "App-owned writeback handler endpoint." },
+        ...tokenEnv ? [{ name: tokenEnv, value: "<handler-bearer-token>", comment: "Optional handler bearer token." }] : [],
+        ...signingSecretEnv ? [{ name: signingSecretEnv, value: "<handler-hmac-signing-secret>", comment: "Optional HMAC signing secret for Runner-to-handler requests." }] : []
+      ]
+    };
+  }
+  const commandEnv = spec.writeback?.handler_command_env ?? "SYNAPSOR_APP_WRITEBACK_COMMAND";
+  return {
+    executor,
+    executorName,
+    executors: {
+      [executorName]: {
+        type: "command_handler",
+        command_env: commandEnv,
+        timeout_ms: spec.writeback?.timeout_ms ?? 5e3
+      }
+    },
+    extraEnv: [
+      { name: commandEnv, value: "node ./examples/app-owned-writeback/command-handler.mjs", comment: "Command receives the structured handler proposal JSON on stdin." }
+    ]
+  };
+}
 function inferPatchArgs(patch, explicit, numericBounds, transitionGuards) {
   const args = {};
   for (const [column, binding] of Object.entries(patch)) {
@@ -4475,14 +5026,18 @@ function envExample(input) {
     "# Synapsor Runner local environment.",
     "# Replace examples locally. Do not commit real credentials.",
     `${input.readUrlEnv}="${readExample}"`,
-    ...input.mode === "review" ? [`${input.writeUrlEnv}="${writeExample}"`] : [],
+    ...input.mode === "review" && input.writeUrlEnv ? [`${input.writeUrlEnv}="${writeExample}"`] : [],
+    ...(input.extraEnv ?? []).flatMap((item) => [
+      ...item.comment ? [`# ${item.comment}`] : [],
+      `${item.name}="${item.value}"`
+    ]),
     `${input.tenantEnv}="acme"`,
     `${input.principalEnv}="local_operator"`,
     ""
   ].join("\n");
 }
 function mcpSnippets() {
-  const command = "synapsor";
+  const command = "synapsor-runner";
   const args = ["mcp", "serve", "--config", "./synapsor.runner.json", "--store", "./.synapsor/local.db"];
   return {
     "generic-stdio.json": { command, args },
@@ -4495,6 +5050,16 @@ 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.");
+  }
+  if (spec.mode !== "review" && spec.writeback?.executor && spec.writeback.executor !== "sql_update") {
+    throw new Error("app-owned writeback executors are only valid in review mode.");
+  }
+  if (spec.writeback?.timeout_ms !== void 0 && (!Number.isInteger(spec.writeback.timeout_ms) || spec.writeback.timeout_ms <= 0)) {
+    throw new Error("selection writeback.timeout_ms must be a positive integer.");
+  }
   for (const [label, value] of Object.entries({
     schema: spec.schema,
     table: spec.table,
@@ -4540,6 +5105,7 @@ function validateSelectionSpec(spec) {
     spec.tenant_key,
     spec.conflict_column,
     spec.lookup_arg,
+    spec.writeback?.executor_name,
     ...spec.visible_columns ?? [],
     ...spec.allowed_columns ?? [],
     ...Object.keys(spec.numeric_bounds ?? {}),
@@ -4552,6 +5118,10 @@ function validateSelectionSpec(spec) {
     spec.read_url_env,
     spec.database_url_env,
     spec.write_url_env,
+    spec.writeback?.handler_url_env,
+    spec.writeback?.handler_token_env,
+    spec.writeback?.handler_signing_secret_env,
+    spec.writeback?.handler_command_env,
     spec.trusted_context?.tenant_id_env,
     spec.trusted_context?.principal_env
   ].filter(Boolean)) {
@@ -4585,6 +5155,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}`);
@@ -6036,43 +6610,248 @@ var dangerousDatabaseMcpAuditExample = {
 var defaultConfigPath = "synapsor.runner.json";
 var defaultStorePath = "./.synapsor/local.db";
 var quickDemoStorePath = "./.synapsor/quick-demo.db";
-var referenceDemoDir = "examples/reference-support-billing-app";
-var referenceDemoConfigPath = `${referenceDemoDir}/synapsor.runner.json`;
-var referenceDemoContainer = "synapsor_runner_reference_support_billing";
-var referenceDemoDatabase = "synapsor_reference_support_billing";
-var referenceDemoEnv = {
-  REFERENCE_POSTGRES_READ_URL: "postgresql://synapsor_reader:synapsor_reader_password@localhost:55435/synapsor_reference_support_billing",
-  REFERENCE_POSTGRES_WRITE_URL: "postgresql://synapsor_writer:synapsor_writer_password@localhost:55435/synapsor_reference_support_billing",
-  SYNAPSOR_TENANT_ID: "acme",
-  SYNAPSOR_PRINCIPAL: "local_reviewer",
-  SYNAPSOR_ENGINE: "postgres",
-  SYNAPSOR_DATABASE_URL: "postgresql://synapsor_writer:synapsor_writer_password@localhost:55435/synapsor_reference_support_billing",
-  SYNAPSOR_RUNNER_ID: "synapsor_demo_runner",
-  SYNAPSOR_SOURCE_ID: "app_postgres",
-  SYNAPSOR_CONTROL_PLANE_URL: "http://127.0.0.1:0",
-  SYNAPSOR_RUNNER_TOKEN: "syn_wbr_demo_local"
-};
-async function main(argv) {
-  const [command, ...rest] = argv;
-  if (!command || command === "--help" || command === "-h") {
-    usage([]);
-    return 0;
+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"],
+    fileName: "synapsor-writeback-handler.mjs",
+    description: "HTTP handler template for a Node/Fastify application service.",
+    content: `import Fastify from "fastify";
+
+const port = Number(process.env.PORT || 8787);
+const expectedToken = process.env.SYNAPSOR_APP_WRITEBACK_TOKEN || "dev-handler-token";
+
+const app = Fastify({ logger: true });
+
+app.post("/synapsor/writeback", async (request, reply) => {
+  const auth = request.headers.authorization || "";
+  if (auth !== \`Bearer \${expectedToken}\`) {
+    return reply.code(401).send({ status: "failed", safe_error_code: "UNAUTHORIZED" });
   }
-  if (!isKnownTopLevelCommand(command)) {
-    process2.stderr.write(`Unknown command: ${cliCommandName()} ${command}
 
-Try:
-${cliCommandName()} --help
-`);
-    return 2;
+  const body = request.body || {};
+  const changeSet = body.change_set || {};
+
+  if (!body.proposal_id || !body.idempotency_key || !changeSet.scope?.tenant_id) {
+    return reply.code(400).send({ status: "failed", safe_error_code: "BAD_WRITEBACK_REQUEST" });
   }
-  if (isHelpRequest(rest)) {
-    usage([command, ...rest.filter((arg) => arg !== "--help" && arg !== "-h")]);
-    return 0;
+
+  if (body.dry_run) {
+    return {
+      status: "applied",
+      rows_affected: 0,
+      source_database_mutated: false,
+      details: { dry_run: true },
+    };
   }
-  if (command === "help") {
-    usage(rest);
-    return 0;
+
+  /*
+   * 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:
+   * - insert a refund_review row;
+   * - insert an account_credit row;
+   * - open a support_ticket row;
+   * - update multiple related rows in one app transaction.
+   *
+   * Re-check tenant/principal authorization, idempotency, row/version guards,
+   * and business policy before mutating application state.
+   */
+
+  return {
+    status: "applied",
+    rows_affected: 1,
+    previous_version: String(changeSet.guards?.expected_version?.value || ""),
+    new_version: new Date().toISOString(),
+    source_database_mutated: true,
+  };
+});
+
+app.listen({ host: "127.0.0.1", port });
+`
+  },
+  "python-fastapi": {
+    aliases: ["python", "fastapi"],
+    fileName: "synapsor_writeback_handler.py",
+    description: "HTTP handler template for a Python/FastAPI application service.",
+    content: `import os
+from datetime import datetime, timezone
+
+from fastapi import FastAPI, Header, HTTPException
+
+app = FastAPI()
+expected_token = os.getenv("SYNAPSOR_APP_WRITEBACK_TOKEN", "dev-handler-token")
+
+
+@app.post("/synapsor/writeback")
+async def synapsor_writeback(body: dict, authorization: str | None = Header(default=None)):
+    if authorization != f"Bearer {expected_token}":
+        raise HTTPException(status_code=401, detail={"status": "failed", "safe_error_code": "UNAUTHORIZED"})
+
+    change_set = body.get("change_set") or {}
+    scope = change_set.get("scope") or {}
+    if not body.get("proposal_id") or not body.get("idempotency_key") or not scope.get("tenant_id"):
+        raise HTTPException(status_code=400, detail={"status": "failed", "safe_error_code": "BAD_WRITEBACK_REQUEST"})
+
+    if body.get("dry_run"):
+        return {
+            "status": "applied",
+            "rows_affected": 0,
+            "source_database_mutated": False,
+            "details": {"dry_run": True},
+        }
+
+    # 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;
+    # - open a support_ticket row;
+    # - update multiple related rows in one app transaction.
+    #
+    # Re-check tenant/principal authorization, idempotency, row/version guards,
+    # and business policy before mutating application state.
+
+    expected_version = ((change_set.get("guards") or {}).get("expected_version") or {}).get("value", "")
+    return {
+        "status": "applied",
+        "rows_affected": 1,
+        "previous_version": str(expected_version),
+        "new_version": datetime.now(timezone.utc).isoformat(),
+        "source_database_mutated": True,
+    }
+`
+  },
+  command: {
+    aliases: ["script", "local-command"],
+    fileName: "synapsor-command-handler.mjs",
+    description: "Local command handler template for scripts or job runners.",
+    content: `#!/usr/bin/env node
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+
+const request = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+const changeSet = request.change_set || {};
+
+if (!request.proposal_id || !request.idempotency_key || !changeSet.scope?.tenant_id) {
+  process.stdout.write(JSON.stringify({
+    status: "failed",
+    safe_error_code: "BAD_WRITEBACK_REQUEST",
+    source_database_mutated: false,
+  }));
+  process.exit(0);
+}
+
+if (request.dry_run) {
+  process.stdout.write(JSON.stringify({
+    status: "applied",
+    rows_affected: 0,
+    source_database_mutated: false,
+    details: { dry_run: true },
+  }));
+  process.exit(0);
+}
+
+/*
+ * 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:
+ * - call an internal service;
+ * - enqueue a review job;
+ * - run an app script that uses your normal ORM.
+ *
+ * Re-check tenant/principal authorization, idempotency, row/version guards,
+ * and business policy before mutating application state.
+ */
+
+process.stdout.write(JSON.stringify({
+  status: "applied",
+  rows_affected: 1,
+  previous_version: String(changeSet.guards?.expected_version?.value || ""),
+  new_version: new Date().toISOString(),
+  source_database_mutated: true,
+}));
+`
+  }
+};
+var referenceDemoDir = "examples/reference-support-billing-app";
+var referenceDemoConfigPath = `${referenceDemoDir}/synapsor.runner.json`;
+var referenceDemoContainer = "synapsor_runner_reference_support_billing";
+var referenceDemoDatabase = "synapsor_reference_support_billing";
+var referenceDemoEnv = {
+  REFERENCE_POSTGRES_READ_URL: "postgresql://synapsor_reader:synapsor_reader_password@localhost:55435/synapsor_reference_support_billing",
+  REFERENCE_POSTGRES_WRITE_URL: "postgresql://synapsor_writer:synapsor_writer_password@localhost:55435/synapsor_reference_support_billing",
+  SYNAPSOR_TENANT_ID: "acme",
+  SYNAPSOR_PRINCIPAL: "local_reviewer",
+  SYNAPSOR_ENGINE: "postgres",
+  SYNAPSOR_DATABASE_URL: "postgresql://synapsor_writer:synapsor_writer_password@localhost:55435/synapsor_reference_support_billing",
+  SYNAPSOR_RUNNER_ID: "synapsor_demo_runner",
+  SYNAPSOR_SOURCE_ID: "app_postgres",
+  SYNAPSOR_CONTROL_PLANE_URL: "http://127.0.0.1:0",
+  SYNAPSOR_RUNNER_TOKEN: "syn_wbr_demo_local"
+};
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === "--help" || command === "-h") {
+    usage([]);
+    return 0;
+  }
+  if (!isKnownTopLevelCommand(command)) {
+    process2.stderr.write(`Unknown command: ${cliCommandName()} ${command}
+
+Try:
+${cliCommandName()} --help
+`);
+    return 2;
+  }
+  if (isHelpRequest(rest)) {
+    usage([command, ...rest.filter((arg) => arg !== "--help" && arg !== "-h")]);
+    return 0;
+  }
+  if (command === "help") {
+    usage(rest);
+    return 0;
   }
   if (command === "init") return init(rest);
   if (command === "inspect") return inspect(rest);
@@ -6082,11 +6861,15 @@ ${cliCommandName()} --help
   if (command === "apply") return apply(rest);
   if (command === "propose") return propose(rest);
   if (command === "audit") return audit(rest);
-  if (command === "start") return start();
+  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);
+  if (command === "smoke") return smoke(rest);
   if (command === "tools") return tools(rest);
+  if (command === "writeback") return writeback(rest);
+  if (command === "handler") return handler(rest);
   if (command === "onboard") return onboard(rest);
   if (command === "demo") return demo(rest);
   if (command === "recipes") return recipes(rest);
@@ -6097,6 +6880,7 @@ ${cliCommandName()} --help
   if (command === "query-audit") return queryAudit(rest);
   if (command === "receipts") return receipts(rest);
   if (command === "activity") return activity(rest);
+  if (command === "events") return events(rest);
   if (command === "store") return storeCommand(rest);
   if (command === "shadow") return shadow(rest);
   if (command === "ui") return ui(rest);
@@ -6108,11 +6892,16 @@ ${cliCommandName()} --help
   return 2;
 }
 async function init(args) {
+  const answersPath = optionalArg(args, "--answers");
+  if (answersPath) {
+    return initFromAnswers(args, answersPath);
+  }
   const specPath = optionalArg(args, "--spec");
   if (specPath) {
     return initFromSpec(args, specPath);
   }
-  if (args.includes("--wizard") || process2.stdin.isTTY && process2.stdout.isTTY && !args.includes("--starter")) {
+  const scripted = isScriptedOnboardingArgs(args);
+  if (args.includes("--wizard") || process2.stdin.isTTY && process2.stdout.isTTY && !args.includes("--starter") && !scripted) {
     return runInitWizard(args);
   }
   const inspectionJson = optionalArg(args, "--inspection-json");
@@ -6278,12 +7067,94 @@ async function runInitWizard(args, options = {}) {
       if (transitionFromColumns.length > 0) ensureColumnsExist(transitionFromColumns, columns, "transition from");
     }
   }
-  const namespace = await askDefault(ask, "Capability namespace", optionalArg(args, "--namespace") ?? recipeSpec?.namespace ?? "source");
-  const objectName = await askDefault(ask, "Business object name", optionalArg(args, "--object-name") ?? recipeSpec?.object_name ?? safeObjectName(table.name));
+  const inferredObjectName = recipeSpec?.object_name ?? safeObjectName(table.name);
+  const namespace = await askDefault(ask, "Capability namespace", optionalArg(args, "--namespace") ?? recipeSpec?.namespace ?? inferCapabilityNamespace(table.name));
+  const objectName = await askDefault(ask, "Business object name", optionalArg(args, "--object-name") ?? inferredObjectName);
   const lookupArg = await askDefault(ask, "Model-visible object id argument", optionalArg(args, "--lookup-arg") ?? recipeSpec?.lookup_arg ?? `${objectName}_id`);
-  const writeUrlEnv = mode === "review" ? await askEnvName(ask, "Write URL env var for trusted apply path", optionalArg(args, "--write-url-env") ?? "SYNAPSOR_DATABASE_WRITE_URL") : optionalArg(args, "--write-url-env") ?? "SYNAPSOR_DATABASE_WRITE_URL";
+  const defaultInspectToolName = recipeSpec?.inspect_tool_name ?? `${namespace}.inspect_${objectName}`;
+  const inspectToolName = await askDefault(
+    ask,
+    "Read capability name",
+    optionalArg(args, "--read-tool") ?? optionalArg(args, "--inspect-tool-name") ?? defaultInspectToolName
+  );
+  const defaultProposalToolName = recipeSpec?.proposal_tool_name ?? `${namespace}.propose_${objectName}_update`;
+  const proposalToolName = mode === "read_only" ? void 0 : await askDefault(
+    ask,
+    "Proposal capability name",
+    optionalArg(args, "--proposal-tool") ?? optionalArg(args, "--proposal-tool-name") ?? defaultProposalToolName
+  );
+  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")) : "v2", ["v2", "v1", "default"]);
+  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,
+      "Writeback path",
+      optionalArg(args, "--writeback") ?? "sql_update",
+      ["sql_update", "http_handler", "command_handler"]
+    );
+    if (writebackPath === "sql_update") {
+      writeUrlEnv = await askEnvName(ask, "Write URL env var for trusted direct SQL apply", writeUrlEnv ?? "SYNAPSOR_DATABASE_WRITE_URL");
+      writeback2 = { executor: "sql_update" };
+    } else if (writebackPath === "http_handler") {
+      const urlEnv = await askEnvName(ask, "App-owned HTTP handler URL env var", optionalArg(args, "--handler-url-env") ?? "SYNAPSOR_APP_WRITEBACK_URL");
+      const tokenEnv = await askOptionalEnvName(ask, "Optional HTTP handler bearer-token env var", optionalArg(args, "--handler-token-env") ?? "");
+      const signingSecretEnv = await askOptionalEnvName(ask, "Optional HTTP handler HMAC signing-secret env var", optionalArg(args, "--handler-signing-secret-env") ?? "");
+      writeback2 = {
+        executor: "http_handler",
+        executor_name: optionalArg(args, "--executor-name"),
+        handler_url_env: urlEnv,
+        ...tokenEnv ? { handler_token_env: tokenEnv } : {},
+        ...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-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 = {
+        executor: "command_handler",
+        executor_name: optionalArg(args, "--executor-name"),
+        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-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");
-  const spec = {
+  let spec = {
     version: 1,
     engine: inspection.engine,
     mode,
@@ -6298,9 +7169,14 @@ async function runInitWizard(args, options = {}) {
     conflict_column: conflictAnswer || void 0,
     namespace,
     object_name: objectName,
-    inspect_tool_name: recipeSpec?.inspect_tool_name,
-    proposal_tool_name: recipeSpec?.proposal_tool_name,
+    inspect_tool_name: inspectToolName,
+    proposal_tool_name: proposalToolName,
+    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,
@@ -6313,27 +7189,115 @@ async function runInitWizard(args, options = {}) {
     },
     approval: {
       required_role: approvalRole
-    }
+    },
+    writeback: writeback2
   };
-  const generated = generateRunnerConfigFromSpec(spec);
-  const tools2 = generated.config.capabilities.map((capability) => `${capability.name} (${capability.kind})`);
+  let generated = generateRunnerConfigFromSpec(spec);
   stdout.write("\nPreview:\n");
-  stdout.write(`  trusted context: tenant from ${tenantEnv}${singleTenantDev ? " (single-tenant dev source)" : tenantAnswer ? ` via ${tenantAnswer}` : ""}; principal from ${principalEnv}
+  printWizardContractPreview(stdout, { spec, generated, engine: inspection.engine, table });
+  if (generatedHandlerTemplate) {
+    stdout.write(`  handler template: ${generatedHandlerTemplate.output}
 `);
-  stdout.write(`  source: ${inspection.engine} ${table.schema}.${table.name}
+    stdout.write(`${handlerSecurityWarning}
 `);
-  stdout.write(`  mode: ${mode}
-`);
-  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");
+  }
+  const editPreview = await askDefault(ask, "Edit visible fields or capability names before writing? Type yes to edit", "no");
+  if (editPreview.toLowerCase() === "yes") {
+    const updatedVisible = parseColumnList(await askDefault(
+      ask,
+      "Final visible columns",
+      spec.visible_columns?.join(",") ?? visibleColumns.join(",")
+    ));
+    ensureColumnsExist(updatedVisible, columns, "visible");
+    const currentReadTool = spec.inspect_tool_name ?? generated.config.capabilities.find((capability) => capability.kind === "read")?.name ?? inspectToolName;
+    const updatedReadTool = await askDefault(ask, "Final read capability name", currentReadTool);
+    const currentProposalTool = spec.proposal_tool_name ?? generated.config.capabilities.find((capability) => capability.kind === "proposal")?.name ?? proposalToolName ?? "";
+    const updatedProposalTool = spec.mode === "read_only" ? void 0 : await askDefault(ask, "Final proposal capability name", currentProposalTool);
+    spec = {
+      ...spec,
+      visible_columns: updatedVisible,
+      inspect_tool_name: updatedReadTool,
+      proposal_tool_name: updatedProposalTool
+    };
+    generated = generateRunnerConfigFromSpec(spec);
+    stdout.write("\nUpdated preview:\n");
+    printWizardContractPreview(stdout, { spec, generated, engine: inspection.engine, table });
+  }
+  const generatedCapabilities = generated.config.capabilities;
+  const smokeToolName = generatedCapabilities[0]?.name ?? "<inspect_tool>";
   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");
-  await writeGeneratedOnboardingFiles(outputArg(args) ?? "synapsor.runner.json", generated, args.includes("--force"));
-  stdout.write(`Next: run \`${cliCommandName()} doctor --config synapsor.runner.json\`, then \`${cliCommandName()} mcp serve --config synapsor.runner.json --store ./.synapsor/local.db\`.
+  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}
+`);
+    const smoke2 = await maybeRunGeneratedSmokeCall({
+      config: generated.config,
+      env: options.env ?? process2.env,
+      input: { [lookupArg]: smokeObjectId },
+      readUrlEnv: configDatabaseUrlEnv,
+      tenantEnv,
+      principalEnv,
+      readRow: options.readRow,
+      storePath: defaultStorePath,
+      toolName: smokeToolName
+    });
+    stdout.write(smoke2);
+  }
+  stdout.write("Next:\n");
+  stdout.write(`  1. Set trusted env vars from .env.example, then run: ${cliCommandName()} doctor --config ${outputPath}
+`);
+  if (smokeObjectId) {
+    stdout.write(`  2. Smoke-call the read capability: ${cliCommandName()} smoke call ${smokeToolName} --input ${generatedSmokeInputPath} --config ${outputPath} --store ${defaultStorePath}
+`);
+  } else {
+    stdout.write(`  2. Smoke-call a real row: ${cliCommandName()} smoke call ${smokeToolName} --json '{"${lookupArg}":"<real_id>"}' --config ${outputPath} --store ${defaultStorePath}
+`);
+  }
+  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;
 }
+function printWizardContractPreview(stdout, input) {
+  const capabilities = input.generated.config.capabilities;
+  const tools2 = capabilities.map((capability) => `${capability.name} (${capability.kind})`);
+  const readCapability = capabilities.find((capability) => capability.kind === "read")?.name ?? input.spec.inspect_tool_name ?? "<read_tool>";
+  const proposalCapability = capabilities.find((capability) => capability.kind === "proposal")?.name ?? input.spec.proposal_tool_name;
+  const visibleColumns = input.spec.visible_columns ?? [];
+  const tenantEnv = input.spec.trusted_context?.tenant_id_env ?? "SYNAPSOR_TENANT_ID";
+  const principalEnv = input.spec.trusted_context?.principal_env ?? "SYNAPSOR_PRINCIPAL";
+  const visiblePreview = visibleColumns.length <= 12 ? visibleColumns.join(", ") : `${visibleColumns.slice(0, 12).join(", ")} (+${visibleColumns.length - 12} more)`;
+  stdout.write(`  trusted context: tenant from ${tenantEnv}${input.spec.single_tenant_dev ? " (single-tenant dev source)" : input.spec.tenant_key ? ` via ${input.spec.tenant_key}` : ""}; principal from ${principalEnv}
+`);
+  stdout.write(`  source: ${input.engine} ${input.table.schema}.${input.table.name}
+`);
+  stdout.write(`  primary key: ${input.spec.primary_key}${input.spec.conflict_column ? `; conflict guard: ${input.spec.conflict_column}` : ""}
+`);
+  stdout.write(`  visible fields: ${visiblePreview || "none"}
+`);
+  stdout.write(`  mode: ${input.spec.mode}
+`);
+  stdout.write(`  result envelope: ${input.spec.result_format ? `v${input.spec.result_format}` : "default"}
+`);
+  stdout.write(`  writeback path: ${input.spec.writeback?.executor ?? (input.spec.mode === "review" ? "sql_update" : "none")}
+`);
+  stdout.write(`  read capability: ${readCapability}
+`);
+  if (proposalCapability) stdout.write(`  proposal capability: ${proposalCapability}
+`);
+  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");
+}
 async function initFromSpec(args, specPath) {
   if (!args.includes("--non-interactive")) {
     throw new Error("init --spec requires --non-interactive so reviewed selections are explicit.");
@@ -6342,9 +7306,123 @@ async function initFromSpec(args, specPath) {
   const force = args.includes("--force");
   const spec = JSON.parse(await fs3.readFile(specPath, "utf8"));
   const generated = generateRunnerConfigFromSpec(spec);
+  if (args.includes("--dry-run")) {
+    process2.stdout.write(`${JSON.stringify(generated.config, null, 2)}
+`);
+    return 0;
+  }
   await writeGeneratedOnboardingFiles(output, generated, force);
   return 0;
 }
+async function initFromAnswers(args, answersPath) {
+  const output = outputArg(args) ?? "synapsor.runner.json";
+  const force = args.includes("--force");
+  const raw = JSON.parse(await fs3.readFile(answersPath, "utf8"));
+  const spec = answersToSelectionSpec(raw);
+  const generated = generateRunnerConfigFromSpec(spec);
+  if (args.includes("--dry-run")) {
+    process2.stdout.write(`${JSON.stringify(generated.config, null, 2)}
+`);
+    return 0;
+  }
+  await writeGeneratedOnboardingFiles(output, generated, force);
+  await maybeWriteHandlerTemplateForArgs(args, spec.writeback);
+  return 0;
+}
+function isScriptedOnboardingArgs(args) {
+  return args.includes("--yes") || args.includes("--non-interactive") || args.includes("--dry-run") || Boolean(optionalArg(args, "--answers")) || Boolean(optionalArg(args, "--inspection-json")) || Boolean(optionalArg(args, "--table"));
+}
+function answersToSelectionSpec(raw) {
+  if (!isRecord6(raw)) throw new Error("--answers file must contain a JSON object");
+  const mode = stringValue(raw.mode) ?? "review";
+  if (!["read_only", "shadow", "review"].includes(mode)) throw new Error("answers.mode must be read_only, shadow, or review");
+  const engine = stringValue(raw.engine) ?? "postgres";
+  if (engine !== "postgres" && engine !== "mysql") throw new Error("answers.engine must be postgres or mysql");
+  const table = requiredAnswerString(raw.table, "table");
+  const objectName = stringValue(raw.object_name) ?? safeObjectName(table);
+  const namespace = stringValue(raw.namespace) ?? inferCapabilityNamespace(table);
+  const writebackRaw = stringValue(raw.writeback) ?? "sql_update";
+  if (!["sql_update", "http_handler", "command_handler"].includes(writebackRaw)) throw new Error("answers.writeback must be sql_update, http_handler, or command_handler");
+  const writeback2 = writebackRaw === "sql_update" ? { executor: "sql_update" } : writebackRaw === "http_handler" ? {
+    executor: "http_handler",
+    handler_url_env: stringValue(raw.handler_url_env) ?? "SYNAPSOR_APP_WRITEBACK_URL",
+    ...stringValue(raw.handler_token_env) ? { handler_token_env: stringValue(raw.handler_token_env) } : {},
+    ...stringValue(raw.handler_signing_secret_env) ? { handler_signing_secret_env: stringValue(raw.handler_signing_secret_env) } : {}
+  } : {
+    executor: "command_handler",
+    handler_command_env: stringValue(raw.handler_command_env) ?? "SYNAPSOR_APP_WRITEBACK_COMMAND"
+  };
+  const patch = parsePatchBindings(arrayOrStringList(raw.patch), "--answers.patch");
+  const allowedColumns = arrayOrStringList(raw.allowed_columns);
+  return {
+    version: 1,
+    engine,
+    mode,
+    source_name: stringValue(raw.source_name),
+    read_url_env: stringValue(raw.read_url_env) ?? stringValue(raw.database_url_env) ?? "DATABASE_URL",
+    write_url_env: writeback2.executor === "sql_update" ? stringValue(raw.write_url_env) ?? "SYNAPSOR_DATABASE_WRITE_URL" : stringValue(raw.write_url_env),
+    schema: requiredAnswerString(raw.schema, "schema"),
+    table,
+    primary_key: requiredAnswerString(raw.primary_key, "primary_key"),
+    tenant_key: stringValue(raw.tenant_column) ?? stringValue(raw.tenant_key),
+    single_tenant_dev: raw.single_tenant_dev === true,
+    conflict_column: stringValue(raw.conflict_column),
+    namespace,
+    object_name: objectName,
+    inspect_tool_name: stringValue(raw.read_tool) ?? stringValue(raw.inspect_tool_name),
+    proposal_tool_name: stringValue(raw.proposal_tool) ?? stringValue(raw.proposal_tool_name),
+    lookup_arg: stringValue(raw.id_arg) ?? stringValue(raw.lookup_arg),
+    inspect_description: stringValue(raw.read_description) ?? stringValue(raw.inspect_description),
+    inspect_returns_hint: stringValue(raw.read_returns_hint) ?? stringValue(raw.inspect_returns_hint),
+    proposal_description: stringValue(raw.proposal_description),
+    proposal_returns_hint: stringValue(raw.proposal_returns_hint),
+    result_format: resultFormatFromAnswerValue(raw.result_format),
+    visible_columns: arrayOrStringList(raw.visible_columns),
+    allowed_columns: allowedColumns.length > 0 ? allowedColumns : void 0,
+    patch,
+    numeric_bounds: parseNumericBoundsInput(arrayOrStringList(raw.patch_bounds ?? raw.numeric_bounds).join(",")),
+    transition_guards: parseTransitionGuardsInput(arrayOrStringList(raw.status_guards ?? raw.transition_guards).join(",")),
+    trusted_context: {
+      tenant_id_env: stringValue(raw.tenant_env) ?? "SYNAPSOR_TENANT_ID",
+      principal_env: stringValue(raw.principal_env) ?? "SYNAPSOR_PRINCIPAL"
+    },
+    approval: {
+      required_role: stringValue(raw.approval_role) ?? "local_reviewer"
+    },
+    writeback: writeback2
+  };
+}
+async function maybeWriteHandlerTemplateForArgs(args, writeback2) {
+  if (!writeback2 || writeback2.executor === "sql_update" || args.includes("--no-emit-handler") || args.includes("--skip-handler-template")) return;
+  if (!args.includes("--emit-handler") && !optionalArg(args, "--handler-template") && !optionalArg(args, "--handler-output") && !optionalArg(args, "--handler-template-output")) return;
+  const defaultTemplate = writeback2.executor === "command_handler" ? "command" : "node-fastify";
+  const template = resolveHandlerTemplateName(optionalArg(args, "--handler-template") ?? defaultTemplate);
+  const output = optionalArg(args, "--handler-output") ?? optionalArg(args, "--handler-template-output") ?? handlerTemplateDefinitions[template].fileName;
+  await writeHandlerTemplateFile(template, output, args.includes("--force"));
+  process2.stdout.write(`created ${output}
+`);
+  process2.stdout.write(`${handlerSecurityWarning}
+`);
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function requiredAnswerString(value, field) {
+  const result = stringValue(value);
+  if (!result) throw new Error(`--answers missing ${field}`);
+  return result;
+}
+function arrayOrStringList(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item).trim()).filter(Boolean);
+  if (typeof value === "string") return value.split(",").map((item) => item.trim()).filter(Boolean);
+  return [];
+}
+function resultFormatFromAnswerValue(value) {
+  if (value === void 0 || value === null || value === "" || value === "default") return void 0;
+  if (value === 1 || value === "1" || value === "v1") return 1;
+  if (value === 2 || value === "2" || value === "v2") return 2;
+  throw new Error("result_format must be default, v1, v2, 1, or 2");
+}
 async function initFromInspection(args, inspection, databaseUrlEnv) {
   const tableName = optionalArg(args, "--table");
   if (!tableName) {
@@ -6368,7 +7446,7 @@ async function initFromInspection(args, inspection, databaseUrlEnv) {
     process2.stderr.write(`warning: no database primary-key constraint detected for ${table.schema}.${table.name}; using candidate column ${primaryKey}. Verify uniqueness before enabling writeback.
 `);
   }
-  const tenantKey = optionalArg(args, "--tenant-key") ?? table.suggestions.tenant_columns[0];
+  const tenantKey = optionalArg(args, "--tenant-column") ?? optionalArg(args, "--tenant-key") ?? table.suggestions.tenant_columns[0];
   const singleTenantDev = args.includes("--single-tenant-dev");
   if (!tenantKey && !singleTenantDev) {
     throw new Error(`--tenant-key is required for ${table.schema}.${table.name}, or pass --single-tenant-dev for a reviewed single-tenant dev source.`);
@@ -6389,22 +7467,33 @@ async function initFromInspection(args, inspection, databaseUrlEnv) {
   const numericBounds = parseNumericBoundsFlags(args);
   const transitionGuards = parseTransitionGuardFlags(args);
   const allowedColumns = listArg(args, "--allowed-columns") ?? Object.keys(patch);
+  const writeback2 = writebackSpecFromArgs(args);
+  const sqlWriteback = (writeback2?.executor ?? "sql_update") === "sql_update";
+  const objectName = optionalArg(args, "--object-name") ?? safeObjectName(table.name);
+  const namespace = optionalArg(args, "--namespace") ?? inferCapabilityNamespace(table.name);
   const spec = {
     version: 1,
     engine: inspection.engine,
     mode,
     source_name: optionalArg(args, "--source-name"),
     read_url_env: databaseUrlEnv,
-    write_url_env: optionalArg(args, "--write-url-env") ?? "SYNAPSOR_DATABASE_WRITE_URL",
+    write_url_env: sqlWriteback ? optionalArg(args, "--write-url-env") ?? "SYNAPSOR_DATABASE_WRITE_URL" : optionalArg(args, "--write-url-env"),
     schema: table.schema,
     table: table.name,
     primary_key: primaryKey,
     tenant_key: tenantKey,
     single_tenant_dev: singleTenantDev,
     conflict_column: conflictColumn,
-    namespace: optionalArg(args, "--namespace") ?? "source",
-    object_name: optionalArg(args, "--object-name"),
-    lookup_arg: optionalArg(args, "--lookup-arg"),
+    namespace,
+    object_name: objectName,
+    inspect_tool_name: optionalArg(args, "--read-tool") ?? optionalArg(args, "--inspect-tool-name"),
+    proposal_tool_name: optionalArg(args, "--proposal-tool") ?? optionalArg(args, "--proposal-tool-name"),
+    lookup_arg: optionalArg(args, "--id-arg") ?? optionalArg(args, "--lookup-arg"),
+    inspect_description: optionalArg(args, "--read-description") ?? optionalArg(args, "--inspect-description"),
+    inspect_returns_hint: optionalArg(args, "--read-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,
@@ -6416,17 +7505,24 @@ async function initFromInspection(args, inspection, databaseUrlEnv) {
     },
     approval: {
       required_role: optionalArg(args, "--approval-role") ?? "local_reviewer"
-    }
+    },
+    writeback: writeback2
   };
   const generated = generateRunnerConfigFromSpec(spec);
+  if (args.includes("--dry-run")) {
+    process2.stdout.write(`${JSON.stringify(generated.config, null, 2)}
+`);
+    return 0;
+  }
   await writeGeneratedOnboardingFiles(outputArg(args) ?? "synapsor.runner.json", generated, args.includes("--force"));
+  await maybeWriteHandlerTemplateForArgs(args, writeback2);
   process2.stdout.write(`selected ${table.schema}.${table.name} from ${inspection.engine} inspection
 `);
   process2.stdout.write(`exposed tools: ${generated.config.capabilities.map((capability) => capability.name).join(", ")}
 `);
   return 0;
 }
-async function writeGeneratedOnboardingFiles(output, generated, force) {
+async function writeGeneratedOnboardingFiles(output, generated, force, options = {}) {
   await writeFileGuarded(output, `${JSON.stringify(generated.config, null, 2)}
 `, force);
   await writeFileGuarded(".env.example", generated.envExample, force);
@@ -6440,8 +7536,46 @@ async function writeGeneratedOnboardingFiles(output, generated, force) {
 `);
   process2.stdout.write("created .env.example\n");
   process2.stdout.write("created MCP client snippets under .synapsor/mcp\n");
-  process2.stdout.write(`Next: set the referenced environment variables, run \`${cliCommandName()} config validate\`, then run \`${cliCommandName()} mcp serve\`.
+  if (options.printNext !== false) {
+    process2.stdout.write(`Next: set the referenced environment variables, run \`${cliCommandName()} config validate\`, then run \`${cliCommandName()} mcp serve\`.
 `);
+  }
+}
+async function writeGeneratedSmokeInputFile(lookupArg, objectId, force) {
+  await fs3.mkdir(path3.dirname(path3.resolve(generatedSmokeInputPath)), { recursive: true });
+  await writeFileGuarded(generatedSmokeInputPath, `${JSON.stringify({ [lookupArg]: objectId }, null, 2)}
+`, force);
+}
+async function maybeRunGeneratedSmokeCall(input) {
+  const required = uniqueStrings([input.readUrlEnv, input.tenantEnv, input.principalEnv]).filter((envName) => !input.env[envName]);
+  if (required.length > 0) {
+    return [
+      "Smoke call not run yet.",
+      `Missing trusted/runtime env vars: ${required.join(", ")}`,
+      "Set them from .env.example, then run the printed smoke command.",
+      ""
+    ].join("\n");
+  }
+  const store = new ProposalStore(input.storePath);
+  const runtime = createMcpRuntime(input.config, { store, env: input.env, readRow: input.readRow });
+  try {
+    const result = await runtime.callTool(input.toolName, input.input);
+    return [
+      "Smoke call ran successfully.",
+      "",
+      formatSmokeCallResult(input.toolName, input.input, result, input.storePath)
+    ].join("\n");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return [
+      "Smoke call attempted but did not pass.",
+      `Reason: ${message}`,
+      "The generated config was written. Fix the trusted env values or object id, then rerun the printed smoke command.",
+      ""
+    ].join("\n");
+  } finally {
+    runtime.close();
+  }
 }
 async function askTtyQuestion(question, defaultValue) {
   const rl = readline.createInterface({ input: process2.stdin, output: process2.stderr });
@@ -6466,12 +7600,49 @@ async function askEnvName(ask, question, defaultValue) {
   if (!/^[A-Z_][A-Z0-9_]*$/.test(answer)) throw new Error(`${question} must be an environment-variable name`);
   return answer;
 }
+async function askOptionalEnvName(ask, question, defaultValue) {
+  const answer = await askDefault(ask, question, defaultValue);
+  if (!answer) return void 0;
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(answer)) throw new Error(`${question} must be an environment-variable name`);
+  return answer;
+}
 async function askColumn(ask, question, defaultValue, columns) {
   const answer = await askDefault(ask, question, defaultValue);
   if (!answer) throw new Error(`${question} is required`);
   if (!columns.includes(answer)) throw new Error(`${question} ${answer} does not exist in selected table/view`);
   return answer;
 }
+function positiveIntegerOption(args, name) {
+  const raw = optionalArg(args, name);
+  if (!raw) return void 0;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) throw new Error(`${name} must be a positive integer`);
+  return value;
+}
+function writebackSpecFromArgs(args) {
+  const raw = optionalArg(args, "--writeback");
+  if (!raw) return void 0;
+  if (!["sql_update", "http_handler", "command_handler"].includes(raw)) {
+    throw new Error("--writeback must be sql_update, http_handler, or command_handler");
+  }
+  if (raw === "sql_update") return { executor: "sql_update" };
+  if (raw === "http_handler") {
+    return {
+      executor: "http_handler",
+      executor_name: optionalArg(args, "--executor-name"),
+      handler_url_env: optionalArg(args, "--handler-url-env") ?? "SYNAPSOR_APP_WRITEBACK_URL",
+      ...optionalArg(args, "--handler-token-env") ? { handler_token_env: optionalArg(args, "--handler-token-env") } : {},
+      ...optionalArg(args, "--handler-signing-secret-env") ? { handler_signing_secret_env: optionalArg(args, "--handler-signing-secret-env") } : {},
+      timeout_ms: positiveIntegerOption(args, "--handler-timeout-ms")
+    };
+  }
+  return {
+    executor: "command_handler",
+    executor_name: optionalArg(args, "--executor-name"),
+    handler_command_env: optionalArg(args, "--handler-command-env") ?? "SYNAPSOR_APP_WRITEBACK_COMMAND",
+    timeout_ms: positiveIntegerOption(args, "--handler-timeout-ms")
+  };
+}
 function parseColumnList(value) {
   return uniqueStrings(value.split(",").map((item) => item.trim()).filter(Boolean));
 }
@@ -6560,6 +7731,82 @@ function safeObjectName(tableName) {
   const base = tableName.replace(/[^A-Za-z0-9_]/g, "_").replace(/s$/, "");
   return /^[A-Za-z_]/.test(base) ? base : `record_${base}`;
 }
+function inferCapabilityNamespace(tableName) {
+  const objectName = safeObjectName(tableName);
+  const [firstPart] = objectName.split("_").filter(Boolean);
+  return firstPart ?? objectName;
+}
+function requiredWritebackEngine(args) {
+  const value = optionalArg(args, "--engine") ?? firstPositional(args);
+  if (value === "postgres" || value === "mysql") return value;
+  throw new Error("writeback command requires --engine postgres or --engine mysql");
+}
+function formatPostgresReceiptMigration(schema) {
+  if (!schema) {
+    return [
+      "-- Synapsor Runner direct SQL writeback receipt table.",
+      "-- Run this as a database owner, or grant CREATE on the target schema to the trusted writer.",
+      `${postgresReceiptMigration};`,
+      ""
+    ].join("\n");
+  }
+  const quotedSchema = quoteSqlIdentifier(schema, "postgres");
+  const qualified = `${quotedSchema}.synapsor_writeback_receipts`;
+  return [
+    "-- Synapsor Runner direct SQL writeback receipt table.",
+    "-- If you use a dedicated schema, ensure the writer connection search_path includes it.",
+    `CREATE SCHEMA IF NOT EXISTS ${quotedSchema};`,
+    `${postgresReceiptMigration.replace("synapsor_writeback_receipts", qualified)};`,
+    "",
+    "-- Example writer URL option for this schema:",
+    `-- postgresql://writer:...@host/db?options=-csearch_path%3D${encodeURIComponent(`${schema},public`)}`,
+    ""
+  ].join("\n");
+}
+function formatMysqlReceiptMigration(database) {
+  return [
+    "-- Synapsor Runner direct SQL writeback receipt table.",
+    "-- Run this in the database/schema used by the trusted writer connection.",
+    ...database ? [`USE ${quoteSqlIdentifier(database, "mysql")};`] : [],
+    `${mysqlReceiptMigration};`,
+    ""
+  ].join("\n");
+}
+function formatPostgresReceiptGrants(schema, writerRole) {
+  const quotedSchema = quoteSqlIdentifier(schema, "postgres");
+  const quotedRole = writerRole === "<writer_role>" ? writerRole : quoteSqlIdentifier(writerRole, "postgres");
+  const table = `${quotedSchema}.synapsor_writeback_receipts`;
+  return [
+    "-- Least-privilege grants for a pre-created Synapsor Runner receipt table.",
+    `GRANT USAGE ON SCHEMA ${quotedSchema} TO ${quotedRole};`,
+    `GRANT SELECT, INSERT, UPDATE ON TABLE ${table} TO ${quotedRole};`,
+    "",
+    "-- If you want Runner to create the receipt table itself, also grant CREATE on the schema:",
+    `-- GRANT CREATE ON SCHEMA ${quotedSchema} TO ${quotedRole};`,
+    "",
+    "-- If the schema is not public, make sure the writer connection search_path includes it.",
+    `-- ALTER ROLE ${quotedRole} SET search_path = ${schema}, public;`,
+    ""
+  ].join("\n");
+}
+function formatMysqlReceiptGrants(database, writerRole) {
+  const quotedDatabase = database === "<database_name>" ? "`<database_name>`" : quoteSqlIdentifier(database, "mysql");
+  const account = writerRole === "<writer_role>" ? "'<writer_user>'@'%'" : writerRole;
+  return [
+    "-- Least-privilege grants for a pre-created Synapsor Runner receipt table.",
+    `GRANT SELECT, INSERT, UPDATE ON ${quotedDatabase}.synapsor_writeback_receipts TO ${account};`,
+    "",
+    "-- If you want Runner to create the receipt table itself, also grant CREATE on the database:",
+    `-- GRANT CREATE ON ${quotedDatabase}.* TO ${account};`,
+    ""
+  ].join("\n");
+}
+function quoteSqlIdentifier(identifier, engine) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
+    throw new Error(`unsafe ${engine} identifier: ${identifier}`);
+  }
+  return engine === "postgres" ? `"${identifier}"` : `\`${identifier}\``;
+}
 function findInspectionTable(inspection, tableName, schemaName) {
   const candidates = inspection.tables.filter((table) => {
     if (schemaName && table.schema !== schemaName) return false;
@@ -6593,6 +7840,7 @@ function repeatedArgs(args, flag) {
 }
 function parsePatchFlags(args) {
   const patch = {};
+  Object.assign(patch, parsePatchBindings(repeatedArgs(args, "--patch"), "--patch"));
   for (const binding of repeatedArgs(args, "--patch-fixed")) {
     const [column, ...rest] = binding.split("=");
     const value = rest.join("=");
@@ -6607,8 +7855,27 @@ function parsePatchFlags(args) {
   }
   return patch;
 }
+function parsePatchBindings(bindings, label) {
+  const patch = {};
+  for (const rawBinding of bindings.flatMap((binding) => binding.split(",")).map((item) => item.trim()).filter(Boolean)) {
+    const [column, ...rest] = rawBinding.split("=");
+    const expression = rest.join("=");
+    if (!column || !expression) throw new Error(`${label} must use column=fixed:value or column=arg:name`);
+    const [kind, ...valueParts] = expression.split(":");
+    const value = valueParts.join(":");
+    if (!valueParts.length || !value) throw new Error(`${label} must use column=fixed:value or column=arg:name`);
+    if (kind === "fixed") {
+      patch[column] = { fixed: parseFixedPatchValue(value) };
+    } else if (kind === "arg") {
+      patch[column] = { from_arg: value };
+    } else {
+      throw new Error(`${label} patch kind for ${column} must be fixed or arg`);
+    }
+  }
+  return patch;
+}
 function parseNumericBoundsFlags(args) {
-  return parseNumericBoundsInput(repeatedArgs(args, "--numeric-bound").join(","));
+  return parseNumericBoundsInput([...repeatedArgs(args, "--numeric-bound"), ...repeatedArgs(args, "--patch-bounds")].join(","));
 }
 function parseNumericBoundsInput(input) {
   const bounds = {};
@@ -6640,7 +7907,7 @@ function formatNumericBounds(bounds) {
   return Object.entries(bounds).map(([column, bound]) => `${column}=${bound.minimum ?? ""}:${bound.maximum ?? ""}`).join(",");
 }
 function parseTransitionGuardFlags(args) {
-  return parseTransitionGuardsInput(repeatedArgs(args, "--transition-guard").join(","));
+  return parseTransitionGuardsInput([...repeatedArgs(args, "--transition-guard"), ...repeatedArgs(args, "--status-guards")].join(","));
 }
 function parseTransitionGuardsInput(input) {
   const guards = {};
@@ -6722,7 +7989,7 @@ function formatSchemaInspectionForCli(inspection, databaseUrlEnv) {
   }
   lines.push("");
   lines.push("Next:");
-  lines.push(`  ${cliCommandName()} init --wizard --from-env ${databaseUrlEnv}`);
+  lines.push(`  ${cliCommandName()} onboard db --from-env ${databaseUrlEnv}`);
   lines.push(`  ${cliCommandName()} tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db`);
   return `${lines.join("\n")}
 `;
@@ -6829,6 +8096,54 @@ function envPresenceCheck(envName, message) {
     message: process2.env[envName] ? `${envName} is set.` : message
   };
 }
+async function httpHandlerReachabilityCheck(executorName, rawUrl, timeoutMs) {
+  try {
+    const url = new URL(rawUrl);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return {
+        name: `executor:${executorName}:handler-reachability`,
+        ok: false,
+        level: "fail",
+        message: "HTTP handler URL must use http or https."
+      };
+    }
+  } catch {
+    return {
+      name: `executor:${executorName}:handler-reachability`,
+      ok: false,
+      level: "fail",
+      message: "HTTP handler URL env value is not a valid URL."
+    };
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), Math.max(1, Math.min(timeoutMs || 3e3, 1e4)));
+  try {
+    const response = await fetch(rawUrl, {
+      method: "OPTIONS",
+      headers: { accept: "application/json" },
+      signal: controller.signal
+    });
+    return {
+      name: `executor:${executorName}:handler-reachability`,
+      ok: true,
+      level: "pass",
+      message: `HTTP handler endpoint responded with HTTP ${response.status}; network path is reachable. This is not an apply/writeback probe.`
+    };
+  } catch (error) {
+    return {
+      name: `executor:${executorName}:handler-reachability`,
+      ok: false,
+      level: "fail",
+      message: `HTTP handler endpoint did not respond to the reachability probe (${safeReachabilityError(error)}).`
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function safeReachabilityError(error) {
+  if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) return "timeout";
+  return "connection failed";
+}
 async function inspectConfiguredSource(input) {
   if (!process2.env[input.source.read_url_env]) return;
   const capabilities = (input.config.capabilities ?? []).filter((capability) => capability.source === input.sourceName);
@@ -7101,7 +8416,7 @@ async function firstRunDoctor(args) {
   const configPath = optionalArg(args, "--config") ?? "synapsor.runner.json";
   const storePath = optionalArg(args, "--store") ?? "./.synapsor/local.db";
   const configExists = await fileExists(configPath);
-  checks.push(configExists ? pass("config", `Runner config exists at ${configPath}.`, "MCP serve/smoke need a reviewed config.", "No action needed.") : warn("config", `Runner config not found at ${configPath}.`, "Own-database MCP setup needs a generated config.", `Run ${cliCommandName()} demo first, or run ${cliCommandName()} init --wizard --from-env DATABASE_URL.`));
+  checks.push(configExists ? pass("config", `Runner config exists at ${configPath}.`, "MCP serve/smoke need a reviewed config.", "No action needed.") : warn("config", `Runner config not found at ${configPath}.`, "Own-database MCP setup needs a generated config.", `Run ${cliCommandName()} demo first, or run ${cliCommandName()} onboard db --from-env DATABASE_URL.`));
   if (configExists) {
     const parsedConfig = JSON.parse(await fs3.readFile(configPath, "utf8"));
     const validation = validateRunnerCapabilityConfig(parsedConfig);
@@ -7258,6 +8573,8 @@ function formatFirstRunDoctor(report) {
 async function localDoctor(args) {
   const configPath = optionalArg(args, "--config") ?? "synapsor.runner.json";
   const allowSharedCredential = args.includes("--allow-shared-credential");
+  const checkHandlers = args.includes("--check-handlers");
+  const checkWriteback = args.includes("--check-writeback") || args.includes("--check-db");
   const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
   const checks = [];
   const validation = validateRunnerCapabilityConfig(parsed);
@@ -7300,6 +8617,24 @@ async function localDoctor(args) {
         } else {
           checks.push({ name: `source:${sourceName}:write-url-env`, ok: false, level: "fail", message: "SQL writeback proposal capabilities require write_url_env for trusted writeback." });
         }
+        const writeUrl = source.write_url_env ? process2.env[source.write_url_env] : void 0;
+        if (checkWriteback && writeUrl) {
+          checks.push(...await directSqlWritebackDoctorChecks(parsed, sourceName, source, writeUrl));
+        } else if (checkWriteback) {
+          checks.push({
+            name: `source:${sourceName}:writeback-probe`,
+            ok: false,
+            level: "fail",
+            message: "Direct SQL writeback probe skipped because the writer env var is missing."
+          });
+        } else {
+          checks.push({
+            name: `source:${sourceName}:writeback-probe`,
+            ok: true,
+            level: "warn",
+            message: `Direct SQL writeback was not probed. Rerun doctor with --check-writeback to verify writer connectivity, receipt-table permissions, and rollback-only target-table access.`
+          });
+        }
       }
     }
     await inspectConfiguredSource({ config: parsed, sourceName, source, checks });
@@ -7308,10 +8643,34 @@ async function localDoctor(args) {
     if (!isRecord6(executor)) continue;
     if (executor.type === "http_handler") {
       const urlEnv = String(executor.url_env ?? "");
-      if (urlEnv) checks.push(envPresenceCheck(urlEnv, `${urlEnv} is required for http_handler executor ${executorName}.`));
+      if (urlEnv) {
+        checks.push(envPresenceCheck(urlEnv, `${urlEnv} is required for http_handler executor ${executorName}.`));
+        const handlerUrl = process2.env[urlEnv];
+        if (checkHandlers && handlerUrl) {
+          checks.push(await httpHandlerReachabilityCheck(executorName, handlerUrl, Number(executor.timeout_ms ?? 3e3)));
+        } else if (!checkHandlers) {
+          checks.push({
+            name: `executor:${executorName}:handler-reachability`,
+            ok: true,
+            level: "warn",
+            message: `Handler reachability was not probed for ${executorName}. Rerun doctor with --check-handlers to verify the network path without applying a proposal.`
+          });
+        }
+      }
       const auth = isRecord6(executor.auth) ? executor.auth : void 0;
       const tokenEnv = typeof auth?.token_env === "string" ? auth.token_env : void 0;
       if (tokenEnv) checks.push(envPresenceCheck(tokenEnv, `${tokenEnv} is required for http_handler executor ${executorName} bearer auth.`));
+      const signingSecretEnv = typeof executor.signing_secret_env === "string" ? executor.signing_secret_env : void 0;
+      if (signingSecretEnv) {
+        checks.push(envPresenceCheck(signingSecretEnv, `${signingSecretEnv} is required to sign http_handler requests for executor ${executorName}.`));
+      } else {
+        checks.push({
+          name: `executor:${executorName}:handler-signing`,
+          ok: true,
+          level: "warn",
+          message: `No signing_secret_env is configured for http_handler executor ${executorName}. HMAC signing is recommended unless the handler is loopback-only and protected by another trusted boundary.`
+        });
+      }
     }
     if (executor.type === "command_handler") {
       const commandEnv = String(executor.command_env ?? "");
@@ -7348,6 +8707,155 @@ async function localDoctor(args) {
   }
   return report.ok ? 0 : 1;
 }
+async function directSqlWritebackDoctorChecks(config, sourceName, source, writeUrl) {
+  const checks = [];
+  try {
+    const result = await adapters[source.engine].doctor({
+      controlPlaneUrl: "local",
+      runnerToken: "local",
+      runnerId: "doctor",
+      sourceId: sourceName,
+      databaseUrl: writeUrl,
+      engine: source.engine,
+      pollIntervalMs: 0,
+      logLevel: "error",
+      dryRun: true,
+      stateDir: "./state"
+    });
+    checks.push({
+      name: `source:${sourceName}:receipt-table-probe`,
+      ok: result.ok,
+      level: result.ok ? "pass" : "fail",
+      message: result.ok ? "Writer credential can reach the database and the receipt-table rollback probe succeeded." : `Writer receipt-table probe failed (${safeDatabaseProbeError(result.details)}). ${receiptTableGuidance(source.engine)}`
+    });
+  } catch (error) {
+    checks.push({
+      name: `source:${sourceName}:receipt-table-probe`,
+      ok: false,
+      level: "fail",
+      message: `Writer receipt-table probe failed (${safeDatabaseProbeError(error)}). ${receiptTableGuidance(source.engine)}`
+    });
+  }
+  for (const capability of directSqlProposalCapabilities(config, sourceName)) {
+    try {
+      await rollbackOnlyTargetProbe(source.engine, writeUrl, capability);
+      checks.push({
+        name: `capability:${capability.name}:writeback-target-probe`,
+        ok: true,
+        level: "pass",
+        message: `Rollback-only writer probe reached ${capability.target.schema}.${capability.target.table} and verified configured write columns without mutating business rows.`
+      });
+    } catch (error) {
+      checks.push({
+        name: `capability:${capability.name}:writeback-target-probe`,
+        ok: false,
+        level: "fail",
+        message: `Rollback-only writer probe failed for configured target ${capability.target.schema}.${capability.target.table} (${safeDatabaseProbeError(error)}). Verify writer SELECT/UPDATE on the target table and configured columns.`
+      });
+    }
+  }
+  return checks;
+}
+function directSqlProposalCapabilities(config, sourceName) {
+  return (config.capabilities ?? []).filter((capability) => {
+    if (capability.kind !== "proposal" || capability.source !== sourceName) return false;
+    return (capability.executor ?? "sql_update") === "sql_update";
+  });
+}
+async function rollbackOnlyTargetProbe(engine, databaseUrl, capability) {
+  if (engine === "postgres") {
+    await rollbackOnlyPostgresTargetProbe(databaseUrl, capability);
+    return;
+  }
+  await rollbackOnlyMysqlTargetProbe(databaseUrl, capability);
+}
+async function rollbackOnlyPostgresTargetProbe(databaseUrl, capability) {
+  const pg = await dynamicImportModule("pg");
+  const pool = new pg.Pool({ connectionString: databaseUrl });
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    try {
+      const table = `${quotePostgresIdentifier2(capability.target.schema)}.${quotePostgresIdentifier2(capability.target.table)}`;
+      const columns = proposalProbeColumns(capability).map(quotePostgresIdentifier2).join(", ");
+      await client.query(`SELECT ${columns} FROM ${table} WHERE false FOR UPDATE`);
+      for (const column of proposalUpdateProbeColumns(capability)) {
+        const quoted = quotePostgresIdentifier2(column);
+        await client.query(`UPDATE ${table} SET ${quoted} = ${quoted} WHERE false`);
+      }
+      await client.query("ROLLBACK");
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    }
+  } finally {
+    client.release();
+    await pool.end();
+  }
+}
+async function rollbackOnlyMysqlTargetProbe(databaseUrl, capability) {
+  const mysql4 = await dynamicImportModule("mysql2/promise");
+  const connection = await mysql4.createConnection({ uri: databaseUrl, dateStrings: true });
+  try {
+    await connection.beginTransaction();
+    try {
+      const table = `${quoteMysqlIdentifier2(capability.target.schema)}.${quoteMysqlIdentifier2(capability.target.table)}`;
+      const columns = proposalProbeColumns(capability).map(quoteMysqlIdentifier2).join(", ");
+      await connection.query(`SELECT ${columns} FROM ${table} WHERE 1 = 0 FOR UPDATE`);
+      for (const column of proposalUpdateProbeColumns(capability)) {
+        const quoted = quoteMysqlIdentifier2(column);
+        await connection.query(`UPDATE ${table} SET ${quoted} = ${quoted} WHERE 1 = 0`);
+      }
+      await connection.rollback();
+    } catch (error) {
+      await connection.rollback().catch(() => void 0);
+      throw error;
+    }
+  } finally {
+    await connection.end();
+  }
+}
+async function dynamicImportModule(specifier) {
+  const importer = new Function("specifier", "return import(specifier)");
+  return importer(specifier);
+}
+function proposalProbeColumns(capability) {
+  const columns = /* @__PURE__ */ new Set();
+  columns.add(capability.target.primary_key);
+  if (capability.target.tenant_key) columns.add(capability.target.tenant_key);
+  if (capability.conflict_guard?.column) columns.add(capability.conflict_guard.column);
+  for (const column of capability.visible_columns ?? []) columns.add(column);
+  for (const column of proposalUpdateProbeColumns(capability)) columns.add(column);
+  return [...columns];
+}
+function proposalUpdateProbeColumns(capability) {
+  const columns = /* @__PURE__ */ new Set();
+  for (const column of capability.allowed_columns ?? []) columns.add(column);
+  for (const column of Object.keys(capability.patch ?? {})) columns.add(column);
+  return [...columns];
+}
+function quotePostgresIdentifier2(value) {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+function quoteMysqlIdentifier2(value) {
+  return `\`${value.replace(/`/g, "``")}\``;
+}
+function safeDatabaseProbeError(error) {
+  const raw = typeof error === "string" ? error : error instanceof Error ? error.message : JSON.stringify(error ?? {});
+  const message = raw.toLowerCase();
+  if (/permission|denied|not authorized|insufficient|42501|er_tableaccess_denied|er_dbaccess_denied/.test(message)) return "permission denied";
+  if (/authentication|password|28p01|access denied for user|invalid authorization/.test(message)) return "authentication failed";
+  if (/timeout|timed out|etimedout/.test(message)) return "timeout";
+  if (/econnrefused|enotfound|eai_again|network|connection terminated|connection failed/.test(message)) return "connection failed";
+  if (/does not exist|unknown database|no such table|undefined_table|er_no_such_table|42p01/.test(message)) return "configured object not found";
+  return "database probe failed";
+}
+function receiptTableGuidance(engine) {
+  if (engine === "postgres") {
+    return `Pre-create the receipt table with "${cliCommandName()} writeback migration --engine postgres --schema synapsor" and grant it with "${cliCommandName()} writeback grants --engine postgres --schema synapsor --writer-role <writer_role>", or use an app-owned handler executor.`;
+  }
+  return `Pre-create the receipt table with "${cliCommandName()} writeback migration --engine mysql --schema <database_name>" and grant it with "${cliCommandName()} writeback grants --engine mysql --schema <database_name> --writer-role \\"'<writer>'@'%'\\"", or use an app-owned handler executor.`;
+}
 async function localDoctorStoreStats(storePath) {
   if (!storePath || storePath === ":memory:") return { path: storePath ?? "not configured", exists: storePath === ":memory:" };
   if (!await fileExists(storePath)) return { path: storePath, exists: false };
@@ -7522,8 +9030,8 @@ function findProposalCapability(config, proposal) {
   return capability;
 }
 function proposalExecutorName(proposal, capability) {
-  const writeback = proposal.change_set.writeback;
-  return capability.executor ?? (typeof writeback.executor === "string" ? writeback.executor : void 0) ?? "sql_update";
+  const writeback2 = proposal.change_set.writeback;
+  return capability.executor ?? (typeof writeback2.executor === "string" ? writeback2.executor : void 0) ?? "sql_update";
 }
 function executorConfig(config, executorName) {
   const raw = config.executors?.[executorName];
@@ -7533,6 +9041,9 @@ function executorConfig(config, executorName) {
   if (raw.type === "sql_update") return { type: "sql_update" };
   throw new Error(`executor ${executorName} has unsupported type`);
 }
+function signHandlerRequestBody(body, secret) {
+  return `sha256=${crypto5.createHmac("sha256", secret).update(body).digest("hex")}`;
+}
 async function applyHttpHandlerProposal(input) {
   const duplicate = duplicateHandlerReceipt(input.store, input.proposalId);
   if (duplicate) return alreadyAppliedReceipt(duplicate.receipt, input.runnerId);
@@ -7557,6 +9068,21 @@ async function applyHttpHandlerProposal(input) {
     if (!token) throw new Error(`${input.executor.auth.token_env} is not set`);
     headers.authorization = `Bearer ${token}`;
   }
+  const issuedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const requestBody = JSON.stringify({
+    protocol_version: "1.0",
+    ...prepared.request,
+    issued_at: issuedAt,
+    executor: input.executorName,
+    dry_run: input.dryRun
+  });
+  headers["x-synapsor-issued-at"] = issuedAt;
+  headers["x-synapsor-proposal-id"] = prepared.proposal.proposal_id;
+  if (input.executor.signing_secret_env) {
+    const signingSecret = input.env[input.executor.signing_secret_env];
+    if (!signingSecret) throw new Error(`${input.executor.signing_secret_env} is not set`);
+    headers["x-synapsor-signature"] = signHandlerRequestBody(requestBody, signingSecret);
+  }
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), Math.max(1, input.executor.timeout_ms ?? 5e3));
   let receipt;
@@ -7564,7 +9090,7 @@ async function applyHttpHandlerProposal(input) {
     const response = await fetch(url, {
       method: input.executor.method ?? "POST",
       headers,
-      body: JSON.stringify({ ...prepared.request, executor: input.executorName, dry_run: input.dryRun }),
+      body: requestBody,
       signal: controller.signal
     });
     const text = await response.text();
@@ -7937,7 +9463,13 @@ function capabilityMatchesJob(capability, job) {
   if (reviewedAllowed.size === 0) return false;
   return Object.keys(job.patch).every((column) => reviewedAllowed.has(column));
 }
-async function start() {
+async function start(args = []) {
+  if (args.length > 0) {
+    if (args.includes("--from-env") || args.includes("--schema") || args.includes("--mode") || args.includes("--engine")) {
+      return onboard(["db", ...args]);
+    }
+    throw new Error(`start accepts own-database onboarding flags such as --from-env DATABASE_URL, or no flags for the legacy polling worker. Unknown start arguments: ${args.join(" ")}`);
+  }
   const config = loadConfig();
   const controller = new AbortController();
   process2.on("SIGINT", () => controller.abort());
@@ -7945,9 +9477,211 @@ async function start() {
   await startPolling(config, adapters, controller.signal);
   return 0;
 }
+async function up(args = []) {
+  const allowed = /* @__PURE__ */ new Set([
+    "--config",
+    "--store",
+    "--transport",
+    "--serve",
+    "--with-handler",
+    "--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 serveRequested = args.includes("--serve");
+  const transport = optionalArg(args, "--transport") ?? (serveRequested ? "streamable-http" : "stdio");
+  if (transport !== "stdio" && transport !== "streamable-http") {
+    throw new Error("--transport must be stdio or streamable-http");
+  }
+  if (serveRequested && transport === "stdio") {
+    throw new Error("up --serve starts the Streamable HTTP MCP server. Omit --transport or use --transport streamable-http; for stdio, use mcp client-config so the client launches Runner.");
+  }
+  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,
+    serveRequested,
+    storePath,
+    transport
+  }));
+  if (args.includes("--with-handler") || 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") || !serveRequested) return boundary.ok ? 0 : 1;
+  if (!boundary.ok) return 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}`,
+    `Serve now: ${input.serveRequested ? "yes" : "no"}`,
+    `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"})`,
+      input.serveRequested ? input.dryRun ? "  Status: dry run only; server not started." : "  Status: starting after this checklist." : `  Start command: ${cliCommandName()} up --serve --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();
+  if (subcommand === "start") return start(rest);
+  if (subcommand === "up") return up(rest);
   if (subcommand === "doctor") return doctor(rest);
   usage();
   return 2;
@@ -7986,7 +9720,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.8").trim();
+  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0").trim();
   const engines = normalizeEngines(parsed.cloud.engines);
   const capabilities = normalizeCapabilities(parsed.cloud.capabilities);
   const client = new ControlPlaneClient({
@@ -8037,8 +9771,10 @@ async function mcp(args) {
   const [subcommand, ...rest] = args;
   if (subcommand === "serve") return mcpServe(rest);
   if (subcommand === "serve-http") return mcpServeHttp(rest);
+  if (subcommand === "serve-streamable-http") return mcpServeStreamableHttp(rest);
   if (subcommand === "audit") return mcpAudit(rest);
   if (subcommand === "config") return mcpConfig(rest);
+  if (subcommand === "client-config") return mcpConfigure(rest);
   if (subcommand === "configure") return mcpConfigure(rest);
   if (subcommand === "smoke") return mcpSmoke(rest);
   usage(["mcp"]);
@@ -8047,9 +9783,158 @@ async function mcp(args) {
 async function tools(args) {
   const [subcommand, ...rest] = args;
   if (subcommand === "preview") return toolsPreview(rest);
+  if (subcommand === "list") return toolsPreview(rest);
   usage(["tools"]);
   return 2;
 }
+async function smoke(args) {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "call") return smokeCall(rest);
+  if (subcommand === "boundary") return mcpSmoke(rest);
+  usage(["smoke"]);
+  return 2;
+}
+async function writeback(args) {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "doctor") return writebackDoctor(rest);
+  if (subcommand === "migration") return writebackMigration(rest);
+  if (subcommand === "grants") return writebackGrants(rest);
+  usage(["writeback"]);
+  return 2;
+}
+async function handler(args) {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "template") return handlerTemplate(rest);
+  usage(["handler"]);
+  return 2;
+}
+async function handlerTemplate(args) {
+  const allowed = /* @__PURE__ */ new Set(["--list", "--output", "--out", "--stdout", "--force"]);
+  assertKnownOptions(args, allowed, "handler template");
+  if (args.includes("--list")) {
+    process2.stdout.write(formatHandlerTemplateList());
+    return 0;
+  }
+  const requested = positional(args, 0);
+  if (!requested) throw new Error("handler template requires <node-fastify|python-fastapi|command>, or use --list");
+  const name = resolveHandlerTemplateName(requested);
+  const definition = handlerTemplateDefinitions[name];
+  const content = definition.content;
+  if (args.includes("--stdout")) {
+    process2.stdout.write(content);
+    return 0;
+  }
+  const output = outputArg(args) ?? definition.fileName;
+  await writeHandlerTemplateFile(name, output, args.includes("--force"));
+  process2.stdout.write(`created ${output}
+`);
+  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`,
+    `  ${cliCommandName()} handler template command --output ./synapsor-command-handler.mjs`,
+    ""
+  ].join("\n");
+}
+function resolveHandlerTemplateName(value) {
+  const normalized = value.trim().toLowerCase();
+  for (const [name, definition] of Object.entries(handlerTemplateDefinitions)) {
+    if (normalized === name || definition.aliases.includes(normalized)) return name;
+  }
+  throw new Error(`unknown handler template: ${value}. Use ${cliCommandName()} handler template --list`);
+}
+async function writebackDoctor(args) {
+  const configPath = optionalArg(args, "--config") ?? defaultConfigPath;
+  const config = await readRuntimeConfig(configPath);
+  const checkDb = args.includes("--check-db");
+  const sqlSources = Object.entries(config.sources ?? {}).filter(([sourceName]) => sourceNeedsSqlWriteback(config, sourceName));
+  const lines = [
+    "Synapsor writeback doctor",
+    `Config: ${configPath}`,
+    ""
+  ];
+  if (sqlSources.length === 0) {
+    lines.push("No direct SQL writeback sources found.", "Rich writes can use app-owned http_handler or command_handler executors without Runner creating receipt tables.", "");
+    process2.stdout.write(lines.join("\n"));
+    return 0;
+  }
+  let ok = true;
+  for (const [sourceName, source] of sqlSources) {
+    const writeEnv = source.write_url_env;
+    const writeUrl = writeEnv ? process2.env[writeEnv] : void 0;
+    lines.push(`Source: ${sourceName}`);
+    lines.push(`  engine: ${source.engine}`);
+    lines.push(`  writer env: ${writeEnv ?? "(missing write_url_env)"}`);
+    lines.push(`  env status: ${writeUrl ? "set" : "missing"}`);
+    lines.push("  receipt table: synapsor_writeback_receipts");
+    if (!writeEnv || !writeUrl) ok = false;
+    if (checkDb && writeUrl) {
+      const result = await adapters[source.engine].doctor({
+        controlPlaneUrl: "local",
+        runnerToken: "local",
+        runnerId: "writeback-doctor",
+        sourceId: sourceName,
+        databaseUrl: writeUrl,
+        engine: source.engine,
+        pollIntervalMs: 0,
+        logLevel: "error",
+        dryRun: true,
+        stateDir: "./state"
+      });
+      lines.push(`  db check: ${result.ok ? "ok" : "failed"}`);
+      lines.push(`  details: ${JSON.stringify(redactConfig(result.details ?? {}))}`);
+      if (!result.ok) ok = false;
+    } else if (checkDb) {
+      lines.push("  db check: skipped because writer env is missing");
+    }
+    lines.push("");
+  }
+  lines.push("Next:");
+  lines.push(`  ${cliCommandName()} writeback migration --engine postgres`);
+  lines.push(`  ${cliCommandName()} writeback grants --engine postgres --writer-role <writer_role>`);
+  lines.push("");
+  process2.stdout.write(lines.join("\n"));
+  return ok ? 0 : 1;
+}
+async function writebackMigration(args) {
+  const engine = requiredWritebackEngine(args);
+  const schema = optionalArg(args, "--schema");
+  if (engine === "postgres") {
+    process2.stdout.write(formatPostgresReceiptMigration(schema));
+    return 0;
+  }
+  process2.stdout.write(formatMysqlReceiptMigration(schema));
+  return 0;
+}
+async function writebackGrants(args) {
+  const engine = requiredWritebackEngine(args);
+  const writerRole = optionalArg(args, "--writer-role") ?? "<writer_role>";
+  const schema = optionalArg(args, "--schema") ?? (engine === "postgres" ? "public" : "<database_name>");
+  if (engine === "postgres") {
+    process2.stdout.write(formatPostgresReceiptGrants(schema, writerRole));
+    return 0;
+  }
+  process2.stdout.write(formatMysqlReceiptGrants(schema, writerRole));
+  return 0;
+}
 async function onboard(args) {
   const [subcommand, ...rest] = args;
   if (subcommand !== "db") {
@@ -8060,8 +9945,10 @@ async function onboard(args) {
   process2.stdout.write("You will inspect metadata, choose one table/view, confirm safety rules, and generate semantic MCP tools without writing JSON by hand.\n\n");
   const outputPath = outputArg(rest) ?? "synapsor.runner.json";
   const storePath = optionalArg(rest, "--store") ?? "./.synapsor/local.db";
-  const result = await runInitWizard(["--wizard", ...rest]);
+  const scripted = isScriptedOnboardingArgs(rest);
+  const result = scripted ? await init(["--non-interactive", ...rest]) : await runInitWizard(["--wizard", ...rest]);
   if (result !== 0) return result;
+  if (rest.includes("--dry-run")) return 0;
   process2.stdout.write("\nValidation:\n");
   const configCode = await configValidate(["--config", outputPath]);
   const smokeCode = await mcpSmoke(["--config", outputPath, "--store", storePath]);
@@ -8075,7 +9962,7 @@ async function onboard(args) {
    ${cliCommandName()} mcp serve --config ${outputPath} --store ${storePath}
 `);
   process2.stdout.write(`2. Open local UI:
-   ${cliCommandName()} ui --tour --config ${outputPath} --store ${storePath}
+   ${cliCommandName()} ui --open --tour --config ${outputPath} --store ${storePath}
 `);
   process2.stdout.write("3. Approve/apply only after setting a trusted write credential and reviewing the proposal.\n");
   return configCode === 0 && smokeCode === 0 ? 0 : 1;
@@ -8173,7 +10060,7 @@ function formatQuickDemoDetails(seeded) {
     quickDemoStorePath,
     "",
     "If you ran this through one-off npx and did not install the package, prefix",
-    "follow-up commands with: npx -y -p @synapsor/runner@alpha synapsor-runner",
+    "follow-up commands with: npx -y -p @synapsor/runner synapsor-runner",
     "",
     "Raw MCP shape:",
     "execute_sql(sql: string)",
@@ -8299,7 +10186,7 @@ function quickDemoGuidedScreens(seeded) {
       body: [
         "Run this next:",
         "",
-        "npx -y -p @synapsor/runner@alpha synapsor-runner demo inspect",
+        "npx -y -p @synapsor/runner synapsor-runner demo inspect",
         "",
         "demo inspect shows the proposal, evidence, activity search, and replay commands.",
         "",
@@ -8318,7 +10205,7 @@ function quickDemoGuidedScreens(seeded) {
         "",
         "Use your own staging DB:",
         'export DATABASE_URL="postgres://..."',
-        `${cliCommandName()} inspect --from-env DATABASE_URL`,
+        `${cliCommandName()} onboard db --from-env DATABASE_URL`,
         "",
         "Done. You just saw Synapsor's core boundary: business tools for the model, approval/writeback outside the model, and replay for inspection."
       ]
@@ -8351,7 +10238,7 @@ async function waitForEnter(message, options) {
   }
 }
 function quickDemoInspectCommands(useNpx) {
-  const cmd = useNpx ? "npx -y -p @synapsor/runner@alpha synapsor-runner" : cliCommandName();
+  const cmd = useNpx ? "npx -y -p @synapsor/runner synapsor-runner" : cliCommandName();
   return [
     {
       label: "Proposal summary",
@@ -8556,44 +10443,122 @@ function quickDemoChangeSet() {
   };
 }
 async function mcpServe(args) {
+  const transport = optionalArg(args, "--transport") ?? "stdio";
+  if (transport === "streamable-http") return mcpServeStreamableHttp(args);
+  if (transport === "http" || transport === "json-rpc-http" || transport === "jsonrpc-http") return mcpServeHttp(args);
+  if (transport !== "stdio") throw new Error("--transport must be stdio, streamable-http, or http");
   const configPath = optionalArg(args, "--config") ?? process2.env.SYNAPSOR_MCP_CONFIG;
   const readOnly = args.includes("--read-only");
   const config = readOnly ? { ...await readRuntimeConfig(configPath ?? defaultConfigPath), mode: "read_only" } : void 0;
-  await serveStdio({
-    configPath,
-    storePath: optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE,
-    config
-  });
-  return 0;
+  const toolNameStyle = toolNameStyleOption(args);
+  const resultFormat = resultFormatOption(args);
+  const storePath = optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE;
+  const releaseLease = await writeStoreLease(storePath, "mcp", "stdio", args.includes("--allow-concurrent-store"));
+  try {
+    await serveStdio({
+      configPath,
+      storePath,
+      config,
+      toolNameStyle,
+      resultFormat
+    });
+    return 0;
+  } finally {
+    await releaseLease();
+  }
 }
 async function mcpServeHttp(args) {
+  process2.stderr.write([
+    "Warning: mcp serve-http is a legacy JSON-RPC bridge, not spec MCP Streamable HTTP.",
+    `For OpenAI Agents SDK or standard HTTP MCP clients, use: ${cliCommandName()} mcp serve --transport streamable-http`,
+    ""
+  ].join("\n"));
   const configPath = optionalArg(args, "--config") ?? process2.env.SYNAPSOR_MCP_CONFIG;
   const readOnly = args.includes("--read-only");
   const config = readOnly ? { ...await readRuntimeConfig(configPath ?? defaultConfigPath), mode: "read_only" } : void 0;
   const host = optionalArg(args, "--host") ?? "127.0.0.1";
   const port = Number(optionalArg(args, "--port") ?? "8765");
+  const resultFormat = resultFormatOption(args);
   if (!Number.isInteger(port) || port <= 0 || port > 65535) {
     throw new Error("--port must be an integer from 1 to 65535");
   }
   if (host === "0.0.0.0") {
     process2.stderr.write("Warning: binding Synapsor Runner HTTP MCP to 0.0.0.0 exposes model-facing tools on the network. Use TLS, private networking, authentication, and rate limits.\n");
   }
-  const server = await startHttpMcpServer({
-    configPath,
-    config,
-    storePath: optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE,
-    host,
-    port,
-    authTokenEnv: optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
-    devNoAuth: args.includes("--dev-no-auth"),
-    corsOrigin: optionalArg(args, "--cors-origin")
+  const storePath = optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE;
+  const releaseLease = await writeStoreLease(storePath, "mcp", "legacy-jsonrpc", args.includes("--allow-concurrent-store"));
+  let server;
+  try {
+    server = await startHttpMcpServer({
+      configPath,
+      config,
+      storePath,
+      host,
+      port,
+      authTokenEnv: optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
+      devNoAuth: args.includes("--dev-no-auth"),
+      corsOrigin: optionalArg(args, "--cors-origin"),
+      resultFormat
+    });
+  } catch (error) {
+    await releaseLease();
+    throw error;
+  }
+  process2.stderr.write("Press Ctrl+C to stop.\n");
+  await new Promise((resolve) => {
+    const stop = async () => {
+      process2.off("SIGINT", stop);
+      process2.off("SIGTERM", stop);
+      await server.close();
+      await releaseLease();
+      resolve();
+    };
+    process2.once("SIGINT", stop);
+    process2.once("SIGTERM", stop);
   });
+  return 0;
+}
+async function mcpServeStreamableHttp(args) {
+  const configPath = optionalArg(args, "--config") ?? process2.env.SYNAPSOR_MCP_CONFIG;
+  const readOnly = args.includes("--read-only");
+  const config = readOnly ? { ...await readRuntimeConfig(configPath ?? defaultConfigPath), mode: "read_only" } : void 0;
+  const toolNameStyle = toolNameStyleOption(args);
+  const resultFormat = resultFormatOption(args);
+  const host = optionalArg(args, "--host") ?? "127.0.0.1";
+  const port = Number(optionalArg(args, "--port") ?? "8766");
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("--port must be an integer from 1 to 65535");
+  }
+  if (host === "0.0.0.0") {
+    process2.stderr.write("Warning: binding Synapsor Runner Streamable HTTP MCP to 0.0.0.0 exposes model-facing tools on the network. Use TLS, private networking, authentication, and rate limits.\n");
+  }
+  const storePath = optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE;
+  const releaseLease = await writeStoreLease(storePath, "mcp", "streamable-http", args.includes("--allow-concurrent-store"));
+  let server;
+  try {
+    server = await startStreamableHttpMcpServer({
+      configPath,
+      config,
+      storePath,
+      host,
+      port,
+      toolNameStyle,
+      authTokenEnv: optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
+      devNoAuth: args.includes("--dev-no-auth"),
+      corsOrigin: optionalArg(args, "--cors-origin"),
+      resultFormat
+    });
+  } catch (error) {
+    await releaseLease();
+    throw error;
+  }
   process2.stderr.write("Press Ctrl+C to stop.\n");
   await new Promise((resolve) => {
     const stop = async () => {
       process2.off("SIGINT", stop);
       process2.off("SIGTERM", stop);
       await server.close();
+      await releaseLease();
       resolve();
     };
     process2.once("SIGINT", stop);
@@ -8601,6 +10566,107 @@ async function mcpServeHttp(args) {
   });
   return 0;
 }
+async function writeStoreLease(storePath, mode, transport, allowConcurrent) {
+  const resolved = resolveStorePathForLease(storePath);
+  if (!resolved) return async () => void 0;
+  await assertNoActiveStoreLease(resolved, allowConcurrent, "serve");
+  const leasePath = storeLeasePath(resolved);
+  const lease = {
+    pid: process2.pid,
+    mode,
+    transport,
+    store_path: resolved,
+    started_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await fs3.mkdir(path3.dirname(resolved), { recursive: true });
+  await fs3.writeFile(leasePath, `${JSON.stringify(lease, null, 2)}
+`, "utf8");
+  return async () => {
+    const current = await readStoreLease(resolved);
+    if (current?.pid === process2.pid && current.transport === transport) {
+      await fs3.rm(leasePath, { force: true });
+    }
+  };
+}
+async function assertNoActiveStoreLease(storePath, force, operation) {
+  const resolved = resolveStorePathForLease(storePath);
+  if (!resolved) return;
+  const lease = await readStoreLease(resolved);
+  if (!lease) return;
+  if (!pidIsActive(lease.pid)) {
+    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 --allow-concurrent-store/--force if you have verified it is safe.`;
+  if (!force) throw new Error(message);
+  process2.stderr.write(`Warning: ${message}
+`);
+}
+function resolveStorePathForLease(storePath) {
+  const value = storePath ?? process2.env.SYNAPSOR_LOCAL_STORE ?? "./.synapsor/local.db";
+  if (value === ":memory:") return void 0;
+  return path3.resolve(value);
+}
+function storeLeasePath(resolvedStorePath) {
+  return `${resolvedStorePath}.lease.json`;
+}
+async function readStoreLease(storePath) {
+  const resolved = resolveStorePathForLease(storePath);
+  if (!resolved) return void 0;
+  try {
+    const parsed = JSON.parse(await fs3.readFile(storeLeasePath(resolved), "utf8"));
+    if (typeof parsed.pid !== "number" || typeof parsed.mode !== "string" || typeof parsed.transport !== "string" || typeof parsed.started_at !== "string") {
+      return void 0;
+    }
+    return {
+      pid: parsed.pid,
+      mode: parsed.mode,
+      transport: parsed.transport,
+      store_path: typeof parsed.store_path === "string" ? parsed.store_path : resolved,
+      started_at: parsed.started_at
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    return void 0;
+  }
+}
+function pidIsActive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process2.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function toolNameStyleOption(args) {
+  const requestedStyle = optionalArg(args, "--tool-name-style");
+  const requestedAliasMode = optionalArg(args, "--alias-mode");
+  if (requestedStyle && requestedAliasMode && requestedStyle !== requestedAliasMode) {
+    throw new Error("--tool-name-style and --alias-mode must match when both are provided");
+  }
+  const requested = requestedAliasMode ?? requestedStyle;
+  if (args.includes("--openai-tool-aliases")) {
+    if (requested && requested !== "openai") throw new Error("--openai-tool-aliases cannot be combined with a non-openai alias mode");
+    return "openai";
+  }
+  if (!requested) return "canonical";
+  if (requested === "canonical" || requested === "openai" || requested === "both") return requested;
+  throw new Error("--alias-mode must be canonical, openai, or both");
+}
+function resultFormatOption(args) {
+  const requested = optionalArg(args, "--result-format");
+  if (!requested) return void 0;
+  if (requested === "1" || requested === "v1") return 1;
+  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)) {
@@ -8743,21 +10809,33 @@ function formatProposeResult(capabilityName, result, storePath) {
 `;
 }
 async function mcpConfigure(args) {
-  const client = optionalArg(args, "--client");
-  if (!client) throw new Error("mcp configure requires --client generic-stdio|claude-desktop|cursor|vscode");
+  const client = normalizeMcpClientName(optionalArg(args, "--client"));
+  if (!client) throw new Error("mcp configure requires --client generic-stdio|claude|claude-desktop|cursor|vscode|openai-agents");
   const useAbsolutePaths = args.includes("--absolute-paths");
   const rawConfigPath = optionalArg(args, "--config") ?? "./synapsor.runner.json";
   const rawStorePath = optionalArg(args, "--store") ?? "./.synapsor/local.db";
   const configPath = useAbsolutePaths ? path3.resolve(rawConfigPath) : rawConfigPath;
   const storePath = useAbsolutePaths ? path3.resolve(rawStorePath) : rawStorePath;
+  const transport = mcpClientConfigTransport(args, client);
+  const aliasMode = mcpClientConfigAliasMode(args, client);
+  const includeInstructions = args.includes("--include-instructions");
+  const host = optionalArg(args, "--host") ?? "127.0.0.1";
+  const port = Number(optionalArg(args, "--port") ?? "8766");
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("--port must be an integer from 1 to 65535");
+  }
+  const authTokenEnv = optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN";
   if (!await fileExists(rawConfigPath)) {
     process2.stderr.write(`Warning: config path does not exist yet: ${rawConfigPath}
 `);
   }
-  if (!path3.isAbsolute(configPath) || !path3.isAbsolute(storePath)) {
+  if (transport === "stdio" && (!path3.isAbsolute(configPath) || !path3.isAbsolute(storePath))) {
     process2.stderr.write("Warning: relative paths are resolved by the MCP client working directory. Use --absolute-paths if the client runs from another directory.\n");
   }
-  const snippet = mcpClientSnippet(client, configPath, storePath);
+  const snippet = mcpClientSnippet(client, configPath, storePath, { transport, aliasMode, host, port, authTokenEnv });
+  if (includeInstructions) {
+    snippet.agent_instructions = mcpAgentInstructions(client, aliasMode);
+  }
   if (args.includes("--write")) {
     const destination = optionalArg(args, "--destination");
     if (!destination) throw new Error("mcp configure --write requires --destination <path>");
@@ -8775,20 +10853,124 @@ async function mcpConfigure(args) {
 async function mcpConfig(args) {
   const [client, ...rest] = args;
   if (!client || client.startsWith("--")) return mcpConfigure(["--client", "claude-desktop", ...args]);
-  return mcpConfigure(["--client", client, ...rest]);
+  return mcpConfigure(["--client", normalizeMcpClientName(client) ?? client, ...rest]);
+}
+function normalizeMcpClientName(client) {
+  if (client === "claude") return "claude-desktop";
+  return client;
+}
+function mcpClientConfigTransport(args, client) {
+  const requested = optionalArg(args, "--transport") ?? (client === "openai-agents" ? "streamable-http" : "stdio");
+  if (requested === "stdio" || requested === "streamable-http") return requested;
+  if (requested === "http" || requested === "json-rpc-http" || requested === "jsonrpc-http") {
+    throw new Error("mcp config uses stdio or streamable-http. The lightweight JSON-RPC HTTP bridge is not a standard MCP client transport.");
+  }
+  throw new Error("--transport must be stdio or streamable-http");
+}
+function mcpClientConfigAliasMode(args, client) {
+  const requested = optionalArg(args, "--alias-mode");
+  const aliasMode = requested ?? (args.includes("--openai-tool-aliases") ? "openai" : client === "openai-agents" ? "openai" : "canonical");
+  if (aliasMode === "canonical" || aliasMode === "openai" || aliasMode === "both") return aliasMode;
+  throw new Error("--alias-mode must be canonical, openai, or both");
+}
+function serveArgsForClient(configPath, storePath, options) {
+  const args = options.transport === "streamable-http" ? [
+    "mcp",
+    "serve-streamable-http",
+    "--config",
+    configPath,
+    "--store",
+    storePath,
+    "--host",
+    options.host,
+    "--port",
+    String(options.port),
+    "--auth-token-env",
+    options.authTokenEnv
+  ] : ["mcp", "serve", "--config", configPath, "--store", storePath];
+  if (options.aliasMode !== "canonical") args.push("--alias-mode", options.aliasMode);
+  return args;
 }
-function mcpClientSnippet(client, configPath, storePath) {
-  const command = "synapsor";
-  const args = ["mcp", "serve", "--config", configPath, "--store", storePath];
+function mcpClientSnippet(client, configPath, storePath, options) {
+  const command = cliCommandName();
+  const args = serveArgsForClient(configPath, storePath, options);
   if (client === "generic" || client === "generic-stdio") return { command, args };
   if (client === "claude-desktop" || client === "cursor") {
+    if (options.transport !== "stdio") throw new Error(`${client} config output currently supports stdio. Use --transport stdio.`);
     return { mcpServers: { synapsor: { command, args } } };
   }
   if (client === "vscode") {
+    if (options.transport !== "stdio") throw new Error("vscode config output currently supports stdio. Use --transport stdio.");
     return { servers: { synapsor: { type: "stdio", command, args } } };
   }
+  if (client === "openai-agents") {
+    if (options.transport !== "streamable-http") throw new Error("openai-agents config output uses Streamable HTTP. Use --transport streamable-http.");
+    const url = `http://${options.host}:${options.port}/mcp`;
+    return {
+      transport: "streamable-http",
+      start_server: {
+        command,
+        args,
+        env: {
+          [options.authTokenEnv]: "<set-a-random-local-token>"
+        }
+      },
+      openai_agents_sdk: {
+        package: "openai-agents",
+        url,
+        headers_from_env: {
+          Authorization: `Bearer $${options.authTokenEnv}`
+        },
+        python: [
+          "import os",
+          "from agents.mcp import MCPServerStreamableHttp",
+          "",
+          "synapsor_mcp = MCPServerStreamableHttp(",
+          `    params={`,
+          `        "url": "${url}",`,
+          `        "headers": {"Authorization": f"Bearer {os.environ['${options.authTokenEnv}']}"},`,
+          "    }",
+          ")"
+        ].join("\n")
+      },
+      tool_names: {
+        canonical: "billing.inspect_invoice",
+        model_visible_with_alias_mode_openai: "billing__inspect_invoice",
+        alias_mode: options.aliasMode
+      },
+      notes: [
+        "Start the local Streamable HTTP MCP server before creating the OpenAI Agents SDK server.",
+        "OpenAI-facing configs should use --alias-mode openai because OpenAI function names cannot contain dots.",
+        "Runner maps aliases back to canonical Synapsor capability names and includes the canonical name in MCP tool metadata.",
+        "This config contains no database URLs, write credentials, API keys, or bearer token values."
+      ]
+    };
+  }
   throw new Error(`unsupported MCP client: ${client}`);
 }
+function mcpAgentInstructions(client, aliasMode) {
+  const toolNameNote = aliasMode === "openai" ? "OpenAI-facing tool names may use aliases such as billing__inspect_invoice. Treat the canonical Synapsor capability name in tool metadata/results as the audit name." : "Use the model-visible Synapsor tool names exactly as listed by the MCP client.";
+  return {
+    target_client: client,
+    alias_mode: aliasMode,
+    recommended_system_prompt: [
+      "Use Synapsor Runner tools in a propose-first pattern.",
+      "Inspect relevant records, policy rows, and other evidence before proposing a change.",
+      "Do not claim a database change was committed unless a result says source_database_changed: true.",
+      "Proposal tools create reviewable proposals only; they do not commit writes.",
+      "You cannot approve, apply, commit, or write back through model-facing MCP tools.",
+      "On VERSION_CONFLICT, re-inspect the record before proposing again.",
+      "Evidence handles are audit/replay handles; you do not need to call them during the turn.",
+      toolNameNote
+    ].join(" "),
+    checklist: [
+      "Inspect evidence before proposing.",
+      "Use trusted session scope; never ask the user/model for tenant or principal values.",
+      "Report proposal ids and source_database_changed exactly from the tool result.",
+      "If ok is false, follow error.code. On TEMPORARILY_UNAVAILABLE, retry later. On NOT_FOUND_IN_TENANT, do not infer cross-tenant existence."
+    ]
+  };
+}
 async function mcpSmoke(args) {
   const boundary = await inspectMcpToolBoundary(args);
   if (args.includes("--json")) {
@@ -8799,6 +10981,35 @@ async function mcpSmoke(args) {
   }
   return boundary.ok ? 0 : 1;
 }
+async function smokeCall(args) {
+  const configPath = optionalArg(args, "--config") ?? defaultConfigPath;
+  const storePath = optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE ?? defaultStorePath;
+  const config = await readRuntimeConfig(configPath);
+  const env = envWithDemoDefaults(config, configPath);
+  const store = new ProposalStore(storePath);
+  const runtime = createMcpRuntime(config, { store, env });
+  try {
+    const tools2 = runtime.listTools();
+    const requestedTool = firstPositional(args);
+    const toolName = requestedTool ?? (tools2.length === 1 ? tools2[0]?.name : void 0);
+    if (!toolName) {
+      throw new Error(`smoke call needs <capability-name> because ${tools2.length} tools are exposed: ${tools2.map((tool) => tool.name).join(", ") || "none"}`);
+    }
+    const capability = (config.capabilities ?? []).find((item) => item.name === toolName);
+    if (!capability && config.mode !== "cloud") throw new Error(`capability not found in ${configPath}: ${toolName}`);
+    const input = capability ? await smokeToolInput(args, capability) : await smokeInputFromArgs(args);
+    const result = await runtime.callTool(toolName, input);
+    if (args.includes("--json")) {
+      process2.stdout.write(`${JSON.stringify({ ok: true, tool: toolName, input, result, store_path: storePath }, null, 2)}
+`);
+    } else {
+      process2.stdout.write(formatSmokeCallResult(toolName, input, result, storePath));
+    }
+    return 0;
+  } finally {
+    runtime.close();
+  }
+}
 async function toolsPreview(args) {
   const boundary = await inspectMcpToolBoundary(args);
   if (args.includes("--json")) {
@@ -8806,7 +11017,9 @@ async function toolsPreview(args) {
       ok: boundary.ok,
       config_path: boundary.configPath,
       store_path: boundary.storePath,
+      alias_mode: boundary.aliasMode,
       exposed_to_mcp: boundary.names,
+      alias_mappings: boundary.exposures,
       not_exposed_to_mcp: defaultBlockedToolSurface(),
       checks: boundary.checks
     }, null, 2)}
@@ -8819,6 +11032,7 @@ async function toolsPreview(args) {
 async function inspectMcpToolBoundary(args) {
   const configPath = optionalArg(args, "--config") ?? "./synapsor.runner.json";
   const storePath = optionalArg(args, "--store") ?? "./.synapsor/local.db";
+  const aliasMode = args.includes("--aliases") && !optionalArg(args, "--alias-mode") && !optionalArg(args, "--tool-name-style") ? "both" : toolNameStyleOption(args);
   if (!await fileExists(configPath)) {
     throw new Error(`MCP tool preview could not find ${configPath}.
 
@@ -8826,13 +11040,14 @@ Why it matters:
 The MCP server needs a reviewed config before it can expose semantic tools.
 
 Fix:
-Run ${cliCommandName()} init --wizard --from-env DATABASE_URL, or pass --config <path>.`);
+Run ${cliCommandName()} onboard db --from-env DATABASE_URL, or pass --config <path>.`);
   }
   const parsed = JSON.parse(await fs3.readFile(configPath, "utf8"));
   const runtime = createMcpRuntime(parsed, { storePath });
   try {
     const tools2 = runtime.listTools();
-    const names = tools2.map((tool) => tool.name);
+    const exposures = toolNameExposures(tools2.map((tool) => tool.name), aliasMode);
+    const names = exposures.map((item) => item.exposedName);
     const serialized = JSON.stringify(tools2);
     const checks = [
       { name: "semantic tools present", ok: names.length > 0, detail: names.join(", ") || "none" },
@@ -8843,7 +11058,7 @@ Run ${cliCommandName()} init --wizard --from-env DATABASE_URL, or pass --config
       { name: "write credentials absent", ok: !/(password|secret|bearer|private[_-]?key|token)/i.test(serialized), detail: "MCP tools do not include write credentials" }
     ];
     const ok = checks.every((check) => check.ok);
-    return { ok, configPath, storePath, names, checks };
+    return { ok, configPath, storePath, aliasMode, names, exposures, checks };
   } finally {
     runtime.close();
   }
@@ -8860,13 +11075,15 @@ function defaultBlockedToolSurface() {
   ];
 }
 function formatToolsPreview(input) {
+  const exposedLines = input.exposures.length > 0 ? input.exposures.map((item) => item.isAlias ? `  - ${item.exposedName} -> ${item.canonicalName}` : `  - ${item.exposedName}`) : ["  - (none)"];
   const lines = [
     `Synapsor tools preview: ${input.ok ? "ok" : "failed"}`,
     `Config: ${input.configPath}`,
     `Store: ${input.storePath}`,
+    `Alias mode: ${input.aliasMode}`,
     "",
     "Exposed to MCP:",
-    ...input.names.length > 0 ? input.names.map((name) => `  - ${name}`) : ["  - (none)"],
+    ...exposedLines,
     "",
     "Not exposed to MCP:",
     ...defaultBlockedToolSurface().map((name) => `  - ${name}`),
@@ -8900,6 +11117,69 @@ function formatMcpSmoke(input) {
   return `${lines.join("\n")}
 `;
 }
+async function smokeToolInput(args, capability) {
+  if (!args.includes("--sample") && !optionalArg(args, "--input") && !optionalArg(args, "--json")) {
+    return sampleInputForCapability(capability);
+  }
+  return await smokeInputFromArgs(args, capability);
+}
+async function smokeInputFromArgs(args, capability) {
+  const jsonInput = optionalArg(args, "--json");
+  const inputPath = optionalArg(args, "--input");
+  const sample = args.includes("--sample");
+  const selected = [Boolean(jsonInput), Boolean(inputPath), sample].filter(Boolean).length;
+  if (selected > 1) throw new Error("smoke call accepts only one of --sample, --input, or --json");
+  if (jsonInput) {
+    const parsed = JSON.parse(jsonInput);
+    if (!isRecord6(parsed)) throw new Error("smoke call --json must be a JSON object");
+    return parsed;
+  }
+  if (inputPath) {
+    const parsed = JSON.parse(await fs3.readFile(inputPath, "utf8"));
+    if (!isRecord6(parsed)) throw new Error("smoke call --input must point to a JSON object");
+    return parsed;
+  }
+  if (sample && capability) return sampleInputForCapability(capability);
+  if (sample) return {};
+  return {};
+}
+function formatSmokeCallResult(toolName, input, result, storePath) {
+  const evidenceId = stringField(result, "evidence_bundle_id");
+  const proposalId = stringField(result, "proposal_id");
+  const replayResource = stringField(result, "replay_resource");
+  const sourceChanged = result.source_database_changed === true || result.source_database_mutated === true;
+  const lines = [
+    "Synapsor smoke call: ok",
+    "",
+    "Tool:",
+    toolName,
+    "",
+    "Input:",
+    JSON.stringify(input, null, 2),
+    "",
+    "Source DB changed:",
+    sourceChanged ? "yes" : "no",
+    "",
+    "Evidence:",
+    evidenceId || "(not returned)",
+    ""
+  ];
+  if (proposalId) {
+    lines.push("Proposal:", proposalId, "", "Replay:", replayResource || `synapsor://replay/replay_${proposalId}`, "");
+  }
+  lines.push("Next:");
+  if (evidenceId) lines.push(`  ${cliCommandName()} evidence show ${evidenceId} --store ${storePath}`);
+  if (proposalId) {
+    lines.push(`  ${cliCommandName()} proposals show ${proposalId} --store ${storePath}`);
+    lines.push(`  ${cliCommandName()} proposals approve ${proposalId} --store ${storePath}`);
+    lines.push(`  ${cliCommandName()} apply ${proposalId} --store ${storePath}`);
+    lines.push(`  ${cliCommandName()} replay show --proposal ${proposalId} --store ${storePath}`);
+  } else if (evidenceId) {
+    lines.push(`  ${cliCommandName()} query-audit list --evidence ${evidenceId} --store ${storePath}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
 async function writeMcpClientSnippet(destination, client, snippet, yes) {
   const resolved = path3.resolve(destination);
   let existing = {};
@@ -9406,11 +11686,19 @@ async function activity(args) {
   usage(["activity"]);
   return 2;
 }
+async function events(args) {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "tail") return eventsTail(rest);
+  if (subcommand === "webhook" || subcommand === "push") return eventsWebhook(rest);
+  usage(["events"]);
+  return 2;
+}
 async function storeCommand(args) {
   const [subcommand, ...rest] = args;
   if (subcommand === "stats") return storeStats(rest);
   if (subcommand === "vacuum") return storeVacuum(rest);
   if (subcommand === "prune") return storePrune(rest);
+  if (subcommand === "reset") return storeReset(rest);
   usage(["store"]);
   return 2;
 }
@@ -9435,6 +11723,10 @@ async function ui(args) {
   });
   process2.stdout.write(`Synapsor Runner local UI: ${server.url}
 `);
+  if (args.includes("--open")) {
+    openBrowser(server.url);
+    process2.stdout.write("Opening the local review UI in your browser when a desktop opener is available.\n");
+  }
   process2.stdout.write("Approval and rejection actions require the per-run local session plus CSRF token. Press Ctrl+C to stop.\n");
   await new Promise((resolve) => {
     const stop = async () => {
@@ -9448,6 +11740,13 @@ async function ui(args) {
   });
   return 0;
 }
+function openBrowser(url) {
+  const command = process2.platform === "darwin" ? "open" : process2.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process2.platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = spawn(command, args, { detached: true, stdio: "ignore" });
+  child.on("error", () => void 0);
+  child.unref();
+}
 async function shadowList(args) {
   const store = await openLocalStore(args);
   try {
@@ -9915,6 +12214,125 @@ async function activitySearch(args) {
     store.close();
   }
 }
+async function eventsTail(args) {
+  assertKnownOptions(args, eventTailAllowedOptions, "events tail");
+  const follow = args.includes("--follow");
+  if (follow && args.includes("--json")) throw new Error("events tail --follow does not support --json yet");
+  const storePath = optionalArg(args, "--store");
+  const intervalMs = Number(optionalArg(args, "--interval-ms") ?? "1000");
+  if (!Number.isFinite(intervalMs) || intervalMs < 250) throw new Error("--interval-ms must be at least 250");
+  const filters = eventFiltersFromArgs(args);
+  const printOnce = async (seen2) => {
+    const store = await openLocalStore(["--store", storePath ?? "./.synapsor/local.db"]);
+    try {
+      const rows = store.listEvents(filters).sort((left, right) => left.event_id - right.event_id).filter((event) => !seen2?.has(event.event_id));
+      if (seen2) rows.forEach((event) => seen2.add(event.event_id));
+      if (args.includes("--json")) {
+        process2.stdout.write(`${JSON.stringify({ events: rows }, null, 2)}
+`);
+      } else if (rows.length === 0 && !follow) {
+        process2.stdout.write("No local events found.\n");
+      } else {
+        for (const event of rows) process2.stdout.write(formatEventLine(event, showDetails(args)));
+      }
+      return rows.length;
+    } finally {
+      store.close();
+    }
+  };
+  if (!follow) {
+    await printOnce();
+    return 0;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  await printOnce(seen);
+  await new Promise((resolve) => {
+    const timer = setInterval(() => {
+      void printOnce(seen).catch((error) => {
+        process2.stderr.write(`events tail error: ${safeErrorMessage(error)}
+`);
+      });
+    }, intervalMs);
+    const stop = () => {
+      clearInterval(timer);
+      process2.off("SIGINT", stop);
+      process2.off("SIGTERM", stop);
+      resolve();
+    };
+    process2.once("SIGINT", stop);
+    process2.once("SIGTERM", stop);
+  });
+  return 0;
+}
+async function eventsWebhook(args) {
+  assertKnownOptions(args, eventWebhookAllowedOptions, "events webhook");
+  const url = optionalArg(args, "--url") ?? envValue(optionalArg(args, "--url-env"));
+  if (!url) throw new Error("events webhook requires --url <https://...> or --url-env <ENV>");
+  const endpoint = new URL(url);
+  if (!["http:", "https:"].includes(endpoint.protocol)) throw new Error("events webhook URL must use http or https");
+  const follow = args.includes("--follow");
+  const dryRun = args.includes("--dry-run");
+  const jsonOutput = args.includes("--json");
+  if (follow && jsonOutput) throw new Error("events webhook --follow does not support --json");
+  const storePath = optionalArg(args, "--store");
+  const intervalMs = Number(optionalArg(args, "--interval-ms") ?? "1000");
+  const timeoutMs = Number(optionalArg(args, "--timeout-ms") ?? "5000");
+  const sinceEventId = optionalPositiveIntegerArg(args, "--since-event-id");
+  if (!Number.isFinite(intervalMs) || intervalMs < 250) throw new Error("--interval-ms must be at least 250");
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 250) throw new Error("--timeout-ms must be at least 250");
+  const token = envValue(optionalArg(args, "--auth-token-env"));
+  const filters = eventFiltersFromArgs(args);
+  const seen = /* @__PURE__ */ new Set();
+  const pushOnce = async () => {
+    const store = await openLocalStore(["--store", storePath ?? "./.synapsor/local.db"]);
+    try {
+      const rows = store.listEvents(filters).filter((event) => sinceEventId === void 0 || event.event_id > sinceEventId).sort((left, right) => left.event_id - right.event_id).filter((event) => !seen.has(event.event_id));
+      rows.forEach((event) => seen.add(event.event_id));
+      let delivered = 0;
+      const payloads = [];
+      for (const event of rows) {
+        const payload = localEventWebhookPayload(event, store.path);
+        payloads.push(payload);
+        if (dryRun) {
+          if (!jsonOutput) process2.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+        } else {
+          await postLocalEventWebhook(endpoint, payload, { token, timeoutMs });
+          if (!jsonOutput) process2.stdout.write(`pushed event ${event.event_id} ${event.kind} for ${event.proposal_id} to ${redactWebhookUrl(endpoint)}
+`);
+        }
+        delivered += 1;
+      }
+      if (rows.length === 0 && !follow && !jsonOutput) process2.stdout.write(dryRun ? "No local events matched for dry-run.\n" : "No local events matched.\n");
+      return { delivered, payloads };
+    } finally {
+      store.close();
+    }
+  };
+  const first = await pushOnce();
+  if (jsonOutput && !follow) {
+    process2.stdout.write(`${JSON.stringify({ ok: true, dry_run: dryRun, delivered: first.delivered, webhook: redactWebhookUrl(endpoint), events: first.payloads }, null, 2)}
+`);
+  }
+  if (!follow) return 0;
+  await new Promise((resolve) => {
+    const timer = setInterval(() => {
+      void pushOnce().catch((error) => {
+        process2.stderr.write(`events webhook error: ${safeErrorMessage(error)}
+`);
+      });
+    }, intervalMs);
+    const stop = () => {
+      clearInterval(timer);
+      process2.off("SIGINT", stop);
+      process2.off("SIGTERM", stop);
+      resolve();
+    };
+    process2.once("SIGINT", stop);
+    process2.once("SIGTERM", stop);
+  });
+  return 0;
+}
 async function storeStats(args) {
   assertKnownOptions(args, storeStatsAllowedOptions, "store stats");
   const store = await openLocalStore(args);
@@ -9952,6 +12370,7 @@ async function storePrune(args) {
   if (args.includes("--yes") && args.includes("--dry-run")) throw new Error("store prune accepts either --dry-run or --yes, not both");
   const cutoff = cutoffFromOlderThan(olderThan);
   const dryRun = !args.includes("--yes");
+  if (!dryRun) await assertNoActiveStoreLease(optionalArg(args, "--store"), args.includes("--force"), "store prune");
   const store = await openLocalStore(args);
   try {
     const result = store.pruneBefore(cutoff, { dryRun });
@@ -9963,6 +12382,36 @@ async function storePrune(args) {
     store.close();
   }
 }
+async function storeReset(args) {
+  assertKnownOptions(args, storeResetAllowedOptions, "store reset");
+  const storePath = optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE ?? "./.synapsor/local.db";
+  if (storePath === ":memory:") throw new Error("store reset does not apply to :memory: stores");
+  if (!args.includes("--yes")) {
+    throw new Error("store reset is destructive for the local ledger. Rerun with --yes after backing up anything you need.");
+  }
+  await assertNoActiveStoreLease(storePath, args.includes("--force"), "store reset");
+  const resolved = path3.resolve(storePath);
+  const candidates = [resolved, `${resolved}-wal`, `${resolved}-shm`, storeLeasePath(resolved)];
+  const removed = [];
+  for (const candidate of candidates) {
+    try {
+      await fs3.rm(candidate, { force: true });
+      removed.push(candidate);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  const result = {
+    ok: true,
+    store: resolved,
+    removed,
+    source_database_changed: false
+  };
+  if (args.includes("--json")) process2.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  else process2.stdout.write(formatStoreReset(result));
+  return 0;
+}
 var commonReadOptions = /* @__PURE__ */ new Set(["--store", "--json", "--details", "--debug"]);
 var showAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions]);
 var exportAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions, "--output", "--out", "--format", "--evidence", "--audit"]);
@@ -10022,6 +12471,26 @@ var receiptListAllowedOptions = /* @__PURE__ */ new Set([
   "--to",
   "--limit"
 ]);
+var eventTailAllowedOptions = /* @__PURE__ */ new Set([
+  ...commonReadOptions,
+  "--proposal",
+  "--kind",
+  "--actor",
+  "--from",
+  "--to",
+  "--limit",
+  "--follow",
+  "--interval-ms"
+]);
+var eventWebhookAllowedOptions = /* @__PURE__ */ new Set([
+  ...eventTailAllowedOptions,
+  "--url",
+  "--url-env",
+  "--auth-token-env",
+  "--timeout-ms",
+  "--since-event-id",
+  "--dry-run"
+]);
 var replayShowAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions, "--proposal", "--replay", "--evidence"]);
 var replayExportAllowedOptions = /* @__PURE__ */ new Set([...replayShowAllowedOptions, "--output", "--out", "--format"]);
 var replayListAllowedOptions = /* @__PURE__ */ new Set([
@@ -10064,7 +12533,8 @@ var activitySearchAllowedOptions = /* @__PURE__ */ new Set([
 ]);
 var storeStatsAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions]);
 var storeVacuumAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions]);
-var storePruneAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions, "--older-than", "--dry-run", "--yes"]);
+var storePruneAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions, "--older-than", "--dry-run", "--yes", "--force"]);
+var storeResetAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions, "--yes", "--force"]);
 function assertKnownOptions(args, allowed, commandName) {
   for (const arg of args) {
     if (!arg.startsWith("--")) continue;
@@ -10213,6 +12683,27 @@ function receiptFiltersFromActivityArgs(args, store) {
     limit: limitFromArgs(args)
   };
 }
+function eventFiltersFromArgs(args) {
+  return {
+    proposal: optionalArg(args, "--proposal"),
+    kind: optionalArg(args, "--kind"),
+    actor: optionalArg(args, "--actor"),
+    from: optionalArg(args, "--from"),
+    to: optionalArg(args, "--to"),
+    limit: limitFromArgs(args)
+  };
+}
+function optionalPositiveIntegerArg(args, flag) {
+  const value = optionalArg(args, flag);
+  if (!value) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${flag} must be a non-negative integer`);
+  return parsed;
+}
+function envValue(name) {
+  if (!name) return void 0;
+  return process2.env[name];
+}
 function linkedProposalFilter(args, store, options = {}) {
   const noLinkedProposal = "__synapsor_no_linked_proposal__";
   const replay2 = optionalArg(args, "--replay");
@@ -10393,8 +12884,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([
@@ -10416,7 +12907,7 @@ async function prepareReferenceDemo(args) {
     `${cliCommandName()} mcp config --absolute-paths --config ./synapsor.runner.json --store ./.synapsor/local.db`,
     "",
     "Open UI:",
-    `${cliCommandName()} ui --tour`,
+    `${cliCommandName()} ui --open --tour`,
     ""
   ].join("\n"));
   return 0;
@@ -10470,7 +12961,7 @@ function databaseInputFromArgs(args) {
   if (inlineUrl && !isDatabaseUrl(inlineUrl)) {
     throw new Error("--from must be a postgres://, postgresql://, or mysql:// URL.");
   }
-  const fromEnv = optionalArg(args, "--from-env") ?? optionalArg(args, "--database-url-env");
+  const fromEnv = optionalArg(args, "--from-env") ?? optionalArg(args, "--url-env") ?? optionalArg(args, "--database-url-env");
   const configDatabaseUrlEnv = fromEnv ?? "SYNAPSOR_DATABASE_READ_URL";
   if (inlineUrl) {
     return {
@@ -10516,6 +13007,7 @@ function firstPositional(args) {
     "--format",
     "--from",
     "--from-env",
+    "--url-env",
     "--host",
     "--idempotency-key",
     "--input",
@@ -10545,6 +13037,10 @@ function firstPositional(args) {
     "--reason",
     "--recipe",
     "--receipt",
+    "--read-tool",
+    "--inspect-tool-name",
+    "--proposal-tool",
+    "--proposal-tool-name",
     "--replay",
     "--runner",
     "--schema",
@@ -10706,11 +13202,11 @@ function formatProposalDetail(proposal, storedEvidenceItemCount) {
     ...formatChangeLines(proposal)
   ].join("\n") + "\n";
 }
-function formatProposalEventDetail(events) {
-  if (events.length === 0) return "Events:\n  none\n";
+function formatProposalEventDetail(events2) {
+  if (events2.length === 0) return "Events:\n  none\n";
   return [
     "Events:",
-    ...events.map((event) => `  event ${event.event_id}: ${event.kind} by ${event.actor} at ${event.created_at}`)
+    ...events2.map((event) => `  event ${event.event_id}: ${event.kind} by ${event.actor} at ${event.created_at}`)
   ].join("\n") + "\n";
 }
 function formatProposalDebug(proposal, storePath) {
@@ -11172,6 +13668,64 @@ function formatActivityNext(items, storeSuffix) {
   return `${lines.join("\n")}
 `;
 }
+function formatEventLine(event, details = false) {
+  const lines = [
+    `${event.created_at}  ${event.kind}`,
+    `  proposal: ${event.proposal_id}`,
+    `  actor: ${event.actor}`
+  ];
+  if (details && Object.keys(event.payload).length > 0) {
+    lines.push(`  payload: ${JSON.stringify(event.payload)}`);
+  }
+  lines.push("");
+  return `${lines.join("\n")}
+`;
+}
+function localEventWebhookPayload(event, storePath) {
+  return {
+    schema_version: "synapsor.local-event-webhook.v1",
+    delivered_at: (/* @__PURE__ */ new Date()).toISOString(),
+    source: {
+      kind: "local_store",
+      store_path: storePath
+    },
+    event
+  };
+}
+async function postLocalEventWebhook(endpoint, payload, options) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    const headers = {
+      "content-type": "application/json",
+      accept: "application/json",
+      "user-agent": "synapsor-runner-events-webhook"
+    };
+    if (options.token) headers.authorization = `Bearer ${options.token}`;
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(`webhook returned HTTP ${response.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+    }
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function redactWebhookUrl(endpoint) {
+  const copy = new URL(endpoint.toString());
+  copy.username = "";
+  copy.password = "";
+  copy.search = "";
+  return copy.toString();
+}
+function safeErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 function formatStoreStats(stats) {
   return [
     `Local store: ${stats.path}`,
@@ -11203,6 +13757,18 @@ function formatStorePrune(result) {
   return `${lines.join("\n")}
 `;
 }
+function formatStoreReset(result) {
+  const lines = [
+    "Local store reset complete",
+    `Store: ${result.store}`,
+    `Source database changed: ${result.source_database_changed ? "yes" : "no"}`,
+    "",
+    "Removed:",
+    ...result.removed.length ? result.removed.map((entry) => `  - ${entry}`) : ["  - no local store files were present"]
+  ];
+  return `${lines.join("\n")}
+`;
+}
 function cutoffFromOlderThan(value) {
   const match = value.match(/^(\d+)([smhd])$/i);
   if (!match) throw new Error("--older-than must use a duration such as 30d, 12h, 90m, or 0d");
@@ -11444,7 +14010,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.8",
+      runner_version: "0.1.0",
       project_id: "token_scope",
       adapter_id: "mcp.your_adapter",
       source_id: "src_replace_me",
@@ -11479,10 +14045,14 @@ function isKnownTopLevelCommand(command) {
     "propose",
     "audit",
     "start",
+    "up",
     "runner",
     "cloud",
     "mcp",
+    "smoke",
     "tools",
+    "writeback",
+    "handler",
     "onboard",
     "demo",
     "recipes",
@@ -11493,6 +14063,7 @@ function isKnownTopLevelCommand(command) {
     "query-audit",
     "receipts",
     "activity",
+    "events",
     "store",
     "shadow",
     "ui"
@@ -11504,7 +14075,7 @@ function cliCommandName() {
 }
 function usage(args = []) {
   const [command, subcommand] = args;
-  const key = command === "mcp" && subcommand ? `mcp ${subcommand}` : command ?? "";
+  const key = (command === "mcp" || command === "handler") && subcommand ? `${command} ${subcommand}` : command ?? "";
   const cmd = cliCommandName();
   const help = {
     "": `Synapsor Runner
@@ -11516,8 +14087,15 @@ 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
+  smoke        Test generated tool calls before wiring an MCP client
+  tools        List model-facing MCP tools and aliases
+  writeback    Print direct SQL writeback receipt DDL, grants, and checks
+  handler      Create app-owned writeback handler templates
   propose      Create a local evidence-backed proposal
   audit        Review MCP/database tool risk
   proposals   Review, approve, or reject proposals
@@ -11525,6 +14103,7 @@ Commands:
   query-audit Inspect local query audit records
   receipts    Inspect guarded writeback receipts
   activity    Search local evidence/replay ledger
+  events      Tail or push local proposal/writeback lifecycle events
   store       Inspect and maintain the local SQLite ledger
   apply        Apply an approved proposal with guarded writeback
   replay       Show what happened
@@ -11532,47 +14111,137 @@ Commands:
   ui           Open the local review UI
 
 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
+  ${cmd} smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} tools list --aliases --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} handler template node-fastify --output ./synapsor-writeback-handler.mjs
   ${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 --serve --config ./synapsor.runner.json --store ./.synapsor/local.db --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. \`${cmd} up --serve\` starts the standard Streamable HTTP
+MCP server after the checklist. Use --with-handler to run the handler doctor
+before serving app-owned writeback configs.
+
+Options:
+  --serve
+  --alias-mode canonical|openai|both
+  --result-format v1|v2
+  --handler-check
+  --with-handler
+  --open-ui
+  --dry-run
+`,
+    start: `Usage:
+  ${cmd} start --from-env DATABASE_URL [--schema public] [--mode read_only|shadow|review]
+  ${cmd} start --from-env DATABASE_URL --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL [--handler-signing-secret-env APP_WRITEBACK_SIGNING_SECRET]
+  ${cmd} start
+
+With --from-env, run the guided own-database setup: inspect schema, choose one
+object, create trusted context, generate semantic MCP tools, run/print a smoke
+call, and print MCP/UI next steps.
+
+With no flags, start the legacy cloud-linked writeback polling worker from the
+worker environment config. Prefer \`${cmd} runner start\` for that worker path
+so it is not confused with first-run onboarding.
 `,
     inspect: `Usage:
   ${cmd} inspect --from-env DATABASE_URL [--engine auto|postgres|mysql] [--schema public] [--json]
+  ${cmd} inspect --engine postgres --url-env DATABASE_URL
   ${cmd} inspect "<postgres-or-mysql-url>" [--engine auto|postgres|mysql] [--schema public] [--json]
 
 Inspect schema metadata without mutating the database or printing credentials.
 `,
     init: `Usage:
   ${cmd} init --wizard --from-env DATABASE_URL [--mode read_only|review|shadow] [--out synapsor.runner.json]
-  ${cmd} init --inspection-json schema.json --table invoices --mode review --patch-from-arg waiver_reason=reason
+  ${cmd} init --engine postgres --url-env DATABASE_URL --mode review --table public.invoices
+  ${cmd} init --inspection-json schema.json --table invoices --mode review --patch late_fee_cents=fixed:0,waiver_reason=arg:reason
+  ${cmd} init --answers answers.json --yes
+  ${cmd} init --inspection-json schema.json --table invoices --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL --emit-handler [--handler-signing-secret-env APP_WRITEBACK_SIGNING_SECRET]
 
 Generate a reviewed Synapsor Runner contract. Defaults to read-only in the wizard.
-`,
+Review mode writeback choices: sql_update, http_handler, command_handler.
+If --namespace is omitted, init derives one from the table name instead of using source.*.
+Use --read-tool and --proposal-tool to override the exact model-facing capability names.
+The guided wizard shows a final preview and lets you revise visible fields or capability names before writing files.
+Use --yes/--non-interactive plus explicit flags, or --answers, for script/agent-friendly setup without prompts.
+	`,
     mcp: `Usage:
   ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} mcp serve --transport streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+  ${cmd} mcp serve-streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
   ${cmd} mcp serve-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
   ${cmd} mcp config --absolute-paths --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} mcp client-config --client openai-agents --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} mcp audit --example dangerous-db-mcp
   ${cmd} mcp audit ./tools-list.json
 
-Use stdio for local MCP clients that launch the runner. Use authenticated HTTP for app/server deployments.
+Use stdio for local MCP clients that launch the runner. Use Streamable HTTP for standard HTTP MCP clients. Use serve-http only when you explicitly want the lightweight JSON-RPC bridge.
 MCP clients see semantic tools. They do not receive raw SQL, write credentials, approval tools, or commit tools.
+`,
+    tools: `Usage:
+  ${cmd} tools list --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} tools list --aliases --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+
+List the model-facing MCP tools generated from a reviewed Runner config.
+Use --aliases to show canonical Synapsor names and OpenAI-safe aliases.
+This command never prints database URLs or write credentials.
 `,
     "mcp serve": `Usage:
-  ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db [--read-only] [--local]
+  ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db [--transport stdio] [--read-only] [--local] [--alias-mode canonical|openai|both] [--result-format v1|v2]
+  ${cmd} mcp serve --transport streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN [--result-format v2]
 
 Start the stdio MCP server for local MCP clients such as Claude Desktop, Cursor, or local agent tools. Startup logs stay off stdout so the MCP protocol remains clean.
+Use --alias-mode openai, or --openai-tool-aliases, for clients that reject dotted tool names. Use --alias-mode both to expose canonical and alias names.
+Use --result-format v2 to return one stable ok/summary/data/proposal/error envelope from every tool call.
+`,
+    "mcp serve-streamable-http": `Usage:
+  export SYNAPSOR_RUNNER_HTTP_TOKEN=...
+  ${cmd} mcp serve-streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db [--host 127.0.0.1] [--port 8766] [--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN] [--alias-mode canonical|openai|both] [--result-format v1|v2]
+
+Start the spec-compatible MCP Streamable HTTP endpoint for clients and SDKs that support HTTP MCP.
+Bearer auth is required by default.
+
+Alpha scope:
+  - Supports MCP initialize/session behavior through the official MCP Streamable HTTP transport.
+  - Use --alias-mode openai, or --openai-tool-aliases, for clients that reject dotted tool names.
+  - Use --alias-mode both to expose canonical names and aliases.
+  - Use --result-format v2 for the stable ok/summary/data/proposal/error envelope.
+  - OpenAI aliases expose names such as billing__inspect_invoice while preserving the canonical Synapsor name in _meta.
+  - Use /mcp for the MCP endpoint and /healthz for service health.
+  - Sessions are in-memory. Restarting the runner clears active HTTP MCP sessions.
+
+Security:
+  - Defaults to 127.0.0.1:8766.
+  - Refuses to start if the auth token env var is missing.
+  - Use --dev-no-auth only for localhost development.
+  - If binding to 0.0.0.0, use TLS, private networking, authentication, and rate limits.
+  - Optional CORS: --cors-origin http://localhost:3000
 `,
     "mcp serve-http": `Usage:
   export SYNAPSOR_RUNNER_HTTP_TOKEN=...
-  ${cmd} mcp serve-http --config ./synapsor.runner.json --store ./.synapsor/local.db [--host 127.0.0.1] [--port 8765] [--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN]
+  ${cmd} mcp serve-http --config ./synapsor.runner.json --store ./.synapsor/local.db [--host 127.0.0.1] [--port 8765] [--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN] [--result-format v1|v2]
 
-Start the HTTP JSON-RPC MCP endpoint for app/server deployments. Bearer auth is required by default.
+Start the lightweight HTTP JSON-RPC bridge for app/server deployments that want simple POST calls.
+Bearer auth is required by default.
 
 Alpha scope: supports POST /mcp methods tools/list, tools/call, and resources/read.
-It does not implement full MCP Streamable HTTP initialize/SSE sessions.
+It does not implement MCP Streamable HTTP initialize/session behavior. Use ${cmd} mcp serve-streamable-http for standard HTTP MCP clients.
 
 Security:
   - Defaults to 127.0.0.1:8765.
@@ -11582,9 +14251,67 @@ Security:
   - Optional CORS: --cors-origin http://localhost:3000
 `,
     "mcp config": `Usage:
-  ${cmd} mcp config [claude-desktop|cursor|generic|vscode] [--absolute-paths] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} mcp config [claude-desktop|cursor|generic|vscode|openai-agents] [--absolute-paths] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} mcp client-config --client openai-agents [--transport streamable-http] [--port 8766] [--alias-mode openai] [--include-instructions] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
 
 Print MCP client configuration that references the local runner command, not database URLs. Defaults to claude-desktop.
+OpenAI Agents SDK output uses Streamable HTTP and OpenAI-safe aliases by default.
+`,
+    "mcp client-config": `Usage:
+  ${cmd} mcp client-config --client claude-desktop [--absolute-paths] [--include-instructions] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} mcp client-config --client cursor [--absolute-paths] [--include-instructions] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} mcp client-config --client openai-agents [--transport streamable-http] [--port 8766] [--alias-mode openai] [--include-instructions] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+
+Print MCP client configuration that references the local runner command, not database URLs.
+OpenAI Agents SDK output uses Streamable HTTP and OpenAI-safe aliases by default.
+Use --include-instructions to include the recommended propose-first agent prompt.
+`,
+    smoke: `Usage:
+  ${cmd} smoke call [capability-name] [--sample] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} smoke call [capability-name] --json '{"record_id":"..."}'
+  ${cmd} smoke boundary [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+
+Call a generated semantic tool locally before wiring Claude, Cursor, or another MCP client. The call uses the same runtime as MCP, records evidence/query audit/proposals in the local store, and does not expose raw SQL or write credentials.
+`,
+    writeback: `Usage:
+  ${cmd} writeback doctor --config ./synapsor.runner.json [--check-db]
+  ${cmd} writeback migration --engine postgres [--schema synapsor]
+  ${cmd} writeback migration --engine mysql [--schema appdb]
+  ${cmd} writeback grants --engine postgres --writer-role app_writer [--schema synapsor]
+  ${cmd} writeback grants --engine mysql --writer-role "'app_writer'@'%'" [--schema appdb]
+
+Print and verify the receipt-table setup required by direct SQL writeback. Rich writes should prefer app-owned http_handler or command_handler executors.
+`,
+    handler: `Usage:
+  ${cmd} handler template --list
+  ${cmd} handler template node-fastify [--output ./synapsor-writeback-handler.mjs] [--force]
+  ${cmd} handler template python-fastapi [--output ./synapsor_writeback_handler.py] [--force]
+  ${cmd} handler template command [--output ./synapsor-command-handler.mjs] [--force]
+
+Write starter app-owned writeback handlers for approved proposals. Use these when rich writes should run through your application service instead of Runner-managed SQL.
+`,
+    "handler template": `Usage:
+  ${cmd} handler template --list
+  ${cmd} handler template node-fastify [--output ./synapsor-writeback-handler.mjs] [--force]
+  ${cmd} handler template python-fastapi [--output ./synapsor_writeback_handler.py] [--force]
+  ${cmd} handler template command [--output ./synapsor-command-handler.mjs] [--force]
+  ${cmd} handler template node-fastify --stdout
+
+Templates:
+  node-fastify    HTTP handler for a Node/Fastify application service
+  python-fastapi  HTTP handler for a Python/FastAPI application service
+  command         Local command handler for scripts or job runners
+
+The template receives an approved proposal writeback request and must return an applied/conflict/failed receipt. Re-check tenant, principal, idempotency, row/version guards, and business policy before mutating state.
+`,
+    onboard: `Usage:
+  ${cmd} onboard db --from-env DATABASE_URL [--schema public] [--mode read_only|shadow|review]
+  ${cmd} onboard db --from-env DATABASE_URL --table invoices --mode review --patch late_fee_cents=fixed:0 --write-url-env SYNAPSOR_DATABASE_WRITE_URL --yes
+  ${cmd} onboard db --from-env DATABASE_URL --table invoices --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL --emit-handler --yes
+  ${cmd} onboard db --answers answers.json --yes
+
+Guided own-database setup: inspect schema, choose one object, create trusted context, choose read-only/shadow/review writeback mode, generate semantic tools, validate config, run a tool-boundary smoke check, and print the MCP/UI next steps.
+Use --yes/--non-interactive with explicit flags, or --answers, when CI or an LLM agent must run without prompts.
 `,
     propose: `Usage:
   ${cmd} propose <capability-name> --sample [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
@@ -11612,10 +14339,13 @@ Static MCP/database risk review only. This is not a security guarantee.
     doctor: `Usage:
   ${cmd} doctor --config synapsor.runner.json
   ${cmd} doctor --config synapsor.runner.json --json
+  ${cmd} doctor --config synapsor.runner.json --check-handlers
+  ${cmd} doctor --config synapsor.runner.json --check-writeback
   ${cmd} doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
   ${cmd} doctor --first-run
 
-Validate local config, environment bindings, semantic tool boundary, source metadata when reachable, and local store stats. Reports are redacted; do not paste secrets into issues.
+Validate local config, environment bindings, semantic tool boundary, source metadata when reachable, handler signing/reachability, direct SQL writeback readiness, and local store stats. Reports are redacted; do not paste secrets into issues.
+Use --check-writeback only after reviewing receipt-table DDL/grants; it connects with the trusted writer and can create the receipt table if the writer has permission.
 `,
     proposals: `Usage:
 	  ${cmd} proposals list [--tenant acme] [--capability billing.propose_late_fee_waiver] [--object invoice:INV-3001] [--status applied]
@@ -11655,6 +14385,14 @@ Inspect local query fingerprints, table names, row counts, and redacted-paramete
   ${cmd} apply --job job.json --config ./synapsor.runner.json --store ./.synapsor/local.db
 
 Apply an approved proposal through guarded writeback. Requires a trusted write credential.
+
+With --config, the writer connection comes from source.write_url_env, such as
+SYNAPSOR_DATABASE_WRITE_URL. SYNAPSOR_DATABASE_URL is only the legacy fallback
+for direct worker/apply flows without a local config.
+
+Direct SQL writeback creates or writes synapsor_writeback_receipts for
+idempotency and replay, so the trusted writer needs permission for that table
+or an administrator must pre-create and grant it.
 `,
     replay: `Usage:
   ${cmd} replay list [--tenant acme] [--object invoice:INV-3001]
@@ -11675,13 +14413,26 @@ Apply an approved proposal through guarded writeback. Requires a trusted write c
 
 Search the local SQLite evidence/replay ledger across proposals, evidence, query audit, receipts, and replay records.
 `,
+    events: `Usage:
+  ${cmd} events tail --store ./.synapsor/local.db
+	  ${cmd} events tail --proposal wrp_...
+	  ${cmd} events tail --kind writeback_applied
+	  ${cmd} events tail --follow --interval-ms 1000
+  ${cmd} events webhook --url http://127.0.0.1:8788/synapsor/events --kind proposal_created
+  ${cmd} events webhook --url-env SYNAPSOR_EVENT_WEBHOOK_URL --auth-token-env SYNAPSOR_EVENT_WEBHOOK_TOKEN --follow
+  ${cmd} events webhook --url http://127.0.0.1:8788/synapsor/events --dry-run
+
+Show or push local proposal/writeback lifecycle events such as proposal_created, proposal_approved, writeback_applied, writeback_conflict, and writeback_failed. Webhook delivery POSTs one local event envelope per event and never exposes database credentials.
+	`,
     store: `Usage:
   ${cmd} store stats --store ./.synapsor/local.db
   ${cmd} store vacuum --store ./.synapsor/local.db
   ${cmd} store prune --store ./.synapsor/local.db --older-than 30d --dry-run
   ${cmd} store prune --store ./.synapsor/local.db --older-than 30d --yes
+  ${cmd} store prune --store ./.synapsor/local.db --older-than 30d --yes --force
+  ${cmd} store reset --store ./.synapsor/local.db --yes
 
-Local store maintenance only. Prune defaults to dry-run and never touches your source Postgres/MySQL database.
+Local store maintenance only. Prune defaults to dry-run and reset requires --yes. These commands never touch your source Postgres/MySQL database. Destructive operations refuse while an active server lease exists unless --force is provided.
 `,
     demo: `Usage:
 	  ${cmd} demo [--force]
@@ -11696,9 +14447,10 @@ Local store maintenance only. Prune defaults to dry-run and never touches your s
 	Use --quick for a fixture-only guided walkthrough and local ledger seed with no Docker startup. Use demo inspect to print follow-up commands for the quick-demo fixture.
 	`,
     ui: `Usage:
-  ${cmd} ui [--tour] [--config synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${cmd} ui [--open] [--tour] [--config synapsor.runner.json] [--store ./.synapsor/local.db]
 
 Open the localhost review UI for proposals, diffs, evidence, receipts, and replay.
+Use --open to launch the URL in your browser when a desktop opener is available.
 `
   };
   process2.stdout.write(help[key] ?? help[command ?? ""] ?? help[""] ?? "");