@synapsor/runner 0.1.0-alpha.11 → 0.1.0-alpha.14

package/dist/runner.mjs

@@ -444,7 +444,7 @@ 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([
@@ -456,11 +456,13 @@ var SOURCE_KEYS = /* @__PURE__ */ new Set([
 ]);
 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 +482,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 +551,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." });
   }
@@ -797,6 +802,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 +860,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 +940,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." });
     }
@@ -2073,6 +2090,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);
@@ -2387,6 +2409,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} = ?`);
@@ -2670,24 +2701,53 @@ 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 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.11" },
+    { name: "synapsor-runner", version: "0.1.0-alpha.14" },
     { capabilities: { tools: {}, resources: {} } }
   );
   const toolNameStyle = options.toolNameStyle ?? "canonical";
@@ -2700,7 +2760,7 @@ function createSynapsorMcpServer(runtime, options = {}) {
           exposedName,
           {
             title: tool.title,
-            description: tool.description,
+            description: toolDescriptionWithCanonical(tool.description, tool.name, exposedName),
             inputSchema: zodInputShapeFromJsonSchema(tool.input_schema),
             annotations: {
               readOnlyHint: Boolean(tool.annotations.readOnlyHint),
@@ -2731,7 +2791,7 @@ function createSynapsorMcpServer(runtime, options = {}) {
           exposedName,
           {
             title: capability.name,
-            description: capabilityDescription(capability),
+            description: capabilityDescription(capability, exposedName),
             inputSchema: zodInputShape(capability),
             annotations: {
               readOnlyHint: capability.kind === "read",
@@ -2778,7 +2838,7 @@ function createSynapsorMcpServer(runtime, options = {}) {
 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 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);
@@ -2814,6 +2874,7 @@ async function startHttpMcpServer(options = {}) {
   const runtime = createMcpRuntime(config, {
     env,
     storePath: options.storePath,
+    resultFormat: options.resultFormat,
     readRow: options.readRow,
     cloudTools
   });
@@ -2888,6 +2949,7 @@ async function startStreamableHttpMcpServer(options = {}) {
       cloudTools,
       env,
       toolNameStyle: options.toolNameStyle,
+      resultFormat: options.resultFormat,
       authToken,
       devNoAuth,
       corsOrigin: options.corsOrigin,
@@ -2930,7 +2992,7 @@ async function startStreamableHttpMcpServer(options = {}) {
   };
 }
 async function handleStreamableHttpMcpRequest(input) {
-  const { request, response, config, storePath, readRow, cloudTools, env, toolNameStyle, authToken, devNoAuth, corsOrigin, sessions, openSessions } = 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) {
@@ -2992,7 +3054,7 @@ async function handleStreamableHttpMcpRequest(input) {
         }
       }
     });
-    const runtime = createMcpRuntime(config, { env, storePath, readRow, cloudTools });
+    const runtime = createMcpRuntime(config, { env, storePath, resultFormat, readRow, cloudTools });
     session = { transport, runtime };
     openSessions.add(session);
     transport.onclose = () => {
@@ -3330,6 +3392,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();
@@ -3507,6 +3574,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);
@@ -3708,7 +3904,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;
 }
@@ -3721,6 +3917,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 } : {},
@@ -3736,11 +3933,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.");
@@ -3857,6 +4066,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) };
@@ -4719,6 +4931,7 @@ function normalizedWriteback(spec) {
   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,
@@ -4728,12 +4941,14 @@ function normalizedWriteback(spec) {
           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." }] : []
+        ...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." }] : []
       ]
     };
   }
@@ -4871,6 +5086,7 @@ function validateSelectionSpec(spec) {
     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
@@ -6585,6 +6801,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);
@@ -6785,11 +7002,13 @@ async function runInitWizard(args, options = {}) {
     } 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")
       };
     } else {
@@ -7092,6 +7311,7 @@ function writebackSpecFromArgs(args) {
       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")
     };
   }
@@ -7530,6 +7750,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);
@@ -7959,6 +8227,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);
@@ -8001,6 +8271,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 });
@@ -8009,10 +8297,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 ?? "");
@@ -8049,6 +8361,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 };
@@ -8234,6 +8695,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);
@@ -8258,6 +8722,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;
@@ -8265,7 +8744,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();
@@ -8693,7 +9172,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.11").trim();
+  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.14").trim();
   const engines = normalizeEngines(parsed.cloud.engines);
   const capabilities = normalizeCapabilities(parsed.cloud.capabilities);
   const client = new ControlPlaneClient({
@@ -8756,6 +9235,7 @@ 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;
 }
@@ -9414,42 +9894,66 @@ async function mcpServe(args) {
   const readOnly = args.includes("--read-only");
   const config = readOnly ? { ...await readRuntimeConfig(configPath ?? defaultConfigPath), mode: "read_only" } : void 0;
   const toolNameStyle = toolNameStyleOption(args);
-  await serveStdio({
-    configPath,
-    storePath: optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE,
-    config,
-    toolNameStyle
-  });
-  return 0;
+  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);
@@ -9462,6 +9966,7 @@ async function mcpServeStreamableHttp(args) {
   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) {
@@ -9470,23 +9975,33 @@ async function mcpServeStreamableHttp(args) {
   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 server = await startStreamableHttpMcpServer({
-    configPath,
-    config,
-    storePath: optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE,
-    host,
-    port,
-    toolNameStyle,
-    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", "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);
@@ -9494,6 +10009,79 @@ async function mcpServeStreamableHttp(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 --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");
@@ -9509,6 +10097,13 @@ function toolNameStyleOption(args) {
   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");
+}
 async function mcpAudit(args) {
   const format = optionalArg(args, "--format") ?? (args.includes("--json") ? "json" : "text");
   if (!["text", "json", "markdown"].includes(format)) {
@@ -9660,6 +10255,7 @@ async function mcpConfigure(args) {
   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) {
@@ -9674,6 +10270,9 @@ async function mcpConfigure(args) {
     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, { 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>");
@@ -9786,6 +10385,29 @@ function mcpClientSnippet(client, configPath, storePath, options) {
   }
   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")) {
@@ -10501,11 +11123,18 @@ async function activity(args) {
   usage(["activity"]);
   return 2;
 }
+async function events(args) {
+  const [subcommand, ...rest] = args;
+  if (subcommand === "tail") return eventsTail(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;
 }
@@ -11021,6 +11650,56 @@ 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 storeStats(args) {
   assertKnownOptions(args, storeStatsAllowedOptions, "store stats");
   const store = await openLocalStore(args);
@@ -11058,6 +11737,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 });
@@ -11069,6 +11749,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"]);
@@ -11128,6 +11838,17 @@ var receiptListAllowedOptions = /* @__PURE__ */ new Set([
   "--to",
   "--limit"
 ]);
+var eventTailAllowedOptions = /* @__PURE__ */ new Set([
+  ...commonReadOptions,
+  "--proposal",
+  "--kind",
+  "--actor",
+  "--from",
+  "--to",
+  "--limit",
+  "--follow",
+  "--interval-ms"
+]);
 var replayShowAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions, "--proposal", "--replay", "--evidence"]);
 var replayExportAllowedOptions = /* @__PURE__ */ new Set([...replayShowAllowedOptions, "--output", "--out", "--format"]);
 var replayListAllowedOptions = /* @__PURE__ */ new Set([
@@ -11170,7 +11891,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;
@@ -11319,6 +12041,16 @@ 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 linkedProposalFilter(args, store, options = {}) {
   const noLinkedProposal = "__synapsor_no_linked_proposal__";
   const replay2 = optionalArg(args, "--replay");
@@ -11813,11 +12545,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) {
@@ -12279,6 +13011,22 @@ 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 safeErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 function formatStoreStats(stats) {
   return [
     `Local store: ${stats.path}`,
@@ -12310,6 +13058,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");
@@ -12551,7 +13311,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.11",
+      runner_version: "0.1.0-alpha.14",
       project_id: "token_scope",
       adapter_id: "mcp.your_adapter",
       source_id: "src_replace_me",
@@ -12603,6 +13363,7 @@ function isKnownTopLevelCommand(command) {
     "query-audit",
     "receipts",
     "activity",
+    "events",
     "store",
     "shadow",
     "ui"
@@ -12631,6 +13392,7 @@ Commands:
   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
@@ -12640,6 +13402,7 @@ Commands:
   query-audit Inspect local query audit records
   receipts    Inspect guarded writeback receipts
   activity    Search local evidence/replay ledger
+  events      Tail 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
@@ -12652,6 +13415,7 @@ Examples:
   ${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
@@ -12659,7 +13423,7 @@ Examples:
 `,
     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
