@shield-agent/kya 0.32.7 → 0.32.9

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "shield-kya",
-  "version": "0.32.7",
+  "version": "0.32.9",
   "description": "Audit trail and traceability for AI agents. See what every coding agent did and check each tool call against policy.",
   "author": {
     "name": "Shield Agent",

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.32.7", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.32.9", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@shield-agent/kya.svg?logo=npm&label=npm)](https://www.npmjs.com/package/@shield-agent/kya)
 [![npm downloads/week](https://img.shields.io/npm/dw/@shield-agent/kya.svg?logo=npm&label=downloads%2Fweek)](https://www.npmjs.com/package/@shield-agent/kya)
-[![npm downloads](https://img.shields.io/npm/dt/@shield-agent/kya.svg?logo=npm&label=total%20downloads)](https://www.npmjs.com/package/@shield-agent/kya)
+[![npm downloads, 18 months](https://img.shields.io/npm/d18m/@shield-agent/kya.svg?logo=npm&label=downloads%2C%2018%20months)](https://www.npmjs.com/package/@shield-agent/kya)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 [![Install](https://img.shields.io/badge/install-shield--agent.com%2Finstall-0A0A0A)](https://shield-agent.com/install)
 [![X](https://img.shields.io/badge/X-%40coscosmico-000000?logo=x&logoColor=white)](https://x.com/coscosmico)
@@ -50,7 +50,7 @@ More ways to install (same package; npm stays the reference path):
 
 ```bash
 # Homebrew. Homebrew 7 may ask you to trust a third-party tap: run `brew tap The-Pixel-Boys/tap` first.
-# The formula installs about 270MB because of the optional semantic-search runtime.
+# The formula does not install the semantic-search runtime. Search stays lexical until you opt in (see Natural-language search).
 brew install The-Pixel-Boys/tap/shield-kya
 
 # Scoop (not yet verified on Windows)
@@ -122,7 +122,7 @@ This repo is also a Claude Code plugin marketplace named `shield-kya` with one p
 /plugin install kya@shield-kya
 ```
 
-The plugin is **advisory and fails open**: it records every tool call on the local record (`~/.kya/trail.jsonl`) and blocks only the small never-list. If kya is missing, crashes or times out, the tool call proceeds and nothing is recorded. It evaluates offline, so it has no Hold and no approval. Hosted enforcement is the MCP gate path.
+The plugin is **advisory and fails open**: it records every tool call on the local record (`~/.kya/trail.jsonl`) and blocks only the small never-list. If kya is missing, crashes or times out, the tool call proceeds and nothing is recorded. It evaluates offline, so it has no Hold and no approval. Hosted enforcement is the MCP policy path against a hosted workspace.
 
 Team rollout: commit `extraKnownMarketplaces` (the `shield-kya` GitHub source) and `enabledPlugins` (`"kya@shield-kya": true`) to the repository's `.claude/settings.json`, or force it org-wide with managed settings. Details and limits: [docs/hosts/claude-plugin.md](docs/hosts/claude-plugin.md).
 
@@ -196,7 +196,7 @@ Install hub: [https://shield-agent.com/install](https://shield-agent.com/install
 
 ## Activity record (global)
 
-One record (trail) for all projects: `~/.kya/trail.jsonl` (`KYA_HOME` overrides `~`). `kya receipt --open` from any directory shows activity from every project. Each event carries its project folder name. The report adds a Projects rollup once two or more projects appear, and shows the project on each feed entry. Older per-project `<project>/.kya/trail.jsonl` files are still read and merged; no migration. The record is capped at 1 MB (tail-read: oldest events drop away) and shared across all projects.
+One record (trail) for all projects: `~/.kya/trail.jsonl` (`KYA_HOME` overrides `~`). `kya receipt --open` from any directory shows activity from every project. Each event carries its project folder name. The report adds a Projects rollup once two or more projects appear, and shows the project on each feed entry. Older per-project `<project>/.kya/trail.jsonl` files are still read and merged; no migration. Reports read only the last 1 MB of the record (oldest events drop out of the view); it is shared across all projects.
 
 The report itself is a dashboard. A hero row on top shows the live **Certify** result, the decision mix, an activity sparkline, and showback (cost per agent). Tabbed sections sit below: **Overview** (analytics, sessions, reasons), **Certify** (the full live requirement table: every requirement grouped by domain with status, evidence, and attestation), **Activity** (the filterable event feed), **System** (wired hosts, sandboxes, ORR). Everything is one standalone offline HTML page. The live view adds a single external link: "Star on GitHub". The live daemon from `kya start` re-renders it on every event.
 
@@ -208,14 +208,37 @@ Sharing is a single attempt by design (storm-proof: no silent retries against th
 
 ### Natural-language search
 
-The **Activity** search box understands plain English. It runs a hybrid of BM25 over tool IDs, summaries, reason codes, decisions, projects, and MCP server labels, plus local MiniLM semantic reranking (shipped as an optional dependency; the report falls back to lexical-only if the model runtime is unavailable). A built-in concept glossary maps everyday words to the vocabulary events actually use, so `dangerous` finds rm/kill/delete/sudo calls, `blocked` finds denials, and `held` finds approval requests. You can also type things like `failed stripe transfers`, `files written by grok`, or `approval required production`. Stopwords and stemming are handled automatically, and the same search works across the global record.
+The **Activity** search box understands plain English. It runs a hybrid of BM25 over tool IDs, summaries, reason codes, decisions, projects, and MCP server labels, plus local MiniLM semantic reranking, which is opt-in. The runtime is not part of the default install. Without it, search stays lexical (BM25) and the live report server writes one line to its log (for `kya start`, the background report daemon log) that names the install command. Install it once:
+
+```bash
+# macOS and Linux (bash or zsh)
+npm install --prefix "$HOME/.kya/semantic" @shield-agent/fastembed@3.0.0
+```
+
+```bat
+:: Windows cmd
+npm install --prefix "%USERPROFILE%\.kya\semantic" @shield-agent/fastembed@3.0.0
+```
+
+```powershell
+# Windows PowerShell
+npm install --prefix "$env:USERPROFILE\.kya\semantic" @shield-agent/fastembed@3.0.0
+```
+
+If `KYA_HOME` is set, the prefix is `$KYA_HOME/.kya/semantic` (`%KYA_HOME%\.kya\semantic` on Windows). A built-in concept glossary maps everyday words to the vocabulary events actually use, so `dangerous` finds rm/kill/delete/sudo calls, `blocked` finds denials, and `held` finds approval requests. You can also type things like `failed stripe transfers`, `files written by grok`, or `approval required production`. Stopwords and stemming are handled automatically, and the same search works across the global record.
 
 - Offline or `KYA_OFFLINE=1` keeps search purely lexical (no model download).
-- By default the live server downloads `BAAI/bge-small-en-v1.5` once into `~/.kya/models` and caches event vectors in `~/.kya/search-index.json`.
+- After you opt in, the live server downloads `BAAI/bge-small-en-v1.5` once into `~/.kya/models` and caches event vectors in `~/.kya/search-index.json`.
 - `KYA_SEARCH_SEMANTIC=off` disables the model while still keeping BM25.
 
 The hosted console uses the same hybrid search on the server side (Postgres full-text + optional OpenAI-compatible embeddings), so queries typed in either place behave the same way.
 
+## Upgrade notes
+
+- Semantic search is no longer installed by default (about 230 MB less on disk). After upgrading, activity search is lexical (BM25) only until you run the install command in [Natural-language search](#natural-language-search).
+- The CLI loads the OpenTelemetry SDK only when an OTLP endpoint is set. A start error is logged once to stderr; metrics stay off and the command continues.
+- Hook verdicts and fail-open rules are unchanged.
+
 ## Dual plane
 
 ```
@@ -229,6 +252,22 @@ The hosted console uses the same hybrid search on the server side (Postgres full
 
 Tag sessions with `KYA_HOST=ide` or `KYA_HOST=runtime`. Same policy path either way.
 
+## Plans (hosted, plan tiers v2)
+
+The rows below apply only when the hosted service turns plan tiers v2 on. Until then the hosted plans are Free, Starter, Pro and Scale.
+
+The hosted console has these plans. The CLI works on every plan. Solo and the no-card trial appear only when the hosted service turns plan tiers on.
+
+| Plan | Price | Seats | Trail history | Notes |
+|---|---|---|---|---|
+| Free | $0 | 2 | 30 days | Start here |
+| Solo | $90 a year | 1 | 90 days | CSV evidence export. Yearly only |
+| Team | $29 a month | 5 | 90 days | Formerly "Starter" |
+| Pro | $149 a month | 25 | 90 days | Compliance report PDF, signed evidence bundles |
+| Scale | $499 a month | Unlimited | 365 days | SSO and SCIM |
+
+n8n and Zapier access is included in every paid plan. There is no add-on price.
+
 ## Environment
 
 | Variable | Required | Meaning |
@@ -247,6 +286,9 @@ Tag sessions with `KYA_HOST=ide` or `KYA_HOST=runtime`. Same policy path either
 | `KYA_SHARE_URL` | No | `kya receipt --share` collector base (default `https://shield-agent.com`) |
 | `KYA_TELEMETRY` | No | `0`/`off` forces anonymous usage stats off ([docs/telemetry.md](docs/telemetry.md)); they are off unless you opted in |
 | `DO_NOT_TRACK` | No | `1` forces anonymous usage stats off, same as `KYA_TELEMETRY=0` |
+| `KYA_BASE_URL` | No | Hosted console for `kya login` (default `https://shield-agent.com`; https or loopback only) |
+| `KYA_QUIET` | No | Any true value hides the one-line hosted calls to action (`kya certify`, `kya receipt`) |
+| `KYA_CTA` | No | `0`/`off` turns off the one-line hosted calls to action ([docs/login.md](docs/login.md#calls-to-action-one-line)) |
 
 Gate mode can also be set in the project's `.kya/config.json`:
 `{"gateMode": "hold"}` or `{"gateMode": "offline"}` (exact values only;
@@ -270,7 +312,7 @@ MCP Registry entry: `server.json` plus package `mcpName` `io.github.The-Pixel-Bo
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.32.7", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.32.9", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "http://127.0.0.1:8090",
         "KYA_API_KEY": "${KYA_API_KEY}",
@@ -304,7 +346,9 @@ const run = governed({ toolId: "write_file", server: "filesystem", fn: myWrite }
 await run({ path: "out.txt", content: "hi" }); // throws KyaDeniedError on DENY
 ```
 
-Offline evaluate by default (no network, no hosted plane); an explicit config uses the live plane. `governA2aSend` gates in-process agent-to-agent sends. A fail-open Python shim with a LangChain middleware is in development and not yet released. Support matrix and recipes: `docs/sdk-integrations.md`; runnable scripts: `examples/sdk/`.
+Offline evaluate by default (no network, no hosted plane); an explicit config uses the live plane. `governA2aSend` gates in-process agent-to-agent sends. The `shield-kya` Python package on PyPI ships framework hooks (LangChain, CrewAI, OpenAI Agents SDK and others), fail-open like `kya hook`. Support matrix and recipes: `docs/sdk-integrations.md`; runnable scripts: `examples/sdk/`.
+
+Framework recipes (each one tested with a scripted model and the published CLI): [LangChain](docs/sdk-integrations.md#langchain-python) · [OpenAI Agents SDK](docs/sdk-integrations.md#openai-agents-sdk-python) · [CrewAI](docs/sdk-integrations.md#crewai-python) · [LlamaIndex](docs/sdk-integrations.md#llamaindex-python) · [Mastra](docs/sdk-integrations.md#mastra-typescript) · [Vercel AI SDK](docs/sdk-integrations.md#vercel-ai-sdk-typescript)
 
 ## Claude connector
 
@@ -312,7 +356,7 @@ Offline evaluate by default (no network, no hosted plane); an explicit config us
 
 ```bash
 # Prefer a preinstalled package (no registry auto-install):
-npx --no-install @shield-agent/kya@0.32.7 serve-mcp --stdio
+npx --no-install @shield-agent/kya@0.32.9 serve-mcp --stdio
 # Or after npm i -g / local install:
 kya serve-mcp --stdio
 ```
@@ -323,7 +367,7 @@ Copy `claude/claude_desktop_config.example.json` into Claude Desktop MCP setting
 
 ## OpenAI (Codex / Responses)
 
-**Codex CLI plugin (hooks):** see [Codex plugin](#codex-plugin). **Codex CLI / IDE (MCP):** copy `openai/codex.config.example.toml` into `~/.codex/config.toml`. Local stdio uses `npx --no-install @shield-agent/kya@0.32.7 serve-mcp --stdio`. Hosted Codex uses `url = "https://shield-agent.com/mcp"` with `bearer_token_env_var = "KYA_API_KEY"`.
+**Codex CLI plugin (hooks):** see [Codex plugin](#codex-plugin). **Codex CLI / IDE (MCP):** copy `openai/codex.config.example.toml` into `~/.codex/config.toml`. Local stdio uses `npx --no-install @shield-agent/kya@0.32.9 serve-mcp --stdio`. Hosted Codex uses `url = "https://shield-agent.com/mcp"` with `bearer_token_env_var = "KYA_API_KEY"`.
 
 **Responses API:** see `openai/responses-mcp.example.json` (`server_url` + `Authorization: Bearer <KYA_API_KEY>`).
 
@@ -496,6 +540,7 @@ pnpm build
 - [Top-20 MCP server support matrix (taxonomy + gate recipes)](docs/mcp-servers.md)
 - [OTLP metrics (OSS + hosted)](docs/otlp.md)
 - [Anonymous usage stats (opt-in): what is sent, controls, retention](docs/telemetry.md)
+- [Link this machine to the hosted console (kya login)](docs/login.md)
 - [OWASP MCP governance map](docs/owasp-mcp-governance.md)
 - [Claude Code plugin](docs/hosts/claude-plugin.md) · [Copilot CLI plugin](docs/hosts/copilot.md#plugin) · [Codex plugin](docs/hosts/codex.md#codex-plugin) · [Gemini CLI extension](docs/hosts/gemini.md#gemini-cli-extension)
 - [Import the AGT audit log (CLI)](docs/import-agt.md) · [hosted](docs/import-agt-hosted.md)
@@ -508,6 +553,10 @@ pnpm build
 - [What is open source and what is hosted](docs/oss-vs-hosted.md)
 - See also `LIMITATIONS.md` in this repo
 
+## Hosted console (`kya login`, optional)
+
+`kya login` links this machine to your hosted Shield KYA workspace. It uses the device code flow: the CLI shows a short code, you approve it in the hosted console, and the CLI saves a full-workspace API key with mode 0600 in `~/.kya/hosted-credentials.json`. `kya logout` deletes that file. It does not revoke the key on the server, so revoke it in the console too. The OSS CLI works without an account, and `kya certify` and the hook never read the saved key. Details, failure cases and the one-line calls to action: [docs/login.md](docs/login.md).
+
 ## Anonymous usage stats (opt-in, off by default)
 
 The first time you run `kya start`, `kya init` or `kya connect` in a terminal, KYA asks once whether to share anonymous usage stats (`[y/N]`, the default is No). Only an explicit `y` or `yes` turns it on. Nothing is sent in CI, in non-interactive runs, with `--json`, or when `DO_NOT_TRACK=1` / `KYA_TELEMETRY=0` is set. `kya hook` itself never touches the network; when you opted in it starts a detached helper at most once a day that sends one `ping`, so hook-only installs still count as active.

package/amp/settings.example.json

@@ -2,7 +2,7 @@
   "amp.mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.32.7", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.32.9", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/claude/claude_desktop_config.example.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.32.7", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.32.9", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/cline/cline_mcp_settings.example.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.32.7", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.32.9", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/copilot/mcp-config.example.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "shield-kya": {
       "command": "npx",
-      "args": ["--no-install", "@shield-agent/kya@0.32.7", "serve-mcp", "--stdio"],
+      "args": ["--no-install", "@shield-agent/kya@0.32.9", "serve-mcp", "--stdio"],
       "env": {
         "KYA_BASE_URL": "https://shield-agent.com",
         "KYA_API_KEY": "${KYA_API_KEY}",

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AA8PH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,qGAAqG;IACrG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACtD;AAWD,oGAAoG;AACpG,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,+FAA+F;AAC/F,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAAiB,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAwvBjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AA2JH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,qGAAqG;IACrG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACtD;AAWD,oGAAoG;AACpG,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,+FAA+F;AAC/F,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAAiB,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA20BjB"}

package/dist/cli.js

@@ -12,43 +12,9 @@ import { fileURLToPath } from "node:url";
 import { resolveConfig } from "./config.js";
 import { 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)
+const helpFor = (hosts) => `Shield KYA light CLI - Know Your Agent (provider-agnostic)
 
 Usage:
   kya <command> [options]
@@ -63,7 +29,7 @@ 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)
                     --gate points the host at the local kya gateway (kya gate run)
@@ -74,6 +40,9 @@ 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)
@@ -183,6 +152,11 @@ 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),
@@ -210,7 +184,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 +193,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,
@@ -249,10 +227,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 +257,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,
@@ -286,6 +283,9 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 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 +293,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 +330,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 +402,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 +415,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 +434,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 +452,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 +472,10 @@ 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 input = evalToolInputFromArgs(parsed);
                 const config = resolveConfig({
                     cwd,
@@ -494,6 +507,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 +547,15 @@ 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 "wrap": {
+                const { formatWrapHuman, runWrap, wrapExitCode, wrapInputFromArgs } = await import("./commands/wrap.js");
                 const input = wrapInputFromArgs(parsed);
                 const config = resolveConfig({
                     cwd,
@@ -565,6 +586,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 +606,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 +627,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 +668,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 +688,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 +704,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 +737,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 +749,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 +762,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 +775,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 +791,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 +803,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 +815,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 +832,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 +844,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 +856,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
@@ -886,21 +933,25 @@ export async function runCli(argv, io = defaultIo, env = process.env, cwd = proc
                 return r.exitCode;
             }
             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;
         }
     }