@shield-agent/kya 0.32.7 → 0.33.1

package/dist/cli.js

@@ -10,45 +10,12 @@
 import { realpathSync, writeSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { resolveConfig } from "./config.js";
-import { KyaError } from "./errors.js";
+import { AuthRequiredError, KyaError } from "./errors.js";
 import { flagBool, flagString, parseArgs } from "./parse-args.js";
-import { initFromArgs } from "./commands/init.js";
-import { registerAgentInputFromArgs, runRegisterAgent, } from "./commands/register-agent.js";
-import { evalToolInputFromArgs, formatEvalHuman, runEvalTool, } from "./commands/eval-tool.js";
-import { runServeMcp, serveMcpOptionsFromArgs, } from "./commands/serve-mcp.js";
-import { orrRunOptionsFromArgs, runOrr, } from "./commands/orr.js";
-import { certifyOptionsFromArgs, formatCertifySummary, runCertify, } from "./commands/certify.js";
-import { runDash } from "./commands/dash.js";
-import { formatAgentTable, formatApprovalTable, formatSessionTable, requireId, runGetAgent, runGetPassport, runKillAgent, runListAgents, runListApprovals, runListSessions, runShrinkSession, shrinkToFromArgs, } from "./commands/ops.js";
-import { formatWrapHuman, runWrap, verdictExitCode, wrapExitCode, wrapInputFromArgs, } from "./commands/wrap.js";
-import { formatReceiptHuman, openPath, receiptInputFromArgs, runReceipt, runReceiptShare, } from "./commands/receipt.js";
-import { formatShareLine, SHARE_HOSTED_HINT } from "./receipt/share.js";
-import { formatStartHuman, runStart } from "./commands/start.js";
-import { connectableHosts, formatConnectHuman, runConnect, } from "./commands/connect.js";
-import { appendTrail, defaultSessionId } from "./trail.js";
-import { deriveTargetPath } from "./trail-summary.js";
-import { decideIdFromArgs, runDecide } from "./commands/decide.js";
-import { formatInvokeHuman, invokeInputFromArgs, runInvoke, } from "./commands/invoke.js";
-import { runSandboxCommand } from "./commands/sandbox.js";
-import { runHook } from "./commands/hook.js";
-import { crashDecision, guardStream, hostedCrashHandler, planeBudgetMs } from "./commands/hosted-hook.js";
-import { importOptionsFromArgs, runImport } from "./commands/import-traces.js";
-import { investigateOptionsFromArgs, runInvestigate, } from "./commands/investigate.js";
-import { discoverOptionsFromArgs, runDiscover, } from "./commands/discover.js";
-import { runNotifyFlush } from "./commands/notify-flush.js";
-import { formatStopHuman, runStop } from "./commands/stop.js";
-import { runReceiptServe } from "./commands/receipt-serve.js";
-import { maybePrintStarCta } from "./star-cta.js";
-import { formatGateDoctorHuman, gateMcpUrl, gateSubcommand, runGateDoctor, runGateInit, runGateRun, runGateSetup, runGateStop, } from "./commands/gate.js";
-import { triggerHostedSyncFromEnv } from "./gate/hosted-sync.js";
-import { runGateServe } from "./commands/gate-serve.js";
 import { ensureSupportedNode } from "./node-upgrade.js";
 import { CLI_VERSION } from "./version.js";
-import { checkForUpdate, formatUpdateBanner, shouldSkipUpdateCheck, } from "./update-check.js";
-import { runUpdate } from "./commands/update.js";
-import { formatTeamInitHuman, managedSettings, runTeamInit } from "./commands/team.js";
-import { maybePromptConsent, maybeSpawnHookPing, runTelemetryCommand, startSessionBeacon, } from "./telemetry.js";
-const HELP = `Shield KYA light CLI - Know Your Agent (provider-agnostic)
+import { isNeverCode } from "./never-code.js";
+const helpFor = (hosts) => `Shield KYA light CLI - Know Your Agent (provider-agnostic)
 
 Usage:
   kya <command> [options]
@@ -63,9 +30,9 @@ Commands:
                     (--all also stops orphaned report daemons from other
                     directories or older installs)
   connect <host>    Wire KYA MCP into a coding host config
-                    (${connectableHosts().join("|")}; --project for project scope, --force to overwrite)
+                    (${hosts}; --project for project scope, --force to overwrite)
                     --hooks also wires the host's PreToolUse hook (claude|grok|kimi)
-                    --hooks --hosted --plane-config <abs path> wires the hosted hook (claude, beta)
+                    --hooks --hosted --plane-config <abs path> wires the hosted hook (claude, preview)
                     --gate points the host at the local kya gateway (kya gate run)
   gate              Local MCP gateway: govern + audit tool calls to any MCP server
                     (init | setup | doctor | status | run | stop)
@@ -74,11 +41,16 @@ Commands:
                     merges a tag-pinned marketplace + enabledPlugins into the project's
                     .claude/settings.json (--dry-run shows the change, writes nothing)
   team managed-settings  Print the managed-settings JSON an admin deploys
+  login             Link this machine to the hosted console (device code). Saves a 0600
+                    key in ~/.kya/hosted-credentials.json. --base-url <url> or KYA_BASE_URL
+  logout            Delete the saved hosted key (the key stays active until you revoke it)
   update            Self-update to the latest npm version (kya start warns when
                     a newer release exists; --no-update-check / KYA_UPDATE_CHECK=0 opts out)
   register-agent    POST /api/v1/kya/agents (human mint; server applies allow/break-glass/approve)
   eval-tool         Policy evaluate (HTTP plane or --offline sample)
-  wrap              Evaluate + record trail. Never executes.
+  wrap              Evaluate + record trail. With --tool-id it never executes.
+                    wrap [--offline] -- <cmd...>: gate the command as a shell call, run it
+                    only if allowed (exit = the command's; 1 denied, 4 Hold pending).
                     Default observe: no Hold ticket (no second approve). --hold / KYA_HOLD=1 for org Hold.
   hook              PreToolUse interception for native-hook hosts (claude|grok|kimi|…)
                     Reads the hook payload from stdin; exit 2 blocks. --strict denies advisory.
@@ -87,12 +59,26 @@ Commands:
                     timeout needs onFailure=block in the plugin hooks.json.
                     Records once per tool_use_id (dual-hook safe). Never-list DENY
                     blocks in both modes.
-                    --plane-config <abs path> (beta): evaluate on the hosted plane,
+                    Guard pack (local, default on, exit 2, rule id in the message):
+                      NEVER_SHELL        rm of home/root, terraform destroy, SQL drops, force
+                                         push, delete main, docker volumes, kubectl delete ns,
+                                         cloud deletes, git hard reset plus git clean
+                      NEVER_SECRET_READ  ssh/cloud/kube/docker/railway credentials, .env
+                      NEVER_SECRET_WRITE AWS/GitHub/Slack/Stripe keys, private key headers
+                      NEVER_EXFIL        env or credential files sent to a non-loopback host
+                    Config in ~/.kya/config.json only: shellNeverList, secretsGuard,
+                    exfilGuard (default true), guardAllow [{rule, path|command}].
+                    A project .kya/config.json cannot lift a deny. docs/guard-pack.md.
+                    --plane-config <abs path> (preview): evaluate on the hosted plane,
                     fail closed; key/URL/agent come only from that 0600 file.
                     --plane-shadow records hosted verdicts without blocking;
                     --plane-budget-ms <n> total plane budget (default 3000, max 4000).
   receipt           Activity report HTML/JSON/MD (default: last 3 days, all tools; --open)
                     --q pre-fills feed search · --share publishes a redacted summary (see --share-url)
+  map               Map of agent actions: device, agent, tool and target graph with KYA verdicts (local only)
+                    --days <n> window (default 3) · --json · --html <file> · --session <id>
+  export            Local trail as an agent-flow JSONL event log (classes only, no args; local only)
+                    --format agent-flow · --days <n> (default 3) · --session <id> · --out <file>
   invoke            Authorize on the plane after Allow or APPROVED. Never runs the write here.
   approve           Human APPROVE an approval id (kya.approve scope)
   reject            Human REJECT an approval id (kya.approve scope)
@@ -109,6 +95,12 @@ Commands:
   orr run           Read-only ORR board (reporting only - not a second PEP)
                     Optional: --producer harness.agentshield [--agentshield-json <file>]
   dash              Terminal desk (FREE panes; actions on a TTY, --once for CI)
+  doctor            Local checks. doctor --iocs scans this machine now for known supply-chain
+                    indicators (advisory; read-only, offline). --json for scripts. Last result: kya dash/receipt
+                    Background daily scan (from kya hook) is off with KYA_IOC=0 or ioc.enabled=false in ~/.kya/config.json
+  posture           Developer posture report, OFF by default. status | on [--yes] | off |
+                    send [--dry-run --json] | label NAME. "on" prints the exact report first.
+                    Sent once a day only when the local toggle AND the workspace allow it.
   sandbox           Opt-in Firecracker wrap (spawn|exec|kill|status). Not MCP.
                     Requires KYA_SANDBOX=mock|firecracker. MCP still never execs.
   certify           Agent Trust Baseline gap report from local evidence
@@ -183,14 +175,21 @@ Examples:
 Docs: https://shield-agent.com/install · docs/guides/kya-light-install.md
 Doctrine: sole PEP is Shield; DENY is hard; missing APPROVED ⇒ no irreversible side effect.
 `;
+/** Help text. The host list comes from the connect registry, loaded on demand so `kya hook` stays light. */
+async function helpText() {
+    const { connectableHosts } = await import("./commands/connect.js");
+    return helpFor(connectableHosts().join("|"));
+}
 const defaultIo = {
     log: (m) => console.log(m),
     error: (m) => console.error(m),
     exit: (c) => process.exit(c),
 };
-/** Set by the hosted hook: the CLI entry exits right after the answer is flushed. */
+/** The hook decides on the bytes it has after this long when the host never closes stdin. */
+const HOOK_STDIN_TIMEOUT_MS = 10_000;
+/** Set by the hook command: the CLI entry exits right after the answer is flushed. */
 let exitWhenDone = false;
-/** Whether the CLI entry will exit right after the hook answer (hosted mode). Exposed for tests. */
+/** Whether the CLI entry will exit right after the hook answer. Exposed for tests. */
 export function hostedExitPending() {
     return exitWhenDone;
 }
@@ -210,7 +209,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
         parsed.command === "help" ||
         parsed.flags["help"] === true ||
         parsed.flags["h"] === true) {
-        io.log(HELP);
+        io.log(await helpText());
         return 0;
     }
     try {
@@ -219,6 +218,10 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
             return nodeHandoff;
         switch (parsed.command) {
             case "start": {
+                const { formatStartHuman, runStart } = await import("./commands/start.js");
+                const { maybePrintStarCta } = await import("./star-cta.js");
+                const { checkForUpdate, formatUpdateBanner, shouldSkipUpdateCheck } = await import("./update-check.js");
+                const { maybePromptConsent } = await import("./telemetry.js");
                 const config = resolveConfig({
                     cwd,
                     env,
@@ -232,6 +235,11 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 const noGate = parsed.flags["no-gate"] === true || parsed.flags["no-gate"] === "true";
                 if (!config.json)
                     await maybePromptConsent(io, env);
+                // Before the report server starts, so the first search already sees the runtime. Never fails start.
+                if (!config.json) {
+                    const { maybeOfferSemanticSearch } = await import("./receipt/semantic-setup.js");
+                    await maybeOfferSemanticSearch(io, env).catch(() => undefined);
+                }
                 const result = await runStart(config, { force, open: !noOpen, gate: !noGate });
                 if (config.json) {
                     io.log(JSON.stringify(result, null, 2));
@@ -249,10 +257,26 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 }
                 return 0;
             }
+            case "login": {
+                const { loginBrowserOpener, runLogin } = await import("./commands/login.js");
+                const { openPath } = await import("./commands/receipt.js");
+                return await runLogin({
+                    io,
+                    env,
+                    baseUrl: flagString(parsed.flags, "base-url"),
+                    open: loginBrowserOpener(env, io.isTty ?? Boolean(process.stdout.isTTY), (url) => openPath(url)),
+                });
+            }
+            case "logout": {
+                const { runLogout } = await import("./commands/login.js");
+                return runLogout({ io, env });
+            }
             case "update": {
+                const { runUpdate } = await import("./commands/update.js");
                 return await runUpdate();
             }
             case "stop": {
+                const { formatStopHuman, runStop } = await import("./commands/stop.js");
                 const result = await runStop(cwd, { all: flagBool(parsed.flags, "all") });
                 if (parsed.flags["json"] === true || parsed.flags["json"] === "true") {
                     io.log(JSON.stringify(result, null, 2));
@@ -263,6 +287,9 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "receipt-serve": {
+                const { receiptInputFromArgs } = await import("./commands/receipt.js");
+                const { runReceiptServe } = await import("./commands/receipt-serve.js");
+                const { startSessionBeacon } = await import("./telemetry.js");
                 // Internal: detached child of `kya start` / `kya receipt --open`.
                 const config = resolveConfig({
                     cwd,
@@ -283,9 +310,15 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 finally {
                     await beacon.stop();
                 }
+                // The server is closed (signal, idle, folder gone, memory ceiling). A running search warm-up or
+                // another handle must not keep this process alive after its state file is gone.
+                exitWhenDone = true;
                 return 0;
             }
             case "connect": {
+                const { formatConnectHuman, runConnect } = await import("./commands/connect.js");
+                const { gateMcpUrl } = await import("./commands/gate.js");
+                const { maybePromptConsent } = await import("./telemetry.js");
                 if (parsed.flags["plane-config"] !== undefined && !flagBool(parsed.flags, "hosted")) {
                     // Without --hosted this would quietly wire the local, fail-open hook.
                     io.error("--plane-config needs --hosted (kya connect claude --hooks --hosted --plane-config <absolute path>)");
@@ -293,6 +326,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 }
                 const host = parsed.positionals[0];
                 if (!host) {
+                    const { connectableHosts } = await import("./commands/connect.js");
                     io.error(`Usage: kya connect <host>  (${connectableHosts().join("|")})`);
                     return 2;
                 }
@@ -329,6 +363,8 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "gate": {
+                const { formatGateDoctorHuman, gateSubcommand, runGateDoctor, runGateInit, runGateRun, runGateSetup, runGateStop } = await import("./commands/gate.js");
+                const { triggerHostedSyncFromEnv } = await import("./gate/hosted-sync.js");
                 const sub = gateSubcommand(parsed);
                 if (sub === "init") {
                     const result = runGateInit(env);
@@ -399,6 +435,8 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "gate-serve": {
+                const { runGateServe } = await import("./commands/gate-serve.js");
+                const { startSessionBeacon } = await import("./telemetry.js");
                 // Internal: detached supervisor child of `kya gate run`.
                 const beacon = startSessionBeacon("gateway", { env, cwd });
                 try {
@@ -410,6 +448,8 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "init": {
+                const { initFromArgs } = await import("./commands/init.js");
+                const { maybePromptConsent } = await import("./telemetry.js");
                 if (!flagBool(parsed.flags, "json"))
                     await maybePromptConsent(io, env);
                 const result = initFromArgs(parsed, cwd);
@@ -427,6 +467,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "team": {
+                const { formatTeamInitHuman, managedSettings, runTeamInit } = await import("./commands/team.js");
                 const sub = parsed.positionals[0];
                 if (sub === "managed-settings") {
                     io.log(JSON.stringify(managedSettings(), null, 2));
@@ -444,6 +485,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "register-agent": {
+                const { registerAgentInputFromArgs, runRegisterAgent } = await import("./commands/register-agent.js");
                 const config = resolveConfig({
                     cwd,
                     env,
@@ -463,6 +505,11 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "eval-tool": {
+                const { evalToolInputFromArgs, formatEvalHuman, runEvalTool } = await import("./commands/eval-tool.js");
+                const { verdictExitCode } = await import("./commands/wrap.js");
+                const { appendTrail, defaultSessionId } = await import("./trail.js");
+                const { deriveTargetPath } = await import("./trail-summary.js");
+                const { trailMapFields } = await import("./trail-map-fields.js");
                 const input = evalToolInputFromArgs(parsed);
                 const config = resolveConfig({
                     cwd,
@@ -481,8 +528,9 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                     verdict: result.response.verdict,
                     reasonCode: result.response.reasonCode ?? "",
                     mode: result.offline ? "offline" : config.holdEnabled ? "hold" : "observe",
-                    neverEvent: result.response.reasonCode === "NEVER_EVENT",
+                    neverEvent: isNeverCode(result.response.reasonCode),
                     argsHash: result.argsHash,
+                    ...trailMapFields(result.response.toolId ?? input.toolId, input.args, config.cwd, env),
                     ...(targetPath ? { targetPath } : {}),
                 }, env);
                 if (config.json) {
@@ -494,6 +542,9 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return verdictExitCode(result.response.verdict);
             }
             case "receipt": {
+                const { formatReceiptHuman, receiptInputFromArgs, runReceipt, runReceiptShare } = await import("./commands/receipt.js");
+                const { SHARE_HOSTED_HINT, formatShareLine } = await import("./receipt/share.js");
+                const { maybePrintStarCta } = await import("./star-cta.js");
                 const config = resolveConfig({
                     cwd,
                     env,
@@ -531,10 +582,60 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                     io.log(formatReceiptHuman(result));
                     if (result.liveUrl)
                         maybePrintStarCta(cwd, result.days, io.log);
+                    // One CTA per day at most: the truncation pitch wins over the --share hint.
+                    const { maybeCta } = await import("./cta.js");
+                    const { trailTruncated } = await import("./trail.js");
+                    maybeCta(trailTruncated(cwd, env) ? "receipt-truncated" : "receipt-share", { env, cwd, isTty: io.isTty ?? Boolean(process.stdout.isTTY) }, io.log);
                 }
                 return 0;
             }
+            case "map": {
+                const { mapOptionsFromArgs, runMap } = await import("./commands/map.js");
+                return await runMap(mapOptionsFromArgs(parsed), io, cwd, env);
+            }
+            case "export": {
+                const { exportOptionsFromArgs, runExport } = await import("./commands/export.js");
+                return await runExport(exportOptionsFromArgs(parsed), io, cwd, env);
+            }
             case "wrap": {
+                const { formatWrapHuman, runWrap, runWrapCommand, spawnWrapped, wrapCommandFromArgs, wrapCommandInputFromArgs, wrapExitCode, wrapInputFromArgs } = await import("./commands/wrap.js");
+                const argv = wrapCommandFromArgs(parsed);
+                if (argv) {
+                    // Command form: verdict lines go to stderr so the child's stdout stays clean.
+                    const cmdInput = wrapCommandInputFromArgs(parsed);
+                    // No key and no --offline: gate with the local sample policy (never-list included) instead of refusing to run.
+                    const cmdBase = { cwd, env, flags: parsed.flags };
+                    const cmdConfig = (() => {
+                        if (cmdInput.offline)
+                            return resolveConfig({ ...cmdBase, requireApiKey: false, offline: true });
+                        try {
+                            return resolveConfig({ ...cmdBase, requireApiKey: true });
+                        }
+                        catch (e) {
+                            if (!(e instanceof AuthRequiredError))
+                                throw e;
+                            return resolveConfig({ ...cmdBase, requireApiKey: false, offline: true });
+                        }
+                    })();
+                    const { exitCode } = await runWrapCommand(cmdConfig, argv, cmdInput, {
+                        run: (a) => spawnWrapped(a, io.error),
+                        onEvaluated: async (w) => {
+                            io.error(cmdConfig.json ? JSON.stringify(w, null, 2) : formatWrapHuman(w));
+                            try {
+                                const { autoOpenReceiptAfterWrap } = await import("./receipt/auto-open.js");
+                                const force = w.eval.response.verdict.toUpperCase() === "DENY" ||
+                                    w.eval.response.reasonCode === "NEVER_EVENT";
+                                const auto = await autoOpenReceiptAfterWrap(cmdConfig, { force, env });
+                                if (!cmdConfig.json && auto.hint)
+                                    io.error(auto.hint);
+                            }
+                            catch {
+                                /* receipt open is best-effort */
+                            }
+                        },
+                    });
+                    return exitCode;
+                }
                 const input = wrapInputFromArgs(parsed);
                 const config = resolveConfig({
                     cwd,
@@ -554,7 +655,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 try {
                     const { autoOpenReceiptAfterWrap } = await import("./receipt/auto-open.js");
                     const force = result.eval.response.verdict.toUpperCase() === "DENY" ||
-                        result.eval.response.reasonCode === "NEVER_EVENT";
+                        isNeverCode(result.eval.response.reasonCode);
                     const auto = await autoOpenReceiptAfterWrap(config, { force, env });
                     if (!config.json && auto.hint)
                         io.log(auto.hint);
@@ -565,6 +666,8 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return wrapExitCode(result);
             }
             case "invoke": {
+                const { verdictExitCode } = await import("./commands/wrap.js");
+                const { formatInvokeHuman, invokeInputFromArgs, runInvoke } = await import("./commands/invoke.js");
                 const input = invokeInputFromArgs(parsed);
                 const config = resolveConfig({
                     cwd,
@@ -583,6 +686,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
             }
             case "approve":
             case "reject": {
+                const { decideIdFromArgs, runDecide } = await import("./commands/decide.js");
                 const id = decideIdFromArgs(parsed, parsed.command);
                 const config = resolveConfig({
                     cwd,
@@ -603,6 +707,8 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "serve-mcp": {
+                const { runServeMcp, serveMcpOptionsFromArgs } = await import("./commands/serve-mcp.js");
+                const { startSessionBeacon } = await import("./telemetry.js");
                 const config = resolveConfig({
                     cwd,
                     env,
@@ -642,6 +748,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "orr": {
+                const { orrRunOptionsFromArgs, runOrr } = await import("./commands/orr.js");
                 const sub = parsed.positionals[0];
                 if (sub !== "run") {
                     io.error('Usage: kya orr run --path <dir> [options]');
@@ -661,6 +768,8 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return result.exitCode;
             }
             case "certify": {
+                const { certifyOptionsFromArgs, formatCertifySummary, runCertify } = await import("./commands/certify.js");
+                const { openPath } = await import("./commands/receipt.js");
                 // Local-first, evidence-only: no resolveConfig, no API key, no network.
                 const opts = certifyOptionsFromArgs(parsed);
                 const result = runCertify({ ...opts, cwd, env });
@@ -675,6 +784,11 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                             io.log(`  wrote ${p}`);
                     }
                     io.log("(evidence only - sole PEP remains Shield KYA; certify never allows or blocks)");
+                    if (result.report.overall.result === "gap") {
+                        // One-line CTA, silent in CI, non-TTY, quiet, opt-out and within 24 h of the last one. Never changes exit code.
+                        const { maybeCta } = await import("./cta.js");
+                        maybeCta("certify-gaps", { env, cwd, isTty: io.isTty ?? Boolean(process.stdout.isTTY), json: jsonOut, quiet: opts.quiet }, io.log);
+                    }
                 }
                 // Attestation confirmation is safety-relevant (proof the attest write
                 // happened): it prints even under --quiet, like the key notice;
@@ -703,6 +817,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return result.exitCode;
             }
             case "agents": {
+                const { formatAgentTable, runListAgents } = await import("./commands/ops.js");
                 const config = resolveConfig({
                     cwd,
                     env,
@@ -714,6 +829,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "agent": {
+                const { formatAgentTable, requireId, runGetAgent } = await import("./commands/ops.js");
                 const id = requireId(parsed, "agent");
                 const config = resolveConfig({
                     cwd,
@@ -726,6 +842,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "passport": {
+                const { requireId, runGetPassport } = await import("./commands/ops.js");
                 const id = requireId(parsed, "passport");
                 const config = resolveConfig({
                     cwd,
@@ -738,6 +855,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "kill": {
+                const { requireId, runKillAgent } = await import("./commands/ops.js");
                 const id = requireId(parsed, "kill");
                 const config = resolveConfig({
                     cwd,
@@ -753,6 +871,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "approvals": {
+                const { formatApprovalTable, runListApprovals } = await import("./commands/ops.js");
                 const config = resolveConfig({
                     cwd,
                     env,
@@ -764,6 +883,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "sessions": {
+                const { formatSessionTable, runListSessions } = await import("./commands/ops.js");
                 const config = resolveConfig({
                     cwd,
                     env,
@@ -775,6 +895,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "shrink": {
+                const { requireId, runShrinkSession, shrinkToFromArgs } = await import("./commands/ops.js");
                 const id = requireId(parsed, "shrink");
                 const to = shrinkToFromArgs(parsed);
                 const config = resolveConfig({
@@ -791,6 +912,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return 0;
             }
             case "dash": {
+                const { runDash } = await import("./commands/dash.js");
                 const config = resolveConfig({
                     cwd,
                     env,
@@ -802,9 +924,11 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return await runDash(config, parsed, io, env);
             }
             case "sandbox": {
+                const { runSandboxCommand } = await import("./commands/sandbox.js");
                 return await runSandboxCommand(parsed);
             }
             case "telemetry": {
+                const { runTelemetryCommand } = await import("./telemetry.js");
                 return runTelemetryCommand({
                     sub: parsed.positionals[0],
                     purge: flagBool(parsed.flags, "purge"),
@@ -812,6 +936,9 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 }, io, env, cwd);
             }
             case "hook": {
+                const { runHook } = await import("./commands/hook.js");
+                const { crashDecision, guardStream, hostedCrashHandler, planeBudgetMs } = await import("./commands/hosted-hook.js");
+                const { maybeSpawnHookPing } = await import("./telemetry.js");
                 const host = flagString(parsed.flags, "host") ?? "other";
                 const strict = flagBool(parsed.flags, "strict");
                 // Strict boolean: parseArgs would otherwise swallow a following word
@@ -819,7 +946,7 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 // Present means on, except an explicit false/0.
                 const fcFlag = parsed.flags["fail-closed"];
                 const failClosed = fcFlag !== undefined && fcFlag !== false && !/^(false|0)$/i.test(String(fcFlag));
-                // Hosted plane (beta): argv only. Missing or empty path still means hosted (it denies PLANE_CONFIG).
+                // Hosted plane (preview): argv only. Missing or empty path still means hosted (it denies PLANE_CONFIG).
                 const planeFlag = parsed.flags["plane-config"];
                 const plane = planeFlag === undefined
                     ? undefined
@@ -842,16 +969,29 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                     process.on("uncaughtException", crash);
                     process.on("unhandledRejection", crash);
                 }
+                // A host that closed its end of stdout must not turn the answer into a crash (EPIPE).
+                if (isCliEntry()) {
+                    process.stdout.on("error", () => undefined);
+                    process.stderr.on("error", () => undefined);
+                }
                 let stdinText = "";
                 if (!process.stdin.isTTY) {
                     stdinText = await new Promise((res) => {
                         // Buffer chunks, not string concat - a multibyte UTF-8 char can
                         // straddle a chunk boundary.
                         const chunks = [];
+                        const done = () => {
+                            clearTimeout(timer);
+                            res(Buffer.concat(chunks).toString("utf8"));
+                        };
+                        // A host that never closes stdin would hold the hook for days: decide on what arrived.
+                        // Fixed on purpose: an env value (a repo can set it in committed settings) must not shorten it
+                        // and so turn a slow payload into an empty one that the OSS hook allows.
+                        const timer = setTimeout(done, HOOK_STDIN_TIMEOUT_MS);
                         process.stdin.on("data", (c) => chunks.push(c));
                         // Pipe errors must not hang the hook - resolve with what arrived.
-                        process.stdin.on("error", () => res(Buffer.concat(chunks).toString("utf8")));
-                        process.stdin.on("end", () => res(Buffer.concat(chunks).toString("utf8")));
+                        process.stdin.on("error", done);
+                        process.stdin.on("end", done);
                     });
                 }
                 let r;
@@ -871,36 +1011,80 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                     }
                     return d.code;
                 }
-                // Await the write callbacks: pipes can be async, and hosted mode exits explicitly below.
+                // Await the write callbacks: pipes can be async, and the exit below must not cut them off.
                 if (r.stdout)
                     await new Promise((ok) => process.stdout.write(r.stdout, () => ok()));
                 if (r.stderr)
                     await new Promise((ok) => process.stderr.write(r.stderr, () => ok()));
-                // Hosted: no lingering socket may hold the hook past the host timeout.
-                if (plane)
-                    exitWhenDone = true;
+                // Exit with the same code once the answer is out and the spawns below are issued. Detached
+                // children (ping, IoC, posture, notify) are unref'd and keep running; no other handle may hold a hook.
+                exitWhenDone = true;
                 // After the answer is out. Opt-in, at most daily, detached: the hook never waits on the network.
                 // Skipped when another hook copy already handled this tool_use_id.
                 if (r.firstSeen !== false)
                     maybeSpawnHookPing({ env, cwd, host });
+                // Daily IoC scan: detached, at most once per 24 h, never awaited. Fail open.
+                const { maybeSpawnIocScan } = await import("./ioc/spawn.js");
+                maybeSpawnIocScan({ env });
+                // Daily posture send: only when the local toggle is on. Detached, at most once per 24 h, never awaited.
+                const { maybeSpawnPostureSend } = await import("./posture/spawn.js");
+                maybeSpawnPostureSend({ env });
                 return r.exitCode;
             }
+            case "posture": {
+                const { runPosture } = await import("./commands/posture.js");
+                const [sub, ...rest] = parsed.positionals;
+                return await runPosture({
+                    io: { log: (line) => io.log(line), error: (line) => io.error(line) },
+                    env,
+                    sub: parsed.command === "posture" ? sub : undefined,
+                    args: rest,
+                    flags: parsed.flags,
+                    isTty: io.isTty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                });
+            }
+            case "posture-send": {
+                // Internal: detached daily posture send started by the hook (posture/spawn.ts). Not in help.
+                const { runPostureSendDetached } = await import("./commands/posture.js");
+                await runPostureSendDetached(env);
+                return 0;
+            }
+            case "doctor": {
+                const { runDoctor } = await import("./commands/doctor.js");
+                return await runDoctor((line) => io.log(line), {
+                    env,
+                    iocs: flagBool(parsed.flags, "iocs"),
+                    json: flagBool(parsed.flags, "json"),
+                    cwd,
+                    warn: (line) => io.error(line),
+                });
+            }
+            case "ioc-scan": {
+                // Internal: detached daily IoC scan started by kya hook (ioc/spawn.ts). Not in help.
+                const { runDetachedIocScan } = await import("./ioc/scan.js");
+                await runDetachedIocScan(env);
+                return 0;
+            }
             case "import": {
+                const { importOptionsFromArgs, runImport } = await import("./commands/import-traces.js");
                 return await runImport(importOptionsFromArgs(parsed), io, cwd, env);
             }
             case "investigate": {
+                const { investigateOptionsFromArgs, runInvestigate } = await import("./commands/investigate.js");
                 return await runInvestigate(investigateOptionsFromArgs(parsed), io, cwd, env);
             }
             case "discover": {
+                const { discoverOptionsFromArgs, runDiscover } = await import("./commands/discover.js");
                 return await runDiscover(discoverOptionsFromArgs(parsed), io, cwd, env);
             }
             case "notify-flush": {
+                const { runNotifyFlush } = await import("./commands/notify-flush.js");
                 // Internal: spawned detached by hook/wrap (src/notify/dispatch.ts).
                 return await runNotifyFlush(env, cwd);
             }
             default:
                 io.error(`Unknown command: ${parsed.command}`);
-                io.log(HELP);
+                io.log(await helpText());
                 return 2;
         }
     }