@sechroom/cli 2026.7.7-rc.56782977 → 2026.7.8-rc.4b6e8ecc

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync12 } from "fs";
+import { readFileSync as readFileSync13 } from "fs";
 import { Command } from "commander";
 
 // src/auth.ts
@@ -657,9 +657,14 @@ async function runApi(label, fn) {
   s.succeed();
   return res.data;
 }
-function fail(error) {
+function formatFailureMessage(error) {
   let msg;
-  if (typeof error === "object" && error !== null && "title" in error) {
+  if (error instanceof Error) {
+    msg = error.message || error.name;
+    if (error.cause instanceof Error && error.cause.message) {
+      msg += `: ${error.cause.message}`;
+    }
+  } else if (typeof error === "object" && error !== null && "title" in error) {
     const problem = error;
     msg = String(problem.title);
     if (problem.errors && typeof problem.errors === "object") {
@@ -674,6 +679,10 @@ ${detail.join("\n")}`;
   } else {
     msg = String(error);
   }
+  return msg;
+}
+function fail(error) {
+  const msg = formatFailureMessage(error);
   process.stderr.write(`error: ${msg}
 `);
   process.exit(1);
@@ -1140,7 +1149,10 @@ function resolveReferences(systemRows, personalRows, surface) {
 }
 
 // src/setup/skill-resolution-io.ts
-var AGENT_TARGET = { "claude-code": "claude-agent" };
+var AGENT_TARGET = {
+  "claude-code": "claude-agent",
+  "gpt-codex": "gpt-codex-agent"
+};
 function agentTargetFor(surface) {
   return AGENT_TARGET[surface] ?? `${surface}-agent`;
 }
@@ -1205,12 +1217,58 @@ function writeSkills(dir, skills, surface) {
   if (written.length) recordMaterialisedSkills(dir, DEFAULT_SKILLS_SLUG, written, { surface });
   return written;
 }
+function splitAgentFrontmatter(body) {
+  body = body.replaceAll("\r\n", "\n");
+  if (!body.startsWith("---\n")) return { instructions: body };
+  const end = body.indexOf("\n---\n", 4);
+  if (end < 0) return { instructions: body };
+  const frontmatter = body.slice(4, end);
+  const field = (key) => {
+    const line = frontmatter.split("\n").find((candidate) => candidate.startsWith(`${key}:`));
+    return line?.slice(key.length + 1).trim().replace(/^(["'])(.*)\1$/, "$2");
+  };
+  return { name: field("name"), description: field("description"), instructions: body.slice(end + 5).trimStart() };
+}
+function validateCodexSkills(skills) {
+  for (const skill of skills) {
+    const parsed = splitAgentFrontmatter(skill.body);
+    if (parsed.name !== skill.name || !parsed.description) {
+      throw new Error(
+        `Codex skill '${skill.name}' must begin with YAML frontmatter containing matching name and a description.`
+      );
+    }
+  }
+}
+var WORKER_NAMES = ["substrate-drafter", "substrate-miner", "substrate-verifier"];
+function validateCodexWorkerDependencies(skills, agents) {
+  const available = new Set(agents.map((agent) => agent.name));
+  const missing = WORKER_NAMES.filter(
+    (worker) => skills.some((skill) => skill.body.includes(worker)) && !available.has(worker)
+  );
+  if (missing.length) {
+    throw new Error(`Codex skills reference missing agent template(s): ${missing.join(", ")}.`);
+  }
+}
+function codexAgentToml(agent) {
+  const parsed = splitAgentFrontmatter(agent.body);
+  if (!parsed.description) {
+    throw new Error(`Codex agent '${agent.name}' requires a description in its leading YAML frontmatter.`);
+  }
+  return [
+    `name = ${JSON.stringify(parsed.name || agent.name)}`,
+    `description = ${JSON.stringify(parsed.description)}`,
+    `developer_instructions = ${JSON.stringify(parsed.instructions.trimEnd())}`,
+    ""
+  ].join("\n");
+}
 function writeAgents(dir, agents, surface) {
   if (agents.length) mkdirSync3(dir, { recursive: true });
   const written = [];
   for (const a of agents) {
-    const file = `${a.name}.md`;
-    writeFileSync3(join4(dir, file), a.body.endsWith("\n") ? a.body : a.body + "\n");
+    const codex = surface === CLIENT_SURFACE.codex;
+    const file = `${a.name}.${codex ? "toml" : "md"}`;
+    const body = codex ? codexAgentToml(a) : a.body.endsWith("\n") ? a.body : a.body + "\n";
+    writeFileSync3(join4(dir, file), body);
     written.push(file);
   }
   if (written.length) recordMaterialisedSkills(dir, DEFAULT_SKILLS_SLUG, written, { surface });
@@ -1239,7 +1297,7 @@ var AGENT_SPEC = {
   dir: agentsDir,
   resolve: resolveAgentSet,
   write: writeAgents,
-  supportsCodex: false
+  supportsCodex: true
 };
 function scopeOf(opts) {
   return opts.local ? "project" : resolveScope(opts.scope);
@@ -1315,6 +1373,10 @@ async function runInstall(spec, cmd, opts) {
   const rows = await fetchTemplateRows(cfg, personalWorkspaceId);
   const results = targets.map((t) => {
     const items = spec.resolve(rows, t.surface);
+    if (t.client === "codex" && spec.kind === "skill") {
+      validateCodexSkills(items);
+      validateCodexWorkerDependencies(items, resolveAgentSet(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);
@@ -1440,17 +1502,19 @@ function registerAgents(program2) {
     `
 Examples:
   $ sechroom agents install                 materialise your installed agents to ~/.claude/agents
+	$ sechroom agents install --client codex  materialise native TOML agents to ~/.codex/agents
   $ sechroom agents install --scope project  write them to ./.claude/agents instead
   $ sechroom agents install --claude-config-dir ~/.claude-work   target another instance
   $ sechroom agents list                     what's materialised on disk
   $ sechroom agents clean                    remove the materialised agent files
 
-Agents are resolved from the agent target (target:claude-agent), the dispatchable
-workers your loop skills call (e.g. find-prior-art \u2192 substrate-miner).`
+Agents are resolved from the client's agent target (target:claude-agent or
+target:gpt-codex-agent), the dispatchable workers your loop skills call
+(e.g. find-prior-art \u2192 substrate-miner).`
   );
-  agents.command("install").description("Materialise your installed subagents 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(AGENT_SPEC, cmd, opts));
-  agents.command("list").description("List the subagents 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(AGENT_SPEC, cmd, opts));
-  agents.command("clean [slug]").description(`Remove subagent 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(AGENT_SPEC, cmd, opts, slugArg));
+  agents.command("install").description("Materialise your installed subagents 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("--client <client>", "claude, codex, or all").option("--json", "machine output").action((opts, cmd) => runInstall(AGENT_SPEC, cmd, opts));
+  agents.command("list").description("List the subagents 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").option("--client <client>", "claude, codex, or all").action((opts, cmd) => runList(AGENT_SPEC, cmd, opts));
+  agents.command("clean [slug]").description(`Remove subagent 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").option("--client <client>", "claude, codex, or all").action((slugArg, opts, cmd) => runClean(AGENT_SPEC, cmd, opts, slugArg));
 }
 
 // src/commands/channel.ts
@@ -1595,6 +1659,12 @@ function installHooksJson(path, commands, dryRun) {
 function installClaudeCommands(claudeDir, commands, dryRun) {
   return installHooksJson(join6(claudeDir, "settings.json"), commands, dryRun);
 }
+function installCodexCommands(codexHome, commands, dryRun) {
+  return [
+    installHooksJson(join6(codexHome, "hooks.json"), commands, dryRun),
+    installCodexFeatureFlag(join6(codexHome, "config.toml"), dryRun)
+  ];
+}
 function ensureCodexFeaturesHooks(content) {
   const lines = content.split("\n");
   const headerIdx = lines.findIndex((l) => l.trim() === "[features]");
@@ -1697,7 +1767,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"
@@ -1715,7 +1788,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(
@@ -1764,7 +1837,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(
@@ -1875,8 +1948,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();
@@ -3136,6 +3210,340 @@ Examples:
   });
 }
 
+// src/commands/executor.ts
+import { dirname as dirname8, join as join11 } from "path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync9, readFileSync as readFileSync8, writeFileSync as writeFileSync9 } from "fs";
+var EXECUTOR_STATE = "executor.json";
+var EXECUTOR_PULSE_COMMAND = "sechroom executor hook-pulse";
+var EXECUTOR_STOP_COMMAND = "sechroom executor hook-stop";
+var CLAUDE_EXECUTOR_HOOKS = {
+  SessionStart: EXECUTOR_PULSE_COMMAND,
+  UserPromptSubmit: EXECUTOR_PULSE_COMMAND,
+  PreToolUse: EXECUTOR_PULSE_COMMAND,
+  Stop: EXECUTOR_PULSE_COMMAND,
+  SessionEnd: EXECUTOR_STOP_COMMAND
+};
+var CODEX_EXECUTOR_HOOKS = {
+  SessionStart: EXECUTOR_PULSE_COMMAND,
+  UserPromptSubmit: EXECUTOR_PULSE_COMMAND,
+  PreToolUse: EXECUTOR_PULSE_COMMAND,
+  Stop: EXECUTOR_PULSE_COMMAND
+};
+function registerExecutor(program2) {
+  const executor = program2.command("executor").description(
+    "Register and operate a local Claude Code/Codex executor advertisement"
+  );
+  executor.command("install").description("Configure this checkout's harness to advertise itself as a WLP executor").option("--connector <id>", "Approved local-session ConnectorDefinition id").option("--instance-key <key>", "Stable executor identity (defaults to .sechroom/lane.json code-lane)").option("--runtime <kind>", "claude-code | codex").option("--surface <surface>", "claude | codex").option("--capability <key...>", "Capability operation keys claimed by this instance").option("--relay <id>", "Relay identity shared by sibling instances", "sechroom-cli-local").option("--subscription-name <name>", "SignalR delivery binding name", "executor-dispatch").option("--ttl <seconds>", "Advertisement TTL (30-600)", parseInteger, 600).option("--refresh-after <seconds>", "Minimum age before a hook refreshes", parseInteger, 40).option("-y, --yes", "Non-interactive: accept detected surface and lane defaults", false).option("--dry-run", "Show hook files without writing", false).action(async (opts, cmd) => {
+    const globals = cmd.optsWithGlobals();
+    const lane = readSem()?.values["code-lane"];
+    const detected = detectHookSurfaces(process.cwd());
+    let surface = opts.surface;
+    let instanceKey = opts.instanceKey;
+    let runtime = opts.runtime;
+    let connector = opts.connector;
+    let capabilities = opts.capability;
+    const surfaceDefault = detected.length === 1 ? detected[0] : lane?.includes("codex") ? "codex" : "claude";
+    if (!opts.yes && canPrompt()) {
+      surface = await promptText("Harness surface (claude or codex)?", surface ?? surfaceDefault);
+      instanceKey = await promptText("Executor instance key?", instanceKey ?? lane ?? "");
+      runtime = await promptText("Runtime (claude-code or codex)?", runtime ?? (surface === "codex" ? "codex" : "claude-code"));
+      connector = await promptText("Approved local-session connector id?", connector ?? "");
+      const capabilityText = await promptText("Capability keys (comma-separated; blank for none)?", capabilities?.join(",") ?? "");
+      capabilities = capabilityText.split(",").map((x) => x.trim()).filter(Boolean);
+    }
+    surface ??= surfaceDefault;
+    instanceKey ??= lane;
+    runtime ??= surface === "codex" ? "codex" : "claude-code";
+    if (!connector) fail("executor install requires --connector (or an interactive connector id)");
+    if (!instanceKey) fail("no instance key resolved; pass --instance-key or pin .sechroom/lane.json code-lane");
+    if (!opts.yes && !canPrompt()) fail("non-interactive executor install requires --yes");
+    parseRuntimeKind(runtime);
+    if (!["claude", "codex"].includes(surface)) fail("surface must be claude or codex");
+    if (opts.refreshAfter >= opts.ttl) fail("refresh-after must be shorter than the TTL");
+    const sem = readSem();
+    const checkout = sem ? dirname8(dirname8(sem.path)) : process.cwd();
+    const statePath = join11(checkout, ".sechroom", EXECUTOR_STATE);
+    const state = {
+      schemaVersion: 1,
+      instanceKey,
+      runtime: runtime.toLowerCase() === "codex" ? "codex" : "claude-code",
+      connectorId: connector,
+      capabilityKeys: capabilities ?? [],
+      relayId: opts.relay,
+      subscriptionName: opts.subscriptionName,
+      ttlSeconds: opts.ttl,
+      refreshAfterSeconds: opts.refreshAfter
+    };
+    if (!opts.dryRun) {
+      mkdirSync9(dirname8(statePath), { recursive: true });
+      writeFileSync9(statePath, JSON.stringify(state, null, 2) + "\n");
+      ensureStateDirIgnored(checkout);
+    }
+    const configuredClaudeDirs = globals.claudeConfigDir || process.env.CLAUDE_CONFIG_DIR ? resolveClaudeTargets({ override: globals.claudeConfigDir }).map((target) => target.dir) : [join11(checkout, ".claude")];
+    const configuredCodexHomes = globals.codexHome || process.env.CODEX_HOME ? resolveCodexHomes({ override: globals.codexHome }) : [join11(checkout, ".codex")];
+    const hookTargets = surface === "claude" ? configuredClaudeDirs : configuredCodexHomes;
+    for (const target of hookTargets) {
+      const results = surface === "claude" ? [installClaudeCommands(target, CLAUDE_EXECUTOR_HOOKS, opts.dryRun)] : installCodexCommands(target, CODEX_EXECUTOR_HOOKS, opts.dryRun);
+      for (const result of results) process.stderr.write(describe(result, opts.dryRun) + "\n");
+    }
+    warnIfSechroomNotOnPath();
+    process.stderr.write(style.green("executor harness configured") + style.dim(` \u2014 ${instanceKey}
+`));
+  });
+  executor.command("hook-pulse").description("Hook adapter: register or refresh this checkout's executor").action(async (_opts, cmd) => {
+    await drainStdin();
+    const located = readExecutorState();
+    if (!located) return;
+    const { state, path } = located;
+    const age = state.lastRefreshAt ? Date.now() - Date.parse(state.lastRefreshAt) : Number.POSITIVE_INFINITY;
+    if (state.instanceId && age < state.refreshAfterSeconds * 1e3) return;
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    try {
+      let data;
+      if (state.instanceId) {
+        try {
+          data = await refresh(cfg, state.instanceId, state.ttlSeconds);
+        } catch {
+          data = await registerInstance(cfg, state);
+        }
+      } else {
+        data = await registerInstance(cfg, state);
+      }
+      state.instanceId = data.id;
+      state.lastRefreshAt = (/* @__PURE__ */ new Date()).toISOString();
+      writeFileSync9(path, JSON.stringify(state, null, 2) + "\n");
+    } catch {
+    }
+  });
+  executor.command("hook-stop").description("Hook adapter: deregister this checkout's executor").action(async (_opts, cmd) => {
+    await drainStdin();
+    const located = readExecutorState();
+    if (!located?.state.instanceId) return;
+    try {
+      await api(resolveConfig(cmd.optsWithGlobals()), `/me/executor-instances/${encodeURIComponent(located.state.instanceId)}`, { method: "DELETE", body: JSON.stringify({}) });
+      delete located.state.instanceId;
+      delete located.state.lastRefreshAt;
+      writeFileSync9(located.path, JSON.stringify(located.state, null, 2) + "\n");
+    } catch {
+    }
+  });
+  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 registerInstance(cfg, state) {
+  if (!cfg.workspaceId) fail("executor registration requires a configured workspaceId");
+  const subscription = await api(cfg, "/me/delivery-subscriptions/signalr", {
+    method: "POST",
+    body: JSON.stringify({ name: state.subscriptionName, enabled: true, filter: { tags: ["kind:task"], workspaceScope: [cfg.workspaceId] } })
+  });
+  return api(cfg, "/me/executor-instances", {
+    method: "POST",
+    body: JSON.stringify({ relayId: state.relayId, instanceKey: state.instanceKey, runtimeKind: parseRuntimeKind(state.runtime), activationMode: "Attached", deliverySubscriptionId: subscription.id, connectorId: state.connectorId, claimedCapabilityKeys: state.capabilityKeys, toolSetRef: null, ttlSeconds: state.ttlSeconds })
+  });
+}
+function readExecutorState(start = process.cwd()) {
+  const semPath = resolveSemPathForRead(start);
+  const sem = semPath ? readSem(semPath) : void 0;
+  const path = join11(sem ? dirname8(sem.path) : join11(start, ".sechroom"), EXECUTOR_STATE);
+  if (!existsSync9(path)) return void 0;
+  return { state: JSON.parse(readFileSync8(path, "utf8")), path };
+}
+async function drainStdin() {
+  if (process.stdin.isTTY) return;
+  for await (const _chunk of process.stdin) {
+  }
+}
+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");
@@ -3647,8 +4055,8 @@ Examples:
 
 // src/setup/apply.ts
 import { createHash as createHash3 } from "crypto";
-import { mkdirSync as mkdirSync9, readFileSync as readFileSync8, writeFileSync as writeFileSync9, existsSync as existsSync9 } from "fs";
-import { dirname as dirname8 } from "path";
+import { mkdirSync as mkdirSync10, readFileSync as readFileSync9, writeFileSync as writeFileSync10, existsSync as existsSync10 } from "fs";
+import { dirname as dirname9 } from "path";
 var MARKER_BEGIN = "<!-- @sechroom/cli:begin";
 var MARKER_END = "<!-- @sechroom/cli:end";
 function normalizeBody(s) {
@@ -3701,22 +4109,22 @@ function parseManagedBlock(content, block) {
   return null;
 }
 function ensureDir2(path) {
-  mkdirSync9(dirname8(path), { recursive: true });
+  mkdirSync10(dirname9(path), { recursive: true });
 }
 function readOr(path, fallback) {
   try {
-    return readFileSync8(path, "utf8");
+    return readFileSync9(path, "utf8");
   } catch {
     return fallback;
   }
 }
 function mergeMcpJson(path, snippet, dryRun) {
   const incoming = JSON.parse(snippet);
-  const existed = existsSync9(path);
+  const existed = existsSync10(path);
   let current = {};
   if (existed) {
     try {
-      current = JSON.parse(readFileSync8(path, "utf8"));
+      current = JSON.parse(readFileSync9(path, "utf8"));
     } catch {
       return { kind: "mcp", path, status: "skipped", note: "existing file isn't valid JSON \u2014 left untouched" };
     }
@@ -3724,26 +4132,26 @@ function mergeMcpJson(path, snippet, dryRun) {
   current.mcpServers = { ...current.mcpServers ?? {}, ...incoming.mcpServers ?? {} };
   if (dryRun) return { kind: "mcp", path, status: "dry-run" };
   ensureDir2(path);
-  writeFileSync9(path, JSON.stringify(current, null, 2) + "\n", { mode: 384 });
+  writeFileSync10(path, JSON.stringify(current, null, 2) + "\n", { mode: 384 });
   return { kind: "mcp", path, status: existed ? "merged" : "created" };
 }
 function mergeCodexToml(path, snippet, dryRun) {
-  const existed = existsSync9(path);
+  const existed = existsSync10(path);
   let body = readOr(path, "");
   body = body.replace(/(^|\n)\[mcp_servers\.sechroom\][^[]*/, "\n").replace(/\n{3,}/g, "\n\n");
   const trimmed = body.trim();
   const next = (trimmed.length > 0 ? trimmed + "\n\n" : "") + snippet.trim() + "\n";
   if (dryRun) return { kind: "mcp", path, status: "dry-run" };
   ensureDir2(path);
-  writeFileSync9(path, next, { mode: 384 });
+  writeFileSync10(path, next, { mode: 384 });
   return { kind: "mcp", path, status: existed ? "merged" : "created" };
 }
 function writeInstructionBlock(path, write, dryRun) {
-  const existed = existsSync9(path);
+  const existed = existsSync10(path);
   const next = computeBlockFile(readOr(path, ""), write);
   if (dryRun) return { kind: "instruction", path, status: "dry-run" };
   ensureDir2(path);
-  writeFileSync9(path, next);
+  writeFileSync10(path, next);
   return { kind: "instruction", path, status: existed ? "merged" : "created" };
 }
 function computeBlockFile(current, write) {
@@ -3784,7 +4192,7 @@ function applyBlock(path, write, mode, dryRun) {
     const next = computeBlockFile(current, write);
     if (!dryRun) {
       ensureDir2(proposedPath);
-      writeFileSync9(proposedPath, next);
+      writeFileSync10(proposedPath, next);
     }
     return {
       kind: "instruction",
@@ -3914,8 +4322,8 @@ auto-resumes where you left off and checkpoints working state before compacting.
 }
 
 // src/setup/skills-offer.ts
-import { mkdirSync as mkdirSync10, writeFileSync as writeFileSync10 } from "fs";
-import { join as join11 } from "path";
+import { mkdirSync as mkdirSync11, writeFileSync as writeFileSync11 } from "fs";
+import { join as join12 } from "path";
 
 // src/setup/lane-pin.ts
 var CODE_LANE_PREFIX_BY_CLIENT = {
@@ -4031,8 +4439,8 @@ Found ${summary} available to you for ${surface}.
   if (skills.length > 0) {
     const written = [];
     for (const s of skills) {
-      mkdirSync10(join11(sDir, s.name), { recursive: true });
-      writeFileSync10(join11(sDir, s.name, "SKILL.md"), s.body.endsWith("\n") ? s.body : s.body + "\n");
+      mkdirSync11(join12(sDir, s.name), { recursive: true });
+      writeFileSync11(join12(sDir, s.name, "SKILL.md"), s.body.endsWith("\n") ? s.body : s.body + "\n");
       written.push(s.name);
     }
     recordMaterialisedSkills(sDir, DEFAULT_SKILLS_SLUG, written, { surface });
@@ -4040,11 +4448,11 @@ Found ${summary} available to you for ${surface}.
 `);
   }
   if (agents.length > 0) {
-    mkdirSync10(aDir, { recursive: true });
+    mkdirSync11(aDir, { recursive: true });
     const written = [];
     for (const a of agents) {
       const file = `${a.name}.md`;
-      writeFileSync10(join11(aDir, file), a.body.endsWith("\n") ? a.body : a.body + "\n");
+      writeFileSync11(join12(aDir, file), a.body.endsWith("\n") ? a.body : a.body + "\n");
       written.push(file);
     }
     recordMaterialisedSkills(aDir, DEFAULT_SKILLS_SLUG, written, { surface });
@@ -4427,13 +4835,13 @@ Wired to namespace '${slug}'. Restart your AI client (or reload MCP) to pick it
 }
 
 // src/commands/onboard.ts
-import { existsSync as existsSync11 } from "fs";
-import { basename as basename2, join as join13 } from "path";
+import { existsSync as existsSync12 } from "fs";
+import { basename as basename2, join as join14 } from "path";
 
 // src/commands/fanout.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync10, readFileSync as readFileSync9, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
-import { isAbsolute, join as join12, resolve } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync10, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
+import { isAbsolute, join as join13, resolve } from "path";
 var ICON = {
   refresh: "\u21BB",
   bind: "+",
@@ -4453,21 +4861,21 @@ function discoverChildren(root) {
   const out = [];
   for (const name of names.sort()) {
     if (name.startsWith(".") || name === "node_modules") continue;
-    const dir = join12(root, name);
+    const dir = join13(root, name);
     try {
       if (!statSync3(dir).isDirectory()) continue;
     } catch {
       continue;
     }
-    if (existsSync10(join12(dir, ".git")) || committedBindingPath(dir)) out.push(name);
+    if (existsSync11(join13(dir, ".git")) || committedBindingPath(dir)) out.push(name);
   }
   return out;
 }
 function readManifest(path) {
-  if (!existsSync10(path)) return null;
+  if (!existsSync11(path)) return null;
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync9(path, "utf8"));
+    parsed = JSON.parse(readFileSync10(path, "utf8"));
   } catch (err2) {
     throw new Error(`couldn't parse ${path}: ${err2 instanceof Error ? err2.message : String(err2)}`);
   }
@@ -4833,10 +5241,10 @@ async function chooseScope(scopeFlag, yes) {
 }
 async function planRecurseChild(entry, root, client, opts) {
   const dir = resolveChildDir(entry.path, root);
-  if (!existsSync11(dir)) {
+  if (!existsSync12(dir)) {
     return { label: entry.path, dir, disposition: "skip-missing", argv: [], reason: "directory does not exist" };
   }
-  if (existsSync11(join13(dir, ".sechroom.json"))) {
+  if (existsSync12(join14(dir, ".sechroom.json"))) {
     return {
       label: entry.path,
       dir,
@@ -4909,7 +5317,7 @@ This fan-out will pin the same lane in every repo:
 async function runRecurse(cfg, g, opts) {
   const { yes, dryRun, json } = opts;
   const root = process.cwd();
-  const manifestPath = join13(root, ".sechroom", "repos.json");
+  const manifestPath = join14(root, ".sechroom", "repos.json");
   const fromManifest = readManifest(manifestPath);
   const entries = fromManifest ?? discoverChildren(root).map((path) => ({ path }));
   const sourceLabel = fromManifest ? `manifest ${manifestPath}` : `auto-discovered under ${root}`;
@@ -5442,23 +5850,23 @@ Examples:
 
 // src/commands/reset.ts
 import { homedir as homedir4 } from "os";
-import { join as join14 } from "path";
-import { existsSync as existsSync12, readFileSync as readFileSync10, rmSync as rmSync3 } from "fs";
+import { join as join15 } from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync11, rmSync as rmSync3 } from "fs";
 var SKILLS_LOCK2 = ".sechroom-skills.json";
-var localSkillsDir = () => join14(process.cwd(), ".claude", "skills");
-var globalSkillsDir = () => join14(homedir4(), ".claude", "skills");
-var localAgentsDir = () => join14(process.cwd(), ".claude", "agents");
-var globalAgentsDir = () => join14(homedir4(), ".claude", "agents");
+var localSkillsDir = () => join15(process.cwd(), ".claude", "skills");
+var globalSkillsDir = () => join15(homedir4(), ".claude", "skills");
+var localAgentsDir = () => join15(process.cwd(), ".claude", "agents");
+var globalAgentsDir = () => join15(homedir4(), ".claude", "agents");
 function removeMaterialisedSkills(dir) {
   const removed = [];
-  const lockPath = join14(dir, SKILLS_LOCK2);
-  if (!existsSync12(lockPath)) return removed;
+  const lockPath = join15(dir, SKILLS_LOCK2);
+  if (!existsSync13(lockPath)) return removed;
   try {
-    const lock = JSON.parse(readFileSync10(lockPath, "utf8"));
+    const lock = JSON.parse(readFileSync11(lockPath, "utf8"));
     for (const entry of Object.values(lock)) {
       for (const name of entry.skills ?? []) {
-        const p = join14(dir, name);
-        if (existsSync12(p)) {
+        const p = join15(dir, name);
+        if (existsSync13(p)) {
           rmSync3(p, { recursive: true, force: true });
           removed.push(p);
         }
@@ -5503,18 +5911,18 @@ function registerReset(program2) {
       }
     }
     const removed = [];
-    const stateDir = join14(process.cwd(), ".sechroom");
-    if (existsSync12(stateDir)) {
+    const stateDir = join15(process.cwd(), ".sechroom");
+    if (existsSync13(stateDir)) {
       rmSync3(stateDir, { recursive: true, force: true });
       removed.push(stateDir);
     }
-    const legacyCfg = join14(process.cwd(), ".sechroom.json");
-    if (existsSync12(legacyCfg)) {
+    const legacyCfg = join15(process.cwd(), ".sechroom.json");
+    if (existsSync13(legacyCfg)) {
       rmSync3(legacyCfg, { force: true });
       removed.push(legacyCfg);
     }
-    const legacySem = join14(process.cwd(), ".sem");
-    if (existsSync12(legacySem)) {
+    const legacySem = join15(process.cwd(), ".sem");
+    if (existsSync13(legacySem)) {
       rmSync3(legacySem, { force: true });
       removed.push(legacySem);
     }
@@ -5540,8 +5948,8 @@ function registerReset(program2) {
 }
 
 // src/commands/skills.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync11, statSync as statSync4, writeFileSync as writeFileSync11 } from "fs";
-import { join as join15 } from "path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync12, statSync as statSync4, writeFileSync as writeFileSync12 } from "fs";
+import { join as join16 } from "path";
 function filenameFromDisposition(header) {
   if (!header) return void 0;
   const m = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(header);
@@ -5549,11 +5957,11 @@ function filenameFromDisposition(header) {
 }
 function resolveOutputPath(output, serverFilename) {
   const filename = serverFilename || "skills.zip";
-  if (!output) return join15(process.cwd(), filename);
-  const looksLikeDir = output.endsWith("/") || existsSync13(output) && statSync4(output).isDirectory();
+  if (!output) return join16(process.cwd(), filename);
+  const looksLikeDir = output.endsWith("/") || existsSync14(output) && statSync4(output).isDirectory();
   if (looksLikeDir) {
-    mkdirSync11(output, { recursive: true });
-    return join15(output, filename);
+    mkdirSync12(output, { recursive: true });
+    return join16(output, filename);
   }
   return output;
 }
@@ -5584,7 +5992,7 @@ async function downloadZip(label, call, output) {
   const buf = Buffer.from(res.data);
   const filename = filenameFromDisposition(res.response.headers.get("content-disposition")) ?? "skills.zip";
   const path = resolveOutputPath(output, filename);
-  writeFileSync11(path, buf);
+  writeFileSync12(path, buf);
   return { path, bytes: buf.length, filename };
 }
 function registerSkills(program2) {
@@ -5758,12 +6166,12 @@ clients select all; an unconfigured machine preserves the legacy Claude default.
 }
 
 // src/commands/sweep.ts
-import { existsSync as existsSync14 } from "fs";
-import { dirname as dirname9, join as join16, resolve as resolve2 } from "path";
-var DEFAULT_MANIFEST = join16(".sechroom", "repos.json");
+import { existsSync as existsSync15 } from "fs";
+import { dirname as dirname10, join as join17, resolve as resolve2 } from "path";
+var DEFAULT_MANIFEST = join17(".sechroom", "repos.json");
 function planEntry(entry, root) {
   const dir = resolveChildDir(entry.path, root);
-  if (!existsSync14(dir)) {
+  if (!existsSync15(dir)) {
     return { label: entry.path, dir, disposition: "skip-missing", argv: [], reason: "directory does not exist" };
   }
   if (committedBindingPath(dir)) {
@@ -5839,7 +6247,7 @@ Examples:
 `);
       return;
     }
-    const root = dirname9(dirname9(manifestPath));
+    const root = dirname10(dirname10(manifestPath));
     const plans = repos.map((entry) => planEntry(entry, root));
     if (!json) {
       process.stderr.write(
@@ -5858,13 +6266,13 @@ Examples:
 
 // src/commands/telemetry.ts
 import {
-  existsSync as existsSync15,
-  mkdirSync as mkdirSync12,
-  readFileSync as readFileSync11,
+  existsSync as existsSync16,
+  mkdirSync as mkdirSync13,
+  readFileSync as readFileSync12,
   rmSync as rmSync4,
-  writeFileSync as writeFileSync12
+  writeFileSync as writeFileSync13
 } from "fs";
-import { dirname as dirname10, join as join17 } from "path";
+import { dirname as dirname11, join as join18 } from "path";
 function registerTelemetry(program2) {
   const telemetry = program2.command("telemetry").description(
     "Emit WLP run telemetry (an executor leg's progress events) into a decomposition run"
@@ -5934,14 +6342,14 @@ function registerTelemetry(program2) {
     "Decomposition id this session executes"
   ).requiredOption("--task <id>", "Task id this session executes").action((opts, cmd) => {
     const json = Boolean(cmd.optsWithGlobals().json);
-    const dir = join17(process.cwd(), ".sechroom");
-    mkdirSync12(dir, { recursive: true });
-    const path = join17(dir, BINDING_FILE);
+    const dir = join18(process.cwd(), ".sechroom");
+    mkdirSync13(dir, { recursive: true });
+    const path = join18(dir, BINDING_FILE);
     const binding = {
       decompositionId: opts.decomposition,
       taskId: opts.task
     };
-    writeFileSync12(path, JSON.stringify(binding, null, 2) + "\n");
+    writeFileSync13(path, JSON.stringify(binding, null, 2) + "\n");
     ensureStateDirIgnored(process.cwd());
     if (json) {
       emit({ bound: true, ...binding, path }, true);
@@ -5956,8 +6364,8 @@ function registerTelemetry(program2) {
   });
   telemetry.command("unbind").description("Clear this checkout's telemetry binding").action((_opts, cmd) => {
     const json = Boolean(cmd.optsWithGlobals().json);
-    const path = join17(process.cwd(), ".sechroom", BINDING_FILE);
-    const existed = existsSync15(path);
+    const path = join18(process.cwd(), ".sechroom", BINDING_FILE);
+    const existed = existsSync16(path);
     if (existed) rmSync4(path);
     if (json) emit({ unbound: existed, path }, true);
     else
@@ -6065,11 +6473,11 @@ async function postTelemetry(cfg, decompositionId, events) {
 function findBinding(start) {
   let dir = start;
   for (; ; ) {
-    const path = join17(dir, ".sechroom", BINDING_FILE);
-    if (existsSync15(path)) {
+    const path = join18(dir, ".sechroom", BINDING_FILE);
+    if (existsSync16(path)) {
       try {
         const b = JSON.parse(
-          readFileSync11(path, "utf8")
+          readFileSync12(path, "utf8")
         );
         if (b.decompositionId && b.taskId)
           return { decompositionId: b.decompositionId, taskId: b.taskId };
@@ -6077,18 +6485,18 @@ function findBinding(start) {
       }
       return null;
     }
-    const parent = dirname10(dir);
+    const parent = dirname11(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
 function parseTranscript(path) {
-  if (!existsSync15(path)) return null;
+  if (!existsSync16(path)) return null;
   let tokensIn = 0;
   let tokensOut = 0;
   let contextUsed = 0;
   let model = "";
-  for (const line of readFileSync11(path, "utf8").split("\n")) {
+  for (const line of readFileSync12(path, "utf8").split("\n")) {
     if (!line.trim()) continue;
     let obj;
     try {
@@ -6395,7 +6803,7 @@ Examples:
 function resolveVersion() {
   try {
     const pkg = JSON.parse(
-      readFileSync12(new URL("../package.json", import.meta.url), "utf8")
+      readFileSync13(new URL("../package.json", import.meta.url), "utf8")
     );
     return pkg.version ?? "0.0.0";
   } catch {
@@ -6554,6 +6962,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.7-rc.56782977",
+  "version": "2026.7.8-rc.4b6e8ecc",
   "description": "Sechroom CLI — a thin, generated client over the Sechroom HTTP API. An agent/human surface alongside MCP.",
   "type": "module",
   "license": "UNLICENSED",