passcontrol 1.4.0 → 1.5.1

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.
package/cli/sidecar.mjs CHANGED
@@ -5,8 +5,14 @@ import { Readable } from "node:stream";
5
5
  import { bareGatewayOrigin, fail, ok, step, warn } from "./config.mjs";
6
6
  import { classifyConnect, classifyProxyRequest, isLoopbackBindHost } from "./proxy-policy.mjs";
7
7
  import { createVisaClient } from "./visa-client.mjs";
8
- import { declaredSession } from "./declared-session.mjs";
8
+ import { declaredLineage, declaredSession } from "./declared-session.mjs";
9
9
  import { defaultJournalDir, openJournal } from "./journal.mjs";
10
+ import { answer, createWatchFeed, isNotACall, isLocalCaller, LOCAL_PREFIX, peekText, providerOf, refusalCode, requestModel } from "./watch-feed.mjs";
11
+ import { createStopGate, HOOK_PATH, selfAnswerState } from "./subscription-gate.mjs";
12
+ import { createToolGate } from "./tool-gate.mjs";
13
+ import { OTLP_LOGS_PATH, readClaudeCodeEvents } from "./otlp-logs.mjs";
14
+ import { CLIENT_EVENTS_PATH, CLIENT_EVENTS_SOURCE, createCallUploader } from "./client-events-upload.mjs";
15
+ import { heldUsageWindow, WINDOW_PATH } from "./usage-window.mjs";
10
16
 
11
17
  // Hop-by-hop headers plus the ones the sidecar rebuilds itself. `proxy-connection`
12
18
  // and friends only appear once something is used as a FORWARD proxy, which is