+  ${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
@@ -12681,7 +13445,7 @@ Inspect schema metadata without mutating the database or printing credentials.
   ${cmd} init --wizard --from-env DATABASE_URL [--mode read_only|review|shadow] [--out synapsor.runner.json]
   ${cmd} init --engine postgres --url-env DATABASE_URL --mode review --table public.invoices
   ${cmd} init --inspection-json schema.json --table invoices --mode review --patch-from-arg waiver_reason=reason
-  ${cmd} init --inspection-json schema.json --table invoices --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL
+  ${cmd} init --inspection-json schema.json --table invoices --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL [--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.
@@ -12698,17 +13462,27 @@ Review mode writeback choices: sql_update, http_handler, command_handler.
 
 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 [--transport stdio] [--read-only] [--local] [--alias-mode canonical|openai|both]
-  ${cmd} mcp serve --transport streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+  ${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]
+  ${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.
@@ -12717,6 +13491,7 @@ 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.
@@ -12730,7 +13505,7 @@ Security:
 `,
     "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 lightweight HTTP JSON-RPC bridge for app/server deployments that want simple POST calls.
 Bearer auth is required by default.
@@ -12747,18 +13522,19 @@ Security:
 `,
     "mcp config": `Usage:
   ${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] [--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] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
-  ${cmd} mcp client-config --client cursor [--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] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
+  ${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]
@@ -12830,10 +13606,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]
@@ -12900,14 +13679,24 @@ or an administrator must pre-create and grant it.
 	  ${cmd} activity search --capability billing.propose_late_fee_waiver --from 2026-06-01 --to 2026-06-23
 
 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
+
+Show local proposal/writeback lifecycle events such as proposal_created, proposal_approved, writeback_applied, writeback_conflict, and writeback_failed.
 `,
     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]