@stackbone/cli 0.2.7 → 0.2.8

package/main.js

@@ -27,6 +27,7 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import Ajv from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
+import { createRemoteJWKSet, jwtVerify } from "jose";
 import { streamSSE } from "hono/streaming";
 import PgQueryFactory from "pg-query-emscripten";
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
@@ -473,7 +474,7 @@ function requireVersion(contract) {
 * never falls through to a misleading "capability missing" message when the
 * actual problem is a stale datapath. Pure, never throws.
 */
-function requireCapability(capability, contract) {
+function requireCapability$1(capability, contract) {
 	const versionCheck = requireVersion(contract);
 	if (versionCheck.error) return versionCheck;
 	if (!contract.capabilities.includes(capability)) return {
@@ -507,6 +508,7 @@ var init_contract = __esmMin((() => {
 		"ai.openrouter",
 		"prompts.basic"
 	];
+	new Set(CAPABILITIES);
 	MODULE_CAPABILITIES = {
 		database: "database.postgres_direct",
 		rag: "rag.basic",
@@ -522,7 +524,7 @@ var init_contract = __esmMin((() => {
 	contractResponseSchema = z.object({
 		version: z.number().int().min(1),
 		minSupported: z.number().int().min(1),
-		capabilities: z.array(z.enum(CAPABILITIES)),
+		capabilities: z.array(z.string()),
 		build: z.object({
 			name: contractBuildNameSchema,
 			version: z.string().min(1)
@@ -2777,7 +2779,7 @@ var init_contract_handshake = __esmMin((() => {
 */
 function assertCapability(module, contract) {
 	const capability = MODULE_CAPABILITIES[module];
-	const result = requireCapability(capability, contract);
+	const result = requireCapability$1(capability, contract);
 	if (result.error) return err$1(result.error);
 	return {
 		data: void 0,
@@ -5503,11 +5505,11 @@ function isUnsupportedModelError(error) {
 	if (error.code === "ai_validation_error") return true;
 	return false;
 }
-var DEFAULT_BATCH_SIZE$1, DEFAULT_CONCURRENCY, Embedder;
+var DEFAULT_BATCH_SIZE$1, DEFAULT_CONCURRENCY$1, Embedder;
 var init_embedder = __esmMin((() => {
 	init_result$1();
 	DEFAULT_BATCH_SIZE$1 = 128;
-	DEFAULT_CONCURRENCY = 4;
+	DEFAULT_CONCURRENCY$1 = 4;
 	Embedder = class {
 		constructor(options) {
 			const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE$1;
@@ -5515,7 +5517,7 @@ var init_embedder = __esmMin((() => {
 			this._ai = options.ai;
 			this._model = options.model;
 			this._batchSize = batchSize;
-			this._concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+			this._concurrency = options.concurrency ?? DEFAULT_CONCURRENCY$1;
 		}
 		get model() {
 			return this._model;
@@ -8744,6 +8746,169 @@ var createSessionsStore = (opts) => {
 	};
 };
 //#endregion
+//#region ../../libs/runtime/workspace-runtime/src/lib/connect-inbound/trigger-subscriptions-store.ts
+init_store_pool();
+init_uuid();
+var SUBSCRIPTION_COLUMNS = "id, connector, trigger_id, principal_key, workflow_name, mapping, mapping_graph, correlation_key, enabled, mailbox";
+var rowToSubscription = (row) => ({
+	id: row.id,
+	connector: row.connector,
+	trigger: row.trigger_id,
+	principalKey: row.principal_key,
+	workflowName: row.workflow_name,
+	mapping: row.mapping,
+	mappingGraph: row.mapping_graph ?? null,
+	correlationKey: row.correlation_key ?? null,
+	enabled: row.enabled,
+	mailbox: row.mailbox ?? null
+});
+var createTriggerSubscriptionsStore = (opts) => {
+	const { pool, assertOpen, close } = createStorePool("TriggerSubscriptionsStore", opts.connectionString);
+	return {
+		async register(input) {
+			assertOpen();
+			const id = randomUUID();
+			const { rows } = await pool.query(`INSERT INTO stackbone_platform.trigger_subscriptions
+           (id, connector, trigger_id, principal_key, workflow_name, mapping, mapping_graph, correlation_key, enabled, mailbox)
+         VALUES ($1::uuid, $2, $3, $4, $5, $6, $7::jsonb, $8, $9, $10)
+         RETURNING ${SUBSCRIPTION_COLUMNS}`, [
+				id,
+				input.connector,
+				input.trigger,
+				input.principalKey,
+				input.workflowName,
+				input.mapping ?? null,
+				input.mappingGraph == null ? null : JSON.stringify(input.mappingGraph),
+				input.correlationKey ?? null,
+				input.enabled ?? true,
+				input.mailbox ?? null
+			]);
+			return rowToSubscription(rows[0]);
+		},
+		async list() {
+			assertOpen();
+			const { rows } = await pool.query(`SELECT ${SUBSCRIPTION_COLUMNS}
+           FROM stackbone_platform.trigger_subscriptions
+          ORDER BY created_at DESC, id DESC`);
+			return rows.map(rowToSubscription);
+		},
+		async get(id) {
+			if (!isUuid(id)) return null;
+			assertOpen();
+			const { rows } = await pool.query(`SELECT ${SUBSCRIPTION_COLUMNS}
+           FROM stackbone_platform.trigger_subscriptions
+          WHERE id = $1::uuid`, [id]);
+			return rows[0] ? rowToSubscription(rows[0]) : null;
+		},
+		async update(id, patch) {
+			if (!isUuid(id)) return null;
+			assertOpen();
+			const sets = [];
+			const params = [id];
+			if (patch.enabled !== void 0) {
+				params.push(patch.enabled);
+				sets.push(`enabled = $${params.length}`);
+			}
+			if (patch.mapping !== void 0) {
+				params.push(patch.mapping);
+				sets.push(`mapping = $${params.length}`);
+			}
+			if (patch.mappingGraph !== void 0) {
+				params.push(patch.mappingGraph == null ? null : JSON.stringify(patch.mappingGraph));
+				sets.push(`mapping_graph = $${params.length}::jsonb`);
+			}
+			if (patch.correlationKey !== void 0) {
+				params.push(patch.correlationKey);
+				sets.push(`correlation_key = $${params.length}`);
+			}
+			if (sets.length === 0) return this.get(id);
+			const { rows } = await pool.query(`UPDATE stackbone_platform.trigger_subscriptions
+            SET ${sets.join(", ")}, updated_at = now()
+          WHERE id = $1::uuid
+        RETURNING ${SUBSCRIPTION_COLUMNS}`, params);
+			return rows[0] ? rowToSubscription(rows[0]) : null;
+		},
+		async remove(id) {
+			if (!isUuid(id)) return false;
+			assertOpen();
+			await pool.query("DELETE FROM stackbone_platform.trigger_deliveries WHERE subscription_id = $1::uuid", [id]);
+			return ((await pool.query("DELETE FROM stackbone_platform.trigger_subscriptions WHERE id = $1::uuid", [id])).rowCount ?? 0) > 0;
+		},
+		async listActive() {
+			assertOpen();
+			const { rows } = await pool.query(`SELECT ${SUBSCRIPTION_COLUMNS}
+           FROM stackbone_platform.trigger_subscriptions
+          WHERE enabled
+          ORDER BY created_at ASC, id ASC`);
+			return rows.map(rowToSubscription);
+		},
+		async readCursor(subscriptionId) {
+			assertOpen();
+			const { rows } = await pool.query("SELECT poll_cursor FROM stackbone_platform.trigger_subscriptions WHERE id = $1::uuid", [subscriptionId]);
+			return rows[0]?.poll_cursor ?? null;
+		},
+		async saveCursor({ subscriptionId, cursor, lastPolledAt }) {
+			assertOpen();
+			await pool.query(`UPDATE stackbone_platform.trigger_subscriptions
+            SET poll_cursor = $2::jsonb, last_polled_at = $3::timestamptz, updated_at = now()
+          WHERE id = $1::uuid`, [
+				subscriptionId,
+				cursor == null ? null : JSON.stringify(cursor),
+				lastPolledAt.toISOString()
+			]);
+		},
+		async claim(subscriptionId, providerItemId) {
+			assertOpen();
+			const { rows } = await pool.query(`INSERT INTO stackbone_platform.trigger_deliveries
+           (id, subscription_id, provider_item_id, status)
+         VALUES ($1::uuid, $2::uuid, $3, 'claimed')
+         ON CONFLICT (subscription_id, provider_item_id) DO NOTHING
+         RETURNING id`, [
+				randomUUID(),
+				subscriptionId,
+				providerItemId
+			]);
+			return rows.length > 0;
+		},
+		async markStarted(subscriptionId, providerItemId, runId) {
+			assertOpen();
+			await pool.query(`UPDATE stackbone_platform.trigger_deliveries
+            SET status = 'started', run_id = $3, updated_at = now()
+          WHERE subscription_id = $1::uuid AND provider_item_id = $2`, [
+				subscriptionId,
+				providerItemId,
+				runId
+			]);
+		},
+		async markResumed(subscriptionId, providerItemId, runId) {
+			assertOpen();
+			await pool.query(`UPDATE stackbone_platform.trigger_deliveries
+            SET status = 'resumed', run_id = COALESCE($3, run_id), updated_at = now()
+          WHERE subscription_id = $1::uuid AND provider_item_id = $2`, [
+				subscriptionId,
+				providerItemId,
+				runId ?? null
+			]);
+		},
+		async markRejected(subscriptionId, providerItemId, issues) {
+			assertOpen();
+			await pool.query(`UPDATE stackbone_platform.trigger_deliveries
+            SET status = 'rejected', issues = $3::jsonb, updated_at = now()
+          WHERE subscription_id = $1::uuid AND provider_item_id = $2`, [
+				subscriptionId,
+				providerItemId,
+				JSON.stringify(issues)
+			]);
+		},
+		async release(subscriptionId, providerItemId) {
+			assertOpen();
+			await pool.query(`DELETE FROM stackbone_platform.trigger_deliveries
+          WHERE subscription_id = $1::uuid AND provider_item_id = $2`, [subscriptionId, providerItemId]);
+		},
+		close
+	};
+};
+//#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/services/event-bus.ts
 var createEventBus = () => {
 	const listeners = /* @__PURE__ */ new Set();
@@ -9003,21 +9168,26 @@ var deepEqual$1 = (a, b) => {
 	return aKeys.every((key) => deepEqual$1(a[key], b[key]));
 };
 //#endregion
-//#region ../../libs/runtime/workspace-runtime/src/lib/services/dev-hmac-secret.ts
-var DEV_HMAC_SECRET = "dev-stackbone-local-emulator-hmac-secret";
-//#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/request-signature-middleware.ts
 init_src$11();
+var PROXY_CHALLENGE_PATH = "/api/proxy-challenge";
 var DEFAULT_PUBLIC_PREFIXES = [
 	"/api/contract",
 	"/api/health",
 	"/live",
 	"/health",
-	"/api/connect",
+	PROXY_CHALLENGE_PATH,
+	"/api/connect/callback",
+	"/api/connect/connected",
+	"/api/connect/token",
+	"/api/connect/execute",
+	"/api/connect/evict",
 	"/connect/v1",
 	"/openai",
 	"/anthropic",
-	"/agui"
+	"/agui",
+	"/.well-known/workflow/v1",
+	"/api/workflows/hooks"
 ];
 var isPublicPath = (pathname, prefixes) => {
 	if (pathname === "/") return true;
@@ -9054,9 +9224,73 @@ var createRequestSignatureVerifier = (options) => {
 	};
 };
 //#endregion
+//#region ../../libs/runtime/workspace-runtime/src/lib/server/jwt-verifier-middleware.ts
+var JWT_DEFAULT_PUBLIC_PREFIXES = DEFAULT_PUBLIC_PREFIXES;
+var JWKS_COOLDOWN_MS = 3e4;
+var JWKS_CACHE_MAX_AGE_MS = 10 * 6e4;
+/** The Hono context variable the verified identity is stashed under. */
+var VERIFIED_IDENTITY_VAR = "stackboneVerifiedIdentity";
+/** Read the identity a successful JWT verification stashed on the context. */
+var readVerifiedIdentity = (c) => c.get(VERIFIED_IDENTITY_VAR);
+var BEARER_RE = /^Bearer\s+(.+)$/i;
+var extractBearer = (header) => {
+	if (!header) return null;
+	return BEARER_RE.exec(header.trim())?.[1]?.trim() || null;
+};
+var extractIdentity = (payload) => {
+	const userId = typeof payload.sub === "string" && payload.sub ? payload.sub : null;
+	if (!userId) return null;
+	const org = typeof payload["org"] === "string" ? payload["org"] : void 0;
+	const role = typeof payload["role"] === "string" ? payload["role"] : void 0;
+	const install = typeof payload["install"] === "string" ? payload["install"] : void 0;
+	return {
+		userId,
+		...org !== void 0 ? { org } : {},
+		...role !== void 0 ? { role } : {},
+		...install !== void 0 ? { install } : {}
+	};
+};
+/**
+* Build the Hono middleware that gates the box's surface behind a valid asymmetric
+* identity JWT. Mount it right after CORS (like the HMAC verifier) so the preflight
+* is answered by `hono/cors` and every gated route sees a verified caller.
+*/
+var createJwtVerifier = (options) => {
+	const publicPrefixes = options.publicPrefixes ?? JWT_DEFAULT_PUBLIC_PREFIXES;
+	const getKey = options.createJwks?.() ?? createRemoteJWKSet(new URL(options.jwksUrl), {
+		cooldownDuration: JWKS_COOLDOWN_MS,
+		cacheMaxAge: JWKS_CACHE_MAX_AGE_MS
+	});
+	const reject = (c) => c.json({
+		code: "invalid_token",
+		message: "Identity token is missing, expired, or invalid."
+	}, 401);
+	return async (c, next) => {
+		if (c.req.method === "OPTIONS") return next();
+		if (isPublicPath(new URL(c.req.url).pathname, publicPrefixes)) return next();
+		const token = extractBearer(c.req.header("authorization"));
+		if (!token) return reject(c);
+		let payload;
+		try {
+			({payload} = await jwtVerify(token, getKey, {
+				issuer: options.issuer,
+				audience: options.audience
+			}));
+		} catch {
+			return reject(c);
+		}
+		const identity = extractIdentity(payload);
+		if (!identity) return reject(c);
+		if (identity.org !== options.expectedOrg) return reject(c);
+		if (identity.install !== void 0 && identity.install !== options.expectedInstall) return reject(c);
+		c.set(VERIFIED_IDENTITY_VAR, identity);
+		return next();
+	};
+};
+//#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/contract.ts
 init_src$13();
-var STACKBONE_CLI_BUILD_VERSION = "0.2.7";
+var STACKBONE_CLI_BUILD_VERSION = "0.2.8";
 /**
 * Capabilities the local emulator advertises on `GET /api/contract`, derived
 * from the route registry above so the advertised set and the mounted routes
@@ -9698,9 +9932,63 @@ var init_src$6 = __esmMin((() => {
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/actor.ts
 init_src$11();
 function readActorUserId(c) {
+	const verified = readVerifiedIdentity(c);
+	if (verified?.userId) return verified.userId;
 	return c.req.header("x-stackbone-actor-user-id") || null;
 }
 //#endregion
+//#region ../../libs/runtime/workspace-runtime/src/lib/handlers/require-capability.ts
+var ROLES_WITH_CAPABILITY = {
+	"config:write": new Set([
+		"owner",
+		"admin",
+		"member"
+	]),
+	"hitl:decide": new Set([
+		"owner",
+		"admin",
+		"approver"
+	]),
+	"rag:write": new Set([
+		"owner",
+		"admin",
+		"member"
+	]),
+	"runs:invoke": new Set([
+		"owner",
+		"admin",
+		"member"
+	]),
+	"db:query": new Set([
+		"owner",
+		"admin",
+		"member"
+	]),
+	"secrets:rotate": new Set(["owner", "admin"]),
+	"secrets:reveal": new Set(["owner", "admin"]),
+	"connections:manage": new Set(["owner", "admin"])
+};
+/**
+* Build a Hono middleware that requires the caller's verified identity to grant
+* `capability`. A pass-through when there is no verified identity (proxy / dev /
+* self-host datapaths — see the module comment). On the browser-direct datapath a
+* missing/unknown role, or a role the matrix does not grant the capability, is a
+* 403 (fail-closed) before the handler runs.
+*/
+var requireCapability = (capability) => {
+	const allowed = ROLES_WITH_CAPABILITY[capability];
+	return async (c, next) => {
+		const identity = readVerifiedIdentity(c);
+		if (!identity) return next();
+		const role = identity.role;
+		if (!role || !allowed.has(role)) return c.json({
+			code: "forbidden",
+			message: `This action requires the ${capability} capability.`
+		}, 403);
+		return next();
+	};
+};
+//#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/handlers/prompts-handlers.ts
 init_src$10();
 init_src$13();
@@ -9800,7 +10088,7 @@ var createPromptsRouter = (opts) => {
             ORDER BY p.key
             LIMIT 200`)).rows.map((row) => rowToPrompt(row, row.current_version, row.content)) };
 	})));
-	app.post("/", async (c) => {
+	app.post("/", requireCapability("config:write"), async (c) => {
 		const raw = await c.req.json().catch(() => ({}));
 		const parsed = createStudioPromptRequestSchema.safeParse(raw);
 		if (!parsed.success) return c.json(invalidPayload$1(parsed.error.issues), 400);
@@ -9864,7 +10152,7 @@ var createPromptsRouter = (opts) => {
 			return c.json(rowToPrompt(head, head.current_version, head.content));
 		});
 	});
-	app.put("/:key", async (c) => {
+	app.put("/:key", requireCapability("config:write"), async (c) => {
 		const keyParsed = studioPromptKeyParamSchema.safeParse(c.req.param("key"));
 		if (!keyParsed.success) return c.json(notFound, 404);
 		const raw = await c.req.json().catch(() => ({}));
@@ -9897,7 +10185,7 @@ var createPromptsRouter = (opts) => {
 			return updated ? c.json(rowToPrompt(updated, updated.current_version, updated.content)) : c.json(notFound, 404);
 		});
 	});
-	app.delete("/:key", async (c) => {
+	app.delete("/:key", requireCapability("config:write"), async (c) => {
 		const keyParsed = studioPromptKeyParamSchema.safeParse(c.req.param("key"));
 		if (!keyParsed.success) return c.json(notFound, 404);
 		return withClient$2(opts, async (client) => {
@@ -9924,7 +10212,7 @@ var createPromptsRouter = (opts) => {
 			return c.json({ items: res.rows.map(rowToVersionItem) });
 		});
 	});
-	app.post("/:key/rollback", async (c) => {
+	app.post("/:key/rollback", requireCapability("config:write"), async (c) => {
 		const keyParsed = studioPromptKeyParamSchema.safeParse(c.req.param("key"));
 		if (!keyParsed.success) return c.json(notFound, 404);
 		const raw = await c.req.json().catch(() => ({}));
@@ -10169,7 +10457,7 @@ var createStorageRouter = (storageOptions) => {
 		const response = await listObjects$1(storageOptions, bucketParsed.data, queryParsed.data);
 		return c.json(response);
 	});
-	app.post("/buckets/:bucket/upload", async (c) => {
+	app.post("/buckets/:bucket/upload", requireCapability("runs:invoke"), async (c) => {
 		const bucketParsed = studioStorageBucketParamSchema.safeParse(c.req.param("bucket"));
 		if (!bucketParsed.success) return c.json({
 			code: "bucket_not_found",
@@ -10199,7 +10487,7 @@ var createStorageRouter = (storageOptions) => {
 		const response = await uploadObject$1(storageOptions, bucketParsed.data, keyParsed.data, buffer, file.type || void 0);
 		return c.json(response);
 	});
-	app.post("/buckets/:bucket/folders", async (c) => {
+	app.post("/buckets/:bucket/folders", requireCapability("runs:invoke"), async (c) => {
 		const bucketParsed = studioStorageBucketParamSchema.safeParse(c.req.param("bucket"));
 		if (!bucketParsed.success) return c.json({
 			code: "bucket_not_found",
@@ -10227,7 +10515,7 @@ var createStorageRouter = (storageOptions) => {
 			throw err;
 		}
 	});
-	app.delete("/buckets/:bucket/objects/:key", async (c) => {
+	app.delete("/buckets/:bucket/objects/:key", requireCapability("runs:invoke"), async (c) => {
 		const bucketParsed = studioStorageBucketParamSchema.safeParse(c.req.param("bucket"));
 		if (!bucketParsed.success) return c.json({
 			code: "bucket_not_found",
@@ -10414,11 +10702,11 @@ init_src$13();
 */
 var createSecretsRouter = (secretsOptions) => {
 	const app = new Hono();
-	app.get("/", async (c) => {
+	app.get("/", requireCapability("secrets:rotate"), async (c) => {
 		const response = await listSecrets$1(secretsOptions);
 		return c.json(response);
 	});
-	app.post("/", async (c) => {
+	app.post("/", requireCapability("secrets:rotate"), async (c) => {
 		const raw = await c.req.json().catch(() => ({}));
 		const parsed = createStudioSecretRequestSchema.safeParse(raw);
 		if (!parsed.success) return c.json({
@@ -10437,7 +10725,7 @@ var createSecretsRouter = (secretsOptions) => {
 			throw err;
 		}
 	});
-	app.delete("/:name", async (c) => {
+	app.delete("/:name", requireCapability("secrets:rotate"), async (c) => {
 		const parsed = studioSecretNameParamSchema.safeParse(c.req.param("name"));
 		if (!parsed.success) return c.json({
 			code: "studio_secret_not_found",
@@ -10461,7 +10749,7 @@ var createSecretsRouter = (secretsOptions) => {
 			throw err;
 		}
 	});
-	app.post("/:name/reveal", async (c) => {
+	app.post("/:name/reveal", requireCapability("secrets:reveal"), async (c) => {
 		const parsed = studioSecretNameParamSchema.safeParse(c.req.param("name"));
 		if (!parsed.success) return c.json({
 			code: "studio_secret_not_found",
@@ -10684,7 +10972,7 @@ var createConfigRouter = (agentConfigOptions) => {
 		const response = await getAgentConfig(agentConfigOptions);
 		return c.json(response);
 	});
-	app.put("/", async (c) => {
+	app.put("/", requireCapability("config:write"), async (c) => {
 		const raw = await c.req.json().catch(() => ({}));
 		const parsed = studioAgentConfigPutRequestSchema.safeParse(raw);
 		if (!parsed.success) return c.json({
@@ -10708,7 +10996,7 @@ var createConfigRouter = (agentConfigOptions) => {
 		const response = await listAgentConfigVersions(agentConfigOptions);
 		return c.json(response);
 	});
-	app.post("/rollback/:version", async (c) => {
+	app.post("/rollback/:version", requireCapability("config:write"), async (c) => {
 		const parsed = studioAgentConfigVersionParamSchema.safeParse(c.req.param("version"));
 		if (!parsed.success) return c.json({
 			code: "agent_config_version_not_found",
@@ -11110,7 +11398,7 @@ var createRunsRouter = (deps) => {
 			throw err;
 		}
 	});
-	app.post("/:id/retry", async (c) => {
+	app.post("/:id/retry", requireCapability("runs:invoke"), async (c) => {
 		const result = await deps.invocations.retry(c.req.param("id"));
 		if (!result) return c.json({
 			code: "run_not_found",
@@ -11131,7 +11419,7 @@ var createRunsRouter = (deps) => {
 		});
 		return c.json({ run: result.run }, 202);
 	});
-	app.post("/:id/cancel", async (c) => {
+	app.post("/:id/cancel", requireCapability("runs:invoke"), async (c) => {
 		const result = await deps.invocations.cancel(c.req.param("id"));
 		if (!result) return c.json({
 			code: "run_not_found",
@@ -16587,7 +16875,7 @@ var createApprovalsRouter = (deps) => {
 		}, 404);
 		return c.json(detail);
 	});
-	app.post("/:id/decide", async (c) => {
+	app.post("/:id/decide", requireCapability("hitl:decide"), async (c) => {
 		const raw = await c.req.json().catch(() => ({}));
 		const parsed = decideApprovalRequestSchema.safeParse(raw);
 		if (!parsed.success) return c.json({
@@ -16759,11 +17047,11 @@ init_src$13();
 var createDbExplorerRouter = (deps) => {
 	const app = new Hono();
 	const dbExplorerOptions = { connectionString: deps.connectionString };
-	app.get("/schemas", async (c) => {
+	app.get("/schemas", requireCapability("db:query"), async (c) => {
 		const response = await listSchemas(dbExplorerOptions);
 		return c.json(response);
 	});
-	app.get("/tables/:schema/:table", async (c) => {
+	app.get("/tables/:schema/:table", requireCapability("db:query"), async (c) => {
 		const paramsParsed = dbBrowseParamsSchema.safeParse({
 			schema: c.req.param("schema"),
 			table: c.req.param("table")
@@ -16797,7 +17085,7 @@ var createDbExplorerRouter = (deps) => {
 			throw err;
 		}
 	});
-	app.post("/query", async (c) => {
+	app.post("/query", requireCapability("db:query"), async (c) => {
 		const raw = await c.req.json().catch(() => ({}));
 		const parsed = dbQueryRequestSchema.safeParse(raw);
 		if (!parsed.success) return c.json({
@@ -17010,11 +17298,11 @@ var deleteBrowserProfile = async (opts, origin, identity) => withClient(opts, as
 var createBrowserProfilesRouter = (deps) => {
 	const app = new Hono();
 	const browserProfilesOptions = { connectionString: deps.connectionString };
-	app.get("/", async (c) => {
+	app.get("/", requireCapability("secrets:rotate"), async (c) => {
 		const response = await listBrowserProfiles(browserProfilesOptions);
 		return c.json(response);
 	});
-	app.delete("/", async (c) => {
+	app.delete("/", requireCapability("secrets:rotate"), async (c) => {
 		const origin = c.req.query("origin");
 		const identity = c.req.query("identity") ?? "agent";
 		if (!origin) return c.json({
@@ -17973,7 +18261,7 @@ var createRagRouter = (deps) => {
 			next_cursor: page.nextCursor
 		});
 	});
-	app.post("/jobs/:jobId/cancel", async (c) => {
+	app.post("/jobs/:jobId/cancel", requireCapability("rag:write"), async (c) => {
 		const result = await deps.invocations.cancel(c.req.param("jobId"));
 		if (!result) return c.json({
 			code: "rag_job_not_found",
@@ -17999,7 +18287,7 @@ var createRagRouter = (deps) => {
 			return trigger(input);
 		} } : {}
 	});
-	app.post("/collections", async (c) => {
+	app.post("/collections", requireCapability("rag:write"), async (c) => {
 		const raw = await c.req.json().catch(() => ({}));
 		const parsed = createRagCollectionRequestSchema.safeParse(raw);
 		if (!parsed.success) return c.json({
@@ -18013,7 +18301,7 @@ var createRagRouter = (deps) => {
 			return mapRagWriteError(c, err);
 		}
 	});
-	app.delete("/collections/:name", async (c) => {
+	app.delete("/collections/:name", requireCapability("rag:write"), async (c) => {
 		const nameParsed = ragCollectionNameParamSchema.safeParse(c.req.param("name"));
 		if (!nameParsed.success) return c.json({
 			code: "rag_collection_not_found",
@@ -18025,7 +18313,7 @@ var createRagRouter = (deps) => {
 			return mapRagWriteError(c, err);
 		}
 	});
-	app.post("/collections/:name/docs", async (c) => {
+	app.post("/collections/:name/docs", requireCapability("rag:write"), async (c) => {
 		const nameParsed = ragCollectionNameParamSchema.safeParse(c.req.param("name"));
 		if (!nameParsed.success) return c.json({
 			code: "rag_collection_not_found",
@@ -18067,7 +18355,7 @@ var createRagRouter = (deps) => {
 			return mapRagWriteError(c, err);
 		}
 	});
-	app.delete("/collections/:name/docs/:docId", async (c) => {
+	app.delete("/collections/:name/docs/:docId", requireCapability("rag:write"), async (c) => {
 		const nameParsed = ragCollectionNameParamSchema.safeParse(c.req.param("name"));
 		if (!nameParsed.success) return c.json({
 			code: "rag_collection_not_found",
@@ -18080,7 +18368,7 @@ var createRagRouter = (deps) => {
 			return mapRagWriteError(c, err);
 		}
 	});
-	app.post("/collections/:name/docs/:docId/download", async (c) => {
+	app.post("/collections/:name/docs/:docId/download", requireCapability("rag:write"), async (c) => {
 		const nameParsed = ragCollectionNameParamSchema.safeParse(c.req.param("name"));
 		if (!nameParsed.success) return c.json({
 			code: "rag_collection_not_found",
@@ -18093,7 +18381,7 @@ var createRagRouter = (deps) => {
 			return mapRagWriteError(c, err);
 		}
 	});
-	app.post("/jobs/:jobId/retry", async (c) => {
+	app.post("/jobs/:jobId/retry", requireCapability("rag:write"), async (c) => {
 		const parsed = ragJobIdParamSchema.safeParse({ jobId: c.req.param("jobId") });
 		if (!parsed.success) return c.json({
 			code: "rag_job_not_found",
@@ -19353,6 +19641,24 @@ var init_drizzle_broker_store = __esmMin((() => {
 		async deleteGrant(orgId, connector, principalKey) {
 			await this.db.delete(connectionGrantTable).where(and(eq(connectionGrantTable.organizationId, orgId), eq(connectionGrantTable.connector, connector), eq(connectionGrantTable.principalKey, principalKey)));
 		}
+		async listRefreshableGrants() {
+			const rows = await this.db.select().from(connectionGrantTable);
+			const grants = [];
+			for (const row of rows) try {
+				grants.push({
+					...this.decryptGrant(row),
+					healthStatus: row.healthStatus
+				});
+			} catch {}
+			return grants;
+		}
+		async setGrantHealth(input) {
+			await this.db.update(connectionGrantTable).set({
+				healthStatus: input.status,
+				healthDetail: input.detail,
+				updatedAt: /* @__PURE__ */ new Date()
+			}).where(eq(connectionGrantTable.id, input.grantId));
+		}
 		encrypt(plaintext) {
 			const envelope = this.cipher.encrypt(plaintext);
 			return {
@@ -19492,6 +19798,384 @@ var init_default_oauth_exchanger = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region ../../libs/platform/connect-broker/src/lib/refresh/grant-refresh-ports.ts
+/** Project a decrypted grant onto the refreshable shape the sweep consumes. */
+function grantToRefreshable(grant) {
+	return {
+		id: grant.id ?? `${grant.orgId}:${grant.connector}:${grant.principalKey}`,
+		organizationId: grant.orgId,
+		connectorId: grant.connector,
+		healthStatus: grant.healthStatus,
+		accessTokenExpiresAt: grant.expiresAt === null ? null : new Date(grant.expiresAt),
+		connector: grant.connector,
+		principalKey: grant.principalKey,
+		hasRefreshToken: grant.refreshToken !== null
+	};
+}
+function asHealthStatus(value) {
+	return value;
+}
+/**
+* Whether a refresh failure message signals a PERMANENT grant loss (the grant is
+* gone and a refresh will never succeed) vs a transient provider/network blip.
+* OAuth2 returns `invalid_grant` for a revoked/expired refresh token.
+*/
+function isPermanentRefreshFailure(message) {
+	const lowered = message.toLowerCase();
+	return lowered.includes("invalid_grant") || lowered.includes("invalid grant") || lowered.includes("access_denied") || lowered.includes("unauthorized_client");
+}
+var GrantRefreshableConnectionLoader, GrantConnectionRefresher, GrantConnectionHealthWriter, NoopGrantCascadeDisabler;
+var init_grant_refresh_ports = __esmMin((() => {
+	GrantRefreshableConnectionLoader = class {
+		constructor(lister) {
+			this.lister = lister;
+		}
+		async listRefreshable() {
+			return (await this.lister.listRefreshableGrants()).filter((g) => asHealthStatus(g.healthStatus) !== "revoked").map(grantToRefreshable);
+		}
+	};
+	GrantConnectionRefresher = class {
+		constructor(store, exchanger) {
+			this.store = store;
+			this.exchanger = exchanger;
+		}
+		async refresh(connection) {
+			const grantRef = connection;
+			if (grantRef.hasRefreshToken === false) return {
+				kind: "permanent",
+				reason: "no refresh token"
+			};
+			const grant = await this.store.getGrant(grantRef.organizationId, grantRef.connector, grantRef.principalKey);
+			if (grant === null) return {
+				kind: "permanent",
+				reason: "grant not found"
+			};
+			if (grant.refreshToken === null) return {
+				kind: "permanent",
+				reason: "no refresh token"
+			};
+			const connector = await this.store.getConnector(grant.orgId, grant.connector);
+			if (connector === null) return {
+				kind: "permanent",
+				reason: "connector not registered"
+			};
+			try {
+				const tokens = await this.exchanger.refresh({
+					connector,
+					refreshToken: grant.refreshToken
+				});
+				await this.store.upsertGrant({
+					...grant,
+					accessToken: tokens.accessToken,
+					refreshToken: tokens.refreshToken ?? grant.refreshToken,
+					expiresAt: tokens.expiresAt ?? null
+				});
+				return { kind: "refreshed" };
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				if (isPermanentRefreshFailure(message)) return {
+					kind: "permanent",
+					reason: message
+				};
+				return {
+					kind: "transient",
+					reason: message
+				};
+			}
+		}
+	};
+	GrantConnectionHealthWriter = class {
+		constructor(setter) {
+			this.setter = setter;
+		}
+		async setHealth(input) {
+			await this.setter.setGrantHealth({
+				grantId: input.connectionId,
+				status: input.status,
+				detail: input.detail
+			});
+		}
+	};
+	NoopGrantCascadeDisabler = class {
+		async disableDependents() {
+			return { disabledAutomationIds: [] };
+		}
+	};
+}));
+//#endregion
+//#region ../../libs/platform/connect-broker/src/lib/refresh/logger.ts
+var consoleRefreshLogger;
+var init_logger = __esmMin((() => {
+	consoleRefreshLogger = {
+		error: (message, context) => console.error("ERROR", message, context ? JSON.stringify(context) : ""),
+		warn: (message, context) => console.warn("WARN", message, context ? JSON.stringify(context) : ""),
+		info: (message, context) => console.info("INFO", message, context ? JSON.stringify(context) : ""),
+		debug: (message, context) => console.debug("DEBUG", message, context ? JSON.stringify(context) : "")
+	};
+})), REFRESH_REVOKED_REASON, ConnectionRefreshProcessor;
+var init_connection_refresh_processor = __esmMin((() => {
+	init_logger();
+	REFRESH_REVOKED_REASON = "connection token revoked";
+	ConnectionRefreshProcessor = class {
+		constructor(deps) {
+			this.deps = deps;
+			this.leadMs = deps.leadMs ?? 3e5;
+			this.now = deps.now ?? (() => /* @__PURE__ */ new Date());
+			this.logger = deps.logger ?? consoleRefreshLogger;
+		}
+		/**
+		* Decide whether a connection's token is due for a proactive refresh. A NULL
+		* expiry counts as due (PRD: a provider that omitted `expires_in` with no
+		* fallback would otherwise never refresh). Otherwise due when the expiry is
+		* within `leadMs` of now.
+		*/
+		isRefreshDue(connection) {
+			if (connection.accessTokenExpiresAt === null) return true;
+			return connection.accessTokenExpiresAt.getTime() - this.now().getTime() <= this.leadMs;
+		}
+		/** Sweep every refreshable connection once. Returns one result per connection. */
+		async sweep() {
+			const connections = await this.deps.connections.listRefreshable();
+			const results = [];
+			for (const connection of connections) results.push(await this.process(connection));
+			return results;
+		}
+		/** Run the state machine for ONE connection. */
+		async process(connection) {
+			if (!this.isRefreshDue(connection)) return {
+				connectionId: connection.id,
+				action: "skipped",
+				reason: "token-valid"
+			};
+			const outcome = await this.deps.refresher.refresh(connection);
+			switch (outcome.kind) {
+				case "refreshed":
+					if (connection.healthStatus !== "active") await this.deps.health.setHealth({
+						connectionId: connection.id,
+						status: "active",
+						detail: null
+					});
+					return {
+						connectionId: connection.id,
+						action: "refreshed"
+					};
+				case "transient":
+					await this.deps.health.setHealth({
+						connectionId: connection.id,
+						status: "error",
+						detail: outcome.reason
+					});
+					return {
+						connectionId: connection.id,
+						action: "transient-failure",
+						reason: outcome.reason
+					};
+				case "permanent": {
+					await this.deps.health.setHealth({
+						connectionId: connection.id,
+						status: "revoked",
+						detail: outcome.reason
+					});
+					const { disabledAutomationIds } = await this.deps.cascade.disableDependents({
+						connectionId: connection.id,
+						reason: REFRESH_REVOKED_REASON
+					});
+					this.logger.warn("oauth refresh: connection revoked, cascaded disable", {
+						connectionId: connection.id,
+						connectorId: connection.connectorId,
+						disabled: disabledAutomationIds.length,
+						reason: outcome.reason
+					});
+					return {
+						connectionId: connection.id,
+						action: "revoked",
+						reason: outcome.reason,
+						disabledAutomationIds
+					};
+				}
+			}
+		}
+	};
+})), CONNECTION_REFRESH_QUEUE, CONNECTION_REFRESH_JOB_NAME, CONNECTION_REFRESH_SCHEDULER_ID;
+var init_constants = __esmMin((() => {
+	CONNECTION_REFRESH_QUEUE = "connector-token-refresh";
+	CONNECTION_REFRESH_JOB_NAME = "refresh-sweep";
+	CONNECTION_REFRESH_SCHEDULER_ID = "connector-token-refresh:sweep";
+}));
+//#endregion
+//#region ../../libs/platform/connect-broker/src/lib/refresh/connection-refresh-scheduler.ts
+var ConnectionRefreshScheduler;
+var init_connection_refresh_scheduler = __esmMin((() => {
+	init_logger();
+	init_constants();
+	ConnectionRefreshScheduler = class {
+		constructor(options) {
+			this.logger = options.logger ?? consoleRefreshLogger;
+			this.queue = new Queue(CONNECTION_REFRESH_QUEUE, { connection: options.connection });
+			this.queue.on("error", (err) => {
+				this.logger.error(`connection refresh scheduler queue error: ${err.message}`, { stack: err.stack });
+			});
+			this.intervalMs = options.intervalMs ?? 9e5;
+			this.attempts = options.attempts ?? 3;
+			this.backoffDelayMs = options.backoffDelayMs ?? 3e4;
+		}
+		/**
+		* Ensure the single repeatable sweep exists. Idempotent — a re-`ensure()` on
+		* boot upserts the one scheduler in place, so a restart never stacks a second
+		* sweep.
+		*/
+		async ensure() {
+			const repeat = { every: this.intervalMs };
+			await this.queue.upsertJobScheduler(CONNECTION_REFRESH_SCHEDULER_ID, repeat, {
+				name: CONNECTION_REFRESH_JOB_NAME,
+				opts: {
+					attempts: this.attempts,
+					backoff: {
+						type: "exponential",
+						delay: this.backoffDelayMs
+					},
+					removeOnComplete: true,
+					removeOnFail: {
+						age: 1440 * 60,
+						count: 1e3
+					}
+				}
+			});
+		}
+		/** Remove the repeatable sweep. Idempotent. */
+		async remove() {
+			return { removed: await this.queue.removeJobScheduler(CONNECTION_REFRESH_SCHEDULER_ID) };
+		}
+		async close() {
+			await this.queue.close();
+		}
+	};
+}));
+//#endregion
+//#region ../../libs/platform/connect-broker/src/lib/refresh/connection-refresh-worker.ts
+var DEFAULT_CONCURRENCY, ConnectionRefreshWorker;
+var init_connection_refresh_worker = __esmMin((() => {
+	init_logger();
+	init_constants();
+	DEFAULT_CONCURRENCY = 1;
+	ConnectionRefreshWorker = class {
+		constructor(options) {
+			this.options = options;
+			this.logger = options.logger ?? consoleRefreshLogger;
+			this.worker = new Worker(CONNECTION_REFRESH_QUEUE, async (job) => this.process(job), {
+				connection: options.connection,
+				concurrency: options.concurrency ?? DEFAULT_CONCURRENCY
+			});
+			this.worker.on("error", (err) => {
+				this.logger.error(`connection refresh worker error: ${err.message}`, { stack: err.stack });
+			});
+			this.worker.on("failed", (job, err) => {
+				if (job && job.attemptsMade < (job.opts.attempts ?? 1)) return;
+				this.logger.warn("connection refresh: sweep exhausted", {
+					attempts: job?.attemptsMade ?? null,
+					reason: err.message
+				});
+			});
+		}
+		async waitUntilReady() {
+			await this.worker.waitUntilReady();
+		}
+		async close(force = false) {
+			await this.worker.close(force);
+		}
+		async process(_job) {
+			const results = await this.options.processor.sweep();
+			const revoked = results.filter((r) => r.action === "revoked").length;
+			const transient = results.filter((r) => r.action === "transient-failure").length;
+			const refreshed = results.filter((r) => r.action === "refreshed").length;
+			this.logger.warn("connection refresh: sweep complete", {
+				total: results.length,
+				refreshed,
+				transient,
+				revoked
+			});
+			return results;
+		}
+	};
+}));
+//#endregion
+//#region ../../libs/platform/connect-broker/src/lib/refresh/grant-refresh-runtime.ts
+/**
+* Build the broker's grant-backed refresh processor: the generic
+* `ConnectionRefreshProcessor` with the three grant-backed ports plumbed in. The
+* caller supplies the store + exchanger (the broker's own seams) and the
+* store-side listing + health-writing queries.
+*/
+function createGrantRefreshProcessor(deps) {
+	return new ConnectionRefreshProcessor({
+		connections: new GrantRefreshableConnectionLoader(deps.lister),
+		refresher: new GrantConnectionRefresher(deps.store, deps.exchanger),
+		health: new GrantConnectionHealthWriter(deps.healthSetter),
+		cascade: new NoopGrantCascadeDisabler(),
+		...deps.leadMs !== void 0 ? { leadMs: deps.leadMs } : {},
+		...deps.now !== void 0 ? { now: deps.now } : {},
+		...deps.logger !== void 0 ? { logger: deps.logger } : {}
+	});
+}
+/**
+* Build the broker's refresh SCHEDULER (the single repeatable sweep). A thin
+* re-instantiation of the connection-refresh scheduler — NOT a fork — so the
+* cadence / retry / backoff behaviour stays shared.
+*/
+function createGrantRefreshScheduler(options) {
+	return new ConnectionRefreshScheduler(options);
+}
+/**
+* Build the broker's refresh WORKER, draining the sweep queue and running the
+* grant-backed processor on each tick. A thin re-instantiation of the
+* connection-refresh worker.
+*/
+function createGrantRefreshWorker(options) {
+	return new ConnectionRefreshWorker({
+		connection: options.connection,
+		processor: options.processor,
+		...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {},
+		...options.logger !== void 0 ? { logger: options.logger } : {}
+	});
+}
+/**
+* Arm the box's proactive grant-refresh runtime IN ONE CALL (STA-265): build the
+* single repeatable {@link createGrantRefreshScheduler | sweep scheduler}, start the
+* {@link createGrantRefreshWorker | worker} that drains it, and `ensure()` the
+* repeatable exists. Idempotent across boots — the scheduler upserts the ONE
+* repeatable in place, so a re-arm never stacks a second sweep.
+*
+* This is the seam the box composition root (`emulator-server`, which runs the
+* agent box in cloud BYOC + self-host + the emulator) calls when a Redis URL is
+* present. The processor is built from the SAME box `DrizzleBrokerStore` the token
+* hot path uses, so every refresh reads/writes the box `connection_grant` rows —
+* never the control-plane DB.
+*/
+async function createGrantRefreshRuntime(deps) {
+	const scheduler = createGrantRefreshScheduler({
+		connection: deps.connection,
+		...deps.intervalMs !== void 0 ? { intervalMs: deps.intervalMs } : {},
+		...deps.logger !== void 0 ? { logger: deps.logger } : {}
+	});
+	const worker = createGrantRefreshWorker({
+		connection: deps.connection,
+		processor: deps.processor,
+		...deps.concurrency !== void 0 ? { concurrency: deps.concurrency } : {},
+		...deps.logger !== void 0 ? { logger: deps.logger } : {}
+	});
+	await scheduler.ensure();
+	return { async close() {
+		await worker.close().catch(() => void 0);
+		await scheduler.close().catch(() => void 0);
+	} };
+}
+var init_grant_refresh_runtime = __esmMin((() => {
+	init_connection_refresh_processor();
+	init_connection_refresh_scheduler();
+	init_connection_refresh_worker();
+	init_grant_refresh_ports();
+}));
+//#endregion
 //#region ../../libs/shared/connect-registry/src/lib/triggers/trigger-descriptor.ts
 var triggerCursorSchema, triggerListStepSchema, triggerItemStepSchema, declarativePollSchema, strategyPollSchema, pollSpecSchema, triggerDescriptorSchema;
 var init_trigger_descriptor = __esmMin((() => {
@@ -21043,6 +21727,8 @@ var init_src$2 = __esmMin((() => {
 	init_src$4();
 	init_src$11();
 	init_schema();
+	init_grant_refresh_ports();
+	init_grant_refresh_runtime();
 	init_connect_action_executor();
 	init_spec_introspection();
 	init_connector_definition_from_record();
@@ -21378,6 +22064,7 @@ var makeContextFactory = (opts) => {
 					}
 				}),
 				bindings,
+				exchanger,
 				brokerCallbackBaseUrl,
 				async close() {
 					await sql.end({ timeout: 5 }).catch(() => void 0);
@@ -21398,7 +22085,7 @@ var createConnectRouter = (opts, sharedContext) => {
 	const getContext = sharedContext ?? makeContextFactory(opts);
 	const registry = opts.registry ?? createRegistryStore();
 	const app = new Hono();
-	app.post("/connectors", async (c) => {
+	app.post("/connectors", requireCapability("connections:manage"), async (c) => {
 		const raw = await c.req.json().catch(() => ({}));
 		const parsed = registerConnectorRequestSchema.safeParse(raw);
 		if (!parsed.success) return c.json(invalidPayload(parsed.error.issues), 400);
@@ -21434,10 +22121,10 @@ var createConnectRouter = (opts, sharedContext) => {
 			displayName: persisted.displayName
 		});
 	});
-	app.get("/catalog", (c) => {
+	app.get("/catalog", requireCapability("connections:manage"), (c) => {
 		return c.json({ items: registry.list().map(connectorDefToCatalogEntry) });
 	});
-	app.get("/connectors", async (c) => {
+	app.get("/connectors", requireCapability("connections:manage"), async (c) => {
 		const rows = await (await getContext()).sql`
       SELECT id, provider, connector_id, client_id, client_secret_ciphertext,
              authorize_url, token_url, scopes, auth_mode, placement, display_name
@@ -21446,7 +22133,7 @@ var createConnectRouter = (opts, sharedContext) => {
        ORDER BY provider`;
 		return c.json({ items: rows.map((row) => connectorRowToResponse(row, registry)) });
 	});
-	app.delete("/connectors/:connectorId", async (c) => {
+	app.delete("/connectors/:connectorId", requireCapability("connections:manage"), async (c) => {
 		const connectorId = c.req.param("connectorId");
 		if ((await (await getContext()).sql`
       DELETE FROM connector
@@ -21460,7 +22147,7 @@ var createConnectRouter = (opts, sharedContext) => {
 			status: "deleted"
 		});
 	});
-	app.get("/connectors/:connectorId/operations", async (c) => {
+	app.get("/connectors/:connectorId/operations", requireCapability("connections:manage"), async (c) => {
 		const connectorId = c.req.param("connectorId");
 		const connector = await (await getContext()).store.getConnector(DEV_ORG_ID, connectorId);
 		if (!connector) return c.json({
@@ -21484,7 +22171,7 @@ var createConnectRouter = (opts, sharedContext) => {
 			}, 200);
 		}
 	});
-	app.post("/connectors/:connectorId/test", async (c) => {
+	app.post("/connectors/:connectorId/test", requireCapability("connections:manage"), async (c) => {
 		const connectorId = c.req.param("connectorId");
 		const ctx = await getContext();
 		const connector = await ctx.store.getConnector(DEV_ORG_ID, connectorId);
@@ -21515,7 +22202,7 @@ var createConnectRouter = (opts, sharedContext) => {
 		}
 	});
 	app.get("/connected", (c) => c.html("<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\" /><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\" /><title>Connected</title><style>body{font-family:ui-sans-serif,system-ui,sans-serif;background:#0b0b0c;color:#e7e7ea;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0}.card{text-align:center;max-width:28rem;padding:2rem}.tick{font-size:2.5rem}h1{font-size:1.1rem;margin:.75rem 0 .25rem}p{color:#a1a1aa;font-size:.9rem;line-height:1.5}</style></head><body><div class=\"card\"><div class=\"tick\">✓</div><h1>Account connected</h1><p>The credential is ready. You can close this tab and return to Studio — it now shows the grant under Connections → Grants.</p></div></body></html>"));
-	app.post("/connectors/:connectorId/authorize", async (c) => {
+	app.post("/connectors/:connectorId/authorize", requireCapability("connections:manage"), async (c) => {
 		const connectorId = c.req.param("connectorId");
 		const body = await c.req.json().catch(() => ({}));
 		const agentName = typeof body.agentName === "string" && body.agentName ? body.agentName : void 0;
@@ -21543,7 +22230,7 @@ var createConnectRouter = (opts, sharedContext) => {
 			return brokerErrorResponse(c, err);
 		}
 	});
-	app.get("/grants", async (c) => {
+	app.get("/grants", requireCapability("connections:manage"), async (c) => {
 		const rows = await (await getContext()).sql`
       SELECT id, connector, principal_key, expires_at, external_subject, health_status
         FROM connection_grant
@@ -21551,7 +22238,7 @@ var createConnectRouter = (opts, sharedContext) => {
        ORDER BY connector, principal_key`;
 		return c.json({ items: rows.map(grantRowToResponse) });
 	});
-	app.delete("/grants/:grantId", async (c) => {
+	app.delete("/grants/:grantId", requireCapability("connections:manage"), async (c) => {
 		const grantId = c.req.param("grantId");
 		const ctx = await getContext();
 		const row = (await ctx.sql`
@@ -21792,13 +22479,23 @@ var createConnectHandlers = (opts) => {
 			principal: request.principal
 		});
 	};
+	const createRefreshProcessor = async () => {
+		const ctx = await shared();
+		return createGrantRefreshProcessor({
+			store: ctx.store,
+			exchanger: ctx.exchanger,
+			lister: { listRefreshableGrants: () => ctx.store.listRefreshableGrants() },
+			healthSetter: { setGrantHealth: (input) => ctx.store.setGrantHealth(input) }
+		});
+	};
 	return {
 		management: createConnectRouter(opts, shared),
 		callback: createConnectCallbackRouter(opts, shared),
 		consumerCallback: createConnectConsumerCallbackRouter(opts, shared),
 		token: createConnectTokenRouter(opts, shared),
 		issueToken,
-		evict
+		evict,
+		createRefreshProcessor
 	};
 };
 var mergedCallbackParams = async (req) => {
@@ -28806,8 +29503,9 @@ var init_workflow_start_service = __esmMin((() => {
 		const resolved = await startResolvedWorkflow(deps, name, input);
 		if (resolved.queued) throw new Error(`Cannot await workflow "${name}": it was enqueued behind an active serialized run.`);
 		const { run } = resolved;
-		if (!run.returnValue) throw new Error(`Cannot await workflow "${name}": the runtime did not expose the run's return value (start() must resolve to a WDK Run with a \`returnValue\`).`);
-		const rawOutput = await run.returnValue;
+		const returnValue = run.returnValue;
+		if (!returnValue) throw new Error(`Cannot await workflow "${name}": the runtime did not expose the run's return value (start() must resolve to a WDK Run with a \`returnValue\`).`);
+		const rawOutput = await returnValue;
 		const outputValidator = await loadValidator(deps, name, "output");
 		if (outputValidator) {
 			const verdict = await validateWorkflowInput(outputValidator, rawOutput);
@@ -31595,8 +32293,10 @@ var init_mount = __esmMin((() => {
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/emulator-server.ts
 init_src$13();
+init_src$11();
 init_src$9();
 init_src$6();
+init_src$2();
 init_registry$1();
 init_resume_interrupt();
 /**
@@ -31636,6 +32336,23 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 		exposeHeaders: ["X-Stackbone-Run-Id"]
 	}));
 	if (opts.proxyAuth?.secret) app.use("*", createRequestSignatureVerifier({ secret: opts.proxyAuth.secret }));
+	if (opts.jwtAuth) app.use("*", createJwtVerifier(opts.jwtAuth));
+	if (opts.proxyChallenge?.secret) {
+		const challengeSecret = opts.proxyChallenge.secret;
+		app.get(PROXY_CHALLENGE_PATH, (c) => {
+			const url = new URL(c.req.url);
+			const ok = verifyStackboneSignature({
+				secret: challengeSecret,
+				header: c.req.header(STACKBONE_SIGNATURE_HEADER),
+				payload: proxyRequestPayload({
+					method: "GET",
+					path: url.pathname + url.search,
+					body: ""
+				})
+			});
+			return c.json({ ok }, ok ? 200 : 401);
+		});
+	}
 	app.get("/api/contract", (c) => c.json(buildContractResponse()));
 	app.get("/", (c) => c.html(renderStudioStub({
 		agentSlug: opts.agent.slug,
@@ -31746,12 +32463,15 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 	app.route("/api/prompts", createPromptsRouter({ connectionString: opts.injection.services.postgresUrl }));
 	const connectHandlers = createConnectHandlers({
 		connectionString: opts.injection.services.postgresUrl,
-		hmacSecret: DEV_HMAC_SECRET,
+		hmacSecret: opts.connectIdentity?.hmacSecret ?? "dev-stackbone-local-emulator-hmac-secret",
+		...opts.connectIdentity?.encryptionKey ? { encryptionKey: opts.connectIdentity.encryptionKey } : {},
 		...opts.connectRegistry ? { registry: opts.connectRegistry } : {},
+		...opts.connectCallbackBaseUrl ? { brokerCallbackBaseUrl: `${opts.connectCallbackBaseUrl.replace(/\/+$/, "")}/api/connect/callback` } : {},
 		...hooks.onWorkflowHookResume ? { onConnectionResume: (token) => hooks.onWorkflowHookResume?.(token, { status: "connected" }) } : {}
 	});
 	hooks.captureConnectIssueToken?.(connectHandlers.issueToken);
 	hooks.captureConnectEvictToken?.(connectHandlers.evict);
+	hooks.captureConnectRefreshProcessorFactory?.(connectHandlers.createRefreshProcessor);
 	app.route("/api/connect/callback", connectHandlers.callback);
 	app.route("/connect/v1/callback", connectHandlers.consumerCallback);
 	app.route("/api/connect", connectHandlers.token);
@@ -31824,7 +32544,7 @@ var startEmulatorServer = async (opts) => {
 			body: JSON.stringify(payload ?? {})
 		})).catch((err) => console.warn(`[workflow-hook-resume] decide-driven resume for token "${token}" failed: ${err instanceof Error ? err.message : String(err)}`));
 	};
-	const connectProjectRoot = opts.workflow?.projectRoot;
+	const connectProjectRoot = opts.workflow?.projectRoot ?? opts.deepAgents?.projectRoot;
 	const onConnectLog = opts.onConnectLog ?? ((level, message) => console[level === "warn" ? "warn" : "debug"](`[connect-registry] ${message}`));
 	const seededRegistry = opts.connectRegistry ?? await seedConnectorRegistry(connectProjectRoot, onConnectLog);
 	const seededOpts = {
@@ -31833,6 +32553,8 @@ var startEmulatorServer = async (opts) => {
 	};
 	let connectIssueToken;
 	let connectEvictToken;
+	let connectRefreshProcessorFactory;
+	let grantRefreshRuntime;
 	let deepAgentRegistry;
 	let deepAgentsProjectRoot;
 	const deepAgentLog = opts.onDeepAgentLog ? {
@@ -31871,6 +32593,9 @@ var startEmulatorServer = async (opts) => {
 		captureConnectEvictToken: (fn) => {
 			connectEvictToken = fn;
 		},
+		captureConnectRefreshProcessorFactory: (fn) => {
+			connectRefreshProcessorFactory = fn;
+		},
 		getDeepAgentRegistry: () => deepAgentRegistry
 	});
 	appHolder.app = app;
@@ -31907,6 +32632,19 @@ var startEmulatorServer = async (opts) => {
 		};
 		serialSupportHolder.support = workflowRuntimeHandle.serialSupport;
 	}
+	if (opts.connectRefreshRedisUrl && connectRefreshProcessorFactory) {
+		const redisUrl = opts.connectRefreshRedisUrl;
+		const buildRefreshProcessor = connectRefreshProcessorFactory;
+		try {
+			const processor = await buildRefreshProcessor();
+			grantRefreshRuntime = await createGrantRefreshRuntime({
+				connection: redisConnection(redisUrl),
+				processor
+			});
+		} catch (err) {
+			console.warn(`[grant-refresh] failed to arm the proactive refresh runtime: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
 	if (!opts.workflow) {
 		const fallbackDiscovery = () => ({
 			agents: deepAgentManifestEntries(deepAgentRegistry),
@@ -31929,9 +32667,9 @@ var startEmulatorServer = async (opts) => {
 			createApproval: (input) => opts.approvals.create(input),
 			decideStudioApproval: (threadId, decision) => retireStudioApprovalForThread(opts.approvals, threadId, decision),
 			connectTransport: {
-				hmacSecret: DEV_HMAC_SECRET,
+				hmacSecret: opts.connectIdentity?.hmacSecret ?? "dev-stackbone-local-emulator-hmac-secret",
 				brokerBaseUrl: `http://127.0.0.1:${opts.port}`,
-				installationId: DEV_INSTALLATION_ID
+				installationId: opts.connectIdentity?.installationId ?? "local-dev"
 			},
 			logger: deepAgentLog
 		});
@@ -31973,6 +32711,7 @@ var startEmulatorServer = async (opts) => {
 			workflowRunSweep?.stop();
 			workflowStepUnsubscribe?.();
 			await workflowRuntimeHandle?.close().catch(() => void 0);
+			await grantRefreshRuntime?.close().catch(() => void 0);
 			if (opts.workflow) await opts.workflow.world.close().catch(() => void 0);
 			await deepAgentRegistry?.close().catch(() => void 0);
 			await new Promise((resolve) => {
@@ -32024,169 +32763,6 @@ var buildDevServices = (ports) => ({
 var buildDevRedisUrl = (redisPort) => `redis://127.0.0.1:${redisPort}`;
 var DEV_AGENT_SECRET_KEY = createHash("sha256").update(STUDIO_LOCAL_DEV_ENCRYPTION_KEY).digest("base64");
 //#endregion
-//#region ../../libs/runtime/workspace-runtime/src/lib/connect-inbound/trigger-subscriptions-store.ts
-init_store_pool();
-init_uuid();
-var SUBSCRIPTION_COLUMNS = "id, connector, trigger_id, principal_key, workflow_name, mapping, mapping_graph, correlation_key, enabled, mailbox";
-var rowToSubscription = (row) => ({
-	id: row.id,
-	connector: row.connector,
-	trigger: row.trigger_id,
-	principalKey: row.principal_key,
-	workflowName: row.workflow_name,
-	mapping: row.mapping,
-	mappingGraph: row.mapping_graph ?? null,
-	correlationKey: row.correlation_key ?? null,
-	enabled: row.enabled,
-	mailbox: row.mailbox ?? null
-});
-var createTriggerSubscriptionsStore = (opts) => {
-	const { pool, assertOpen, close } = createStorePool("TriggerSubscriptionsStore", opts.connectionString);
-	return {
-		async register(input) {
-			assertOpen();
-			const id = randomUUID();
-			const { rows } = await pool.query(`INSERT INTO stackbone_platform.trigger_subscriptions
-           (id, connector, trigger_id, principal_key, workflow_name, mapping, mapping_graph, correlation_key, enabled, mailbox)
-         VALUES ($1::uuid, $2, $3, $4, $5, $6, $7::jsonb, $8, $9, $10)
-         RETURNING ${SUBSCRIPTION_COLUMNS}`, [
-				id,
-				input.connector,
-				input.trigger,
-				input.principalKey,
-				input.workflowName,
-				input.mapping ?? null,
-				input.mappingGraph == null ? null : JSON.stringify(input.mappingGraph),
-				input.correlationKey ?? null,
-				input.enabled ?? true,
-				input.mailbox ?? null
-			]);
-			return rowToSubscription(rows[0]);
-		},
-		async list() {
-			assertOpen();
-			const { rows } = await pool.query(`SELECT ${SUBSCRIPTION_COLUMNS}
-           FROM stackbone_platform.trigger_subscriptions
-          ORDER BY created_at DESC, id DESC`);
-			return rows.map(rowToSubscription);
-		},
-		async get(id) {
-			if (!isUuid(id)) return null;
-			assertOpen();
-			const { rows } = await pool.query(`SELECT ${SUBSCRIPTION_COLUMNS}
-           FROM stackbone_platform.trigger_subscriptions
-          WHERE id = $1::uuid`, [id]);
-			return rows[0] ? rowToSubscription(rows[0]) : null;
-		},
-		async update(id, patch) {
-			if (!isUuid(id)) return null;
-			assertOpen();
-			const sets = [];
-			const params = [id];
-			if (patch.enabled !== void 0) {
-				params.push(patch.enabled);
-				sets.push(`enabled = $${params.length}`);
-			}
-			if (patch.mapping !== void 0) {
-				params.push(patch.mapping);
-				sets.push(`mapping = $${params.length}`);
-			}
-			if (patch.mappingGraph !== void 0) {
-				params.push(patch.mappingGraph == null ? null : JSON.stringify(patch.mappingGraph));
-				sets.push(`mapping_graph = $${params.length}::jsonb`);
-			}
-			if (patch.correlationKey !== void 0) {
-				params.push(patch.correlationKey);
-				sets.push(`correlation_key = $${params.length}`);
-			}
-			if (sets.length === 0) return this.get(id);
-			const { rows } = await pool.query(`UPDATE stackbone_platform.trigger_subscriptions
-            SET ${sets.join(", ")}, updated_at = now()
-          WHERE id = $1::uuid
-        RETURNING ${SUBSCRIPTION_COLUMNS}`, params);
-			return rows[0] ? rowToSubscription(rows[0]) : null;
-		},
-		async remove(id) {
-			if (!isUuid(id)) return false;
-			assertOpen();
-			await pool.query("DELETE FROM stackbone_platform.trigger_deliveries WHERE subscription_id = $1::uuid", [id]);
-			return ((await pool.query("DELETE FROM stackbone_platform.trigger_subscriptions WHERE id = $1::uuid", [id])).rowCount ?? 0) > 0;
-		},
-		async listActive() {
-			assertOpen();
-			const { rows } = await pool.query(`SELECT ${SUBSCRIPTION_COLUMNS}
-           FROM stackbone_platform.trigger_subscriptions
-          WHERE enabled
-          ORDER BY created_at ASC, id ASC`);
-			return rows.map(rowToSubscription);
-		},
-		async readCursor(subscriptionId) {
-			assertOpen();
-			const { rows } = await pool.query("SELECT poll_cursor FROM stackbone_platform.trigger_subscriptions WHERE id = $1::uuid", [subscriptionId]);
-			return rows[0]?.poll_cursor ?? null;
-		},
-		async saveCursor({ subscriptionId, cursor, lastPolledAt }) {
-			assertOpen();
-			await pool.query(`UPDATE stackbone_platform.trigger_subscriptions
-            SET poll_cursor = $2::jsonb, last_polled_at = $3::timestamptz, updated_at = now()
-          WHERE id = $1::uuid`, [
-				subscriptionId,
-				cursor == null ? null : JSON.stringify(cursor),
-				lastPolledAt.toISOString()
-			]);
-		},
-		async claim(subscriptionId, providerItemId) {
-			assertOpen();
-			const { rows } = await pool.query(`INSERT INTO stackbone_platform.trigger_deliveries
-           (id, subscription_id, provider_item_id, status)
-         VALUES ($1::uuid, $2::uuid, $3, 'claimed')
-         ON CONFLICT (subscription_id, provider_item_id) DO NOTHING
-         RETURNING id`, [
-				randomUUID(),
-				subscriptionId,
-				providerItemId
-			]);
-			return rows.length > 0;
-		},
-		async markStarted(subscriptionId, providerItemId, runId) {
-			assertOpen();
-			await pool.query(`UPDATE stackbone_platform.trigger_deliveries
-            SET status = 'started', run_id = $3, updated_at = now()
-          WHERE subscription_id = $1::uuid AND provider_item_id = $2`, [
-				subscriptionId,
-				providerItemId,
-				runId
-			]);
-		},
-		async markResumed(subscriptionId, providerItemId, runId) {
-			assertOpen();
-			await pool.query(`UPDATE stackbone_platform.trigger_deliveries
-            SET status = 'resumed', run_id = COALESCE($3, run_id), updated_at = now()
-          WHERE subscription_id = $1::uuid AND provider_item_id = $2`, [
-				subscriptionId,
-				providerItemId,
-				runId ?? null
-			]);
-		},
-		async markRejected(subscriptionId, providerItemId, issues) {
-			assertOpen();
-			await pool.query(`UPDATE stackbone_platform.trigger_deliveries
-            SET status = 'rejected', issues = $3::jsonb, updated_at = now()
-          WHERE subscription_id = $1::uuid AND provider_item_id = $2`, [
-				subscriptionId,
-				providerItemId,
-				JSON.stringify(issues)
-			]);
-		},
-		async release(subscriptionId, providerItemId) {
-			assertOpen();
-			await pool.query(`DELETE FROM stackbone_platform.trigger_deliveries
-          WHERE subscription_id = $1::uuid AND provider_item_id = $2`, [subscriptionId, providerItemId]);
-		},
-		close
-	};
-};
-//#endregion
 //#region src/services/scaffold/file-plan.ts
 /**
 * Concatenate plans into one. On a duplicate path the FIRST plan wins, so a
@@ -32299,7 +32875,7 @@ var calls_workflow_ts_default = "import { z } from \"zod\";\nimport { streamDeep
 var plain_workflow_ts_default = "import { z } from \"zod\";\n\n/**\n * Workflow \"{{name}}\" — a durable pipeline.\n *\n * Each `\"use step\"` is a durable checkpoint: kill the runtime mid-run and it\n * resumes from the last completed step instead of replaying everything.\n */\n\n// THE contract — sibling exports next to the bare workflow function. The build\n// harvests these (by convention) into the manifest + a live validator. The\n// parameter type is DERIVED from `inputSchema` (`z.infer`), so there is no\n// second type that drifts.\nexport const inputSchema = z.object({\n  message: z.string().describe(\"The input to process\"),\n});\n\nexport const outputSchema = z.object({\n  message: z.string(),\n  processed: z.boolean(),\n});\n\ntype {{Name}}Input = z.infer<typeof inputSchema>;\n\nexport async function {{export}}(input: {{Name}}Input) {\n  \"use workflow\";\n\n  const result = await processMessage(input); // step 1 — durable checkpoint\n  return result;\n}\n\nasync function processMessage(input: {{Name}}Input) {\n  \"use step\";\n  // Replace this with the deterministic work of your step (DB write, HTTP call,\n  // an LLM call, …). Returning a value records it as the step's checkpoint.\n  return { message: input.message, processed: true };\n}\n";
 //#endregion
 //#region src/services/scaffold/template-loader.ts
-var SDK_TEMPLATE_VERSION = "0.2.5";
+var SDK_TEMPLATE_VERSION = "0.2.6";
 var PREFIX = "./templates/";
 var templates = new Map(Object.entries(/* @__PURE__ */ Object.assign({
 	"./templates/deep-agents/index.ts.tmpl": index_ts_default,
@@ -33619,7 +34195,7 @@ var runValidateContract = async (ctx, args, deps = {}) => {
 	const versionCheck = requireVersion(contract);
 	if (versionCheck.error) violations.push(versionCheck.error.message);
 	for (const capability of manifest.capabilities) {
-		const check = requireCapability(capability, contract);
+		const check = requireCapability$1(capability, contract);
 		if (check.error) violations.push(check.error.message);
 	}
 	const ok = violations.length === 0;
@@ -35863,12 +36439,32 @@ async function suggest(sourceSample, targetSchema, sourceSchema) {
     'from the source event. Return STRICT JSON of the shape ' +
     '{ "suggestions": [ { "targetPath": "<dotted path in the target>", "jsonata": "<JSONata expression over the source>", "confidence": <0..1>, "note": "<short reason>" } ] }. ' +
     'Only include a suggestion when you are reasonably confident. Omit fields you cannot map. ' +
-    'Return an empty suggestions array if nothing maps.';
-  const payload = { sourceSample: sourceSample, targetSchema: targetSchema };
+    'Return an empty suggestions array if nothing maps.\\n' +
+    // Without this the model writes paths relative to the JSON envelope below
+    // ("sourceSample.subject"), which evaluates to nothing against a real event.
+    'CRITICAL — each expression is evaluated with THE SOURCE EVENT ITSELF as the root ' +
+    'context. Write the path exactly as it appears inside the event: for an event ' +
+    '{ "subject": "Hi", "from": { "address": "a@b.c" } } the expressions are "subject" and ' +
+    '"from.address". NEVER prefix a path with "sourceSample", "event", "input" or any ' +
+    'other wrapper name — those are labels in the prompt below, not part of the data.\\n' +
+    'Return the BARE field reference by default. Do not change case, trim, reformat or ' +
+    'otherwise decorate a value on your own initiative: copying "subject" into a plain ' +
+    'string field is "subject", not $uppercase(subject). Transform only when the TARGET ' +
+    'field asks for it — a different type, a declared format or enum, or its own ' +
+    'description spelling out the shape it wants — and then use ONLY built-in JSONata ' +
+    'functions, which all start with "$" (e.g. $substring, $join, $number). Never invent ' +
+    'a function name.';
+  const parts = [
+    'SOURCE EVENT SAMPLE (the root context your expressions run against):',
+    JSON.stringify(sourceSample, null, 2),
+    '',
+    'TARGET WORKFLOW INPUT SCHEMA (what targetPath addresses):',
+    JSON.stringify(targetSchema, null, 2),
+  ];
   if (sourceSchema) {
-    payload.sourceSchema = sourceSchema;
+    parts.push('', 'SOURCE EVENT JSON SCHEMA:', JSON.stringify(sourceSchema, null, 2));
   }
-  const user = 'Map this source event to the target schema:\\n' + JSON.stringify(payload, null, 2);
+  const user = parts.join('\\n');
 
   const result = await stackbone.ai.chat.completions.create({
     model: MAPPING_SUGGEST_MODEL,
@@ -37650,6 +38246,7 @@ var startDevSession = async (input) => {
 				onConnectLog: (level, message) => input.ctx.logger[level === "warn" ? "warn" : "debug"]({ stage: "connect" }, message),
 				onDeepAgentLog: (level, message) => input.ctx.logger[level]({ stage: "deep-agents" }, message),
 				...workflowRuntime ? { workflow: workflowRuntime } : {},
+				connectRefreshRedisUrl: devRedisUrl,
 				deepAgents: {
 					projectRoot: input.projectRoot,
 					agents: workspace.deepAgents ?? []
@@ -38242,7 +38839,7 @@ Available topics:
   cli/agent-protocol     The HTTP contract a Stackbone workspace exposes: OpenAI-compatible, Anthropic-compatible and AG-UI chat, durable workflows, and health.
   cli/local-development  How stackbone dev boots your agents and durable workflows locally, injects env vars and tunnels to cloud Studio.
   cli/agent-yaml         How a Stackbone project is declared — workspace discovery by convention (deep-agents/<name>/index.ts + workflows/), the optional agent.yaml manifest, and the optional stackbone.config.ts override.
-  cli/troubleshooting    Diagnose and fix the common stackbone dev and stackbone publish failures, keyed on the error codes the CLI actually emits.
+  cli/troubleshooting    Diagnose and fix the common stackbone dev and agent-runtime failures, keyed on the error codes the CLI actually emits.
 
 Run \`stackbone docs <topic>\` to view one.
 `,
@@ -38262,9 +38859,10 @@ A Stackbone project is two things working together:
   approvals, built on the [Workflow SDK](https://workflow-sdk.dev/docs).
   Steps run once, are persisted, and retry on failure.
 
-You author both with the ambient \`stackbone\` client, run them locally with
-\`stackbone dev\`, and ship them with \`stackbone publish\`. This page gets you
-to a running agent on your machine.
+You author both with the ambient \`stackbone\` client and run them locally with
+\`stackbone dev\`. To go live you deploy the agent's container image into your
+own cloud and register it with \`stackbone link\`. This page gets you to a
+running agent on your machine.
 
 ## Prerequisites
 
@@ -38568,8 +39166,8 @@ workspace is read straight from two folders:
   \`<camelCase(name)>Workflow\` function (e.g. \`qualify-lead.workflow.ts\` exports
   \`qualifyLeadWorkflow\`).
 
-\`stackbone dev\` and \`stackbone publish\` both read this same convention. An
-optional \`stackbone.config.ts\` (default-exporting \`defineWorkspace({ workflows })\`)
+\`stackbone dev\` reads this convention. An optional \`stackbone.config.ts\`
+(default-exporting \`defineWorkspace({ workflows })\`)
 is an **override** for workflows only: when it exists it wins over the
 convention scan for workflows; agents are always discovered from
 \`deep-agents/\`. Most projects need no \`stackbone.config.ts\` at all.
@@ -38656,19 +39254,17 @@ control plane, the one \`stackbone init\`, \`stackbone link\` and
 stored per environment in \`~/.stackbone/credentials.json\`, so logging
 into a different control plane keeps its own selection.
 
-\`stackbone publish\` is **not** affected by this setting: it always
-publishes to the organization recorded in that project's
-\`.stackbone/project.json\`. So the way to publish into a specific
-organization is to switch first, then create the project there:
+An already-created project is **not** affected by this setting: it stays with
+the organization recorded in its \`.stackbone/project.json\`. So the way to work
+in a specific organization is to switch first, then create the project there:
 
 \`\`\`bash
 stackbone organization use            # interactive picker (TTY)
 stackbone organization use acme       # switch straight to a slug
 
-# Publish into a chosen org:
+# Create a workspace inside a chosen org:
 stackbone organization use acme        # 1. make "acme" active
 stackbone init my-app --with agent     # 2. the new workspace is registered in "acme"
-stackbone publish                      # 3. publishes to "acme" (from project.json)
 \`\`\`
 
 - With a \`slug\` argument it switches directly (works in CI and \`--json\`).
@@ -38723,7 +39319,7 @@ rely on it.
 Scaffold a new workspace. \`init\` is **workspace-first** and **links the
 workspace** to your organization: it registers the workspace's identity in
 the control plane and writes a \`.stackbone/project.json\` (so \`dev\`,
-\`publish\` and the management commands know which org to talk to). You
+\`link\` and the management commands know which org to talk to). You
 must be signed in (\`stackbone login\`) first, there is no offline \`init\`.
 Alongside the link it writes the workspace shell.
 
@@ -38882,16 +39478,56 @@ workspace), \`1\` generic (a name collision without \`--force\`, or an unknown
 
 ### \`stackbone link\`
 
-Link the current directory to an existing organization + agent. Writes
-\`.stackbone/project.json\`, patches \`.gitignore\` and re-runs the
+Link the current directory to an existing organization + agent, and register
+the **deployment** you run that agent on. Writes \`.stackbone/project.json\`,
+patches \`.gitignore\` and re-runs the
 [Stackbone agent skills install](/docs/coding-agents/overview) (same
 best-effort step \`init\` performs). Does **not** scaffold starter files,
 use \`init\` for that.
 
-| Flag      | Type    | Description                                                                   |
-| --------- | ------- | ----------------------------------------------------------------------------- |
-| \`--agent\` | string  | Agent slug to link to. Required in non-interactive mode (CI, \`--json\`, \`-y\`). |
-| \`--force\` | boolean | Overwrite an existing \`.stackbone/project.json\`.                              |
+You host the agent yourself: you build and deploy the container image into
+your own cloud, then tell Stackbone where it lives. That is what the three
+required flags do. \`--url\` is the public URL the container answers on,
+\`--secret\` is the \`HMAC_SECRET\` you set on the container (it must match
+exactly), and \`--tag\` is the image tag you deployed. The tag is the agent's
+version: there is no separate build step to promote.
+
+\`\`\`sh
+stackbone link \\
+  --agent support \\
+  --url https://support.acme.example.com \\
+  --secret "$STACKBONE_HMAC_SECRET" \\
+  --tag 1.4.0
+\`\`\`
+
+All three flags are validated before any network call, so a missing one fails
+immediately instead of half-linking the project. Re-running \`link\` for the same
+agent updates the existing deployment (the new URL, secret and tag win) rather
+than creating a second one, so it is safe to run on every deploy.
+
+| Flag       | Type    | Description                                                                                      |
+| ---------- | ------- | ------------------------------------------------------------------------------------------------ |
+| \`--agent\`  | string  | Agent slug to link to. Required in non-interactive mode (CI, \`--json\`, \`-y\`).                    |
+| \`--url\`    | string  | **Required.** Public URL where the deployed agent is reachable.                                  |
+| \`--secret\` | string  | **Required.** The \`HMAC_SECRET\` you set on the deployed container. Must match it exactly.        |
+| \`--tag\`    | string  | **Required.** Tag of the image you deployed (a semver or a digest). This is the agent's version. |
+| \`--force\`  | boolean | Overwrite an existing \`.stackbone/project.json\`.                                                 |
+
+**The deploy then link flow.** You generate an HMAC secret, set it as the
+\`HMAC_SECRET\` env var on the container, start the container, then run
+\`stackbone link --agent <slug> --url <url> --secret <value> --tag <tag>\`. The control plane signs
+every request it later proxies to your box with this secret, and your box
+verifies the signature, so the two values have to be identical.
+
+**\`link\` proves the secret before it saves anything.** Before it registers the
+deployment, \`link\` signs a challenge request to your container and your container
+verifies it against its own \`HMAC_SECRET\`. A match saves the secret (encrypted at
+rest). A mismatch stops with an actionable error and saves nothing, so a typo
+fails at \`link\` time instead of quietly breaking the proxy later. If your box is
+unreachable, \`link\` says so and saves nothing.
+
+If you registered a deployment before this check existed, re-run \`stackbone link\`
+once to validate and re-save the secret.
 
 **JSON payload**
 
@@ -38901,6 +39537,13 @@ use \`init\` for that.
   "agent": { "id": "...", "slug": "...", "name": "..." },
   "organization_id": "...",
   "local_dev_installation": { "id": "...", "organization_slug": "..." },
+  "deployment": {
+    "id": "...",
+    "url": "https://support.acme.example.com",
+    "image_tag": "1.4.0",
+    "status": "...",
+    "last_active_at": "2026-07-21T09:00:00Z" /* or null before the first call */,
+  },
   "target_dir": "/abs/path",
   "files_written": [".stackbone/project.json", ".gitignore"],
   "skills_install": {
@@ -39307,61 +39950,13 @@ Classify each migration as \`applied\`, \`pending\` or \`drifted\`
 **Exit codes**: \`0\` ok (regardless of drift), \`3\` no project, \`1\`
 generic (cannot reach the DB).
 
-## Cloud publish
-
-### \`stackbone publish\`
-
-Package the project into a publishable artifact. \`publish\` reads the
-**workspace** by convention, every \`deep-agents/<name>/index.ts\` (or an
-explicit \`stackbone.config.ts\` override for workflows), and compiles
-every agent and every durable workflow into a verifiable tar at
-\`dist/stackbone/workspace-bundle.tar\`.
-
-Native dependencies (\`.node\` add-ons) are rejected up front, the runtime image
-is pure-JS, so a native bundle would crash at boot.
-
-| Flag     | Type    | Default | Description                                              |
-| -------- | ------- | ------- | -------------------------------------------------------- |
-| \`--json\` | boolean | \`false\` | Emit structured JSON envelopes instead of the pretty UI. |
-
-Run \`stackbone publish --help\` for the full reference.
-
-#### Workspace (discovered by convention)
-
-Compiles every agent and every durable workflow **on your machine** and packs
-them into a tar so cold boot only extracts, it never recompiles. In order:
-
-1. Load the workspace and its agents + workflows.
-2. **Native-deps gate, per agent**: a \`.node\` add-on aborts with the offending
-   package name.
-3. Compile each agent to a prebuilt ESM module, keeping the agent-authoring
-   library and its model provider packages external so one copy of each
-   resolves from the runtime image at boot.
-4. **SDK-external guardrail, per agent**: an agent that inlined \`@stackbone/sdk\`
-   aborts (a second copy of the SDK would break per-run logging).
-5. Compile the workflows.
-6. Derive the \`.well-known/workspace.json\` manifest, pack the tar and compute its
-   SHA-256 digest.
+## Going to production
 
-The artifacts land in your project under \`dist/stackbone/\`:
-\`workspace-bundle.tar\` (the bundle) and \`workspace-bundle.json\` (a pointer with
-the digest, size, and the agent + workflow names). The control-plane upload is
-handled by provisioning when you ship the install, \`publish\` produces and
-verifies the bundle.
-
-**JSON payload (workspace)**
-
-\`\`\`jsonc
-{
-  "schema_version": 1,
-  "kind": "workspace",
-  "digest": "<sha256>",
-  "sizeBytes": 1234567,
-  "agents": ["support", "billing"],
-  "workflows": ["onboarding"],
-  "tar": "dist/stackbone/workspace-bundle.tar",
-}
-\`\`\`
+There is no publish command. You run the agent in **your own cloud**: build
+the container image, deploy it wherever you host services, then register it
+with [\`stackbone link\`](#stackbone-link) so Stackbone knows its URL, its HMAC
+secret and the image tag it is running. The tag is the agent's version, so
+shipping a new version means deploying a new image and re-running \`link\`.
 
 ## Inline help
 
@@ -39464,15 +40059,14 @@ Lives under \`~/.stackbone/\`:
 
 Lives at the project root:
 
-| Path                                    | Tracked?                                         | What it stores                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| --------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| \`stackbone.config.ts\`                   | **Optional**                                     | An _optional_ workflow override. By default \`stackbone dev\` and \`stackbone publish\` **derive** the workspace registry by convention — scanning every \`deep-agents/<name>/index.ts\` and every \`workflows/<name>.workflow.ts\` file — so most projects need no config file at all. When this file is present (default-exporting \`defineWorkspace({ workflows })\` from \`@stackbone/sdk\`) its \`workflows\` **win** over the convention scan; agents are always discovered from \`deep-agents/\`. See [Workflows](/docs/workflows/overview). |
-| \`.stackbone/project.json\`               | **No** (gitignored by \`stackbone init\`)          | \`{ schemaVersion, organizationId, agentId, controlPlaneUrl }\`. Identifies which organization this workspace points at.                                                                                                                                                                                                                                                                                                                                                                                                              |
-| \`.stackbone/*.d.ts\`                     | **No** (gitignored)                              | Generated editor types — \`config.d.ts\`, \`agents.d.ts\`, \`connect.d.ts\` — that give the ambient \`stackbone\` client typed autocompletion. Regenerated by \`stackbone dev\`; \`config.d.ts\` also by \`stackbone config types\` (no control plane needed).                                                                                                                                                                                                                                                                                    |
-| \`stackbone.config.json\`                 | **Yes**                                          | \`{ studio: { corsOrigins } }\` and other team-shared knobs. Reviewable in PRs. **Different file** from \`stackbone.config.ts\` above — the \`.json\` holds CLI/Studio knobs, the \`.ts\` holds the workspace manifest.                                                                                                                                                                                                                                                                                                                     |
-| \`agent.yaml\`                            | **Yes**                                          | Manifest. See [agent.yaml reference](/docs/cli/agent-yaml).                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| \`dist/stackbone/\`                       | **No** (build output)                            | Written by \`stackbone publish\` — the workspace bundle (\`workspace-bundle.tar\`) plus its JSON pointer (\`workspace-bundle.json\`, carrying the content digest).                                                                                                                                                                                                                                                                                                                                                                        |
-| \`.claude/\`, \`.cursor/\`, \`.windsurf/\`, … | **No** (gitignored by \`stackbone init\` / \`link\`) | Per-coding-agent skill directories the upstream \`skills\` registry materialises. See [Agent skills overview](/docs/coding-agents/overview).                                                                                                                                                                                                                                                                                                                                                                                          |
+| Path                                    | Tracked?                                         | What it stores                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| --------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| \`stackbone.config.ts\`                   | **Optional**                                     | An _optional_ workflow override. By default \`stackbone dev\` **derives** the workspace registry by convention (scanning every \`deep-agents/<name>/index.ts\` and every \`workflows/<name>.workflow.ts\` file), so most projects need no config file at all. When this file is present (default-exporting \`defineWorkspace({ workflows })\` from \`@stackbone/sdk\`) its \`workflows\` **win** over the convention scan; agents are always discovered from \`deep-agents/\`. See [Workflows](/docs/workflows/overview). |
+| \`.stackbone/project.json\`               | **No** (gitignored by \`stackbone init\`)          | \`{ schemaVersion, organizationId, agentId, controlPlaneUrl }\`. Identifies which organization this workspace points at.                                                                                                                                                                                                                                                                                                                                                                                      |
+| \`.stackbone/*.d.ts\`                     | **No** (gitignored)                              | Generated editor types — \`config.d.ts\`, \`agents.d.ts\`, \`connect.d.ts\` — that give the ambient \`stackbone\` client typed autocompletion. Regenerated by \`stackbone dev\`; \`config.d.ts\` also by \`stackbone config types\` (no control plane needed).                                                                                                                                                                                                                                                            |
+| \`stackbone.config.json\`                 | **Yes**                                          | \`{ studio: { corsOrigins } }\` and other team-shared knobs. Reviewable in PRs. **Different file** from \`stackbone.config.ts\` above — the \`.json\` holds CLI/Studio knobs, the \`.ts\` holds the workspace manifest.                                                                                                                                                                                                                                                                                             |
+| \`agent.yaml\`                            | **Yes**                                          | Manifest. See [agent.yaml reference](/docs/cli/agent-yaml).                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| \`.claude/\`, \`.cursor/\`, \`.windsurf/\`, … | **No** (gitignored by \`stackbone init\` / \`link\`) | Per-coding-agent skill directories the upstream \`skills\` registry materialises. See [Agent skills overview](/docs/coding-agents/overview).                                                                                                                                                                                                                                                                                                                                                                  |
 
 ## Output contract
 
@@ -40144,8 +40738,7 @@ them down in reverse order:
 ### How the workspace is discovered
 
 A **workspace** is discovered by convention from the files on disk, you do
-not maintain a registry. \`stackbone dev\` (and \`stackbone publish\`) scan your
-project the same way:
+not maintain a registry. \`stackbone dev\` scans your project this way:
 
 - **Agents**: every folder under \`deep-agents/\` that contains an \`index.ts\`
   exporting an agent definition. The folder name is both the agent name and
@@ -40421,8 +41014,8 @@ the protocol version. If your CLI is older than \`minSupported\` the UI shows a
 > in only when you need to name your workflows explicitly, and it wins over
 > the convention scan for workflows.
 >
-> \`stackbone dev\` and \`stackbone publish\` both read the same convention: they
-> discover the workspace from every \`deep-agents/<name>/index.ts\` on disk
+> \`stackbone dev\` reads the convention: it
+> discovers the workspace from every \`deep-agents/<name>/index.ts\` on disk
 > (agents are always discovered this way; \`stackbone.config.ts\` can only
 > override the workflow list). When present, \`agent.yaml\` is validated
 > strictly and belongs under version control.
@@ -40430,8 +41023,8 @@ the protocol version. If your CLI is older than \`minSupported\` the UI shows a
 ## Workspace discovery by convention
 
 The runtime derives the workspace from the files on disk, there is no
-hand-maintained registry. \`stackbone dev\` and \`stackbone publish\` both read the
-same two conventions:
+hand-maintained registry. \`stackbone dev\` reads the same two conventions the
+runtime does:
 
 - **Agents**: every folder under \`deep-agents/\` that contains an \`index.ts\`
   entry file. The folder name is both the agent's identity and the \`model\` a
@@ -40512,17 +41105,6 @@ your editor. They are derived artifacts, git-ignore them:
 | \`.stackbone/connect.d.ts\` | \`stackbone.connection('<id>')\` and its connector methods.      |
 | \`.stackbone/config.d.ts\`  | \`stackbone.config.get('<key>')\` typed from your config schema. |
 
-### What \`stackbone publish\` produces
-
-For a workspace, \`stackbone publish\` compiles every agent and every workflow on
-your machine and packs them into a single tar at
-\`dist/stackbone/workspace-bundle.tar\`, next to a \`workspace-bundle.json\` pointer
-(digest, size, the agent + workflow names). Inside the tar is a
-\`.well-known/workspace.json\` manifest the runtime reads at boot to know which
-agents and workflows to launch. The published bundle is pure JavaScript, native
-add-ons are rejected up front, so publish fails early if a dependency is not
-pure-JS.
-
 ## \`agent.yaml\`: the optional workspace manifest
 
 A workspace may carry a single \`agent.yaml\` at its root describing project-wide
@@ -40554,9 +41136,11 @@ Human-readable workspace name. Must be a non-empty string.
 
 ### \`version\` (optional)
 
-A display-only label copied verbatim onto the build at publish time (e.g.
-\`v0.2.0\`). Never validated as semver, never made unique, it just renders next to
-the build on the install detail page. Omit it and the build carries no label.
+A display-only label (e.g. \`v0.2.0\`). Never validated as semver, never made
+unique, it just renders on the install detail page. The version that actually
+identifies what is running is the image tag you register with
+\`stackbone link --tag\`, see
+[Commands → \`stackbone link\`](/docs/cli/commands#stackbone-link).
 
 \`\`\`yaml
 version: v0.2.0
@@ -40711,11 +41295,10 @@ on disk, plus every \`workflows/<name>.workflow.ts\` (or an explicit
 \`stackbone.config.ts\` override for workflows). The optional root \`agent.yaml\`
 supplies the project-wide database/runtime knobs when it is present.
 
-| Command             | What it reads                                                     |
-| ------------------- | ----------------------------------------------------------------- |
-| \`stackbone dev\`     | The discovered workspace, boots every agent + every workflow.     |
-| \`stackbone publish\` | The discovered workspace → \`dist/stackbone/workspace-bundle.tar\`. |
-| \`stackbone db ...\`  | The root \`agent.yaml\` \`database\` block, when present.             |
+| Command            | What it reads                                                 |
+| ------------------ | ------------------------------------------------------------- |
+| \`stackbone dev\`    | The discovered workspace, boots every agent + every workflow. |
+| \`stackbone db ...\` | The root \`agent.yaml\` \`database\` block, when present.         |
 
 Every manifest is yours to edit and belongs under version control, the control
 plane never writes to them.
@@ -40885,68 +41468,22 @@ schema\`) is exercised through \`stackbone dev\` today. Pointed at an installati
 that does not serve the workflow routes, those commands come back empty rather
 than erroring.
 
-## \`stackbone publish\` failures
-
-\`stackbone publish\` compiles your whole workspace **once**, on your machine,
-into a single bundle. Every guardrail below aborts _before_ a bundle is
-produced — a failed publish ships **nothing**, which is the point: a publish
-error is always better than a crash-loop in production. Each abort prints the
-exact fix; here is what each one means.
-
-### \`@stackbone/sdk\` inlined into an agent build
-
-> \`stackbone publish failed: deep agent "<name>" inlined @stackbone/sdk into its build.\`
-
-A workspace agent must keep \`@stackbone/sdk\` **external**, so it resolves to a
-single copy at runtime. A second copy gives the agent its own ambient context
-and per-run logs arrive empty. \`defineDeepAgent\` from \`@stackbone/sdk/deep\`
-keeps the SDK external for you automatically; this error only appears if
-something in your build pipeline forces it to inline anyway (for example a
-bundler config outside \`stackbone publish\` re-processing the output). Remove
-whatever is re-bundling \`@stackbone/sdk\` and re-publish.
-
-### Native dependencies rejected
-
-> \`stackbone publish failed: native dependencies detected in deep agent "<name>".\`
-
-The workspace runtime runs pure-JS agents only. A dependency with native
-bindings (\`.node\` files) is rejected with the offending package name. Remove the
-native dependency from that agent.
-
-### No agents declared
-
-> \`This workspace declares no deep agents (none found under deep-agents/*/index.ts) — a workspace bundle needs at least one deep agent.\`
-
-The workspace has no agents, there is no \`deep-agents/<name>/index.ts\` to
-discover. A workspace bundle needs at least one, so add one (for example
-\`stackbone add agent <name>\`, which scaffolds \`deep-agents/<name>/\`) and
-re-publish.
-
-### An agent's build failed
-
-> \`esbuild failed for deep agent "<name>": …\`
-
-One agent's \`index.ts\` failed to bundle. The message carries the underlying
-esbuild error (a syntax error, a missing import); fix it and re-publish.
-
-### Incompatible \`@stackbone/sdk\`
+## Incompatible \`@stackbone/sdk\`
 
 > \`@stackbone/sdk@<version> is not compatible with this CLI, which supports >=0.1.0 <0.2.0 (built against 0.1.0).\`
 
-Each CLI build supports one minor line of \`@stackbone/sdk\`. \`stackbone publish\`
-blocks when the version installed in your project falls outside that line,
-because an incompatible SDK is what would ship to cloud. Pin the SDK to a
+Each CLI build supports one minor line of \`@stackbone/sdk\`. \`stackbone dev\`
+checks the version installed in your project on boot and warns when it falls
+outside that line, then keeps the local loop running. Pin the SDK to a
 supported version and reinstall:
 
 \`\`\`sh
 pnpm add -E @stackbone/sdk@<version>
 \`\`\`
 
-The same check runs at the start of \`stackbone dev\`, but there it only warns and
-keeps the local loop running. If the SDK is not installed at all, the message
-tells you to run \`pnpm install\` first instead. A scaffolded project pins the SDK
-exactly (no caret), so a stray \`pnpm update\` cannot silently move it off the
-supported line.
+If the SDK is not installed at all, the message tells you to run \`pnpm install\`
+first instead. A scaffolded project pins the SDK exactly (no caret), so a stray
+\`pnpm update\` cannot silently move it off the supported line.
 
 ## Checking a deployed workspace's health
 
@@ -41173,7 +41710,7 @@ engine behind [Vercel Workflows](https://vercel.com/docs/workflows)), so a
 run survives crashes and redeploys and can pause for months.
 
 You don't register workflows by hand. The workspace is **discovered by
-convention**: \`stackbone dev\` and \`stackbone publish\` scan your project and
+convention**: \`stackbone dev\` and the deployed runtime scan your project and
 pick up every agent folder under \`deep-agents/\` that has an \`index.ts\`, and
 every workflow file at \`workflows/<name>.workflow.ts\`. A workflow's name is
 the file basename without the \`.workflow.ts\` suffix, and its exported
@@ -41468,7 +42005,7 @@ suppressed.** Production agents should leave this flag unset.
 - **[Logging & observability](/docs/sdk/observability)** — the run timeline is
   captured for you.
 - **[CLI reference](/docs/cli/commands)** — \`stackbone dev\`,
-  \`stackbone publish\`, \`stackbone workflows\`, \`stackbone runs\`,
+  \`stackbone link\`, \`stackbone workflows\`, \`stackbone runs\`,
   \`stackbone hitl\`.
 `,
 	"sdk/ai": `# stackbone.ai
@@ -42929,9 +43466,10 @@ subpath imports it directly.
 - **Records the approval** so the run shows up in the inbox. The row is
   tied to its run, so you can find it from the run in the dashboard or
   with \`stackbone hitl list\`.
-- **Pauses the run** on a hook keyed by your \`token\`. The pause is
-  durable — the hook's state lives in Redis, so the run survives a
-  crash, a cold start, or a redeploy and resumes deterministically.
+- **Pauses the run** on a hook with its own resume key. The SDK assigns
+  that key per run, so you don't invent one. The pause is durable: the
+  hook's state lives in Redis, so the run survives a crash, a cold
+  start, or a redeploy and resumes deterministically.
 - **Races the decision against a timeout.** If a human decides first,
   the run resumes with that decision. If the \`timeout\` elapses first,
   the \`fallback\` (\`'approve'\` or \`'reject'\`) is applied instead.
@@ -42955,7 +43493,6 @@ import { requestApproval } from '@stackbone/sdk/workflow';
 export const inputSchema = z.object({
   orderId: z.string(),
   amount: z.number().positive(),
-  approvalToken: z.string(),
 });
 
 export const outputSchema = z.object({
@@ -42968,7 +43505,7 @@ export async function refundWorkflow(input: z.infer<typeof inputSchema>) {
   'use workflow';
 
   const decision = await requestApproval({
-    token: input.approvalToken,
+    // No \`token\`: the SDK assigns a unique resume key for this run.
     topic: 'refund',
     payload: { orderId: input.orderId, amount: input.amount },
     title: 'Approve this refund?',
@@ -43002,12 +43539,12 @@ crash, a redeploy — is handled by the durable pause.
 
 | Field      | Type                    | Notes                                                                                     |
 | ---------- | ----------------------- | ----------------------------------------------------------------------------------------- |
-| \`token\`    | \`string\`                | **Required.** The resume key — stable and unguessable, unique per approval within a run.  |
 | \`topic\`    | \`string\`                | **Required.** Approval category, shown in the inbox (e.g. \`'refund'\`, \`'deploy'\`).        |
 | \`payload\`  | \`T\`                     | **Required.** What the reviewer looks at when deciding.                                   |
 | \`title\`    | \`string\`                | Optional. Human-readable title surfaced in the inbox and run view.                        |
 | \`timeout\`  | \`string \\| number\`      | Optional. ISO 8601 duration (\`'24h'\`, \`'15m'\`) or milliseconds. Races the human decision. |
 | \`fallback\` | \`'approve' \\| 'reject'\` | Optional. Applied when the timeout wins the race. Defaults to \`'reject'\`.                 |
+| \`token\`    | \`string\`                | Optional. Your own resume key. Omit it: the SDK assigns a unique one per run.             |
 
 It returns an \`ApprovalDecision\`:
 
@@ -43023,6 +43560,21 @@ Branch on \`status\`. Use \`timedOut\` if you want to treat a fallback
 differently from a real human decision (for example, to alert that
 nobody responded in time).
 
+### Should you pass your own \`token\`?
+
+Almost never. Leave \`token\` out and the SDK generates a resume key that
+is unique to that run, so a retry, or a second run started while the
+first approval is still pending, can't collide with a key another live
+run already holds. Two gates in the same run each get their own key too.
+
+Pass an explicit \`token\` only when something outside the run has to
+rebuild the same key to resume it, and then make sure it is unique per
+approval per run. Reusing a key another active run still holds is the
+one case that can't resume: the approval falls back instead of waiting
+for a person. If what you actually want is for an inbound reply to wake
+this exact run, use a raw hook rather than \`requestApproval()\`. See
+[Wait for a reply](#wait-for-a-reply).
+
 ## Deciding
 
 When the workflow pauses, the approval lands in the inbox. A reviewer
@@ -43063,10 +43615,10 @@ Common patterns:
 
 \`\`\`ts
 // High-risk: auto-reject if no one looks within an hour.
-await requestApproval({ token, topic, payload, timeout: '1h', fallback: 'reject' });
+await requestApproval({ topic, payload, timeout: '1h', fallback: 'reject' });
 
 // Low-risk: auto-approve after a grace period if no one objects.
-await requestApproval({ token, topic, payload, timeout: '15m', fallback: 'approve' });
+await requestApproval({ topic, payload, timeout: '15m', fallback: 'approve' });
 \`\`\`
 
 ## Escape hatch: custom hooks
@@ -43092,10 +43644,11 @@ docs for hook and replay semantics.
 
 A common shape is not approve/reject at all. You send someone a message,
 and you want the **same run** to wake up when they reply. \`requestApproval()\`
-does not fit here, because it models a decision and returns
-\`{ status, payload, timedOut }\`. A reply is free-form content, so drop down to
-a raw hook. A resumed hook returns whatever payload woke it, which is the
-reply itself.
+does not fit here, for two reasons: it models a decision and returns
+\`{ status, payload, timedOut }\`, and its resume key is auto-generated, so no
+incoming event can be matched against it. A reply is free-form content and
+needs a key you choose, so drop down to a raw hook. A resumed hook returns
+whatever payload woke it, which is the reply itself.
 
 Park the hook on a \`token\` you control, and make that token the
 conversation's own id: the email thread id the provider hands back when you
@@ -43731,8 +44284,8 @@ the resume path.
 ## The workspace registry
 
 The CLI and runtime discover your workspace **by convention**, from the
-files on disk, with no registry to hand-maintain. \`stackbone dev\` and
-\`stackbone publish\` both read the same convention:
+files on disk, with no registry to hand-maintain. \`stackbone dev\` and the
+deployed runtime both read the same convention:
 
 - **Agents**: every folder under \`deep-agents/\` with an \`index.ts\` entry
   file. The folder name is both the agent's identity and the \`model\` a
@@ -43768,9 +44321,9 @@ export default defineWorkspace({
 });
 \`\`\`
 
-When present, this file is what \`stackbone dev\`, \`stackbone publish\`,
-\`stackbone workflows list\`, and the typed autocompletion below read
-instead of scanning the filesystem for workflows.
+When present, this file is what \`stackbone dev\`, \`stackbone workflows list\`,
+and the typed autocompletion below read instead of scanning the filesystem for
+workflows.
 
 ## How the CLI connects to the SDK
 
@@ -44351,8 +44904,8 @@ Like \`stackbone.secrets\` and \`stackbone.config\`, this surface is
 directly, so it is not gated on the contract handshake. The only
 prerequisite is that the prompts schema has been applied. Those tables
 are created when your project's migrations run — which happens
-automatically when you boot your project with \`stackbone dev\` (and again
-when you \`stackbone publish\`). A not-yet-migrated agent surfaces
+automatically when you boot your project with \`stackbone dev\`, and again
+when the deployed runtime starts. A not-yet-migrated agent surfaces
 \`prompts_not_configured\` until then.
 
 ## API
@@ -46098,10 +46651,51 @@ var createInitCommand = (ctx) => defineCommand({
 });
 //#endregion
 //#region src/services/deployments.service.ts
+init_src$11();
 init_src$13();
 var registerDeployment = async (ctx, body) => {
 	return parseResponse$2(deploymentResponseSchema, await ctx.http.post("/api/v1/deployments", body), "POST /api/v1/deployments");
 };
+var verifyDeploymentSecret = async (args) => {
+	const fetchImpl = args.fetchImpl ?? fetch;
+	let challengeUrl;
+	try {
+		challengeUrl = new URL(PROXY_CHALLENGE_PATH, args.url).toString();
+	} catch {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `--url is not a valid URL: ${args.url}`,
+			suggestion: "Pass the full public URL of the deployed agent, e.g. https://agent.example.com"
+		});
+	}
+	const header = buildStackboneSignatureHeader({
+		secrets: [args.secret],
+		payload: proxyRequestPayload({
+			method: "GET",
+			path: PROXY_CHALLENGE_PATH,
+			body: ""
+		})
+	});
+	let response;
+	try {
+		response = await fetchImpl(challengeUrl, {
+			method: "GET",
+			headers: { "stackbone-signature": header }
+		});
+	} catch (cause) {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `Could not reach the deployed container at ${args.url} to verify --secret`,
+			suggestion: "Check the --url is the public address of the running container and that it is reachable.",
+			cause
+		});
+	}
+	if (!response.ok) throw new StackboneCliError({
+		code: "generic",
+		message: `The --secret does not match the HMAC_SECRET configured on the deployed container at ${args.url}`,
+		suggestion: "Set the same value the container was started with (its HMAC_SECRET env), then re-run `stackbone link`."
+	});
+};
 //#endregion
 //#region src/commands/link/link.command.ts
 var requireLinkField = (value, flag, description) => {
@@ -46168,6 +46762,11 @@ var runLink = async (ctx, args) => {
 	const activeOrg = await getActiveOrganization(ctx);
 	const agent = await getAgentByOwnerAndSlug(ctx, activeOrg.slug, chosenSlug);
 	if (!ctx.flags.json) log.step(`Linking ${targetDir} to ${agent.slug}`);
+	if (!ctx.flags.json) log.step("Verifying the --secret against the deployed container");
+	await verifyDeploymentSecret({
+		url,
+		secret
+	});
 	const [localDev, deployment] = await Promise.all([upsertLocalDevInstallation(ctx, {
 		creatorOrganizationSlug: activeOrg.slug,
 		agentTemplateSlug: agent.slug