@@ -45,6 +51,24 @@ function isStripped(name) {
45
51
  const STRIP_RES = new Set(["content-encoding", "content-length", "transfer-encoding", "connection"]);
46
52
 
47
53
  const STATUS_TEXT = { 400: "Bad Request", 403: "Forbidden", 502: "Bad Gateway" };
54
+ // An OTLP log export batches every event of a few seconds; Claude Code's run ~30 KB.
55
+ const OTLP_BODY_LIMIT = 4 * 1024 * 1024;
56
+ // Sessions whose calls this sidecar relays, remembered so their telemetry is not
57
+ // counted a second time. Bounded: the oldest is forgotten first.
58
+ const RELAYED_SESSIONS_MAX = 1000;
59
+
60
+ // Claude Code's hook input carries the tool's input (a whole file for Write), so it
61
+ // is not small; past this it is refused rather than buffered.
62
+ const HOOK_BODY_LIMIT = 1024 * 1024;
63
+
64
+ // How long Claude Code waits for the hook, as configure wrote it into the URL
65
+ // (`?t=600`); null for a hook that does not say (a Phase 1 install).
66
+ function hookTimeoutS(url) {
67
+ const t = new URL(url ?? "/", "http://127.0.0.1").searchParams.get("t");
68
+ return t !== null && /^\d{1,4}$/.test(t) && Number(t) > 0 ? Number(t) : null;
69
+ }
70
+ // A usage window is two numbers and two times.
71
+ const WINDOW_BODY_LIMIT = 4 * 1024;
48
72
 
49
73
  /**
50
74
  * A header value is a single line of printable ASCII, always.
@@ -115,6 +139,13 @@ export function createSidecar({
115
139
  runId = randomUUID(),
116
140
  // cli/journal.mjs, or null for `--no-journal`.
117
141
  journal = null,
142
+ // `passcontrol watch`'s feed (cli/watch-feed.mjs). Off when bound off loopback.
143
+ watchFeed = isLoopbackBindHost(host),
144
+ watchCapacity = 200,
145
+ watchMaxSubscribers = 8,
146
+ // Subscription mode, Phase 1b: upload the calls Claude Code reports to the
147
+ // gateway's agent page (cli/client-events-upload.mjs). `--no-report-calls` turns it off.
148
+ reportCalls = true,
118
149
  }) {
119
150
  // The upstream URL below is built from this, not from the argument: the
120
151
  // sidecar forwards a bearer visa on every proxied request, so its destination
@@ -131,6 +162,264 @@ export function createSidecar({
131
162
 
132
163
  // Used only to print the governed base URL back in a refusal. Read from the
133
164
  // live listener when there is one so the advice names the port actually bound.
165
+ const feed = createWatchFeed({ runId, capacity: watchCapacity, maxSubscribers: watchMaxSubscribers, enabled: watchFeed });
166
+ const lineageOf = (headers) =>
167
+ declaredLineage((name) => {
168
+ const v = headers?.[name];
169
+ return Array.isArray(v) ? v[0] : v;
170
+ }, runId);
171
+
172
+ // Subscription mode's Stop (cli/subscription-gate.mjs): Claude Code's hooks ask
173
+ // here, and the answer comes from the gateway's /api/v1/self, read with this
174
+ // sidecar's visa and the session the hook names.
175
+ const SELF_TIMEOUT_MS = 2_000;
176
+ async function readSelf(session) {
177
+ try {
178
+ const response = await visas.fetchWithVisa((visa) => {
179
+ // The tool rules ride on every gate read (Phase 2): no call of their own.
180
+ const path = "/api/v1/self?include=tool_rules";
181
+ const headers = {
182
+ accept: "application/json",
183
+ authorization: `Bearer ${visa}`,
184
+ "x-passcontrol-run": runId,
185
+ "x-passcontrol-proof": visas.createProof(visa, "GET", new URL(path, origin)),
186
+ "accept-encoding": "identity",
187
+ };
188
+ if (session) headers["x-claude-code-session-id"] = session;
189
+ return fetch(`${origin}${path}`, { headers, signal: AbortSignal.timeout(SELF_TIMEOUT_MS) });
190
+ });
191
+ return await selfAnswerState(response);
192
+ } catch (error) {
193
+ return { state: "unknown", reason: error?.name === "TimeoutError" ? "the gateway did not answer in time" : (error?.message ?? "error") };
194
+ }
195
+ }
196
+ const stopGate = createStopGate({ readSelf, dashboardUrl: `${origin}/dashboard` });
197
+
198
+ // Phase 2's `ask_owner` tool rules: the gateway asks the owner (their alert
199
+ // destination is in its Vault) and holds each request a few seconds; this asks
200
+ // again until the owner answers or the tool gate's wait runs out.
201
+ const TOOL_APPROVALS_PATH = "/api/v1/tool-approvals";
202
+ const APPROVAL_REQUEST_TIMEOUT_MS = 25_000;
203
+ const APPROVAL_RETRY_MS = 1_000;
204
+ async function askOwner(input, { session, waitMs }) {
205
+ const deadline = Date.now() + waitMs;
206
+ const body = JSON.stringify({ session: session ?? undefined, tool_name: input.tool_name, tool_input: input.tool_input, cwd: input.cwd });
207
+ while (Date.now() < deadline - 500) {
208
+ let response;
209
+ try {
210
+ response = await visas.fetchWithVisa((visa) => {
211
+ const headers = {
212
+ "content-type": "application/json",
213
+ authorization: `Bearer ${visa}`,
214
+ "x-passcontrol-run": runId,
215
+ "x-passcontrol-proof": visas.createProof(visa, "POST", new URL(TOOL_APPROVALS_PATH, origin)),
216
+ "accept-encoding": "identity",
217
+ };
218
+ if (session) headers["x-claude-code-session-id"] = session;
219
+ return fetch(`${origin}${TOOL_APPROVALS_PATH}`, {
220
+ method: "POST",
221
+ headers,
222
+ body,
223
+ signal: AbortSignal.timeout(Math.min(APPROVAL_REQUEST_TIMEOUT_MS, Math.max(1_000, deadline - Date.now()))),
224
+ });
225
+ });
226
+ } catch {
227
+ // The gateway did not answer this round: ask again while there is time.
228
+ await new Promise((resolve) => setTimeout(resolve, Math.min(APPROVAL_RETRY_MS, Math.max(0, deadline - Date.now()))));
229
+ continue;
230
+ }
231
+ const answered = await response.json().catch(() => ({}));
232
+ if (response.status === 409) return { state: "refused" };
233
+ if (response.status === 413) return { state: "too_large" };
234
+ if (response.status !== 200) return { state: "unavailable" };
235
+ if (["approved", "denied", "full"].includes(answered?.state)) return { state: answered.state };
236
+ if (answered?.state !== "pending") return { state: "unavailable" };
237
+ }
238
+ return { state: "timeout" };
239
+ }
240
+
241
+ // The reported calls go to the gateway as this agent, straight from here: never
242
+ // through this sidecar's own listener, so they are never a call on the board.
243
+ const UPLOAD_TIMEOUT_MS = 10_000;
244
+ async function sendReportedCalls(events) {
245
+ const response = await visas.fetchWithVisa((visa) =>
246
+ fetch(`${origin}${CLIENT_EVENTS_PATH}`, {
247
+ method: "POST",
248
+ headers: {
249
+ "content-type": "application/json",
250
+ authorization: `Bearer ${visa}`,
251
+ "x-passcontrol-run": runId,
252
+ "x-passcontrol-proof": visas.createProof(visa, "POST", new URL(CLIENT_EVENTS_PATH, origin)),
253
+ "accept-encoding": "identity",
254
+ },
255
+ body: JSON.stringify({ source: CLIENT_EVENTS_SOURCE, events }),
256
+ signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
257
+ })
258
+ );
259
+ const body = await response.json().catch(() => ({}));
260
+ return { status: response.status, error: body?.error, retryAfterS: Number(response.headers.get("retry-after")) };
261
+ }
262
+ const uploader = reportCalls ? createCallUploader({ send: sendReportedCalls }) : null;
263
+ // Its decisions reach the agent's page with the reported calls (same opt-out).
264
+ const toolGate = createToolGate({
265
+ askOwner,
266
+ dashboardUrl: `${origin}/dashboard`,
267
+ onDecision: (record) => uploader?.add({ kind: "tool_decision", at: Date.now(), ...record }),
268
+ });
269
+
270
+ const relayedSessions = new Set();
271
+ function rememberRelayed(headers) {
272
+ const session = lineageOf(headers)?.session;
273
+ if (!session || relayedSessions.has(session)) return;
274
+ relayedSessions.add(session);
275
+ if (relayedSessions.size > RELAYED_SESSIONS_MAX) relayedSessions.delete(relayedSessions.values().next().value);
276
+ }
277
+
278
+ /** Reads a local caller's body up to `limit`; resolves null when it is over. */
279
+ function readLocalBody(req, limit) {
280
+ return new Promise((resolve) => {
281
+ const chunks = [];
282
+ let size = 0;
283
+ let over = false;
284
+ req.on("data", (c) => {
285
+ size += c.length;
286
+ if (size > limit) over = true;
287
+ else chunks.push(c);
288
+ });
289
+ req.on("end", () => resolve(over ? null : Buffer.concat(chunks)));
290
+ req.on("error", () => resolve(null));
291
+ });
292
+ }
293
+
294
+ // Subscription mode's telemetry (cli/otlp-logs.mjs): Claude Code's log exporter
295
+ // posts here. Answered as an OTLP collector does, `{}` on success.
296
+ async function serveOtlpLogs(req, res) {
297
+ const port = server.address()?.port;
298
+ if (req.method !== "POST") {
299
+ req.resume();
300
+ return answer(res, 405, "method_not_allowed", "The telemetry endpoint answers POST only.");
301
+ }
302
+ if (!isLocalCaller(req, port)) {
303
+ req.resume();
304
+ return answer(res, 403, "telemetry_refused", "The telemetry endpoint is for Claude Code on this machine only.");
305
+ }
306
+ if (!String(req.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) {
307
+ req.resume();
308
+ return answer(res, 415, "telemetry_protocol", "Send OTLP as JSON: set OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json.");
309
+ }
310
+ const raw = await readLocalBody(req, OTLP_BODY_LIMIT);
311
+ if (raw === null) return answer(res, 413, "telemetry_too_large", "Log export over 4 MB.");
312
+ let body;
313
+ try {
314
+ body = JSON.parse(raw.toString("utf8"));
315
+ } catch {
316
+ return answer(res, 400, "telemetry_not_json", "The log export is not JSON.");
317
+ }
318
+ for (const event of readClaudeCodeEvents(body)) {
319
+ if (event.session && relayedSessions.has(event.session)) continue;
320
+ feed.report({
321
+ at: event.at ?? Date.now(),
322
+ lineage: { session: event.session, agent: event.agent },
323
+ model: event.model,
324
+ provider: "anthropic",
325
+ outcome: event.kind === "api_request" ? "seen" : "error",
326
+ status: event.status,
327
+ ms: event.durationMs,
328
+ cost: event.costMicros,
329
+ });
330
+ uploader?.add(event);
331
+ }
332
+ res.writeHead(200, { "content-type": "application/json", "content-length": 2, "cache-control": "no-store" });
333
+ res.end("{}");
334
+ }
335
+
336
+ // Subscription mode's usage window (cli/usage-window.mjs): the status line posts
337
+ // what Claude Code told it; `watch` gets it on the feed, `/passcontrol` asks for it.
338
+ async function serveWindow(req, res) {
339
+ const port = server.address()?.port;
340
+ if (req.method !== "GET" && req.method !== "POST") {
341
+ req.resume();
342
+ return answer(res, 405, "method_not_allowed", "The usage-window endpoint answers GET and POST only.");
343
+ }
344
+ if (!isLocalCaller(req, port)) {
345
+ req.resume();
346
+ return answer(res, 403, "window_refused", "The usage-window endpoint is for this machine only.");
347
+ }
348
+ if (req.method === "GET") {
349
+ req.resume();
350
+ const current = feed.window();
351
+ if (!current) return answer(res, 404, "window_unknown", "No usage window reported yet.");
352
+ const body = JSON.stringify({ fiveHour: current.fiveHour, sevenDay: current.sevenDay, at: current.at });
353
+ res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(body), "cache-control": "no-store" });
354
+ return res.end(body);
355
+ }
356
+ const raw = await readLocalBody(req, WINDOW_BODY_LIMIT);
357
+ let window = null;
358
+ try {
359
+ window = raw === null ? null : heldUsageWindow(JSON.parse(raw.toString("utf8")));
360
+ } catch {
361
+ window = null;
362
+ }
363
+ if (!window) return answer(res, 400, "window_invalid", "Expected a usage window: { fiveHour, sevenDay }.");
364
+ feed.setWindow(window);
365
+ res.writeHead(204, { "cache-control": "no-store" });
366
+ res.end();
367
+ }
368
+
369
+ function serveHook(req, res) {
370
+ const port = server.address()?.port;
371
+ if (req.method !== "POST") {
372
+ req.resume();
373
+ return answer(res, 405, "method_not_allowed", "The hook endpoint answers POST only.");
374
+ }
375
+ if (!isLocalCaller(req, port)) {
376
+ req.resume();
377
+ return answer(res, 403, "hook_refused", "The hook endpoint is for Claude Code on this machine only.");
378
+ }
379
+ const chunks = [];
380
+ let size = 0;
381
+ let tooBig = false;
382
+ req.on("data", (c) => {
383
+ size += c.length;
384
+ if (size > HOOK_BODY_LIMIT) tooBig = true;
385
+ else chunks.push(c);
386
+ });
387
+ req.on("end", async () => {
388
+ if (tooBig) return answer(res, 413, "hook_too_large", "Hook input over 1 MB.");
389
+ let input;
390
+ try {
391
+ input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
392
+ } catch {
393
+ input = null;
394
+ }
395
+ if (!input || typeof input !== "object" || Array.isArray(input)) {
396
+ return answer(res, 400, "hook_not_json", "Expected Claude Code's hook input, a JSON object.");
397
+ }
398
+ let out;
399
+ try {
400
+ out = await stopGate.decide(input);
401
+ } catch {
402
+ out = {};
403
+ }
404
+ // A stop ends the turn whatever the tool rules say; otherwise a PreToolUse is
405
+ // the tool gate's, which needs to know how long Claude Code waits for this hook.
406
+ if (out.continue !== false && input.hook_event_name === "PreToolUse") {
407
+ let tool;
408
+ try {
409
+ tool = await toolGate.decide(input, stopGate.toolRules(), hookTimeoutS(req.url));
410
+ } catch {
411
+ tool = {};
412
+ }
413
+ const messages = [out.systemMessage, tool.systemMessage].filter(Boolean);
414
+ out = { ...tool, ...(messages.length ? { systemMessage: messages.join("\n") } : {}) };
415
+ }
416
+ const body = JSON.stringify(out);
417
+ res.writeHead(200, { "content-type": "application/json", "content-length": Buffer.byteLength(body), "cache-control": "no-store" });
418
+ res.end(body);
419
+ });
420
+ req.on("error", () => res.destroy());
421
+ }
422
+
134
423
  const localBaseUrl = () => {
135
424
  const address = server?.listening ? server.address() : null;
136
425
  return `http://${host}:${address?.port ?? port}`;
@@ -165,7 +454,11 @@ export function createSidecar({
165
454
  // URL — codeload for an archive download — passes through untouched.
166
455
  const toLocal = (value) => value.split(`${origin}/api/v1/`).join(`${localBaseUrl()}/api/v1/`);
167
456
 
168
- function writeResponse(res, upstream, reqHeaders) {
457
+ // `watch` is the board's handle on this call ({ call, startedAt }), or null for one
458
+ // the board does not show. Its outcome is read from the status and, for an error,
459
+ // from a capped peek at a CLONE of the body, so the client's bytes are untouched
460
+ // and nothing here waits on the peek.
461
+ function writeResponse(res, upstream, reqHeaders, watch = null) {
169
462
  // At the headers, not at the end of the body: a streamed call whose client
170
463
  // disconnects mid-stream still produced a receipt, and the user's record of
171
464
  // it must not depend on how long they kept reading. With the session the call
@@ -184,33 +477,89 @@ export function createSidecar({
184
477
  if (STRIP_RES.has(name)) return;
185
478
  outHeaders[k] = name === "link" || name === "location" ? toLocal(v) : v;
186
479
  });
480
+ let peek = null;
481
+ if (watch) {
482
+ const ttfb = Date.now() - watch.startedAt;
483
+ const status = upstream.status;
484
+ res.on("close", () => watch.call.finish());
485
+ if (status < 400) watch.call.settle({ outcome: "boarded", status, ttfb });
486
+ else if (!upstream.body) watch.call.settle({ outcome: "error", status, ttfb });
487
+ else {
488
+ try {
489
+ peek = upstream.clone().body;
490
+ } catch {
491
+ watch.call.settle({ outcome: "error", status, ttfb });
492
+ }
493
+ if (peek) {
494
+ peekText(peek).then((text) => {
495
+ const code = refusalCode(text);
496
+ watch.call.settle({ outcome: code ? "denied" : "error", code, status, ttfb });
497
+ });
498
+ }
499
+ }
500
+ }
187
501
  res.writeHead(upstream.status, outHeaders);
188
502
  if (upstream.body) Readable.fromWeb(upstream.body).pipe(res);
189
503
  else res.end();
190
504
  }
191
505
 
506
+ /** Begins the board's record of a forwarded call, unless it is not a call (the budget read, an upload). */
507
+ function watchCall(req, path, body, startedAt) {
508
+ if (isNotACall(path)) return null;
509
+ rememberRelayed(req.headers);
510
+ try {
511
+ return { startedAt, call: feed.begin({ startedAt, lineage: lineageOf(req.headers), model: requestModel(body), provider: providerOf(path) }) };
512
+ } catch {
513
+ return null;
514
+ }
515
+ }
516
+
517
+ /** A forwarded call that failed before the gateway answered: shown, then answered 502. */
518
+ function upstreamFailed(res, watch, req, path, e) {
519
+ if (!res.headersSent) {
520
+ if (watch) {
521
+ watch.call.settle({ outcome: "error", code: "sidecar_upstream_error", status: 502 });
522
+ watch.call.finish();
523
+ } else if (!isNotACall(path)) {
524
+ feed.record({ outcome: "error", code: "sidecar_upstream_error", status: 502, lineage: lineageOf(req.headers), provider: providerOf(path) });
525
+ }
526
+ res.writeHead(502, { "content-type": "application/json" });
527
+ res.end(JSON.stringify({ error: "sidecar_upstream_error", message: e.message }));
528
+ } else {
529
+ res.end();
530
+ }
531
+ }
532
+
192
533
  const server = http.createServer(async (req, res) => {
534
+ // The sidecar's own paths: answered here, never forwarded with a visa.
535
+ if (String(req.url ?? "").startsWith(LOCAL_PREFIX)) {
536
+ const localPath = String(req.url).split("?")[0];
537
+ if (localPath === HOOK_PATH) return serveHook(req, res);
538
+ if (localPath === OTLP_LOGS_PATH) return serveOtlpLogs(req, res);
539
+ if (localPath === WINDOW_PATH) return serveWindow(req, res);
540
+ feed.serve(req, res, { port: server.address()?.port });
541
+ return;
542
+ }
543
+ const startedAt = Date.now();
193
544
  // Judge the destination before reading the body: a refused host should not
194
545
  // get to make the sidecar buffer megabytes on its way to a 403.
195
546
  const verdict = classifyProxyRequest({ url: req.url, gatewayOrigin: origin, localBaseUrl: localBaseUrl() });
196
547
  if (!verdict.allow) {
197
548
  req.resume();
198
549
  onRefusal(verdict);
550
+ feed.record({ outcome: "denied", code: verdict.code, status: verdict.status, lineage: lineageOf(req.headers), startedAt });
199
551
  writeRefusal(res, verdict);
200
552
  return;
201
553
  }
202
554
 
555
+ let watch = null;
203
556
  try {
204
557
  const body = await readBody(req);
558
+ watch = watchCall(req, verdict.path, body, startedAt);
205
559
  const upstream = await visas.fetchWithVisa((visa) => fetchUpstream(req, verdict.path, body, visa));
206
- writeResponse(res, upstream, req.headers);
560
+ writeResponse(res, upstream, req.headers, watch);
207
561
  } catch (e) {
208
- if (!res.headersSent) {
209
- res.writeHead(502, { "content-type": "application/json" });
210
- res.end(JSON.stringify({ error: "sidecar_upstream_error", message: e.message }));
211
- } else {
212
- res.end();
213
- }
562
+ upstreamFailed(res, watch, req, verdict.path, e);
214
563
  }
215
564
  });
216
565
 
@@ -239,24 +588,24 @@ export function createSidecar({
239
588
  const probe = url.pathname === "/";
240
589
  const mapped = `/api/v1/local${probe ? "/api/version" : url.pathname}${probe ? "" : url.search}`;
241
590
  const method = probe ? "GET" : req.method;
591
+ const startedAt = Date.now();
592
+ let watch = null;
242
593
  try {
243
594
  const body = probe ? null : await readBody(req);
244
595
  if (probe) req.resume();
596
+ watch = watchCall(req, mapped, body, startedAt);
245
597
  const upstream = await visas.fetchWithVisa((visa) => fetchUpstream({ method, headers: req.headers }, mapped, body, visa));
246
598
  if (req.method === "HEAD") {
599
+ watch?.call.settle({ outcome: upstream.status < 400 ? "boarded" : "error", status: upstream.status, ttfb: Date.now() - startedAt });
600
+ watch?.call.finish();
247
601
  res.writeHead(upstream.status);
248
602
  res.end();
249
603
  await upstream.body?.cancel().catch(() => {});
250
604
  return;
251
605
  }
252
- writeResponse(res, upstream, req.headers);
606
+ writeResponse(res, upstream, req.headers, watch);
253
607
  } catch (e) {
254
- if (!res.headersSent) {
255
- res.writeHead(502, { "content-type": "application/json" });
256
- res.end(JSON.stringify({ error: "sidecar_upstream_error", message: e.message }));
257
- } else {
258
- res.end();
259
- }
608
+ upstreamFailed(res, watch, req, mapped, e);
260
609
  }
261
610
  });
262
611
 
@@ -275,6 +624,7 @@ export function createSidecar({
275
624
  });
276
625
  if (!verdict.allow) {
277
626
  onRefusal(verdict);
627
+ feed.record({ outcome: "denied", code: verdict.code, status: verdict.status, lineage: lineageOf(req.headers) });
278
628
  writeConnectRefusal(clientSocket, verdict);
279
629
  return;
280
630
  }
@@ -292,6 +642,7 @@ export function createSidecar({
292
642
  clientSocket.destroy();
293
643
  return;
294
644
  }
645
+ feed.record({ outcome: "error", code: "tunnel_unreachable", status: 502, lineage: lineageOf(req.headers) });
295
646
  writeConnectRefusal(clientSocket, {
296
647
  status: 502,
297
648
  code: "tunnel_unreachable",
@@ -302,7 +653,8 @@ export function createSidecar({
302
653
  clientSocket.on("close", () => upstream.destroy());
303
654
  });
304
655
 
305
- return { server, ollamaServer, getVisa: visas.getVisa, runId };
656
+ server.on("close", () => uploader?.close());
657
+ return { server, ollamaServer, getVisa: visas.getVisa, runId, feed, uploader };
306
658
  }
307
659
 
308
660
  /**
@@ -335,7 +687,7 @@ export function startSidecar(opts) {
335
687
  onError: (e) =>
336
688
  warn(`journal: could not write ${journal.path} (${e.message}). Calls are unaffected; this run is no longer being recorded.`),
337
689
  });
338
- const { server, ollamaServer, getVisa } = createSidecar({ ...opts, runId, journal });
690
+ const { server, ollamaServer, getVisa, feed } = createSidecar({ ...opts, runId, journal });
339
691
  if (ollamaPort != null) {
340
692
  ollamaServer.listen(ollamaPort, host, () => {
341
693
  step(`Ollama API (local models) on http://${host}:${ollamaPort}: set OLLAMA_HOST=${host}:${ollamaPort}`);
@@ -351,6 +703,11 @@ export function startSidecar(opts) {
351
703
  ? `Journal: ${journal.path} (receipt ids, times, statuses and declared sessions only; --no-journal turns it off)`
352
704
  : "Journal: off (--no-journal). Session seals cannot be checked against this run."
353
705
  );
706
+ step(
707
+ isLoopbackBindHost(host)
708
+ ? `Watch live: passcontrol watch --port ${port} (this machine only; held in memory, never written)`
709
+ : "Watch: off, because this sidecar is bound off loopback."
710
+ );
354
711
  // Said at startup rather than only in a refusal, because the whole point of
355
712
  // HTTPS_PROXY is that nobody reads the docs first.
356
713
  step("HTTPS_PROXY: CONNECT to a provider is refused, not tunnelled — PassControl cannot");
@@ -363,9 +720,72 @@ export function startSidecar(opts) {
363
720
  ? `CONNECT allowlist: ${allowConnectHosts.join(", ")} (provider hosts are never eligible).\n`
364
721
  : "CONNECT allowlist: none — only the gateway.\n"
365
722
  );
366
- getVisa()
367
- .then(() => ok("visa warmed"))
368
- .catch((e) => fail(`could not mint initial visa: ${e.message}`));
723
+ warmVisa({
724
+ getVisa,
725
+ gateway,
726
+ // Closed rather than process.exit(): stderr to a pipe is written
727
+ // asynchronously, and exit() can drop the reason this just printed.
728
+ onRefused: () => {
729
+ process.exitCode = 1;
730
+ // A watching board holds its connection open, and close() waits for it.
731
+ feed.close();
732
+ server.close();
733
+ if (ollamaServer.listening) ollamaServer.close();
734
+ setTimeout(() => process.exit(1), 1000).unref();
735
+ },
736
+ });
369
737
  });
370
738
  return server;
371
739
  }
740
+
741
+ /** Waits between attempts to mint the first visa: backoff, then every 30 seconds. */
742
+ export const WARM_RETRY_MS = [1000, 2000, 4000, 8000, 15000, 30000];
743
+
744
+ /**
745
+ * A gateway that answered and refused the passport: any 4xx except 408 and 429,
746
+ * which mean "not now". No status (no connection) and 5xx mean "not up yet".
747
+ */
748
+ export function isPassportRefusal(error) {
749
+ const status = error?.status;
750
+ return typeof status === "number" && status >= 400 && status < 500 && status !== 408 && status !== 429;
751
+ }
752
+
753
+ /**
754
+ * The first visa (sprint T2). A sidecar is often started before its gateway, by
755
+ * `passcontrol start` or a login script, so a gateway that is not answering is
756
+ * waited for, on screen; a refusal ends the process, because retrying it can only
757
+ * fail again and a sidecar that cannot mint must not look like it is running.
758
+ * Resolves true once warmed, false after a refusal (onRefused has run).
759
+ */
760
+ export async function warmVisa({
761
+ getVisa,
762
+ gateway,
763
+ onRefused,
764
+ sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
765
+ log = { ok, warn, fail },
766
+ delays = WARM_RETRY_MS,
767
+ }) {
768
+ for (let attempt = 0; ; attempt++) {
769
+ try {
770
+ await getVisa();
771
+ log.ok(attempt === 0 ? "visa warmed" : `visa warmed: ${gateway} is answering now`);
772
+ return true;
773
+ } catch (error) {
774
+ if (isPassportRefusal(error)) {
775
+ log.fail(`could not mint a visa: ${error.message}`);
776
+ onRefused(error);
777
+ return false;
778
+ }
779
+ const delay = delays[Math.min(attempt, delays.length - 1)];
780
+ if (attempt === 0) {
781
+ log.warn(
782
+ `${gateway} is not answering yet (${error.message}). Waiting for it, and retrying on its own; ` +
783
+ "calls made before it answers get a 502."
784
+ );
785
+ } else if (attempt % 10 === 0) {
786
+ log.warn(`still waiting for ${gateway} (${error.message})`);
787
+ }
788
+ await sleep(delay);
789
+ }
790
+ }
791
+ }