@sechroom/cli 2026.7.12 → 2026.7.14

package/dist/index.js

@@ -439,6 +439,9 @@ var quiet = false;
 function setQuiet(q) {
   quiet = q;
 }
+function isQuiet() {
+  return quiet;
+}
 function colorOn() {
   return !quiet && !process.env.NO_COLOR && process.env.FORCE_COLOR !== "0" && Boolean(process.stdout.isTTY);
 }
@@ -615,6 +618,22 @@ function emitAction(summary, data, json) {
   process.stdout.write(`${ok("\u2713")} ${summary}
 `);
 }
+var GOVERNANCE_QUEUED_PROBLEM_TYPE = "https://sechroom.dev/problems/governance-review-queued";
+function isGovernanceQueued(body) {
+  return typeof body === "object" && body !== null && "type" in body && body.type === GOVERNANCE_QUEUED_PROBLEM_TYPE;
+}
+function formatQueuedForApproval(body, json) {
+  if (json) return JSON.stringify(body) + "\n";
+  const b = body ?? {};
+  const detail = typeof b.detail === "string" ? b.detail : void 0;
+  const requestId = typeof b.requestId === "string" ? b.requestId : void 0;
+  const message = detail ?? "This change requires operator approval before it takes effect.";
+  let out = `${warn("\u29D7")} Pending approval \u2014 ${message}
+`;
+  if (requestId) out += `  ${style.dim(`request: ${requestId}`)}
+`;
+  return out;
+}
 async function runApi(label, fn) {
   const s = spinner(label);
   let res;
@@ -624,6 +643,12 @@ async function runApi(label, fn) {
     s.fail();
     fail(err2);
   }
+  const queuedBody = res.data ?? res.error;
+  if (res.response?.status === 202 && isGovernanceQueued(queuedBody)) {
+    s.stop();
+    process.stdout.write(formatQueuedForApproval(queuedBody, isQuiet()));
+    process.exit(0);
+  }
   const httpFailed = res.response !== void 0 && !res.response.ok;
   if (res.error !== void 0 && res.error !== null || httpFailed) {
     s.fail();
@@ -1076,14 +1101,23 @@ function bodyOf(row) {
   const m = row?.item ?? row;
   return m?.text ?? m?.Text ?? "";
 }
+function idOf(row) {
+  const m = row?.item ?? row;
+  return String(m?.id ?? m?.memoryId ?? "unknown");
+}
 function entriesFromRows(rows, surface, source, roleTag, namePrefix) {
   const out = /* @__PURE__ */ new Map();
   for (const row of rows ?? []) {
     const tags = tagsOf(row);
     if (!tags.includes(roleTag)) continue;
-    if (tagValue(tags, "target:") !== surface) continue;
+    if (!tags.includes(`target:${surface}`)) continue;
     const name = tagValue(tags, namePrefix);
     if (!name) continue;
+    if (out.has(name)) {
+      throw new Error(
+        `Ambiguous ${source} ${roleTag} '${name}' for target:${surface}: ${idOf(row)} duplicates another eligible component. Resolve the duplicate before installing.`
+      );
+    }
     out.set(name, { name, body: bodyOf(row), source });
   }
   return out;
@@ -1111,20 +1145,33 @@ function agentTargetFor(surface) {
   return AGENT_TARGET[surface] ?? `${surface}-agent`;
 }
 async function fetchFeedRows(cfg, workspaceId) {
-  try {
-    const client = await makeClient(cfg);
-    const feed = await client.GET("/workspaces/{workspaceId}/memories/feed", {
+  const client = await makeClient(cfg);
+  const rows = [];
+  let cursor;
+  do {
+    const { data, error, response } = await client.GET("/workspaces/{workspaceId}/memories/feed", {
       params: {
         path: { workspaceId },
         // cascadeWorkspaces: skills land in an "Operator Skills" SUB-workspace;
         // includeText: the feed omits bodies by default, we need them for SKILL.md.
-        query: { limit: 200, cascadeWorkspaces: true, includeText: true }
+        query: {
+          limit: 200,
+          cascadeWorkspaces: true,
+          includeText: true,
+          ...cursor ? { cursor } : {}
+        }
       }
-    }).then((r) => r.data).catch(() => void 0);
-    return feed?.results ?? feed?.Results ?? [];
-  } catch {
-    return [];
-  }
+    });
+    if (error || !response.ok || !data) {
+      throw new Error(
+        `Could not read operator-skill catalogue from ${workspaceId}: HTTP ${response.status}.`
+      );
+    }
+    const feed = data;
+    rows.push(...feed.results ?? feed.Results ?? []);
+    cursor = feed.nextCursor ?? feed.NextCursor ?? void 0;
+  } while (cursor);
+  return rows;
 }
 async function fetchTemplateRows(cfg, personalWorkspaceId) {
   const [systemRows, personalRows] = await Promise.all([
@@ -1144,7 +1191,10 @@ function resolveReferenceSet(rows, surface) {
 }
 
 // src/setup/materialise.ts
-var CLIENT_SURFACE = "claude-code";
+var CLIENT_SURFACE = {
+  claude: "claude-code",
+  codex: "gpt-codex"
+};
 function writeSkills(dir, skills, surface) {
   const written = [];
   for (const s of skills) {
@@ -1177,11 +1227,71 @@ function writeReferencesIntoSkillDirs(dir, skills, refs) {
   }
   return refs.map((r) => r.name);
 }
-var SKILL_SPEC = { kind: "skill", dir: skillsDir, resolve: resolveSkillSet, write: writeSkills };
-var AGENT_SPEC = { kind: "agent", dir: agentsDir, resolve: resolveAgentSet, write: writeAgents };
+var SKILL_SPEC = {
+  kind: "skill",
+  dir: skillsDir,
+  resolve: resolveSkillSet,
+  write: writeSkills,
+  supportsCodex: true
+};
+var AGENT_SPEC = {
+  kind: "agent",
+  dir: agentsDir,
+  resolve: resolveAgentSet,
+  write: writeAgents,
+  supportsCodex: false
+};
 function scopeOf(opts) {
   return opts.local ? "project" : resolveScope(opts.scope);
 }
+function parseClient(value) {
+  if (value == null) return void 0;
+  if (value === "claude" || value === "codex" || value === "all") return value;
+  throw new Error(`--client must be 'claude', 'codex', or 'all' (got '${value}')`);
+}
+function clientSelection(spec, g, raw) {
+  if (!spec.supportsCodex) return "claude";
+  const explicit = parseClient(raw);
+  if (explicit) return explicit;
+  const claudeConfigured = Boolean(g.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR);
+  const codexConfigured = Boolean(g.codexHome || process.env.CODEX_HOME);
+  if (claudeConfigured || codexConfigured) {
+    if (claudeConfigured && codexConfigured) return "all";
+    return codexConfigured ? "codex" : "claude";
+  }
+  const claudeDetected = resolveClaudeTargets({})[0]?.dir;
+  const codexDetected = resolveCodexHomes({})[0];
+  const hasClaude = Boolean(claudeDetected && existsSync3(claudeDetected));
+  const hasCodex = Boolean(codexDetected && existsSync3(codexDetected));
+  if (hasClaude && hasCodex) return "all";
+  if (hasCodex) return "codex";
+  return "claude";
+}
+function targetsFor(spec, g, scope, selection) {
+  const clients = selection === "all" ? ["claude", "codex"] : [selection];
+  if (scope === "project" && clients.includes("codex")) {
+    throw new Error("Codex skills have no supported project scope; use --scope global or --client claude.");
+  }
+  const targets = [];
+  for (const client of clients) {
+    if (client === "claude") {
+      targets.push(...resolveClaudeTargets({ override: g.claudeConfigDir, scope, cwd: process.cwd() }).map((target) => ({
+        client,
+        surface: CLIENT_SURFACE[client],
+        dir: spec.dir(target.dir),
+        label: target.label
+      })));
+      continue;
+    }
+    targets.push(...resolveCodexHomes({ override: g.codexHome, scope }).map((home) => ({
+      client,
+      surface: CLIENT_SURFACE[client],
+      dir: spec.dir(home),
+      label: home
+    })));
+  }
+  return targets;
+}
 async function runInstall(spec, cmd, opts) {
   const g = cmd.optsWithGlobals();
   let scope;
@@ -1193,31 +1303,48 @@ async function runInstall(spec, cmd, opts) {
   const cfg = resolveConfig(g);
   const dryRun = Boolean(opts.dryRun);
   const json = Boolean(g.json || opts.json);
-  const targets = resolveClaudeTargets({ override: g.claudeConfigDir, scope, cwd: process.cwd() });
+  let selection;
+  let targets;
+  try {
+    selection = clientSelection(spec, g, opts.client);
+    targets = targetsFor(spec, g, scope, selection);
+  } catch (err2) {
+    return fail(err2.message);
+  }
   const personalWorkspaceId = await getPersonalWorkspaceId(cfg);
   const rows = await fetchTemplateRows(cfg, personalWorkspaceId);
-  const items = spec.resolve(rows, CLIENT_SURFACE);
-  const refs = spec.kind === "skill" ? resolveReferenceSet(rows, CLIENT_SURFACE) : [];
   const results = targets.map((t) => {
-    const dir = spec.dir(t.dir);
-    const written = dryRun ? items.map((i) => i.name) : spec.write(dir, items, CLIENT_SURFACE);
-    const refsWritten = dryRun ? refs.map((r) => r.name) : writeReferencesIntoSkillDirs(dir, items, refs);
-    return { dir, label: t.label, written, refsWritten };
+    const items = spec.resolve(rows, t.surface);
+    const refs = spec.kind === "skill" ? resolveReferenceSet(rows, t.surface) : [];
+    const written = dryRun ? items.map((i) => i.name) : spec.write(t.dir, items, t.surface);
+    const refsWritten = dryRun ? refs.map((r) => r.name) : writeReferencesIntoSkillDirs(t.dir, items, refs);
+    return {
+      client: t.client,
+      surface: t.surface,
+      dir: t.dir,
+      label: t.label,
+      available: items.length,
+      references: refs.length,
+      items: items.map(({ name, source }) => ({ name, source })),
+      referenceItems: refs.map(({ name, source }) => ({ name, source })),
+      written,
+      refsWritten
+    };
   });
-  if (json) return emit({ kind: spec.kind, dryRun, available: items.length, references: refs.length, targets: results }, true);
-  if (items.length === 0) {
+  if (json) return emit({ kind: spec.kind, client: selection, dryRun, targets: results }, true);
+  if (results.every((r) => r.available === 0)) {
     console.log(style.dim(`No ${spec.kind}s available to install \u2014 is the bundle installed for your account?`));
     return;
   }
   for (const r of results) {
     console.log(
-      `${dryRun ? "" : style.green("\u2713 ")}${dryRun ? "would write" : "wrote"} ${r.written.length} ${spec.kind}(s) ${style.dim("\u2192")} ${r.dir}`
+      `${dryRun ? "" : style.green("\u2713 ")}${dryRun ? "would write" : "wrote"} ${r.written.length} ${spec.kind}(s) for ${r.client} ${style.dim("\u2192")} ${r.dir}`
     );
     if (r.refsWritten.length)
       console.log(
         `${dryRun ? "" : style.green("\u2713 ")}${dryRun ? "would write" : "wrote"} ${r.refsWritten.length} reference(s) into each skill ${style.dim("\u2192")} ${r.dir}/<skill>/references`
       );
-    if (dryRun) for (const i of items) console.log(`    ${i.name} ${style.dim(`[${i.source}]`)}`);
+    if (dryRun) for (const i of r.items) console.log(`    ${i.name} ${style.dim(`[${i.source}]`)}`);
   }
 }
 function runList(spec, cmd, opts) {
@@ -1229,16 +1356,22 @@ function runList(spec, cmd, opts) {
     return fail(err2.message);
   }
   const json = Boolean(g.json || opts.json);
-  const targets = resolveClaudeTargets({ override: g.claudeConfigDir, scope, cwd: process.cwd() });
+  let selection;
+  let targets;
+  try {
+    selection = clientSelection(spec, g, opts.client);
+    targets = targetsFor(spec, g, scope, selection);
+  } catch (err2) {
+    return fail(err2.message);
+  }
   const out = targets.map((t) => {
-    const dir = spec.dir(t.dir);
-    const lock = readSkillsLock(dir);
+    const lock = readSkillsLock(t.dir);
     const entries = Object.entries(lock).flatMap(
-      ([slug, e]) => (e.skills ?? []).map((name) => ({ slug, name, present: existsSync3(join4(dir, name)) }))
+      ([slug, e]) => (e.skills ?? []).map((name) => ({ slug, name, present: existsSync3(join4(t.dir, name)) }))
     );
-    return { dir, label: t.label, entries };
+    return { client: t.client, surface: t.surface, dir: t.dir, label: t.label, entries };
   });
-  if (json) return emit({ kind: spec.kind, targets: out }, true);
+  if (json) return emit({ kind: spec.kind, client: selection, targets: out }, true);
   let any = false;
   for (const t of out) {
     if (t.entries.length === 0) continue;
@@ -1261,33 +1394,39 @@ function runClean(spec, cmd, opts, slugArg) {
     return fail(err2.message);
   }
   const json = Boolean(g.json || opts.json);
-  const targets = resolveClaudeTargets({ override: g.claudeConfigDir, scope, cwd: process.cwd() });
+  let selection;
+  let targets;
+  try {
+    selection = clientSelection(spec, g, opts.client);
+    targets = targetsFor(spec, g, scope, selection);
+  } catch (err2) {
+    return fail(err2.message);
+  }
   const cleaned = [];
   const missing = [];
   for (const t of targets) {
-    const dir = spec.dir(t.dir);
-    const lock = readSkillsLock(dir);
+    const lock = readSkillsLock(t.dir);
     const entry = lock[slug];
     if (!entry) {
-      missing.push(join4(dir, SKILLS_LOCK));
+      missing.push(join4(t.dir, SKILLS_LOCK));
       continue;
     }
     const removed = [];
     for (const name of entry.skills) {
-      const p = join4(dir, name);
+      const p = join4(t.dir, name);
       if (existsSync3(p)) {
         rmSync2(p, { recursive: true, force: true });
         removed.push(name);
       }
     }
     delete lock[slug];
-    writeSkillsLock(dir, lock);
-    cleaned.push({ dir, removed });
+    writeSkillsLock(t.dir, lock);
+    cleaned.push({ client: t.client, surface: t.surface, dir: t.dir, removed });
   }
   if (cleaned.length === 0) {
     return fail(`No materialised ${spec.kind}s recorded for '${slug}' in ${missing.join(", ")}.`);
   }
-  if (json) return emit({ kind: spec.kind, slug, cleaned, missing }, true);
+  if (json) return emit({ kind: spec.kind, client: selection, slug, cleaned, missing }, true);
   for (const c of cleaned) {
     console.log(style.green(`Removed ${c.removed.length} ${spec.kind}(s) for ${slug} from ${c.dir}`));
   }
@@ -1403,15 +1542,24 @@ var CLAUDE_HOOK_COMMANDS = {
   SessionStart: "sechroom hook session-start",
   PreCompact: "sechroom hook pre-compact",
   SessionEnd: "sechroom hook session-end",
-  // WLP telemetry tap (D-WLP-10) — per-turn executor self-report. No-op (exit 0) unless this
-  // checkout is bound to a decomposition+task via `sechroom telemetry bind`, so it's safe to wire
-  // for every Claude install. Claude-only (it parses a Claude Code transcript).
-  Stop: "sechroom telemetry hook"
+  // WLP telemetry tap (D-WLP-10 + FR-352 Tier 1) — per-turn executor self-report. The one
+  // `telemetry hook` verb dispatches on hook_event_name: Stop/SubagentStop → parsed (token/context) +
+  // terminal (turn end), Notification/PermissionDenied → approval. No-op (exit 0) unless this checkout
+  // is bound via `sechroom telemetry bind`, so it's safe to wire for every Claude install; an event a
+  // given Claude Code version doesn't know is inert (never fires). Claude-only.
+  Stop: "sechroom telemetry hook",
+  SubagentStop: "sechroom telemetry hook",
+  Notification: "sechroom telemetry hook",
+  PermissionDenied: "sechroom telemetry hook"
 };
 var CODEX_HOOK_COMMANDS = {
   SessionStart: "sechroom hook session-start",
+  PreCompact: "sechroom hook pre-compact",
   Stop: "sechroom hook session-end --debounce-minutes 10"
 };
+function hookCommandsForSurface(surface) {
+  return surface === "claude" ? CLAUDE_HOOK_COMMANDS : CODEX_HOOK_COMMANDS;
+}
 function hasHookCommand(config2, event, command) {
   const groups = config2.hooks?.[event] ?? [];
   return groups.some((g) => (g.hooks ?? []).some((h) => h.type === "command" && h.command === command));
@@ -1549,7 +1697,10 @@ function registerChannel(program2) {
     "--tag <tag...>",
     "Tag(s) the event must carry to match (repeatable). Default targets WLP task dispatches.",
     ["kind:task"]
-  ).option("--workspace <wsp...>", "Restrict to these workspace id(s)");
+  ).option("--workspace <wsp...>", "Restrict to these workspace id(s)").option(
+    "--executor-instance <id>",
+    "Join the exact executor-instance SignalR group"
+  );
   withFilterOpts(
     channel.command("connect").description(
       "Register a SignalR subscription and stream matched events to stdout"
@@ -1567,7 +1718,7 @@ function registerChannel(program2) {
         (typeof payload === "string" ? payload : JSON.stringify(payload)) + "\n"
       )
     );
-    const conn = await openConnection(cfg, deliver);
+    const conn = await openConnection(cfg, deliver, opts.executorInstance);
     await reconcile(cfg, filter, deliver);
     if (json) {
       emit(
@@ -1616,7 +1767,7 @@ function registerChannel(program2) {
 `))
       );
     });
-    const conn = await openConnection(cfg, deliver);
+    const conn = await openConnection(cfg, deliver, opts.executorInstance);
     await reconcile(cfg, filter, deliver);
     process.stderr.write(
       style.dim(
@@ -1727,8 +1878,9 @@ async function ensureSubscription(cfg, name, filter) {
     );
   return await resp.json();
 }
-async function openConnection(cfg, onEvent) {
-  const conn = new HubConnectionBuilder().withUrl(`${cfg.baseUrl}/notifications/${cfg.tenant}`, {
+async function openConnection(cfg, onEvent, executorInstanceId) {
+  const query = executorInstanceId ? `?executorInstanceId=${encodeURIComponent(executorInstanceId)}` : "";
+  const conn = new HubConnectionBuilder().withUrl(`${cfg.baseUrl}/notifications/${cfg.tenant}${query}`, {
     transport: HttpTransportType.LongPolling,
     accessTokenFactory: () => requireToken(cfg)
   }).withAutomaticReconnect().build();
@@ -2431,6 +2583,12 @@ Fail-soft: no lane / no auth / no-or-partial intent file / API error -> exit 0,
         const surfaceResults = installHookSurfaces(["codex"], { dryRun, claudeDir: "", codexHome })[0].results;
         process.stdout.write(`${HOOK_SURFACE_LABEL.codex}:
 `);
+        if (dryRun) {
+          for (const [event, command] of Object.entries(hookCommandsForSurface("codex"))) {
+            process.stdout.write(`  ${event}: ${command}
+`);
+          }
+        }
         for (const r of surfaceResults) {
           results.push(r);
           process.stdout.write(describe(r, dryRun) + "\n");
@@ -2891,6 +3049,7 @@ function registerDecomposition(program2) {
 Examples:
   $ sechroom decomposition decompose mem_XXXX
   $ sechroom decomposition execute sug_XXXX
+  $ sechroom decomposition publish-run sug_XXXX
   $ sechroom decomposition accept sug_XXXX
   $ sechroom decomposition reject sug_XXXX --reason "wrong shape"`
   );
@@ -2928,6 +3087,23 @@ Examples:
       cmd.optsWithGlobals().json
     );
   });
+  decomposition.command("publish-run <decompositionId>").description(
+    "Publish an accepted decomposition's context pack on demand (POST /decompositions/{id}/publish-run)"
+  ).action(async (decompositionId, _opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const data = await runApi("Publishing context pack", async () => {
+      const client = await makeClient(cfg);
+      return client.POST("/decompositions/{id}/publish-run", {
+        params: { path: { id: decompositionId } },
+        body: {}
+      });
+    });
+    emitAction(
+      `published ${style.bold(decompositionId)} \u2192 run ${style.bold(data.runRecordId)} (${data.outcome})`,
+      data,
+      cmd.optsWithGlobals().json
+    );
+  });
   decomposition.command("accept <decompositionId>").description(
     "Accept a Pending decomposition \u2014 promote + ratify its Tasks (POST /decompositions/{id}/accept)"
   ).action(async (decompositionId, _opts, cmd) => {
@@ -2964,6 +3140,205 @@ Examples:
   });
 }
 
+// src/commands/executor.ts
+function registerExecutor(program2) {
+  const executor = program2.command("executor").description(
+    "Register and operate a local Claude Code/Codex executor advertisement"
+  );
+  executor.command("submit-connector").description(
+    "Submit a local-session connector definition for governed approval"
+  ).requiredOption("--slug <slug>", "Unique connector definition slug").requiredOption("--display-name <name>", "Human-readable connector name").requiredOption("--transport <kind>", "push | pull").option("--profile <profile...>", "Advertised runtime profiles", [
+    "base",
+    "dotnet-10"
+  ]).action(async (opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const data = await api(cfg, "/connectors/definitions", {
+      method: "POST",
+      body: JSON.stringify({
+        slug: opts.slug,
+        displayName: opts.displayName,
+        runtimeProfiles: opts.profile,
+        connectorKind: "ExecutionRuntime",
+        providerKind: "local-session",
+        dispatchTransport: parseTransport(opts.transport)
+      })
+    });
+    emit(data, Boolean(cmd.optsWithGlobals().json));
+    if (!cmd.optsWithGlobals().json) {
+      process.stderr.write(
+        style.dim(
+          "approve this connector definition before registering executors\n"
+        )
+      );
+    }
+  });
+  executor.command("register").description(
+    "Create/reuse a SignalR binding and register this local executor instance"
+  ).requiredOption(
+    "--instance-key <key>",
+    "Stable key for this concrete session/lane"
+  ).requiredOption(
+    "--connector <id>",
+    "Approved local-session ConnectorDefinition id"
+  ).option("--runtime <kind>", "claude-code | codex", "claude-code").option(
+    "--relay <id>",
+    "Relay identity shared by sibling instances",
+    "sechroom-cli-local"
+  ).option(
+    "--subscription-name <name>",
+    "SignalR delivery binding name",
+    "executor-dispatch"
+  ).option(
+    "--capability <key...>",
+    "Capability operation keys claimed by this instance"
+  ).option("--tool-set-ref <ref>", "Optional governed tool-set reference").option("--ttl <seconds>", "Advertisement TTL (30-600)", parseInteger, 120).action(async (opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    if (!cfg.workspaceId)
+      fail("executor register requires a configured workspaceId");
+    const subscription = await api(
+      cfg,
+      "/me/delivery-subscriptions/signalr",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          name: opts.subscriptionName,
+          enabled: true,
+          filter: { tags: ["kind:task"], workspaceScope: [cfg.workspaceId] }
+        })
+      }
+    );
+    const data = await api(
+      cfg,
+      "/me/executor-instances",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          relayId: opts.relay,
+          instanceKey: opts.instanceKey,
+          runtimeKind: parseRuntimeKind(opts.runtime),
+          activationMode: "Attached",
+          deliverySubscriptionId: subscription.id,
+          connectorId: opts.connector,
+          claimedCapabilityKeys: opts.capability ?? [],
+          toolSetRef: opts.toolSetRef ?? null,
+          ttlSeconds: opts.ttl
+        })
+      }
+    );
+    emit(data, Boolean(cmd.optsWithGlobals().json));
+    if (!cmd.optsWithGlobals().json)
+      process.stderr.write(
+        style.dim(`refresh with: sechroom executor heartbeat ${data.id}
+`)
+      );
+  });
+  executor.command("refresh <id>").description("Refresh one advertisement lease once").option("--ttl <seconds>", "Advertisement TTL (30-600)", parseInteger, 120).action(async (id, opts, cmd) => {
+    const data = await refresh(
+      resolveConfig(cmd.optsWithGlobals()),
+      id,
+      opts.ttl
+    );
+    emit(data, Boolean(cmd.optsWithGlobals().json));
+  });
+  executor.command("heartbeat <id>").description("Keep an advertisement alive until interrupted").option("--ttl <seconds>", "Advertisement TTL (30-600)", parseInteger, 120).option("--interval <seconds>", "Refresh interval", parseInteger, 40).action(async (id, opts, cmd) => {
+    if (opts.interval >= opts.ttl)
+      fail("heartbeat interval must be shorter than the TTL");
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    await refresh(cfg, id, opts.ttl);
+    process.stderr.write(
+      style.green("executor heartbeat active") + style.dim(` \u2014 ${id}
+`)
+    );
+    await holdHeartbeat(async () => {
+      await refresh(cfg, id, opts.ttl);
+    }, opts.interval * 1e3);
+  });
+  executor.command("offers <id>").description("List live dispatch offers addressed to this exact instance").action(async (id, _opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const data = await api(
+      cfg,
+      `/me/executor-instances/${encodeURIComponent(id)}/dispatch-offers`
+    );
+    emit(data, Boolean(cmd.optsWithGlobals().json));
+  });
+  executor.command("deregister <id>").description("Stop advertising this executor instance").action(async (id, _opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const data = await api(
+      cfg,
+      `/me/executor-instances/${encodeURIComponent(id)}`,
+      {
+        method: "DELETE",
+        body: JSON.stringify({})
+      }
+    );
+    emit(data, Boolean(cmd.optsWithGlobals().json));
+  });
+}
+function parseRuntimeKind(value) {
+  switch (value.trim().toLowerCase()) {
+    case "claude":
+    case "claude-code":
+      return "ClaudeCode";
+    case "codex":
+      return "Codex";
+    default:
+      return fail("runtime must be claude-code or codex");
+  }
+}
+function parseTransport(value) {
+  switch (value.trim().toLowerCase()) {
+    case "push":
+      return "Push";
+    case "pull":
+      return "Pull";
+    default:
+      return fail("transport must be push or pull");
+  }
+}
+async function refresh(cfg, id, ttlSeconds) {
+  return api(
+    cfg,
+    `/me/executor-instances/${encodeURIComponent(id)}/refresh`,
+    {
+      method: "POST",
+      body: JSON.stringify({ ttlSeconds })
+    }
+  );
+}
+async function api(cfg, path, init) {
+  const token = await requireToken(cfg);
+  const response = await fetch(`${cfg.baseUrl}${path}`, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${token}`,
+      tenant: cfg.tenant,
+      "content-type": "application/json",
+      "x-sechroom-surface": "cli"
+    }
+  });
+  if (!response.ok)
+    fail(
+      `${init?.method ?? "GET"} ${path} failed (${response.status}): ${await response.text()}`
+    );
+  return response.json();
+}
+function parseInteger(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) fail(`expected an integer, got '${value}'`);
+  return parsed;
+}
+function holdHeartbeat(tick, intervalMs) {
+  return new Promise((resolve3, reject) => {
+    const timer = setInterval(() => void tick().catch(reject), intervalMs);
+    const stop = () => {
+      clearInterval(timer);
+      resolve3();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+}
+
 // src/commands/filing.ts
 function registerFiling(program2) {
   const filing = program2.command("filing").description("Review and act on filing suggestions");
@@ -5421,7 +5796,9 @@ function registerSkills(program2) {
     "after",
     `
 Examples:
-  $ sechroom skills install                 materialise your installed skills to ~/.claude/skills
+  $ sechroom skills install --client claude  materialise target:claude-code skills to ~/.claude/skills
+  $ sechroom skills install --client codex   materialise target:gpt-codex skills to ~/.codex/skills
+  $ sechroom skills install --client all     keep both global clients in sync
   $ sechroom skills install --scope project  write them to ./.claude/skills instead
   $ sechroom skills list                     what's materialised on disk
   $ sechroom skills clean                    remove the materialised skill files
@@ -5430,11 +5807,15 @@ Examples:
   $ sechroom skills package --from-source --workspace wsp_abc -o ./dist   zip a draft from source
   $ sechroom skills set-lane --code-lane claude-code-chris --design-lane claude-design-chris
 
+When --client is omitted, configured client flags/environment variables win;
+otherwise existing default client homes are detected. Both configured/detected
+clients select all; an unconfigured machine preserves the legacy Claude default.
+
 `
   );
-  skills.command("install").description("Materialise your installed skills to disk (the already-installed bundle \u2014 no server install)").option("--scope <scope>", "global (config dir / CLAUDE_CONFIG_DIR) or project (<cwd>/.claude) \u2014 default global").option("--local", "alias for --scope project").option("--dry-run", "print what would be written; write nothing").option("--json", "machine output").action((opts, cmd) => runInstall(SKILL_SPEC, cmd, opts));
-  skills.command("list").description("List the skills materialised on disk (per resolved config dir)").option("--scope <scope>", "global (config dir / CLAUDE_CONFIG_DIR) or project (<cwd>/.claude) \u2014 default global").option("--local", "alias for --scope project").option("--json", "machine output").action((opts, cmd) => runList(SKILL_SPEC, cmd, opts));
-  skills.command("clean [slug]").description(`Remove skill files materialised to disk (default ${DEFAULT_SKILLS_SLUG})`).option("--scope <scope>", "global (config dir / CLAUDE_CONFIG_DIR) or project (<cwd>/.claude) \u2014 default global").option("--local", "alias for --scope project").option("--json", "machine output").action((slugArg, opts, cmd) => runClean(SKILL_SPEC, cmd, opts, slugArg));
+  skills.command("install").description("Materialise your installed skills to disk (the already-installed bundle \u2014 no server install)").option("--scope <scope>", "global (config dir / CLAUDE_CONFIG_DIR) or project (<cwd>/.claude) \u2014 default global").option("--local", "alias for --scope project").option("--client <client>", "claude, codex, or all (default: configured/detected clients)").option("--dry-run", "print what would be written; write nothing").option("--json", "machine output").action((opts, cmd) => runInstall(SKILL_SPEC, cmd, opts));
+  skills.command("list").description("List the skills materialised on disk (per resolved config dir)").option("--scope <scope>", "global (config dir / CLAUDE_CONFIG_DIR) or project (<cwd>/.claude) \u2014 default global").option("--local", "alias for --scope project").option("--client <client>", "claude, codex, or all (default: configured/detected clients)").option("--json", "machine output").action((opts, cmd) => runList(SKILL_SPEC, cmd, opts));
+  skills.command("clean [slug]").description(`Remove skill files materialised to disk (default ${DEFAULT_SKILLS_SLUG})`).option("--scope <scope>", "global (config dir / CLAUDE_CONFIG_DIR) or project (<cwd>/.claude) \u2014 default global").option("--local", "alias for --scope project").option("--client <client>", "claude, codex, or all (default: configured/detected clients)").option("--json", "machine output").action((slugArg, opts, cmd) => runClean(SKILL_SPEC, cmd, opts, slugArg));
   skills.command("preview").description("Render a workspace's draft bundle from source (no publish/install) and report the components").requiredOption("--workspace <id>", "workspace holding the draft bundle sources (wsp_\u2026)").option("--slug <slug>", "override the derived bundle slug").option("--title <title>", "override the derived bundle title").option("--version <version>", "override the derived bundle version").option("--default-install-parent <path>", "override the derived default install parent").option("--json", "machine output (the full RenderBundlePreviewResponse)").action(async (opts, cmd) => {
     const json = Boolean(opts.json) || Boolean(cmd.optsWithGlobals().json);
     const client = await makeClient(resolveConfig(cmd.optsWithGlobals()));
@@ -5788,7 +6169,7 @@ function registerTelemetry(program2) {
       );
   });
   telemetry.command("hook").description(
-    "Per-turn telemetry self-report for a Claude Code Stop hook (reads stdin; no-op unless bound). Fail-soft."
+    "Per-turn telemetry self-report for Claude Code hooks \u2014 Stop/SubagentStop \u2192 parsed + terminal, Notification/PermissionDenied \u2192 approval (reads stdin; no-op unless bound). Fail-soft."
   ).action(async (_opts, cmd) => {
     try {
       const raw = await readStdin2();
@@ -5797,21 +6178,10 @@ function registerTelemetry(program2) {
       const binding = findBinding(cwd);
       if (!binding) return process.exit(0);
       const usage = input.transcript_path ? parseTranscript(input.transcript_path) : null;
-      if (!usage) return process.exit(0);
+      const events = buildHookEvents(input, usage, binding.taskId);
+      if (events.length === 0) return process.exit(0);
       const cfg = resolveConfig(cmd.optsWithGlobals());
-      await postTelemetry(cfg, binding.decompositionId, [
-        {
-          taskId: binding.taskId,
-          kind: "Parsed",
-          tokensIn: usage.tokensIn,
-          tokensOut: usage.tokensOut,
-          contextUsed: usage.contextUsed,
-          contextWindow: usage.contextWindow,
-          text: null,
-          approvalState: null,
-          verdict: null
-        }
-      ]);
+      await postTelemetry(cfg, binding.decompositionId, events);
       return process.exit(0);
     } catch {
       return process.exit(0);
@@ -5839,7 +6209,12 @@ function registerTelemetry(program2) {
       scope,
       cwd
     });
-    const commands = { Stop: "sechroom telemetry hook" };
+    const commands = {
+      Stop: "sechroom telemetry hook",
+      SubagentStop: "sechroom telemetry hook",
+      Notification: "sechroom telemetry hook",
+      PermissionDenied: "sechroom telemetry hook"
+    };
     try {
       const multi = targets.length > 1;
       const results = targets.map((t) => {
@@ -5940,6 +6315,55 @@ function windowFor(model, contextUsed = 0) {
   if (m.includes("[1m]") || m.includes("-1m")) return 1e6;
   return contextUsed > 2e5 ? 1e6 : 2e5;
 }
+function buildHookEvents(input, usage, taskId) {
+  const events = [];
+  const base = (kind, over) => ({
+    taskId,
+    kind,
+    tokensIn: null,
+    tokensOut: null,
+    contextUsed: null,
+    contextWindow: null,
+    text: null,
+    approvalState: null,
+    verdict: null,
+    ...over
+  });
+  if (usage) {
+    events.push(
+      base("Parsed", {
+        tokensIn: usage.tokensIn,
+        tokensOut: usage.tokensOut,
+        contextUsed: usage.contextUsed,
+        contextWindow: usage.contextWindow
+      })
+    );
+  }
+  switch (input.hook_event_name) {
+    case "PermissionDenied":
+      events.push(
+        base("Approval", {
+          approvalState: "denied",
+          text: input.tool_name ?? input.message ?? null
+        })
+      );
+      break;
+    case "Notification":
+      if (isPermissionNotification(input))
+        events.push(base("Approval", { text: input.message ?? null }));
+      break;
+    case "Stop":
+    case "SubagentStop":
+      events.push(base("Terminal", { text: input.last_assistant_message ?? null }));
+      break;
+  }
+  return events;
+}
+function isPermissionNotification(input) {
+  const t = (input.notification_type ?? input.type ?? "").toLowerCase();
+  if (t) return t.includes("permission");
+  return (input.message ?? "").toLowerCase().includes("permission");
+}
 async function readStdin2() {
   if (process.stdin.isTTY) return "";
   const chunks = [];
@@ -6333,6 +6757,7 @@ registerRelationships(program);
 registerWorkspace(program);
 registerProject(program);
 registerDecomposition(program);
+registerExecutor(program);
 registerClose(program);
 registerFiling(program);
 registerContinuity(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sechroom/cli",
-  "version": "2026.7.12",
+  "version": "2026.7.14",
   "description": "Sechroom CLI — a thin, generated client over the Sechroom HTTP API. An agent/human surface alongside MCP.",
   "type": "module",
   "license": "UNLICENSED",
@@ -36,12 +36,14 @@
     "openapi-typescript": "^7.4.0",
     "tsup": "^8.3.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "typescript-7": "npm:typescript@^7.0.2"
   },
   "scripts": {
     "gen": "openapi-typescript \"${SECHROOM_OPENAPI_URL:-https://app.sechroom.ai/api/openapi/v1.json}\" -o src/generated/api.d.ts",
     "build": "tsup src/index.ts --format esm --target node20 --clean",
     "dev": "tsx src/index.ts",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
     "check-types": "tsc --noEmit"
   }
 }