switchroom 0.14.35 → 0.14.37

package/dist/agent-scheduler/index.js

@@ -11386,7 +11386,8 @@ var VaultConfigSchema = exports_external.object({
     autoUnlock: exports_external.boolean().default(false).describe("Auto-unlock the vault at broker start using a machine-bound " + "encrypted blob. Off by default. When enabled, the broker reads " + "the configured blob path, derives the AES key from /etc/machine-id, " + "decrypts the passphrase, and unlocks the vault — no sudo, no " + "systemd-creds, no TPM. Run `switchroom vault broker " + "enable-auto-unlock` once to write the blob."),
     autoUnlockCredentialPath: exports_external.string().default("~/.switchroom/vault-auto-unlock").describe("Path to the machine-bound auto-unlock blob (see " + "src/vault/auto-unlock.ts for the format). Default lives under " + "~/.switchroom so it can be bind-mounted into the vault-broker " + "container by docker compose. Tilde-expansion happens " + "at read time."),
     approvalAuth: exports_external.enum(["passphrase", "telegram-id"]).default("passphrase").describe("Posture for tap-to-Approve on vault grant cards. `passphrase` " + "(default) prompts the operator to type the vault passphrase on " + "every Approve — two-factor (Telegram ID + passphrase). " + "`telegram-id` mints immediately on Approve with no passphrase " + "prompt — single-factor (Telegram ID only); REQUIRES " + "`autoUnlock: true` so the broker already holds the passphrase. " + "Trades a factor of security for smoother UX; opt-in only."),
-    postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config.")
+    postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config."),
+    adminOnlyKeys: exports_external.array(exports_external.string().min(1)).default([]).describe("Vault keys held to a higher approval bar: only the admin operator " + "(`access.allowFrom[0]`) may approve a grant for them, and they can " + "NEVER be minted via posture attestation — granting one requires the " + "operator passphrase (so an agent, even one on `postureMintAgents`, " + "cannot self-grant it). Entries are exact key names or `*` globs, " + "e.g. `stripe/*`, `*/oauth-token`, `microsoft/ken-tokens` (`*` matches " + "any run of characters incl. `/`; case-sensitive). Default `[]` — no " + "key is admin-only. Posture may RETAIN an admin-only key across a " + "union re-mint but never ADD one. Takes effect on broker + gateway " + "restart (broker has no ACL hot-reload).")
   }).default({}).superRefine((broker, ctx) => {
     if (broker.approvalAuth === "telegram-id" && broker.autoUnlock !== true) {
       ctx.addIssue({

package/dist/auth-broker/index.js

@@ -11386,7 +11386,8 @@ var VaultConfigSchema = exports_external.object({
     autoUnlock: exports_external.boolean().default(false).describe("Auto-unlock the vault at broker start using a machine-bound " + "encrypted blob. Off by default. When enabled, the broker reads " + "the configured blob path, derives the AES key from /etc/machine-id, " + "decrypts the passphrase, and unlocks the vault — no sudo, no " + "systemd-creds, no TPM. Run `switchroom vault broker " + "enable-auto-unlock` once to write the blob."),
     autoUnlockCredentialPath: exports_external.string().default("~/.switchroom/vault-auto-unlock").describe("Path to the machine-bound auto-unlock blob (see " + "src/vault/auto-unlock.ts for the format). Default lives under " + "~/.switchroom so it can be bind-mounted into the vault-broker " + "container by docker compose. Tilde-expansion happens " + "at read time."),
     approvalAuth: exports_external.enum(["passphrase", "telegram-id"]).default("passphrase").describe("Posture for tap-to-Approve on vault grant cards. `passphrase` " + "(default) prompts the operator to type the vault passphrase on " + "every Approve — two-factor (Telegram ID + passphrase). " + "`telegram-id` mints immediately on Approve with no passphrase " + "prompt — single-factor (Telegram ID only); REQUIRES " + "`autoUnlock: true` so the broker already holds the passphrase. " + "Trades a factor of security for smoother UX; opt-in only."),
-    postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config.")
+    postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config."),
+    adminOnlyKeys: exports_external.array(exports_external.string().min(1)).default([]).describe("Vault keys held to a higher approval bar: only the admin operator " + "(`access.allowFrom[0]`) may approve a grant for them, and they can " + "NEVER be minted via posture attestation — granting one requires the " + "operator passphrase (so an agent, even one on `postureMintAgents`, " + "cannot self-grant it). Entries are exact key names or `*` globs, " + "e.g. `stripe/*`, `*/oauth-token`, `microsoft/ken-tokens` (`*` matches " + "any run of characters incl. `/`; case-sensitive). Default `[]` — no " + "key is admin-only. Posture may RETAIN an admin-only key across a " + "union re-mint but never ADD one. Takes effect on broker + gateway " + "restart (broker has no ACL hot-reload).")
   }).default({}).superRefine((broker, ctx) => {
     if (broker.approvalAuth === "telegram-id" && broker.autoUnlock !== true) {
       ctx.addIssue({

package/dist/cli/notion-write-pretool.mjs

@@ -12134,7 +12134,8 @@ var VaultConfigSchema = exports_external.object({
     autoUnlock: exports_external.boolean().default(false).describe("Auto-unlock the vault at broker start using a machine-bound " + "encrypted blob. Off by default. When enabled, the broker reads " + "the configured blob path, derives the AES key from /etc/machine-id, " + "decrypts the passphrase, and unlocks the vault \u2014 no sudo, no " + "systemd-creds, no TPM. Run `switchroom vault broker " + "enable-auto-unlock` once to write the blob."),
     autoUnlockCredentialPath: exports_external.string().default("~/.switchroom/vault-auto-unlock").describe("Path to the machine-bound auto-unlock blob (see " + "src/vault/auto-unlock.ts for the format). Default lives under " + "~/.switchroom so it can be bind-mounted into the vault-broker " + "container by docker compose. Tilde-expansion happens " + "at read time."),
     approvalAuth: exports_external.enum(["passphrase", "telegram-id"]).default("passphrase").describe("Posture for tap-to-Approve on vault grant cards. `passphrase` " + "(default) prompts the operator to type the vault passphrase on " + "every Approve \u2014 two-factor (Telegram ID + passphrase). " + "`telegram-id` mints immediately on Approve with no passphrase " + "prompt \u2014 single-factor (Telegram ID only); REQUIRES " + "`autoUnlock: true` so the broker already holds the passphrase. " + "Trades a factor of security for smoother UX; opt-in only."),
-    postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` \u2014 no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored \u2014 passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config.")
+    postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` \u2014 no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored \u2014 passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config."),
+    adminOnlyKeys: exports_external.array(exports_external.string().min(1)).default([]).describe("Vault keys held to a higher approval bar: only the admin operator " + "(`access.allowFrom[0]`) may approve a grant for them, and they can " + "NEVER be minted via posture attestation \u2014 granting one requires the " + "operator passphrase (so an agent, even one on `postureMintAgents`, " + "cannot self-grant it). Entries are exact key names or `*` globs, " + "e.g. `stripe/*`, `*/oauth-token`, `microsoft/ken-tokens` (`*` matches " + "any run of characters incl. `/`; case-sensitive). Default `[]` \u2014 no " + "key is admin-only. Posture may RETAIN an admin-only key across a " + "union re-mint but never ADD one. Takes effect on broker + gateway " + "restart (broker has no ACL hot-reload).")
   }).default({}).superRefine((broker, ctx) => {
     if (broker.approvalAuth === "telegram-id" && broker.autoUnlock !== true) {
       ctx.addIssue({

package/dist/cli/switchroom.js

@@ -13950,7 +13950,8 @@ var init_schema = __esm(() => {
       autoUnlock: exports_external.boolean().default(false).describe("Auto-unlock the vault at broker start using a machine-bound " + "encrypted blob. Off by default. When enabled, the broker reads " + "the configured blob path, derives the AES key from /etc/machine-id, " + "decrypts the passphrase, and unlocks the vault \u2014 no sudo, no " + "systemd-creds, no TPM. Run `switchroom vault broker " + "enable-auto-unlock` once to write the blob."),
       autoUnlockCredentialPath: exports_external.string().default("~/.switchroom/vault-auto-unlock").describe("Path to the machine-bound auto-unlock blob (see " + "src/vault/auto-unlock.ts for the format). Default lives under " + "~/.switchroom so it can be bind-mounted into the vault-broker " + "container by docker compose. Tilde-expansion happens " + "at read time."),
       approvalAuth: exports_external.enum(["passphrase", "telegram-id"]).default("passphrase").describe("Posture for tap-to-Approve on vault grant cards. `passphrase` " + "(default) prompts the operator to type the vault passphrase on " + "every Approve \u2014 two-factor (Telegram ID + passphrase). " + "`telegram-id` mints immediately on Approve with no passphrase " + "prompt \u2014 single-factor (Telegram ID only); REQUIRES " + "`autoUnlock: true` so the broker already holds the passphrase. " + "Trades a factor of security for smoother UX; opt-in only."),
-      postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` \u2014 no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored \u2014 passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config.")
+      postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` \u2014 no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored \u2014 passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config."),
+      adminOnlyKeys: exports_external.array(exports_external.string().min(1)).default([]).describe("Vault keys held to a higher approval bar: only the admin operator " + "(`access.allowFrom[0]`) may approve a grant for them, and they can " + "NEVER be minted via posture attestation \u2014 granting one requires the " + "operator passphrase (so an agent, even one on `postureMintAgents`, " + "cannot self-grant it). Entries are exact key names or `*` globs, " + "e.g. `stripe/*`, `*/oauth-token`, `microsoft/ken-tokens` (`*` matches " + "any run of characters incl. `/`; case-sensitive). Default `[]` \u2014 no " + "key is admin-only. Posture may RETAIN an admin-only key across a " + "union re-mint but never ADD one. Takes effect on broker + gateway " + "restart (broker has no ACL hot-reload).")
     }).default({}).superRefine((broker, ctx) => {
       if (broker.approvalAuth === "telegram-id" && broker.autoUnlock !== true) {
         ctx.addIssue({
@@ -49439,8 +49440,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.35";
-var COMMIT_SHA = "7ac06aea";
+var VERSION = "0.14.37";
+var COMMIT_SHA = "90d0c420";
 
 // src/cli/agent.ts
 init_source();
@@ -61321,6 +61322,31 @@ function listGrants(db, agent_slug) {
   return rows.map(rowToGrant);
 }
 
+// src/vault/admin-only-keys.ts
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+function matchesAdminOnlyKey(key, patterns) {
+  for (const p of patterns) {
+    if (p === key)
+      return true;
+    if (p.includes("*") && globToRegExp(p).test(key))
+      return true;
+  }
+  return false;
+}
+function adminOnlyKeysBeingAdded(requestedKeys, existingKeys, patterns) {
+  const existing = new Set(existingKeys);
+  const blocked = [];
+  for (const k of requestedKeys) {
+    if (matchesAdminOnlyKey(k, patterns) && !existing.has(k) && !blocked.includes(k)) {
+      blocked.push(k);
+    }
+  }
+  return blocked;
+}
+
 // src/vault/grants-db.ts
 import * as os3 from "node:os";
 import * as path2 from "node:path";
@@ -62699,6 +62725,30 @@ class VaultBroker {
           socket.write(encodeResponse(errorResponse("DENIED", `posture-attested list refused: request.agent=${reqAgent} but calling peer is ${agentName}`)));
           return;
         }
+        if (req.op === "mint_grant") {
+          const adminOnly = this.config?.vault?.broker?.adminOnlyKeys ?? [];
+          if (adminOnly.length > 0) {
+            const requested = [
+              ...req.keys ?? [],
+              ...req.write_keys ?? []
+            ];
+            const nowSec = Math.floor(Date.now() / 1000);
+            const existingKeys = listGrants(this.grantsDb, agentName).filter((g) => g.expires_at === null || g.expires_at > nowSec).flatMap((g) => [...g.key_allow ?? [], ...g.write_allow ?? []]);
+            const blocked = adminOnlyKeysBeingAdded(requested, existingKeys, adminOnly);
+            if (blocked.length > 0) {
+              writeAudit({
+                ts: new Date().toISOString(),
+                op: req.op,
+                caller: auditCaller,
+                pid: auditPid,
+                cgroup: auditCgroup,
+                result: "denied:posture-mint-admin-only-key"
+              });
+              socket.write(encodeResponse(errorResponse("DENIED", `admin-only credential(s) ${blocked.join(", ")} cannot be minted via posture ` + `attestation \u2014 they require the operator passphrase (vault.broker.adminOnlyKeys)`)));
+              return;
+            }
+          }
+        }
         if (this.passphrase === null) {
           writeAudit({
             ts: new Date().toISOString(),

package/dist/host-control/main.js

@@ -14121,7 +14121,8 @@ var VaultConfigSchema = exports_external.object({
     autoUnlock: exports_external.boolean().default(false).describe("Auto-unlock the vault at broker start using a machine-bound " + "encrypted blob. Off by default. When enabled, the broker reads " + "the configured blob path, derives the AES key from /etc/machine-id, " + "decrypts the passphrase, and unlocks the vault — no sudo, no " + "systemd-creds, no TPM. Run `switchroom vault broker " + "enable-auto-unlock` once to write the blob."),
     autoUnlockCredentialPath: exports_external.string().default("~/.switchroom/vault-auto-unlock").describe("Path to the machine-bound auto-unlock blob (see " + "src/vault/auto-unlock.ts for the format). Default lives under " + "~/.switchroom so it can be bind-mounted into the vault-broker " + "container by docker compose. Tilde-expansion happens " + "at read time."),
     approvalAuth: exports_external.enum(["passphrase", "telegram-id"]).default("passphrase").describe("Posture for tap-to-Approve on vault grant cards. `passphrase` " + "(default) prompts the operator to type the vault passphrase on " + "every Approve — two-factor (Telegram ID + passphrase). " + "`telegram-id` mints immediately on Approve with no passphrase " + "prompt — single-factor (Telegram ID only); REQUIRES " + "`autoUnlock: true` so the broker already holds the passphrase. " + "Trades a factor of security for smoother UX; opt-in only."),
-    postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config.")
+    postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config."),
+    adminOnlyKeys: exports_external.array(exports_external.string().min(1)).default([]).describe("Vault keys held to a higher approval bar: only the admin operator " + "(`access.allowFrom[0]`) may approve a grant for them, and they can " + "NEVER be minted via posture attestation — granting one requires the " + "operator passphrase (so an agent, even one on `postureMintAgents`, " + "cannot self-grant it). Entries are exact key names or `*` globs, " + "e.g. `stripe/*`, `*/oauth-token`, `microsoft/ken-tokens` (`*` matches " + "any run of characters incl. `/`; case-sensitive). Default `[]` — no " + "key is admin-only. Posture may RETAIN an admin-only key across a " + "union re-mint but never ADD one. Takes effect on broker + gateway " + "restart (broker has no ACL hot-reload).")
   }).default({}).superRefine((broker, ctx) => {
     if (broker.approvalAuth === "telegram-id" && broker.autoUnlock !== true) {
       ctx.addIssue({

package/dist/vault/approvals/kernel-server.js

@@ -11707,7 +11707,8 @@ var init_schema = __esm(() => {
       autoUnlock: exports_external.boolean().default(false).describe("Auto-unlock the vault at broker start using a machine-bound " + "encrypted blob. Off by default. When enabled, the broker reads " + "the configured blob path, derives the AES key from /etc/machine-id, " + "decrypts the passphrase, and unlocks the vault — no sudo, no " + "systemd-creds, no TPM. Run `switchroom vault broker " + "enable-auto-unlock` once to write the blob."),
       autoUnlockCredentialPath: exports_external.string().default("~/.switchroom/vault-auto-unlock").describe("Path to the machine-bound auto-unlock blob (see " + "src/vault/auto-unlock.ts for the format). Default lives under " + "~/.switchroom so it can be bind-mounted into the vault-broker " + "container by docker compose. Tilde-expansion happens " + "at read time."),
       approvalAuth: exports_external.enum(["passphrase", "telegram-id"]).default("passphrase").describe("Posture for tap-to-Approve on vault grant cards. `passphrase` " + "(default) prompts the operator to type the vault passphrase on " + "every Approve — two-factor (Telegram ID + passphrase). " + "`telegram-id` mints immediately on Approve with no passphrase " + "prompt — single-factor (Telegram ID only); REQUIRES " + "`autoUnlock: true` so the broker already holds the passphrase. " + "Trades a factor of security for smoother UX; opt-in only."),
-      postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config.")
+      postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config."),
+      adminOnlyKeys: exports_external.array(exports_external.string().min(1)).default([]).describe("Vault keys held to a higher approval bar: only the admin operator " + "(`access.allowFrom[0]`) may approve a grant for them, and they can " + "NEVER be minted via posture attestation — granting one requires the " + "operator passphrase (so an agent, even one on `postureMintAgents`, " + "cannot self-grant it). Entries are exact key names or `*` globs, " + "e.g. `stripe/*`, `*/oauth-token`, `microsoft/ken-tokens` (`*` matches " + "any run of characters incl. `/`; case-sensitive). Default `[]` — no " + "key is admin-only. Posture may RETAIN an admin-only key across a " + "union re-mint but never ADD one. Takes effect on broker + gateway " + "restart (broker has no ACL hot-reload).")
     }).default({}).superRefine((broker, ctx) => {
       if (broker.approvalAuth === "telegram-id" && broker.autoUnlock !== true) {
         ctx.addIssue({

package/dist/vault/broker/server.js

@@ -11707,7 +11707,8 @@ var init_schema = __esm(() => {
       autoUnlock: exports_external.boolean().default(false).describe("Auto-unlock the vault at broker start using a machine-bound " + "encrypted blob. Off by default. When enabled, the broker reads " + "the configured blob path, derives the AES key from /etc/machine-id, " + "decrypts the passphrase, and unlocks the vault — no sudo, no " + "systemd-creds, no TPM. Run `switchroom vault broker " + "enable-auto-unlock` once to write the blob."),
       autoUnlockCredentialPath: exports_external.string().default("~/.switchroom/vault-auto-unlock").describe("Path to the machine-bound auto-unlock blob (see " + "src/vault/auto-unlock.ts for the format). Default lives under " + "~/.switchroom so it can be bind-mounted into the vault-broker " + "container by docker compose. Tilde-expansion happens " + "at read time."),
       approvalAuth: exports_external.enum(["passphrase", "telegram-id"]).default("passphrase").describe("Posture for tap-to-Approve on vault grant cards. `passphrase` " + "(default) prompts the operator to type the vault passphrase on " + "every Approve — two-factor (Telegram ID + passphrase). " + "`telegram-id` mints immediately on Approve with no passphrase " + "prompt — single-factor (Telegram ID only); REQUIRES " + "`autoUnlock: true` so the broker already holds the passphrase. " + "Trades a factor of security for smoother UX; opt-in only."),
-      postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config.")
+      postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` — no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored — passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config."),
+      adminOnlyKeys: exports_external.array(exports_external.string().min(1)).default([]).describe("Vault keys held to a higher approval bar: only the admin operator " + "(`access.allowFrom[0]`) may approve a grant for them, and they can " + "NEVER be minted via posture attestation — granting one requires the " + "operator passphrase (so an agent, even one on `postureMintAgents`, " + "cannot self-grant it). Entries are exact key names or `*` globs, " + "e.g. `stripe/*`, `*/oauth-token`, `microsoft/ken-tokens` (`*` matches " + "any run of characters incl. `/`; case-sensitive). Default `[]` — no " + "key is admin-only. Posture may RETAIN an admin-only key across a " + "union re-mint but never ADD one. Takes effect on broker + gateway " + "restart (broker has no ACL hot-reload).")
     }).default({}).superRefine((broker, ctx) => {
       if (broker.approvalAuth === "telegram-id" && broker.autoUnlock !== true) {
         ctx.addIssue({
@@ -15712,6 +15713,31 @@ function listGrants(db, agent_slug) {
   return rows.map(rowToGrant);
 }
 
+// src/vault/admin-only-keys.ts
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+function matchesAdminOnlyKey(key, patterns) {
+  for (const p of patterns) {
+    if (p === key)
+      return true;
+    if (p.includes("*") && globToRegExp(p).test(key))
+      return true;
+  }
+  return false;
+}
+function adminOnlyKeysBeingAdded(requestedKeys, existingKeys, patterns) {
+  const existing = new Set(existingKeys);
+  const blocked = [];
+  for (const k of requestedKeys) {
+    if (matchesAdminOnlyKey(k, patterns) && !existing.has(k) && !blocked.includes(k)) {
+      blocked.push(k);
+    }
+  }
+  return blocked;
+}
+
 // src/vault/grants-db.ts
 import * as os2 from "node:os";
 import * as path2 from "node:path";
@@ -17090,6 +17116,30 @@ class VaultBroker {
           socket.write(encodeResponse(errorResponse("DENIED", `posture-attested list refused: request.agent=${reqAgent} but calling peer is ${agentName}`)));
           return;
         }
+        if (req.op === "mint_grant") {
+          const adminOnly = this.config?.vault?.broker?.adminOnlyKeys ?? [];
+          if (adminOnly.length > 0) {
+            const requested = [
+              ...req.keys ?? [],
+              ...req.write_keys ?? []
+            ];
+            const nowSec = Math.floor(Date.now() / 1000);
+            const existingKeys = listGrants(this.grantsDb, agentName).filter((g) => g.expires_at === null || g.expires_at > nowSec).flatMap((g) => [...g.key_allow ?? [], ...g.write_allow ?? []]);
+            const blocked = adminOnlyKeysBeingAdded(requested, existingKeys, adminOnly);
+            if (blocked.length > 0) {
+              writeAudit({
+                ts: new Date().toISOString(),
+                op: req.op,
+                caller: auditCaller,
+                pid: auditPid,
+                cgroup: auditCgroup,
+                result: "denied:posture-mint-admin-only-key"
+              });
+              socket.write(encodeResponse(errorResponse("DENIED", `admin-only credential(s) ${blocked.join(", ")} cannot be minted via posture ` + `attestation — they require the operator passphrase (vault.broker.adminOnlyKeys)`)));
+              return;
+            }
+          }
+        }
         if (this.passphrase === null) {
           writeAudit({
             ts: new Date().toISOString(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.14.35",
+  "version": "0.14.37",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "pretest": "npm run build",
     "test": "vitest run && bun test telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts",
     "test:vitest": "vitest run",
-    "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts src/vault/grants.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts",
+    "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts src/vault/grants.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts",
     "test:watch": "vitest",
     "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs && node scripts/check-no-broadcast-delivery.mjs",
     "lint:tsc": "tsc --noEmit",

package/telegram-plugin/dist/gateway/gateway.js

@@ -24092,7 +24092,8 @@ var init_schema = __esm(() => {
       autoUnlock: exports_external.boolean().default(false).describe("Auto-unlock the vault at broker start using a machine-bound " + "encrypted blob. Off by default. When enabled, the broker reads " + "the configured blob path, derives the AES key from /etc/machine-id, " + "decrypts the passphrase, and unlocks the vault \u2014 no sudo, no " + "systemd-creds, no TPM. Run `switchroom vault broker " + "enable-auto-unlock` once to write the blob."),
       autoUnlockCredentialPath: exports_external.string().default("~/.switchroom/vault-auto-unlock").describe("Path to the machine-bound auto-unlock blob (see " + "src/vault/auto-unlock.ts for the format). Default lives under " + "~/.switchroom so it can be bind-mounted into the vault-broker " + "container by docker compose. Tilde-expansion happens " + "at read time."),
       approvalAuth: exports_external.enum(["passphrase", "telegram-id"]).default("passphrase").describe("Posture for tap-to-Approve on vault grant cards. `passphrase` " + "(default) prompts the operator to type the vault passphrase on " + "every Approve \u2014 two-factor (Telegram ID + passphrase). " + "`telegram-id` mints immediately on Approve with no passphrase " + "prompt \u2014 single-factor (Telegram ID only); REQUIRES " + "`autoUnlock: true` so the broker already holds the passphrase. " + "Trades a factor of security for smoother UX; opt-in only."),
-      postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` \u2014 no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored \u2014 passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config.")
+      postureMintAgents: exports_external.array(exports_external.string().min(1)).default([]).describe("Per-agent opt-in for posture-attested broker calls (`mint_grant` / " + "`list_grants` / `put` with `attest_via_posture: true`). Only agents " + "whose names are in this list can use the silent-mint path under " + "`approvalAuth: telegram-id`. Default `[]` \u2014 no agent can self-mint " + "until the operator explicitly opts it in. The request's `agent` " + "field must also equal the calling peer's resolved agent name " + "(broker rejects cross-agent posture mints). When `approvalAuth` is " + "`passphrase` this list is ignored \u2014 passphrase attestation still " + "works as before. Each entry is an agent slug exactly as it appears " + "under `agents:` in this config."),
+      adminOnlyKeys: exports_external.array(exports_external.string().min(1)).default([]).describe("Vault keys held to a higher approval bar: only the admin operator " + "(`access.allowFrom[0]`) may approve a grant for them, and they can " + "NEVER be minted via posture attestation \u2014 granting one requires the " + "operator passphrase (so an agent, even one on `postureMintAgents`, " + "cannot self-grant it). Entries are exact key names or `*` globs, " + "e.g. `stripe/*`, `*/oauth-token`, `microsoft/ken-tokens` (`*` matches " + "any run of characters incl. `/`; case-sensitive). Default `[]` \u2014 no " + "key is admin-only. Posture may RETAIN an admin-only key across a " + "union re-mint but never ADD one. Takes effect on broker + gateway " + "restart (broker has no ACL hot-reload).")
     }).default({}).superRefine((broker, ctx) => {
       if (broker.approvalAuth === "telegram-id" && broker.autoUnlock !== true) {
         ctx.addIssue({
@@ -49570,6 +49571,20 @@ function backfillJsonlAgentId(db2, jsonlPath, agentId, log) {
   }
   db2.prepare("UPDATE subagents SET jsonl_agent_id = ? WHERE id = ?").run(agentId, candidate.id);
   log?.(`subagent-watcher: backfill linked ${agentId} \u2192 ${candidate.id}`);
+  try {
+    const linkedRow = db2.prepare("SELECT started_at, parent_turn_key FROM subagents WHERE id = ?").get(candidate.id);
+    if (linkedRow != null && linkedRow.parent_turn_key == null) {
+      const turn = db2.prepare(`SELECT turn_key FROM turns
+           WHERE started_at <= ? AND (ended_at IS NULL OR ended_at >= ?)
+           ORDER BY started_at DESC LIMIT 1`).get(linkedRow.started_at, linkedRow.started_at);
+      if (turn?.turn_key != null) {
+        db2.prepare("UPDATE subagents SET parent_turn_key = ? WHERE id = ?").run(turn.turn_key, candidate.id);
+        log?.(`subagent-watcher: backfill parent_turn_key ${candidate.id} \u2192 ${turn.turn_key}`);
+      }
+    }
+  } catch (err) {
+    log?.(`subagent-watcher: parent_turn_key backfill skipped for ${candidate.id} \u2014 ${err.message}`);
+  }
 }
 function readSubTail(entry, tail, now, onDescriptionUpdate, fs2, log, db2, parentStateDir, onUnstall, onFileVanished, onProgress) {
   try {
@@ -51781,10 +51796,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.35";
-var COMMIT_SHA = "7ac06aea";
-var COMMIT_DATE = "2026-06-01T21:48:46Z";
-var LATEST_PR = 2072;
+var VERSION = "0.14.37";
+var COMMIT_SHA = "90d0c420";
+var COMMIT_DATE = "2026-06-02T02:10:03Z";
+var LATEST_PR = 2078;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -52083,6 +52098,21 @@ function resolveVaultApprovalPosture(broker) {
   return { mode: "passphrase" };
 }
 
+// ../src/vault/admin-only-keys.ts
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+function matchesAdminOnlyKey(key, patterns) {
+  for (const p of patterns) {
+    if (p === key)
+      return true;
+    if (p.includes("*") && globToRegExp(p).test(key))
+      return true;
+  }
+  return false;
+}
+
 // registry/turns-schema.ts
 import { chmodSync as chmodSync4, mkdirSync as mkdirSync22 } from "fs";
 import { join as join33 } from "path";
@@ -53495,6 +53525,7 @@ function rememberAgentButtonMeta(chatId, messageId, meta) {
 var vaultPassphraseCache = new Map;
 var VAULT_PASSPHRASE_TTL_MS = 1800000;
 var VAULT_APPROVAL_AUTH_MODE = "passphrase";
+var ADMIN_ONLY_KEYS = [];
 function initVaultApprovalPosture() {
   let cfg;
   try {
@@ -53508,6 +53539,11 @@ function initVaultApprovalPosture() {
   VAULT_APPROVAL_AUTH_MODE = resolved.mode;
   if (resolved.mode === "telegram-id") {
     process.stderr.write(`telegram gateway: vault approval posture = telegram-id ` + `(single-factor \u2014 broker mediates attestation via attest_via_posture)
+`);
+  }
+  ADMIN_ONLY_KEYS = cfg.vault?.broker?.adminOnlyKeys ?? [];
+  if (ADMIN_ONLY_KEYS.length > 0) {
+    process.stderr.write(`telegram gateway: ${ADMIN_ONLY_KEYS.length} admin-only vault key pattern(s) ` + `\u2014 grants approved by allowFrom[0] + operator passphrase only
 `);
   }
 }
@@ -59724,7 +59760,14 @@ async function handleVaultRequestAccessCallback(ctx, data) {
     return;
   }
   if (action === "approve") {
-    if (VAULT_APPROVAL_AUTH_MODE === "telegram-id") {
+    const isAdminOnly = matchesAdminOnlyKey(pending2.key, ADMIN_ONLY_KEYS);
+    if (isAdminOnly && senderId !== access.allowFrom[0]) {
+      await ctx.answerCallbackQuery({
+        text: "\uD83D\uDD12 Admin-only credential \u2014 only the owner can approve this."
+      }).catch(() => {});
+      return;
+    }
+    if (!isAdminOnly && VAULT_APPROVAL_AUTH_MODE === "telegram-id") {
       const username = ctx.from?.username ?? ctx.from?.first_name ?? `id=${senderId}`;
       if (pending2.card_message_id != null) {
         await ctx.api.editMessageText(pending2.chat_id, pending2.card_message_id, `\u2705 Approved by @${escapeHtmlForTg(username)} \u2014 minting\u2026`, { parse_mode: "HTML", reply_markup: { inline_keyboard: [] } }).catch(() => {});
@@ -59754,7 +59797,9 @@ async function handleVaultRequestAccessCallback(ctx, data) {
       });
       const joiningBatch = items.length > 1;
       await ctx.answerCallbackQuery({ text: joiningBatch ? `\uD83D\uDD10 Queued \u2014 one passphrase covers ${items.length} cards` : "\uD83D\uDD10 Send your passphrase\u2026" }).catch(() => {});
-      await ctx.api.editMessageText(pending2.chat_id, pending2.card_message_id, joiningBatch ? `\uD83D\uDD10 <b>Queued behind an earlier card.</b> Type your passphrase as your next message \u2014 it covers <b>${items.length}</b> pending approvals in this chat (one entry mints all grants, no re-type per card).` : `\uD83D\uDD10 <b>Vault is locked.</b> Reply with your passphrase as your next message \u2014 we'll unlock, mint the grant for <b>${escapeHtmlForTg(pending2.agent)}</b>, and delete the passphrase message in one step.
+      await ctx.api.editMessageText(pending2.chat_id, pending2.card_message_id, joiningBatch ? `\uD83D\uDD10 <b>Queued behind an earlier card.</b> Type your passphrase as your next message \u2014 it covers <b>${items.length}</b> pending approvals in this chat (one entry mints all grants, no re-type per card).` : isAdminOnly ? `\uD83D\uDD12 <b>Admin-only credential.</b> <code>${escapeHtmlForTg(pending2.key)}</code> requires your vault passphrase to grant \u2014 reply with it as your next message and we'll mint the grant for <b>${escapeHtmlForTg(pending2.agent)}</b>, then delete the passphrase message.
+
+<i>The passphrase is what proves it's you: an agent can never mint this key on its own.</i>` : `\uD83D\uDD10 <b>Vault is locked.</b> Reply with your passphrase as your next message \u2014 we'll unlock, mint the grant for <b>${escapeHtmlForTg(pending2.agent)}</b>, and delete the passphrase message in one step.
 
 <i>Mint authority stays operator-only: the broker only accepts the grant when the passphrase matches.</i>`, { parse_mode: "HTML", reply_markup: { inline_keyboard: [] } }).catch(() => {});
       return;

package/telegram-plugin/gateway/gateway.ts

@@ -420,6 +420,7 @@ import {
   approvalRecord,
 } from '../../src/vault/approvals/client.js'
 import { resolveVaultApprovalPosture } from '../vault-approval-posture.js'
+import { matchesAdminOnlyKey } from '../../src/vault/admin-only-keys.js'
 import {
   openTurnsDb,
   markOrphanedWithTimeoutClassification,
@@ -2690,6 +2691,15 @@ const VAULT_PASSPHRASE_TTL_MS = 30 * 60 * 1000
  */
 let VAULT_APPROVAL_AUTH_MODE: 'passphrase' | 'telegram-id' = 'passphrase'
 
+/**
+ * Admin-only vault keys (`vault.broker.adminOnlyKeys`). A grant for one
+ * of these may be approved ONLY by the admin operator
+ * (`access.allowFrom[0]`) and is always minted via the operator
+ * passphrase — never posture, even under telegram-id mode (the broker
+ * enforces the same rule). Cached at boot alongside the posture mode.
+ */
+let ADMIN_ONLY_KEYS: string[] = []
+
 export function initVaultApprovalPosture(): void {
   let cfg: ReturnType<typeof loadSwitchroomConfig>
   try {
@@ -2722,6 +2732,13 @@ export function initVaultApprovalPosture(): void {
         `(single-factor — broker mediates attestation via attest_via_posture)\n`,
     )
   }
+  ADMIN_ONLY_KEYS = cfg.vault?.broker?.adminOnlyKeys ?? []
+  if (ADMIN_ONLY_KEYS.length > 0) {
+    process.stderr.write(
+      `telegram gateway: ${ADMIN_ONLY_KEYS.length} admin-only vault key pattern(s) ` +
+        `— grants approved by allowFrom[0] + operator passphrase only\n`,
+    )
+  }
 }
 /**
  * Gateway-side guard on vault-key shape — UX gate, not a security
@@ -13851,11 +13868,31 @@ async function handleVaultRequestAccessCallback(ctx: Context, data: string): Pro
   }
 
   if (action === 'approve') {
+    // Admin-only credentials (`vault.broker.adminOnlyKeys`) are held to a
+    // higher bar: ONLY the admin operator (allowFrom[0]) may approve, and
+    // the grant must be minted with the operator passphrase — never
+    // posture, even under telegram-id mode (the broker enforces the same
+    // rule, so a posture mint would just be rejected). So for an
+    // admin-only key we (a) reject taps from any non-admin allowFrom
+    // member, and (b) skip the telegram-id posture branch below, falling
+    // through to the passphrase-prompt path. The card + buttons stay
+    // intact on a non-admin tap so the admin can still approve.
+    const isAdminOnly = matchesAdminOnlyKey(pending.key, ADMIN_ONLY_KEYS)
+    if (isAdminOnly && senderId !== access.allowFrom[0]) {
+      await ctx
+        .answerCallbackQuery({
+          text: '🔒 Admin-only credential — only the owner can approve this.',
+        })
+        .catch(() => {})
+      return
+    }
+
     // Posture: telegram-id (opt-in single-factor). The broker is
     // auto-unlocked and we silently hold the passphrase in memory; skip
     // the passphrase-cache lookup + prompt entirely and mint directly.
     // Allowlist check above already attested the operator's Telegram ID.
-    if (VAULT_APPROVAL_AUTH_MODE === 'telegram-id') {
+    // Admin-only keys are excluded — they take the passphrase path below.
+    if (!isAdminOnly && VAULT_APPROVAL_AUTH_MODE === 'telegram-id') {
       const username = ctx.from?.username ?? ctx.from?.first_name ?? `id=${senderId}`
       if (pending.card_message_id != null) {
         await ctx.api
@@ -13920,6 +13957,9 @@ async function handleVaultRequestAccessCallback(ctx: Context, data: string): Pro
           pending.card_message_id,
           joiningBatch
             ? `🔐 <b>Queued behind an earlier card.</b> Type your passphrase as your next message — it covers <b>${items.length}</b> pending approvals in this chat (one entry mints all grants, no re-type per card).`
+            : isAdminOnly
+            ? `🔒 <b>Admin-only credential.</b> <code>${escapeHtmlForTg(pending.key)}</code> requires your vault passphrase to grant — reply with it as your next message and we'll mint the grant for <b>${escapeHtmlForTg(pending.agent)}</b>, then delete the passphrase message.\n\n` +
+              `<i>The passphrase is what proves it's you: an agent can never mint this key on its own.</i>`
             : `🔐 <b>Vault is locked.</b> Reply with your passphrase as your next message — we'll unlock, mint the grant for <b>${escapeHtmlForTg(pending.agent)}</b>, and delete the passphrase message in one step.\n\n` +
               `<i>Mint authority stays operator-only: the broker only accepts the grant when the passphrase matches.</i>`,
           { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },

package/telegram-plugin/hooks/subagent-tracker-posttool.mjs

@@ -156,6 +156,53 @@ function extractResultSummary(toolResponse) {
   return str.slice(0, 200) || null
 }
 
+/**
+ * Extract the full text of a PostToolUse tool_response (untruncated).
+ * Mirrors extractResultSummary's shape handling but returns the whole
+ * string so callers can pattern-match on it.
+ */
+function toolResponseText(toolResponse) {
+  if (!toolResponse) return ''
+  if (Array.isArray(toolResponse.content)) {
+    return toolResponse.content
+      .filter((c) => c && typeof c === 'object' && c.type === 'text' && typeof c.text === 'string')
+      .map((c) => c.text)
+      .join('\n')
+  }
+  if (typeof toolResponse.result === 'string') return toolResponse.result
+  if (typeof toolResponse.output === 'string') return toolResponse.output
+  if (typeof toolResponse === 'string') return toolResponse
+  return ''
+}
+
+/**
+ * Detect Claude Code's async-launch ACK in a PostToolUse tool_response.
+ *
+ * A `run_in_background` Agent/Task returns IMMEDIATELY with an
+ * acknowledgement ("Async agent launched successfully … The agent is working
+ * in the background …"), NOT the sub-agent's final result. This ACK is the
+ * authoritative, uniform signal that the dispatch was a background one — it is
+ * present even when Claude Code omits `run_in_background` from the tool_input
+ * the PREtool hook sees (observed on claude-code 2.1.159: a worker whose
+ * tool_input lacked the flag still returned this ACK and ran ~3 min past the
+ * parent turn, so the pretool recorded background=0 and the worker card never
+ * fired). We therefore trust this ACK over the pretool's input-derived flag.
+ *
+ * Anchored on the specific "async agent launched" phrase (a foreground
+ * sub-agent's final report is extremely unlikely to contain it), with a
+ * structural backstop ("working in the background" + an agentId token) in case
+ * the launch-verb wording drifts. A major wording change degrades to the
+ * pretool flag — still correct whenever the model DID pass run_in_background,
+ * never worse than before.
+ */
+function isAsyncLaunchAck(toolResponse) {
+  const t = toolResponseText(toolResponse).toLowerCase()
+  if (!t) return false
+  if (t.includes('async agent launched')) return true
+  if (t.includes('working in the background') && t.includes('agentid')) return true
+  return false
+}
+
 // ---------------------------------------------------------------------------
 // DB write
 // ---------------------------------------------------------------------------
@@ -172,9 +219,18 @@ function extractResultSummary(toolResponse) {
  * recordSubagentEnd (driven by the JSONL turn_end event) remains the
  * authoritative end-of-life signal.
  *
+ * Mis-recorded background (DB background = 0 but `asyncLaunch` is true):
+ * Claude Code returned the async-launch ACK even though run_in_background was
+ * absent from the tool_input the pretool saw, so the row was wrongly recorded
+ * foreground. PROMOTE it to background = 1 and take the background path — do
+ * NOT terminalize, because the worker is still running (the ACK is a launch,
+ * not a completion). This is the authoritative correction that makes the
+ * gateway's worker-feed card fire (onProgress re-reads `background` per tick)
+ * AND prevents the premature `completed` the foreground path would write.
+ *
  * The done(err | null) callback is invoked after all DB operations complete.
  */
-function updateRow(dbPath, { id, status, resultSummary, now }, done) {
+function updateRow(dbPath, { id, status, resultSummary, now, asyncLaunch }, done) {
   // SQL to read the background flag so we can choose the right update path.
   const SELECT_SQL = `SELECT background FROM subagents WHERE id = ?`
 
@@ -194,12 +250,22 @@ function updateRow(dbPath, { id, status, resultSummary, now }, done) {
       AND status NOT IN ('completed', 'failed')
   `
 
+  // Promote a mis-recorded foreground row to background (sets background = 1),
+  // bumping activity but NOT terminalizing — same shape as BACKGROUND_SQL.
+  const PROMOTE_BACKGROUND_SQL = `
+    UPDATE subagents
+    SET background = 1, result_summary = COALESCE(?, result_summary), last_activity_at = ?
+    WHERE id = ?
+      AND status NOT IN ('completed', 'failed')
+  `
+
   // Snapshot all values used inside closures before setImmediate fires.
   const snapDbPath = dbPath
   const snapId = id
   const snapStatus = status
   const snapResultSummary = resultSummary
   const snapNow = now
+  const snapAsyncLaunch = asyncLaunch === true
 
   // Resolve a synchronous SQLite binding (node:sqlite under Node 22+,
   // bun:sqlite under bun, else null → CLI fallback). See helper docs.
@@ -216,6 +282,8 @@ function updateRow(dbPath, { id, status, resultSummary, now }, done) {
         const isBackground = row != null && row.background === 1
         if (isBackground) {
           db.prepare(BACKGROUND_SQL).run(snapResultSummary, snapNow, snapId)
+        } else if (snapAsyncLaunch) {
+          db.prepare(PROMOTE_BACKGROUND_SQL).run(snapResultSummary, snapNow, snapId)
         } else {
           db.prepare(FOREGROUND_SQL).run(snapNow, snapStatus, snapResultSummary, snapNow, snapId)
         }
@@ -239,6 +307,12 @@ function updateRow(dbPath, { id, status, resultSummary, now }, done) {
         fillPlaceholders(BACKGROUND_SQL.trim(), [snapResultSummary, snapNow, snapId]),
         done,
       )
+    } else if (snapAsyncLaunch) {
+      spawnSql(
+        snapDbPath,
+        fillPlaceholders(PROMOTE_BACKGROUND_SQL.trim(), [snapResultSummary, snapNow, snapId]),
+        done,
+      )
     } else {
       spawnSql(
         snapDbPath,
@@ -345,16 +419,26 @@ function main() {
 
   const toolResponse = event.tool_response ?? null
 
+  // Authoritative background signal: Claude Code's async-launch ACK. Trusted
+  // over the pretool's input-derived flag (which is missing whenever the
+  // model/runtime omits run_in_background from tool_input — see
+  // isAsyncLaunchAck). Gates both the nudge below and the promote path in
+  // updateRow.
+  const asyncLaunch = isAsyncLaunchAck(toolResponse)
+
   // conversational-pacing beat 4 (foreground half). A foreground
   // sub-agent's PostToolUse fires at real completion, mid-parent-turn,
   // with its result in tool_response — nudge the parent to synthesise a
   // user-facing handback. Background sub-agents are gated OUT: their
   // PostToolUse fires on the launch ACK (BACKGROUND_SQL leaves status
   // untouched for that reason), and their handback is driven by the
-  // gateway's subagent-watcher onFinish path instead. Fail-silent: an
-  // unknown background flag (null) skips the nudge.
+  // gateway's subagent-watcher onFinish path instead. A launch ACK is also
+  // gated out via `!asyncLaunch` — at this point the DB flag may still read 0
+  // (updateRow promotes it on the next tick), so the ACK is the reliable
+  // tell. Fail-silent: an unknown background flag (null) skips the nudge.
   if (
     process.env.SWITCHROOM_SUBAGENT_HANDBACK !== '0'
+    && !asyncLaunch
     && detectStatus(toolResponse) === 'completed'
     && readBackgroundFlagSync(dbPath, id) === 0
   ) {
@@ -368,6 +452,7 @@ function main() {
       status: detectStatus(toolResponse),
       resultSummary: extractResultSummary(toolResponse),
       now: Date.now(),
+      asyncLaunch,
     },
     (err) => {
       if (err) {

package/telegram-plugin/hooks/subagent-tracker-pretool.mjs

@@ -262,7 +262,17 @@ function main() {
     {
       id: event.tool_use_id ?? null,
       parentSessionId: event.session_id ?? null,
-      parentTurnKey: event.turn_id ?? null,
+      // parent_turn_key is intentionally NULL here. Claude Code's PreToolUse
+      // payload carries its own session id, not the gateway-minted Telegram
+      // turn_key (a chat+topic+turn key) the `turns` table is keyed on —
+      // `event.turn_id` is always undefined, and even if a future CLI
+      // populated it, it would not match a `turns.turn_key`. The gateway
+      // resolves parent_turn_key from the
+      // sub-agent's started_at at jsonl-link time (subagent-watcher.ts
+      // backfillJsonlAgentId), which works even after the parent turn ends.
+      // Writing a bogus value here would defeat that backfill's
+      // `parent_turn_key IS NULL` guard.
+      parentTurnKey: null,
       agentType: input.subagent_type ?? null,
       description: input.description ?? null,
       background: input.run_in_background === true ? 1 : 0,

package/telegram-plugin/registry/subagents-bugs.test.ts

@@ -387,8 +387,16 @@ describe('Bug 4 — result_summary always NULL (hook integration)', () => {
 
 // ─── Bug 5 — parent_turn_key always NULL ─────────────────────────────────────
 
-describe('Bug 5 — parent_turn_key always NULL (hook integration)', () => {
-  it('pretool stores parent_turn_key from event.turn_id', () => {
+describe('Bug 5 — parent_turn_key backfilled by gateway, not the hook', () => {
+  it('pretool writes parent_turn_key=NULL even when event.turn_id is present', () => {
+    // Claude Code's PreToolUse payload carries its own session id, never the
+    // gateway-minted Telegram turn_key (a chat+topic+turn key) the `turns`
+    // table is keyed on. `event.turn_id` — even if a future CLI populated it —
+    // would not match a `turns.turn_key`, so the hook intentionally writes
+    // NULL and lets the gateway backfill parent_turn_key from the sub-agent's
+    // started_at at jsonl-link time (subagent-watcher.ts backfillJsonlAgentId).
+    // Writing a bogus value here would defeat that backfill's
+    // `parent_turn_key IS NULL` guard.
     const event = {
       session_id: 'sess-turnkey',
       turn_id: 'turn-abc-001',
@@ -406,8 +414,8 @@ describe('Bug 5 — parent_turn_key always NULL (hook integration)', () => {
       | undefined
 
     expect(row).toBeDefined()
-    // After fix: parent_turn_key should be populated from event.turn_id
-    expect(row!.parent_turn_key).toBe('turn-abc-001')
+    // The hook never trusts event.turn_id — gateway backfill owns this column.
+    expect(row!.parent_turn_key).toBeNull()
   })
 
   it('pretool stores parent_turn_key as NULL when turn_id absent (no regression)', () => {

package/telegram-plugin/subagent-watcher.ts

@@ -508,7 +508,10 @@ interface FsLike {
  *   - Row already linked to a different agentId: SQL `WHERE jsonl_agent_id IS
  *     NULL` skips it. Re-runs are safe.
  */
-function backfillJsonlAgentId(
+// Exported for unit-testing the parent_turn_key backfill (telegram-plugin/
+// tests/subagent-watcher-parent-turn-key.test.ts). Not intended for
+// consumption by other modules.
+export function backfillJsonlAgentId(
   db: SubagentLivenessDb,
   jsonlPath: string,
   agentId: string,
@@ -555,6 +558,47 @@ function backfillJsonlAgentId(
     .prepare('UPDATE subagents SET jsonl_agent_id = ? WHERE id = ?')
     .run(agentId, candidate.id)
   log?.(`subagent-watcher: backfill linked ${agentId} → ${candidate.id}`)
+
+  // Backfill parent_turn_key (gateway-side). The PreToolUse hook can't know
+  // the gateway-minted Telegram turn_key (a chat+topic+turn key) — it only
+  // sees Claude Code's session id — so the row was inserted with
+  // parent_turn_key=NULL. Resolve
+  // it now from the turn whose [started_at, ended_at] window contained the
+  // sub-agent's dispatch (its started_at). Keying on the historical
+  // started_at, NOT "the turn active now", is what makes this correct for a
+  // background worker that outlives its parent turn: the turn may have already
+  // ended by link time, but the containment match still finds it. Turns are
+  // processed serially per agent, so at most one window contains a given
+  // instant; the ORDER BY ... DESC LIMIT 1 is just a defensive tie-break.
+  //
+  // Without this, resolveSubagentOriginChat() returns null and the live
+  // worker card + handback fall back to the operator DM instead of the
+  // originating group/forum-topic, and resolveCallingSubagent()'s turn-scoped
+  // heuristic (WHERE parent_turn_key = ?) can never see the row. Best-effort:
+  // any failure leaves parent_turn_key NULL (today's behaviour) and never
+  // throws out of the watcher poll loop.
+  try {
+    const linkedRow = db
+      .prepare('SELECT started_at, parent_turn_key FROM subagents WHERE id = ?')
+      .get(candidate.id) as { started_at: number; parent_turn_key: string | null } | null
+    if (linkedRow != null && linkedRow.parent_turn_key == null) {
+      const turn = db
+        .prepare(
+          `SELECT turn_key FROM turns
+           WHERE started_at <= ? AND (ended_at IS NULL OR ended_at >= ?)
+           ORDER BY started_at DESC LIMIT 1`,
+        )
+        .get(linkedRow.started_at, linkedRow.started_at) as { turn_key: string } | null
+      if (turn?.turn_key != null) {
+        db
+          .prepare('UPDATE subagents SET parent_turn_key = ? WHERE id = ?')
+          .run(turn.turn_key, candidate.id)
+        log?.(`subagent-watcher: backfill parent_turn_key ${candidate.id} → ${turn.turn_key}`)
+      }
+    }
+  } catch (err) {
+    log?.(`subagent-watcher: parent_turn_key backfill skipped for ${candidate.id} — ${(err as Error).message}`)
+  }
 }
 
 // Exported for unit-testing the ENOENT/EACCES deregister path

package/telegram-plugin/tests/subagent-tracker-hooks.test.ts

@@ -271,6 +271,79 @@ describe('subagent-tracker-posttool', () => {
     expect(postResult.status).toBe(0)
     expect(postResult.stdout).not.toContain('additionalContext')
   })
+
+  // The async-launch ACK is Claude Code's verbatim immediate return for a
+  // run_in_background Agent/Task dispatch. The posttool trusts it over the
+  // pretool's input-derived background flag, which is missing whenever the
+  // runtime omits run_in_background from the tool_input the pretool saw
+  // (observed on claude-code 2.1.159 — the clerk worker that never surfaced).
+  const ASYNC_LAUNCH_ACK =
+    'Async agent launched successfully.\n'
+    + 'agentId: go-live-sync-a176dc93\n'
+    + 'The agent is working in the background. You will be notified '
+    + 'automatically when it completes.'
+
+  it('promotes a mis-recorded foreground row to background from the launch ACK', () => {
+    // Pretool sees NO run_in_background key (the production bug) → records
+    // background=0, status=running.
+    const preResult = runHook(PRETOOL_SCRIPT, {
+      session_id: 's-promote',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_promote1',
+      tool_input: { subagent_type: 'worker', description: 'Go-live sync' },
+    })
+    expect(preResult.status).toBe(0)
+
+    const db = openDb()
+    const before = db.prepare('SELECT background, status FROM subagents WHERE id = ?').get('toolu_promote1') as
+      | { background: number; status: string }
+      | undefined
+    expect(before?.background).toBe(0)
+    expect(before?.status).toBe('running')
+
+    // Posttool receives the async-launch ACK → promote to background, do NOT
+    // terminalize, and do NOT emit a foreground handback nudge.
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_promote1',
+      tool_response: { content: [{ type: 'text', text: ASYNC_LAUNCH_ACK }] },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).not.toContain('additionalContext')
+
+    const after = db.prepare('SELECT background, status, ended_at FROM subagents WHERE id = ?').get('toolu_promote1') as
+      | { background: number; status: string; ended_at: number | null }
+      | undefined
+    expect(after?.background).toBe(1)
+    expect(after?.status).toBe('running')
+    expect(after?.ended_at == null).toBe(true)
+  })
+
+  it('still terminalizes a genuine foreground completion (no false promote)', () => {
+    // A real foreground sub-agent whose final report happens to mention
+    // "background" must NOT be mistaken for a launch ACK — the promote path
+    // only fires on the specific async-launch phrasing.
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-noflip',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_noflip1',
+      tool_input: { subagent_type: 'worker', description: 'Real foreground task', run_in_background: false },
+    })
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_noflip1',
+      tool_response: { result: 'Done. The feature now runs as a background job.', is_error: false },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).toContain('additionalContext')
+
+    const db = openDb()
+    const row = db.prepare('SELECT background, status FROM subagents WHERE id = ?').get('toolu_noflip1') as
+      | { background: number; status: string }
+      | undefined
+    expect(row?.background).toBe(0)
+    expect(row?.status).toBe('completed')
+  })
 })
 
 describe('agent-dir resolution (RFC §Bug 2)', () => {

package/telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Unit tests for the parent_turn_key backfill in subagent-watcher.ts
+ * (backfillJsonlAgentId).
+ *
+ * The PreToolUse hook records a sub-agent row with parent_turn_key=NULL — it
+ * only sees Claude Code's session id, never the Telegram turn_key
+ * (chat_id:msg_id) the gateway keys turns on. The gateway backfills
+ * parent_turn_key when it links the JSONL stem to the row, resolving it from
+ * the turn whose [started_at, ended_at] window contained the sub-agent's
+ * dispatch (its started_at). These tests pin that resolution — in particular
+ * that it stays correct for a background worker that outlives its parent turn.
+ *
+ * bun:sqlite — run under Bun:
+ *   bun test telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { openTurnsDbInMemory } from '../registry/turns-schema.js'
+import { applySubagentsSchema } from '../registry/subagents-schema.js'
+import { backfillJsonlAgentId } from '../subagent-watcher.js'
+
+type Db = ReturnType<typeof openTurnsDbInMemory>
+
+let tempDir: string
+let db: Db
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'sub-parent-turn-'))
+  db = openTurnsDbInMemory()
+  applySubagentsSchema(db)
+})
+
+afterEach(() => {
+  try { db.close() } catch { /* ignore */ }
+  try { rmSync(tempDir, { recursive: true, force: true }) } catch { /* ignore */ }
+})
+
+function insertTurn(args: {
+  turnKey: string
+  chatId: string
+  threadId?: string | null
+  startedAt: number
+  endedAt?: number | null
+}) {
+  db.prepare(`
+    INSERT INTO turns (turn_key, chat_id, thread_id, started_at, ended_at, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    args.turnKey,
+    args.chatId,
+    args.threadId ?? null,
+    args.startedAt,
+    args.endedAt ?? null,
+    args.startedAt,
+    args.startedAt,
+  )
+}
+
+function insertSub(args: {
+  id: string
+  agentType: string
+  description: string
+  startedAt: number
+  parentTurnKey?: string | null
+}) {
+  db.prepare(`
+    INSERT INTO subagents
+      (id, parent_session_id, parent_turn_key, agent_type, description,
+       background, started_at, last_activity_at, status, jsonl_agent_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', NULL)
+  `).run(
+    args.id,
+    'sess-1',
+    args.parentTurnKey ?? null,
+    args.agentType,
+    args.description,
+    1,
+    args.startedAt,
+    args.startedAt,
+  )
+}
+
+/** Write the meta.json the backfill reads to match a row by (agentType, description). */
+function writeMeta(agentType: string, description: string): string {
+  const jsonlPath = join(tempDir, 'worker.jsonl')
+  writeFileSync(join(tempDir, 'worker.meta.json'), JSON.stringify({ agentType, description }))
+  return jsonlPath
+}
+
+function readSub(id: string) {
+  return db.prepare('SELECT jsonl_agent_id, parent_turn_key FROM subagents WHERE id = ?').get(id) as
+    | { jsonl_agent_id: string | null; parent_turn_key: string | null }
+    | undefined
+}
+
+describe('backfillJsonlAgentId — parent_turn_key resolution', () => {
+  it('resolves parent_turn_key from the turn whose window contains the sub-agent started_at', () => {
+    insertTurn({ turnKey: '555:10', chatId: '555', threadId: '42', startedAt: 1000, endedAt: 2000 })
+    insertSub({ id: 'toolu_a', agentType: 'worker', description: 'Go-live sync', startedAt: 1500 })
+
+    const jsonlPath = writeMeta('worker', 'Go-live sync')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_a')
+
+    const row = readSub('toolu_a')
+    expect(row?.jsonl_agent_id).toBe('agentstem_a')
+    expect(row?.parent_turn_key).toBe('555:10')
+  })
+
+  it('resolves to the parent turn even after it has ended (background worker outlives the turn)', () => {
+    // Parent turn already ended at 1600; a later turn is active "now".
+    insertTurn({ turnKey: '555:10', chatId: '555', startedAt: 1000, endedAt: 1600 })
+    insertTurn({ turnKey: '555:20', chatId: '555', startedAt: 1700, endedAt: null })
+    // The worker was dispatched at 1500 — inside the FIRST (now-ended) turn.
+    insertSub({ id: 'toolu_b', agentType: 'worker', description: 'Long task', startedAt: 1500 })
+
+    const jsonlPath = writeMeta('worker', 'Long task')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_b')
+
+    // Must pick the containing (ended) turn, NOT the turn active at link time.
+    expect(readSub('toolu_b')?.parent_turn_key).toBe('555:10')
+  })
+
+  it('does NOT overwrite an already-populated parent_turn_key', () => {
+    insertTurn({ turnKey: '555:10', chatId: '555', startedAt: 1000, endedAt: 2000 })
+    insertSub({
+      id: 'toolu_c',
+      agentType: 'worker',
+      description: 'Preset',
+      startedAt: 1500,
+      parentTurnKey: '999:9',
+    })
+
+    const jsonlPath = writeMeta('worker', 'Preset')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_c')
+
+    expect(readSub('toolu_c')?.parent_turn_key).toBe('999:9')
+  })
+
+  it('leaves parent_turn_key NULL when no turn window contains the dispatch', () => {
+    insertTurn({ turnKey: '555:10', chatId: '555', startedAt: 1000, endedAt: 2000 })
+    // Dispatched at 50 — before any turn started.
+    insertSub({ id: 'toolu_d', agentType: 'worker', description: 'Orphan', startedAt: 50 })
+
+    const jsonlPath = writeMeta('worker', 'Orphan')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_d')
+
+    const row = readSub('toolu_d')
+    // Still linked, but no turn to attribute it to.
+    expect(row?.jsonl_agent_id).toBe('agentstem_d')
+    expect(row?.parent_turn_key == null).toBe(true)
+  })
+})