passcontrol 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -90,7 +90,15 @@ import {
90
90
  import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
91
91
  import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from "../cli/local-stack.mjs";
92
92
  import { startSidecar } from "../cli/sidecar.mjs";
93
- import { claudeCodeEnv, claudeCodeSettingsPath, removeClaudeCodeSettings, writeClaudeCodeSettings } from "../cli/claude-code.mjs";
93
+ import { listProfiles, profilePath, readProfile, TOOL_PROFILE_PORTS, writeProfile } from "../cli/profiles.mjs";
94
+ import {
95
+ claudeCodeEnv,
96
+ claudeCodeSettingsPath,
97
+ removeClaudeCodeSettings,
98
+ writeClaudeCodeSettings,
99
+ } from "../cli/claude-code.mjs";
100
+ import { notInPathText, sidecarFromBaseUrl, statusPanelText, statuslineText } from "../cli/statusline.mjs";
101
+ import { runWatch } from "../cli/watch.mjs";
94
102
  import { CODEX_PROFILE, codexProfilePath, codexProfileToml, codexStoresApiKey, removeCodexProfile, writeCodexProfile } from "../cli/codex.mjs";
95
103
  import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
96
104
  import { loginCommand } from "../cli/login.mjs";
@@ -102,7 +110,7 @@ import {
102
110
  instanceKidFromSeed,
103
111
  retiredKeyEntry,
104
112
  } from "../cli/instance-key.mjs";
105
- import { FAILURE_REASONS, verifyAgentToken, verifyReceipt, verifyStatement } from "../cli/verify.mjs";
113
+ import { FAILURE_REASONS, verifyAgentToken, verifyReceipt, verifySession, verifyStatement } from "../cli/verify.mjs";
106
114
  import { compareProtocolSets } from "../cli/protocols.mjs";
107
115
  import { defaultAllowedModelForProvider } from "../cli/integration-defaults.mjs";
108
116
  import {
@@ -200,8 +208,10 @@ ${heading("Quick start")}
200
208
  ${cmd} login [--project] sign in through your browser and set this machine up
201
209
  ${cmd} call "hi" mint a visa and make a governed model call
202
210
  ${cmd} mcp passport identity for Claude Desktop, Cursor, Claude Code
203
- ${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435]
211
+ ${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435] [--no-journal]
204
212
  passport identity for any tool that takes an api_key
213
+ ${cmd} sidecar --profile <name> | --profiles a,b
214
+ run a coding tool's own sidecar (or several, one process)
205
215
 
206
216
  ${heading("Operate")}
207
217
  ${cmd} status [--no-network] [--json]
@@ -217,6 +227,7 @@ ${heading("Operate")}
217
227
 
218
228
  ${heading("Manage")}
219
229
  ${cmd} agent list [--json] list agents
230
+ ${cmd} profile list [--json] show the profiles: one identity per coding tool
220
231
  ${cmd} agent create <name> [--write]
221
232
  create an agent passport (--write saves it here)
222
233
  ${cmd} agent rotate <id> [--grace <seconds>]
@@ -224,6 +235,10 @@ ${heading("Manage")}
224
235
  ${cmd} agent suspend <id> suspend an agent
225
236
  ${cmd} agent resume <id> resume an agent
226
237
  ${cmd} agent revoke <id> permanently revoke an agent
238
+ ${cmd} agent delegations <id> [--json]
239
+ list the delegations its workers have used
240
+ ${cmd} agent revoke-delegation <id> <jti>|--all
241
+ permanently revoke one delegation, or all before now
227
242
  ${cmd} spend [--json] show fleet and per-agent spend
228
243
  ${cmd} audit [--limit 20] [--json]
229
244
  show operator audit history
@@ -231,6 +246,13 @@ ${heading("Manage")}
231
246
  show governed call logs
232
247
  ${cmd} statements [--limit 20] [--json]
233
248
  show the chain of signed spend statements
249
+ ${cmd} sessions [--agent ID] [--limit 20] [--json]
250
+ list Claude Code / Codex sessions (declared by the client)
251
+ ${cmd} seal <session> --agent ID [--out FILE]
252
+ sign one session; save the seal and its receipts
253
+ ${cmd} statusline [--port 8788] one line for Claude Code's status line (configure claude-code --statusline)
254
+ ${cmd} statusline --panel [--session <id>] the longer view the Claude Code plugin's /passcontrol shows
255
+ ${cmd} watch [--port 8788] a live board of each call the sidecar relays (read-only)
234
256
  ${cmd} kill on|off toggle the tenant kill switch
235
257
  ${cmd} export [--out FILE] save a workspace configuration snapshot
236
258
  ${cmd} import <file> [--confirm IMPORT]
@@ -238,7 +260,7 @@ ${heading("Manage")}
238
260
 
239
261
  ${heading("Integrate")}
240
262
  ${cmd} env [integration] print settings without writing anything
241
- ${cmd} configure <integration> [--write] [--force]
263
+ ${cmd} configure <integration> [--write] [--force] [--dedicated]
242
264
  preview or write integration config
243
265
  integrations: ${integrationChoices()}
244
266
 
@@ -291,6 +313,8 @@ ${heading("Usage:")}
291
313
  ${cmd} agent suspend <id>
292
314
  ${cmd} agent resume <id>
293
315
  ${cmd} agent revoke <id>
316
+ ${cmd} agent delegations <id> [--json]
317
+ ${cmd} agent revoke-delegation <id> <jti>|--all
294
318
 
295
319
  ${heading("Examples")}
296
320
  ${cmd} agent create prod-summarizer --provider anthropic --scope 'claude-*'
@@ -362,6 +386,7 @@ async function printCockpit({ noNetwork = false, json = false } = {}) {
362
386
  app: { state: app },
363
387
  config: {
364
388
  source: configFile,
389
+ profile: config.profile,
365
390
  provider: config.provider,
366
391
  model: config.model,
367
392
  passport_configured: passportConfigured,
@@ -2262,9 +2287,66 @@ async function agentCommand(rest, opts) {
2262
2287
  step("passport instead, and leaves this one working everywhere it already runs.");
2263
2288
  break;
2264
2289
  }
2290
+ // An agent's signed delegations to its workers (Bet D). A delegation is made
2291
+ // offline, so the gateway knows a link only once a worker has exchanged it; the
2292
+ // listing says so, and --all is the tool that reaches the ones never seen.
2293
+ case "delegations": {
2294
+ if (!args[0]) throw new Error("Usage: passcontrol agent delegations <agent-id> [--json]");
2295
+ const rows = await api("GET", `/agents/${encodeURIComponent(args[0])}/delegations`);
2296
+ if (opts.json) {
2297
+ console.log(JSON.stringify(rows, null, 2));
2298
+ break;
2299
+ }
2300
+ step("Only delegations a worker has used appear here. A delegation is signed offline, so the");
2301
+ step("gateway learns of it at its first exchange; `revoke-delegation --all` also reaches unseen ones.");
2302
+ if (!Array.isArray(rows) || rows.length === 0) {
2303
+ step("No worker has used a delegation from this agent yet.");
2304
+ break;
2305
+ }
2306
+ // Server text reaches a terminal: keep it to printable ASCII.
2307
+ const printable = (v) => String(v ?? "").replace(/[^\x20-\x7e]/g, "?").slice(0, 64);
2308
+ const now = Date.now();
2309
+ console.table(
2310
+ rows.map((d) => ({
2311
+ jti: printable(d.jti),
2312
+ depth: d.depth,
2313
+ status: d.revoked ? "revoked" : Date.parse(d.expires_at) <= now ? "expired" : "active",
2314
+ worker: `${printable(d.worker_key).slice(0, 12)}…`,
2315
+ cap: usd(d.cap_microcents),
2316
+ models: Array.isArray(d.scope)
2317
+ ? d.scope.map((s) => `${printable(s?.provider)}:${(Array.isArray(s?.models) ? s.models : []).map(printable).join("|")}`).join(", ")
2318
+ : "",
2319
+ expires: printable(d.expires_at).slice(0, 19),
2320
+ "first used": printable(d.first_exchanged_at).slice(0, 19),
2321
+ }))
2322
+ );
2323
+ break;
2324
+ }
2325
+ case "revoke-delegation": {
2326
+ const usage = "Usage: passcontrol agent revoke-delegation <agent-id> <jti>|--all";
2327
+ const [agentId, jti] = args;
2328
+ const all = opts.all === true;
2329
+ if (!agentId || all === Boolean(jti)) throw new Error(usage);
2330
+ const result = await api(
2331
+ "POST",
2332
+ `/agents/${encodeURIComponent(agentId)}/delegations/revoke`,
2333
+ all ? { all: true } : { jti }
2334
+ );
2335
+ ok(
2336
+ all
2337
+ ? `revoked every delegation agent ${agentId} issued before now, seen or not`
2338
+ : `revoked delegation ${jti} and every delegation under it`
2339
+ );
2340
+ step("This is permanent. To let a worker go on, the agent delegates to it again.");
2341
+ if (result?.immediate === false) {
2342
+ step("Recorded, but the gateway's fast copy could not be written: a worker holding a current");
2343
+ step("visa can keep calling until that visa expires (5 minutes by default).");
2344
+ }
2345
+ break;
2346
+ }
2265
2347
  default:
2266
2348
  throw new Error(
2267
- "Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]"
2349
+ "Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]|delegations <id>|revoke-delegation <id> <jti>|--all"
2268
2350
  );
2269
2351
  }
2270
2352
  }
@@ -2357,6 +2439,31 @@ async function sidecarCommand(rest, opts) {
2357
2439
  // sidecar mints on demand for the lifetime of the process, so a bad
2358
2440
  // destination has to be refused at start, not at the first proxied request.
2359
2441
  const gateway = requirePassportGateway(config);
2442
+ if (opts.profiles) {
2443
+ // Several identities, one process: one listener per profile, each with its own
2444
+ // passport, visa and journal (candidate 4). One terminal, one Ctrl-C.
2445
+ const names = String(opts.profiles).split(",").map((n) => n.trim()).filter(Boolean);
2446
+ for (const name of names) {
2447
+ const values = readProfile(name);
2448
+ if (!values?.PASSPORT_ID || !values?.PASSPORT_SECRET) {
2449
+ throw new Error(`Profile ${name} has no passport. Create it with ${cliCommand(`configure ${name} --dedicated --write`)}.`);
2450
+ }
2451
+ step(`Profile ${name}:`);
2452
+ startSidecar({
2453
+ gateway,
2454
+ passportId: values.PASSPORT_ID,
2455
+ passportSecret: values.PASSPORT_SECRET,
2456
+ keyStorage: null,
2457
+ port: sidecarPort({ port: values.SIDECAR_PORT }),
2458
+ host: String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1"),
2459
+ allowNonLoopback: Boolean(opts.allowNonLoopback),
2460
+ allowConnectHosts: [],
2461
+ refreshSkewSeconds: Number(opts.refreshSkewSeconds ?? process.env.REFRESH_SKEW_SECONDS ?? 30),
2462
+ noJournal: opts.journal === false || Boolean(opts.noJournal),
2463
+ });
2464
+ }
2465
+ return;
2466
+ }
2360
2467
  const { passportId, passportSecret, keyStorage } = requirePassport(config);
2361
2468
  startSidecar({
2362
2469
  gateway,
@@ -2382,6 +2489,10 @@ async function sidecarCommand(rest, opts) {
2382
2489
  .map((entry) => entry.trim())
2383
2490
  .filter(Boolean),
2384
2491
  refreshSkewSeconds: Number(opts.refreshSkewSeconds ?? process.env.REFRESH_SKEW_SECONDS ?? 30),
2492
+ // The receipt-id journal (cli/journal.mjs) is on unless the flag says off.
2493
+ // A flag only, like --allow-non-loopback: whether this machine keeps a record
2494
+ // is the operator's to state, not a config file's.
2495
+ noJournal: opts.journal === false || Boolean(opts.noJournal),
2385
2496
  });
2386
2497
 
2387
2498
  if (opts.for) {
@@ -2405,6 +2516,38 @@ function sidecarPort(opts = {}) {
2405
2516
  return port;
2406
2517
  }
2407
2518
 
2519
+ /**
2520
+ * The agent's budget as one line, read through the running sidecar (cli/statusline.mjs).
2521
+ * Never throws: whatever happens, Claude Code gets one line and a clean exit.
2522
+ */
2523
+ async function statuslineCommand(opts) {
2524
+ try {
2525
+ const port = sidecarPort(opts);
2526
+ // `--panel`: the several-line view `/passcontrol` shows in Claude Code (F3).
2527
+ // Without --port, the sidecar Claude Code's own ANTHROPIC_BASE_URL names.
2528
+ if (opts.panel) {
2529
+ const route = opts.port === undefined ? sidecarFromBaseUrl(process.env.ANTHROPIC_BASE_URL) : null;
2530
+ if (route?.remote) return notInPathText(route.remote);
2531
+ return await statusPanelText({
2532
+ port: route?.port ?? port,
2533
+ gateway: config.gateway,
2534
+ session: typeof opts.session === "string" ? opts.session : null,
2535
+ });
2536
+ }
2537
+ const cacheFile = path.join(path.dirname(globalConfigPath()), `statusline-${port}.json`);
2538
+ return await statuslineText({ port, cacheFile });
2539
+ } catch (error) {
2540
+ return `PassControl · ${error instanceof Error && /--port/.test(error.message) ? "bad --port" : "unavailable"}`;
2541
+ }
2542
+ }
2543
+
2544
+ /** The command Claude Code's settings run: the installed binary, or this checkout's. */
2545
+ function statusLineSettingsCommand(port) {
2546
+ const args = `statusline --port ${port}`;
2547
+ if (process.env.npm_lifecycle_event !== "cli") return `passcontrol ${args}`;
2548
+ return `node ${JSON.stringify(CLI_ENTRY)} ${args}`;
2549
+ }
2550
+
2408
2551
  function sidecarBaseUrl(opts = {}) {
2409
2552
  const provider = String(opts.provider || config.provider);
2410
2553
  assertProvider(provider);
@@ -2446,7 +2589,9 @@ function passControlMcpEntry() {
2446
2589
  }
2447
2590
 
2448
2591
  function printMcpPreset(integration, opts = {}) {
2449
- requireGlobalMcpPassport();
2592
+ // Claude Code's lines only point it at the sidecar, which holds the passport (as in
2593
+ // configureMcpClient); the MCP clients below launch `passcontrol mcp`, which needs it.
2594
+ if (integration !== "claude-code") requireGlobalMcpPassport();
2450
2595
  if (integration === "claude-code") {
2451
2596
  const { baseUrl } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
2452
2597
  console.log("# Route Claude Code's model calls through the sidecar (start it first):");
@@ -2619,16 +2764,29 @@ function configureClaudeCode(opts = {}) {
2619
2764
  if (!opts.write) {
2620
2765
  step(`Dry run only. Re-run with \`--write\` to merge these two keys${scope === "project" ? " (or --write --global for every session)" : ""}.`);
2621
2766
  } else {
2622
- const result = writeClaudeCodeSettings({ target, baseUrl, force: Boolean(opts.force) });
2767
+ const result = writeClaudeCodeSettings({
2768
+ target,
2769
+ baseUrl,
2770
+ force: Boolean(opts.force),
2771
+ statusLineCommand: opts.statusline ? statusLineSettingsCommand(port) : null,
2772
+ });
2623
2773
  if (!result.changed) ok(`${target} already routes Claude Code through PassControl`);
2624
2774
  else {
2625
2775
  if (result.backupPath) step(`backed up ${result.backupPath}`);
2626
2776
  ok(`wrote ${target}`);
2627
2777
  }
2778
+ if (result.statusLine?.existing) {
2779
+ warn(`${target} already has a status line (${result.statusLine.existing}); it was left as it is. To show the budget there, add \`${statusLineSettingsCommand(port)}\` to it yourself.`);
2780
+ } else if (result.statusLine?.changed) ok("added the agent's budget to Claude Code's status line");
2628
2781
  if (result.rawKeyFound) {
2629
2782
  warn(`${target} also holds a raw ANTHROPIC_API_KEY. PassControl does not need it there; remove it so no key sits on disk.`);
2630
2783
  }
2631
2784
  }
2785
+ if (opts.statusline && !opts.write) {
2786
+ step(`With --write, the status line would run: ${statusLineSettingsCommand(port)}`);
2787
+ } else if (!opts.statusline) {
2788
+ step(`Optional, the agent's budget in Claude Code's status line: ${cliCommand(`configure claude-code --write --statusline${scope === "user" ? " --global" : ""}`)}`);
2789
+ }
2632
2790
  step(`Start the sidecar before Claude Code: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
2633
2791
  step("The agent's Anthropic scope must allow the models Claude Code uses (its main model, and Haiku for small tasks).");
2634
2792
  step(`Optional, the chat tool as well: ${CLAUDE_CODE_ADD_COMMAND}`);
@@ -2660,6 +2818,68 @@ function printCodexPreset(opts = {}) {
2660
2818
  * Codex layers over its config when started with `--profile passcontrol`.
2661
2819
  * `--remove` deletes that file, and only when PassControl wrote it.
2662
2820
  */
2821
+ // ── One identity per coding tool (candidate 4, plans/one-identity-per-tool.md) ──
2822
+ //
2823
+ // `configure <tool> --dedicated` gives Claude Code or Codex its OWN agent: its own
2824
+ // passport, budget, scope and kill switch, served by its own sidecar port, kept in
2825
+ // a named profile (cli/profiles.mjs). Re-running reuses the profile; it never
2826
+ // creates a second agent.
2827
+ async function prepareDedicatedProfile(tool, opts) {
2828
+ const port = TOOL_PROFILE_PORTS[tool];
2829
+ opts.port = port;
2830
+ const existing = readProfile(tool);
2831
+ if (existing?.PASSPORT_ID && existing?.PASSPORT_SECRET) {
2832
+ opts.port = Number(existing.SIDECAR_PORT || port);
2833
+ step(`Using the ${tool} profile's own agent (passport …${existing.PASSPORT_ID.slice(-8)}), sidecar port ${opts.port}.`);
2834
+ return;
2835
+ }
2836
+ const label = tool === "claude-code" ? "Claude Code" : "Codex";
2837
+ const provider = tool === "claude-code" ? "anthropic" : "openai";
2838
+ const name = `${label} @ ${os.hostname().split(".")[0] || "this machine"}`;
2839
+ if (!opts.write) {
2840
+ step(`With --write: creates the agent "${name}" with its own passport, saved in the ${tool} profile, served on sidecar port ${port}.`);
2841
+ return;
2842
+ }
2843
+ requireControlApiKey(config);
2844
+ // The keypair is made here and only the public half leaves, as in `agent create`.
2845
+ // The profile is written FIRST, so a created agent never exists without its key on
2846
+ // this machine; if creating it fails, the profile is removed again.
2847
+ const priv = ed25519.utils.randomPrivateKey();
2848
+ const passportId = b64url(ed25519.getPublicKey(priv));
2849
+ writeProfile(tool, { PASSPORT_ID: passportId, PASSPORT_SECRET: b64url(priv), PASSPORT_KEY_STORAGE: "", SIDECAR_PORT: String(port) });
2850
+ let created;
2851
+ try {
2852
+ created = await api("POST", "/agents", {
2853
+ name,
2854
+ passportPubkey: passportId,
2855
+ scopes: [{ provider, models: [defaultAllowedModelForProvider(provider)] }],
2856
+ });
2857
+ } catch (error) {
2858
+ fs.rmSync(profilePath(tool), { force: true });
2859
+ throw error;
2860
+ }
2861
+ ok(`created agent ${created.id} (${created.name}); its passport is in the ${tool} profile and was not printed`);
2862
+ }
2863
+
2864
+ function dedicatedSidecarHint(tool) {
2865
+ step(`Run its own sidecar: ${cliCommand(`sidecar --profile ${tool}`)}`);
2866
+ step(`Both coding tools at once, each as its own agent: ${cliCommand("sidecar --profiles claude-code,codex")}`);
2867
+ }
2868
+
2869
+ function profileCommand(rest, opts) {
2870
+ if (rest[0] !== "list") throw new Error("Usage: passcontrol profile list");
2871
+ const rows = listProfiles().map((p) => ({ profile: p.name, passport: p.passportId ? `…${p.passportId.slice(-8)}` : "none", port: p.port || "-" }));
2872
+ if (opts.json) {
2873
+ console.log(JSON.stringify(rows, null, 2));
2874
+ return;
2875
+ }
2876
+ if (!rows.length) {
2877
+ step(`No profiles yet. Give a coding tool its own agent: ${cliCommand("configure claude-code --dedicated --write")}`);
2878
+ return;
2879
+ }
2880
+ for (const r of rows) console.log(`${r.profile.padEnd(20)} passport ${r.passport.padEnd(10)} port ${r.port}`);
2881
+ }
2882
+
2663
2883
  function configureCodex(opts = {}) {
2664
2884
  const target = codexProfilePath();
2665
2885
  if (opts.remove) {
@@ -2690,11 +2910,13 @@ function configureCodex(opts = {}) {
2690
2910
  }
2691
2911
 
2692
2912
  function configureMcpClient(integration, opts = {}) {
2693
- requireGlobalMcpPassport();
2913
+ // Claude Code's settings only point it at the sidecar, which holds the passport
2914
+ // itself; requiring one here also stopped `--remove` once the config was gone.
2694
2915
  if (integration === "claude-code") {
2695
2916
  configureClaudeCode(opts);
2696
2917
  return;
2697
2918
  }
2919
+ requireGlobalMcpPassport();
2698
2920
 
2699
2921
  const target = mcpClientConfigPath(integration);
2700
2922
  const entry = passControlMcpEntry();
@@ -2726,12 +2948,17 @@ async function configureCommand(rest, opts = {}) {
2726
2948
  `Unknown integration "${integration}". Use one of: ${integrationChoices()}.`
2727
2949
  );
2728
2950
  }
2951
+ if (opts.dedicated && (integration === "claude-code" || integration === "codex")) {
2952
+ await prepareDedicatedProfile(integration, opts);
2953
+ }
2729
2954
  if (integration === "codex") {
2730
2955
  configureCodex(opts);
2956
+ if (opts.dedicated) dedicatedSidecarHint(integration);
2731
2957
  return;
2732
2958
  }
2733
2959
  if (isMcpIntegration(integration)) {
2734
2960
  configureMcpClient(integration, opts);
2961
+ if (opts.dedicated && integration === "claude-code") dedicatedSidecarHint(integration);
2735
2962
  return;
2736
2963
  }
2737
2964
  if (!supportsWrite(integration)) {
@@ -3033,11 +3260,12 @@ async function verifyCommand(rest, opts) {
3033
3260
  const artifact = rest[1];
3034
3261
  const issuer = String(opts.issuer || process.env.PASSCONTROL_ISSUER || "");
3035
3262
 
3036
- if ((what !== "token" && what !== "receipt" && what !== "statement") || !artifact) {
3263
+ if ((what !== "token" && what !== "receipt" && what !== "statement" && what !== "session") || !artifact) {
3037
3264
  throw new Error(
3038
3265
  "Usage: passcontrol verify token <jwt> --audience <aud> --issuer <origin>\n" +
3039
3266
  " passcontrol verify receipt <jws> --issuer <origin>\n" +
3040
- " passcontrol verify statement <jws> --issuer <origin>"
3267
+ " passcontrol verify statement <jws> --issuer <origin>\n" +
3268
+ " passcontrol verify session <seal.json> [--journal <file>[,<file>]] --issuer <origin>"
3041
3269
  );
3042
3270
  }
3043
3271
  if (!issuer) {
@@ -3047,6 +3275,11 @@ async function verifyCommand(rest, opts) {
3047
3275
  );
3048
3276
  }
3049
3277
 
3278
+ if (what === "session") {
3279
+ await verifySessionCommand(artifact, opts, issuer);
3280
+ return;
3281
+ }
3282
+
3050
3283
  const result =
3051
3284
  what === "token"
3052
3285
  ? await verifyAgentToken(artifact, { issuer, audience: String(opts.audience || "") })
@@ -3096,6 +3329,17 @@ async function verifyCommand(rest, opts) {
3096
3329
  step(`Verdict: ${c.res?.status} (HTTP ${c.res?.http})`);
3097
3330
  step(`Usage: ${c.use?.in ?? 0} in / ${c.use?.out ?? 0} out · ${c.cost ?? 0} µ¢`);
3098
3331
  if (c.req) step(`Request: ${c.req.alg} ${c.req.dig} (${c.req.len} bytes)`);
3332
+ // Lineage is DECLARED by the client: any local process can send those
3333
+ // headers. Say so on the same line, so nobody reads it as passport-proven.
3334
+ // Printable ASCII only: a signed value is still not a terminal's to obey.
3335
+ if (c.ctx?.ses) {
3336
+ const shown = (v) => String(v).replace(/[^\x20-\x7e]/g, "?").slice(0, 128);
3337
+ const who = c.ctx.agt
3338
+ ? `sub-agent ${shown(c.ctx.agt)}${c.ctx.par ? `, spawned by ${shown(c.ctx.par)}` : ""}`
3339
+ : "main agent";
3340
+ step(`Session: ${shown(c.ctx.ses)} · ${who}`);
3341
+ step(` declared by the client (${shown(c.ctx.cli ?? "unknown")}), not verified`);
3342
+ }
3099
3343
  }
3100
3344
  if (c.own) {
3101
3345
  step(
@@ -3104,6 +3348,184 @@ async function verifyCommand(rest, opts) {
3104
3348
  }
3105
3349
  }
3106
3350
 
3351
+ // ── Session seals (sprint Q7) ───────────────────────────────────────────────
3352
+
3353
+ const SESSION_ARG_RE = /^[A-Za-z0-9._:-]{1,128}$/;
3354
+ const shown = (v) => String(v ?? "").replace(/[^\x20-\x7e]/g, "?").slice(0, 128);
3355
+
3356
+ /** The journal files the sidecar wrote (cli/journal.mjs): one JSON object per line. */
3357
+ function readJournals(spec) {
3358
+ const entries = [];
3359
+ for (const file of String(spec).split(",").map((f) => f.trim()).filter(Boolean)) {
3360
+ const text = fs.readFileSync(file, "utf8");
3361
+ for (const line of text.split("\n")) {
3362
+ if (!line.trim()) continue;
3363
+ try {
3364
+ entries.push(JSON.parse(line));
3365
+ } catch {
3366
+ // An unreadable line is passed through as-is, so the verifier reports the
3367
+ // journal as malformed instead of this command quietly skipping a call.
3368
+ entries.push(line);
3369
+ }
3370
+ }
3371
+ }
3372
+ return entries;
3373
+ }
3374
+
3375
+ async function verifySessionCommand(file, opts, issuer) {
3376
+ let parsed;
3377
+ try {
3378
+ parsed = JSON.parse(fs.readFileSync(String(file), "utf8"));
3379
+ } catch (e) {
3380
+ fail(`Could not read ${shown(file)}: ${e.message}`);
3381
+ process.exitCode = 1;
3382
+ return;
3383
+ }
3384
+ // Accepts the control API's response as saved ({ data: { seal, bundle } }) or
3385
+ // just { seal, bundle }, which is what `passcontrol seal` writes.
3386
+ const doc = parsed?.data && typeof parsed.data === "object" ? parsed.data : parsed;
3387
+ const journal = opts.journal && opts.journal !== true ? readJournals(opts.journal) : undefined;
3388
+ const r = await verifySession({ seal: doc?.seal, bundle: doc?.bundle, journal }, { issuer });
3389
+
3390
+ if (!r.checks.signature) {
3391
+ fail(`Not valid: ${FAILURE_REASONS[r.reason] ?? r.reason}`);
3392
+ process.exitCode = 1;
3393
+ return;
3394
+ }
3395
+ const c = r.claims;
3396
+ (r.ok ? ok : fail)(r.ok ? "Session seal is valid." : "Session seal did not pass every check.");
3397
+ step(`Issuer: ${shown(c.iss)}`);
3398
+ step(`Agent: ${shown(c.sub)}`);
3399
+ step(`Session: ${shown(c.ses?.id)} · declared by the client (${shown(c.ses?.src)}), not verified`);
3400
+ step(`Window: ${new Date(c.per?.from * 1000).toISOString()} → ${new Date(c.per?.to * 1000).toISOString()}`);
3401
+ step(`Covers: ${c.n} of ${c.nr} logged calls · ${c.cost} µ¢`);
3402
+ if (c.unp) step(` ${c.unp} call(s) could not be priced: that cost is unknown, not zero.`);
3403
+ if (c.unk) step(` ${c.unk} call(s) have no recorded cost and no recorded reason.`);
3404
+ for (const node of Array.isArray(c.tree) ? c.tree : []) {
3405
+ const who = node.agt ? `sub-agent ${shown(node.agt)}${node.par ? ` (spawned by ${shown(node.par)})` : ""}` : "main agent";
3406
+ step(` ${who}: ${node.n} call(s), ${node.cost} µ¢${node.refused ? `, ${node.refused} refused` : ""}`);
3407
+ }
3408
+ step("");
3409
+
3410
+ ok("Signature matches the issuer's published key");
3411
+ if (r.checks.bundle) ok(`Bundle: the root and every total recompute from its ${doc.bundle.length} receipt(s)`);
3412
+ else fail(`Bundle: these do not match the receipts it came with: ${r.mismatched.join(", ") || r.reason}`);
3413
+ if (r.checks.receipts === null) step("Receipts: not checked");
3414
+ else if (r.checks.receipts) ok("Receipts: every one verifies and belongs to this agent, session and window");
3415
+ else {
3416
+ fail(`Receipts: ${r.rejected.length} not accepted`);
3417
+ for (const x of r.rejected) step(` #${x.index} ${shown(x.id ?? "?")}: ${FAILURE_REASONS[x.reason] ?? x.reason}`);
3418
+ }
3419
+
3420
+ if (r.checks.journal === null) {
3421
+ step("No journal given. Without your own record this proves no more than a statement does:");
3422
+ step(" that the issuer committed to these receipts, not that it left none out.");
3423
+ step(" Pass --journal with the file your sidecar printed when it started.");
3424
+ } else if (r.reason === "malformed_journal") {
3425
+ fail("Journal: could not be read as a list of receipt ids.");
3426
+ } else if (r.checks.journal) {
3427
+ ok("Journal: every call your sidecar recorded is in the seal");
3428
+ } else {
3429
+ fail(`Journal: ${r.missing.length} call(s) your sidecar recorded are missing from the seal:`);
3430
+ for (const id of r.missing) step(` ${shown(id)}`);
3431
+ step(" Missing means not in this seal. The gateway's log write can fail on its own,");
3432
+ step(" so a missing call can be a lost record as easily as one left out.");
3433
+ }
3434
+ if (r.otherSessions) {
3435
+ step(`Your journal also holds ${r.otherSessions} call(s) from other sessions of the same sidecar run; not checked against this seal.`);
3436
+ }
3437
+ if (r.unjournaled.length) {
3438
+ step(`In the seal but not in your journal (reported, not a failure): ${r.unjournaled.length}`);
3439
+ for (const x of r.unjournaled) {
3440
+ step(` ${shown(x.id)}${x.why === "failover_predecessor" ? " (an earlier attempt of a failed-over call)" : ""}`);
3441
+ }
3442
+ }
3443
+ if (!r.ok) process.exitCode = 1;
3444
+ }
3445
+
3446
+ async function sealCommand(rest, opts) {
3447
+ const session = rest[0];
3448
+ if (!session || !SESSION_ARG_RE.test(session)) {
3449
+ throw new Error("Usage: passcontrol seal <session> --agent <agent-id> [--out FILE]");
3450
+ }
3451
+ if (!opts.agent || opts.agent === true) {
3452
+ throw new Error("Name the agent: passcontrol seal <session> --agent <agent-id> (see `passcontrol sessions`).");
3453
+ }
3454
+ let data;
3455
+ try {
3456
+ data = await api("POST", `/sessions/${encodeURIComponent(session)}/seal`, { agent_id: String(opts.agent) });
3457
+ } catch (e) {
3458
+ // api() leads with the status, then the error code. The route's own 404 carries
3459
+ // `not_found`; a gateway without the route (self-host: sealing is a hosted
3460
+ // capability, the format and verifier are not) answers with no code at all.
3461
+ const message = String(e?.message || "");
3462
+ if (/^404 not_found\b/.test(message)) {
3463
+ throw new Error(`No session ${session} for agent ${opts.agent} on this gateway (see \`passcontrol sessions\`).`);
3464
+ }
3465
+ if (/^404\b/.test(message)) {
3466
+ throw new Error(
3467
+ "This gateway does not seal sessions. Sealing is a hosted capability; checking a seal works anywhere:\n" +
3468
+ " passcontrol verify session <seal.json> --journal <file> --issuer <origin>"
3469
+ );
3470
+ }
3471
+ throw e;
3472
+ }
3473
+ const file = String(opts.out && opts.out !== true ? opts.out : `session-${session}.seal.json`);
3474
+ // It is spend and call volume: owner-only, like the journal it is checked against.
3475
+ fs.writeFileSync(file, JSON.stringify({ seal: data.seal, bundle: data.bundle }, null, 2) + "\n", { mode: 0o600 });
3476
+ fs.chmodSync(file, 0o600);
3477
+ ok(`Sealed ${data.bundle?.length ?? 0} receipt(s) → ${file}`);
3478
+ // The issuer the seal names, not the gateway just called: the two can differ (a
3479
+ // self-host behind a proxy), and the issuer is the one a verifier must trust.
3480
+ // Read without verifying, only to print a suggestion; `verify session` checks it.
3481
+ let issuer = requireControlGateway(config);
3482
+ try {
3483
+ const claims = JSON.parse(Buffer.from(String(data.seal).split(".")[1] ?? "", "base64url").toString("utf8"));
3484
+ if (typeof claims?.iss === "string") issuer = shown(claims.iss);
3485
+ } catch {
3486
+ // Not a JWS: verify session will say so. Keep the gateway as the suggestion.
3487
+ }
3488
+ step(`Check it: passcontrol verify session ${file} --journal <your sidecar journal> --issuer ${issuer}`);
3489
+ }
3490
+
3491
+ async function sessionsCommand(opts) {
3492
+ let rows;
3493
+ try {
3494
+ rows = await api(
3495
+ "GET",
3496
+ controlPath("/sessions", { agent_id: opts.agent === true ? undefined : opts.agent, limit: safeLimit(opts.limit) })
3497
+ );
3498
+ } catch (e) {
3499
+ if (/^404\b/.test(String(e?.message || ""))) {
3500
+ step("This gateway does not serve sessions. Verifying a seal works anywhere:");
3501
+ step(" passcontrol verify session <seal.json> --journal <file> --issuer <origin>");
3502
+ return;
3503
+ }
3504
+ throw e;
3505
+ }
3506
+ if (opts.json) {
3507
+ console.log(JSON.stringify(rows, null, 2));
3508
+ return;
3509
+ }
3510
+ if (!Array.isArray(rows) || rows.length === 0) {
3511
+ step("No sessions yet. Calls appear here once Claude Code or Codex (or a sidecar run) declares one.");
3512
+ return;
3513
+ }
3514
+ step("Sessions are declared by the client: they group calls, they do not prove who made them.");
3515
+ console.table(
3516
+ rows.map((row) => ({
3517
+ session: shown(row.session_id).slice(0, 36),
3518
+ via: row.client_kind,
3519
+ agent: String(row.agent_id ?? "").slice(0, 8),
3520
+ calls: row.calls,
3521
+ "sub-agents": row.subagents,
3522
+ refused: row.refused,
3523
+ cost: usd(row.cost_microcents) + (Number(row.unknown_cost) ? ` + ${row.unknown_cost} unknown` : ""),
3524
+ last: String(row.last_at ?? "").slice(0, 19),
3525
+ }))
3526
+ );
3527
+ }
3528
+
3107
3529
  /**
3108
3530
  * The chain of signed spend statements for this workspace.
3109
3531
  *
@@ -3946,6 +4368,20 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
3946
4368
  const { opts, rest } = parseArgv(argv);
3947
4369
  const [command, ...commandRest] = rest;
3948
4370
 
4371
+ // First, before the update check or anything else that could print or wait:
4372
+ // Claude Code shows this command's whole stdout as its status line, runs it
4373
+ // after every assistant message, and cancels a run that is still going.
4374
+ if (command === "statusline") {
4375
+ console.log(await statuslineCommand(opts));
4376
+ return;
4377
+ }
4378
+
4379
+ // Also before the update check: a full-screen board owns the terminal from its
4380
+ // first frame, and the check's cache would be the one file `watch` ever wrote.
4381
+ if (command === "watch" && !opts.help) {
4382
+ process.exit(await runWatch({ port: sidecarPort(opts) }));
4383
+ }
4384
+
3949
4385
  // Started here and awaited at the very end, so the registry lookup overlaps
3950
4386
  // the command instead of being tacked onto the exit. On anything that touches
3951
4387
  // the network — which is most of this CLI — it costs nothing measurable, and
@@ -4047,6 +4483,9 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
4047
4483
  " `passcontrol login` now does the same thing with YOUR agent rather than a\n" +
4048
4484
  " shared demo one: a governed call and a signed receipt you can verify."
4049
4485
  );
4486
+ case "profile":
4487
+ profileCommand(commandRest, opts);
4488
+ break;
4050
4489
  case "sidecar":
4051
4490
  await sidecarCommand(commandRest, opts);
4052
4491
  break;
@@ -4075,6 +4514,12 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
4075
4514
  case "statements":
4076
4515
  await statementsCommand(opts);
4077
4516
  break;
4517
+ case "sessions":
4518
+ await sessionsCommand(opts);
4519
+ break;
4520
+ case "seal":
4521
+ await sealCommand(commandRest, opts);
4522
+ break;
4078
4523
  case "kill":
4079
4524
  await killCommand(commandRest);
4080
4525
  break;