@synap-core/cli 1.12.2 → 1.13.1-next.20261102.246dc73

package/dist/lib/client-header.test.js

@@ -0,0 +1,103 @@
+/**
+ * Every call names its client program (`X-Synap-Client: <name>/<version>`), so
+ * the pod's usage telemetry can tell the CLI, its stdio MCP bridge and the
+ * synap-bridge mod apart on one key and one conversation.
+ *
+ * Driven through the real doors: `hubGet` (every Hub call goes through
+ * `sessionHeaders`), the real bridge pump, and the `synap mcp bridge` command.
+ */
+import { readFileSync } from "node:fs";
+import { PassThrough } from "node:stream";
+import { afterEach, describe, expect, it, vi } from "vitest";
+const captured = vi.hoisted(() => ({ opts: undefined }));
+vi.mock("./mcp-bridge.js", async (orig) => {
+    const real = await orig();
+    return {
+        ...real,
+        runMcpBridge: vi.fn(async (opts) => {
+            captured.opts = opts;
+        }),
+    };
+});
+import { hubGet } from "./hub-client.js";
+import { mcpBridgeHeaders, CLIENT_HEADER, RUNNER_HEADER, claudeCodeProcess, clientHeader } from "./conversation-headers.js";
+import { mcpBridge } from "../commands/mcp.js";
+const VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+});
+describe("X-Synap-Client", () => {
+    it("names the package version; an unusable version says unknown", () => {
+        expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
+        expect(clientHeader("synap-cli")).toEqual({ [CLIENT_HEADER]: `synap-cli/${VERSION}` });
+        expect(clientHeader("synap-cli", "1 2")).toEqual({ [CLIENT_HEADER]: "synap-cli/unknown" });
+    });
+    it("every Hub call sends synap-cli/<version>", async () => {
+        const seen = [];
+        vi.stubGlobal("fetch", vi.fn(async (_url, init) => {
+            seen.push(init.headers);
+            return new Response(JSON.stringify({ ok: true }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        }));
+        await hubGet("/workspaces", {}, { podUrl: "https://pod.example", apiKey: "k" });
+        expect(seen).toHaveLength(1);
+        expect(seen[0][CLIENT_HEADER]).toBe(`synap-cli/${VERSION}`);
+        // The worker's served stamp is the worker poll's alone: an ordinary command never claims it.
+        expect(seen[0][RUNNER_HEADER]).toBeUndefined();
+    });
+    it("the stdio MCP bridge sends synap-cli-mcp/<version> on every request", async () => {
+        const { runMcpBridge } = await vi.importActual("./mcp-bridge.js");
+        const input = new PassThrough();
+        const output = new PassThrough();
+        const sent = [];
+        const fetchImpl = (async (_u, init) => {
+            sent.push(init.headers);
+            return new Response(JSON.stringify({ jsonrpc: "2.0", id: sent.length, result: {} }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        });
+        const done = runMcpBridge({
+            url: "https://pod/mcp",
+            apiKey: "k",
+            headers: mcpBridgeHeaders(undefined, "/x"),
+            input,
+            output,
+            fetchImpl,
+            log: () => { },
+        });
+        input.write(JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }) + "\n");
+        input.write(JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }) + "\n");
+        input.end();
+        await done;
+        expect(sent.length).toBe(2);
+        for (const h of sent)
+            expect(h[CLIENT_HEADER]).toBe(`synap-cli-mcp/${VERSION}`);
+        for (const h of sent)
+            expect(h[RUNNER_HEADER]).toBeUndefined();
+    });
+    it("`synap mcp bridge` hands the bridge those headers", async () => {
+        vi.stubEnv("SYNAP_HUB_API_KEY", "k");
+        await mcpBridge({ url: "https://pod/mcp" });
+        expect(captured.opts?.headers?.[CLIENT_HEADER]).toBe(`synap-cli-mcp/${VERSION}`);
+        expect(captured.opts?.headers?.["X-Synap-Conversation"]).toBeTruthy();
+    });
+    it("`synap mcp bridge` inside Claude Code names its parent process (plan C2); outside it names none", async () => {
+        vi.stubEnv("SYNAP_HUB_API_KEY", "k");
+        vi.stubEnv("CLAUDE_CODE_SESSION_ID", "8c34a72b-b1c1-4c37-9c1f-02920b69ccb2");
+        await mcpBridge({ url: "https://pod/mcp" });
+        const sent = captured.opts?.headers?.["X-Synap-Process"];
+        // This runner's own parent stands for Claude Code; a host without ps sends none.
+        if (sent !== undefined)
+            expect(sent).toMatch(new RegExp(`^[A-Za-z0-9._-]+:${process.ppid}:\\d{13}$`));
+        else
+            expect(claudeCodeProcess()).toBeUndefined();
+        vi.stubEnv("CLAUDE_CODE_SESSION_ID", "");
+        await mcpBridge({ url: "https://pod/mcp" });
+        expect(captured.opts?.headers?.["X-Synap-Process"]).toBeUndefined();
+    });
+});
+//# sourceMappingURL=client-header.test.js.map

package/dist/lib/client-header.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-header.test.js","sourceRoot":"","sources":["../../src/lib/client-header.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/conversation-headers.d.ts

@@ -1,18 +1,98 @@
-/**
- * The headers that name the calling CONVERSATION to the pod — the agent's own
- * id, the one a person can reopen (`claude --resume <id>`). The pod reads
- * `X-Synap-Conversation` as the conversation half of the client key, so every
- * session the conversation touches records it (`resolveAgentConversation`,
- * @synap-core/types/agents). Sent by every Hub call (`hub-client.ts`) and by
- * the stdio MCP bridge (`mcp-bridge.ts`). Empty outside Claude Code.
- */
 export declare const CONVERSATION_HEADER = "X-Synap-Conversation";
 export declare const CONVERSATION_CWD_HEADER = "X-Synap-Conversation-Cwd";
+/**
+ * Which CLIENT program makes the call, `<name>/<version>`: `synap-cli/<v>` for
+ * the CLI's Hub calls, `synap-cli-mcp/<v>` for the stdio MCP bridge (and
+ * `synap-bridge/<v>` from the Claude Code mod). The pod counts calls per client
+ * in its usage telemetry, so two programs sharing one key and one conversation
+ * can be told apart. Never an identity: it only labels the count.
+ */
+export declare const CLIENT_HEADER = "X-Synap-Client";
+export type SynapClientName = "synap-cli" | "synap-cli-mcp";
+/** `{ "X-Synap-Client": "<name>/<version>" }`; the version is the package's. */
+export declare function clientHeader(name: SynapClientName, version?: string): Record<string, string>;
+/**
+ * The worker's stamp, `synap-worker/<version>`: sent ONLY by `synap worker` on
+ * its own orient poll. The pod records, per key, the last time a request
+ * carried it (`servedAt`): proof that a process serves that agent, which a key
+ * merely being used is not. Interactive commands and the MCP bridge never send
+ * it, or every use of a key would read as "a worker runs".
+ */
+export declare const RUNNER_HEADER = "X-Synap-Runner";
+/** `{ "X-Synap-Runner": "synap-worker/<version>" }`; the version is the package's. */
+export declare function workerRunnerHeader(version?: string): Record<string, string>;
+/**
+ * Which OS process of a conversation calls (`<host>:<pid>:<startedAtMs>`), and
+ * what that runner is doing (`busy` | `idle` | `needs_permission` |
+ * `needs_answer` (a question or a plan dialog) | `ended`).
+ * The pod records both on the conversation's `session_runners` rows; a pod
+ * that reads neither ignores them. synap-bridge sends the state the same way.
+ */
+export declare const PROCESS_HEADER = "X-Synap-Process";
+export declare const RUNNER_STATE_HEADER = "X-Synap-Runner-State";
+/**
+ * Which MODEL a run uses and which PROVIDER serves it: facts the client
+ * reports, never identity (pod decision 5e7c77dc). The pod keeps a provider
+ * slug it knows (anthropic, bedrock, vertex, foundry, openai, openrouter, zai,
+ * deepseek) and reads any other word as `other`; it drops a model id that is
+ * not an id. Send nothing rather than a guess: absent reads unknown, never
+ * "anthropic". Never send a URL. A pod that reads neither ignores them.
+ */
+export declare const MODEL_HEADER = "X-Synap-Model";
+export declare const MODEL_PROVIDER_HEADER = "X-Synap-Model-Provider";
+/** A model id the pod will keep, else undefined (`<synthetic>`, a URL, junk). */
+export declare function reportableModel(model: string | undefined): string | undefined;
+/** `{ X-Synap-Model?, X-Synap-Model-Provider? }`: each only when known. */
+export declare function modelHeaders(model: string | undefined, provider: string | undefined): Record<string, string>;
+/**
+ * THE process identity format, `<host>:<pid>:<startedAtMs>` (the pod's
+ * `parseProcessIdentity`): the host with every character outside
+ * `[A-Za-z0-9._-]` made `-`, at most 255, `computer` when empty. `synap worker`
+ * (`runProcessIdentity`), the stdio MCP bridge (`claudeCodeProcess`) and the
+ * synap-bridge mod (`processIdentity`, `hooks/lib.ts`, byte for byte, tested on
+ * the same fixture) all format through it, so one Claude Code process is one
+ * runner row on the pod.
+ */
+export declare function processIdentity(hostname: string, pid: number, startedAtMs: number): string;
+/**
+ * `ps -o lstart=` read in UTC with the C locale (`Mon Nov  2 13:09:07 2026`,
+ * BSD and procps alike) -> epoch ms; undefined for anything else. Parsed field
+ * by field, never by `Date.parse`, as the synap-bridge mod parses it.
+ */
+export declare function lstartMs(text: string): number | undefined;
+/**
+ * The Claude Code process this stdio MCP bridge serves: Claude Code spawns it
+ * directly, so it is the parent (`process.ppid`), started when `ps` says. Read
+ * once, at the bridge's start. Undefined when it cannot be read (no `ps`, an
+ * orphan): the header is then not sent, never guessed.
+ */
+export declare function claudeCodeProcess(read?: {
+    ppid?: number;
+    hostname?: string;
+    startMs?: (pid: number) => number | undefined;
+}): string | undefined;
+/** The same two values in a request's `params._meta` (reverse-DNS vendor keys; `io.modelcontextprotocol/` is reserved). */
+export declare const CONVERSATION_META_KEY = "live.synap/conversation";
+export declare const CONVERSATION_CWD_META_KEY = "live.synap/conversationCwd";
 /** `claude-code:<uuid>` for the Claude Code conversation we run in, if any. */
 export declare function claudeCodeConversation(sessionId: string | undefined): string | undefined;
+/**
+ * `synap-cli:<id>` for a run outside Claude Code: `SYNAP_RUN_ID` when the caller
+ * names one (a multi-command script), else a UUID minted once per process. An
+ * unusable `SYNAP_RUN_ID` falls back to the process id rather than failing.
+ */
+export declare function cliConversation(env?: NodeJS.ProcessEnv): string;
 /**
  * The headers for `sessionId` (pass it explicitly: the CLI's live id is
  * `getClaudeSessionId()`, a stdio server's is its spawn env). Empty without a
- * real Claude Code id; the cwd rides only with a conversation.
+ * real Claude Code id the run names itself (`cliConversation`); the cwd rides
+ * only with a Claude Code conversation (the one a person can reopen).
  */
 export declare function conversationHeaders(sessionId: string | undefined, cwd?: string): Record<string, string>;
+/**
+ * Every header the stdio MCP bridge sends: its client name, the conversation,
+ * and, with a Claude Code conversation, the Claude Code process it runs in
+ * (`claudeCodeProcess`, the same value the synap-bridge mod sends), so the
+ * pod's runner rows of that process are one, whichever door called.
+ */
+export declare function mcpBridgeHeaders(sessionId: string | undefined, cwd?: string, processId?: string): Record<string, string>;

package/dist/lib/conversation-headers.js

@@ -4,29 +4,182 @@
  * `X-Synap-Conversation` as the conversation half of the client key, so every
  * session the conversation touches records it (`resolveAgentConversation`,
  * @synap-core/types/agents). Sent by every Hub call (`hub-client.ts`) and by
- * the stdio MCP bridge (`mcp-bridge.ts`). Empty outside Claude Code.
+ * the stdio MCP bridge (`mcp-bridge.ts`). Outside Claude Code the conversation is
+ * this process's own run (`synap-cli:<uuid>`, or `SYNAP_RUN_ID` to span a script).
  */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import { cliBuild } from "./cli-build.js";
 export const CONVERSATION_HEADER = "X-Synap-Conversation";
 export const CONVERSATION_CWD_HEADER = "X-Synap-Conversation-Cwd";
+/**
+ * Which CLIENT program makes the call, `<name>/<version>`: `synap-cli/<v>` for
+ * the CLI's Hub calls, `synap-cli-mcp/<v>` for the stdio MCP bridge (and
+ * `synap-bridge/<v>` from the Claude Code mod). The pod counts calls per client
+ * in its usage telemetry, so two programs sharing one key and one conversation
+ * can be told apart. Never an identity: it only labels the count.
+ */
+export const CLIENT_HEADER = "X-Synap-Client";
+/** A header value must be visible ASCII: an odd version reads `unknown` and never fails the call. */
+function headerVersion(version) {
+    return /^[\x21-\x7E]{1,64}$/.test(version) ? version : "unknown";
+}
+/** `{ "X-Synap-Client": "<name>/<version>" }`; the version is the package's. */
+export function clientHeader(name, version = cliBuild().version) {
+    return { [CLIENT_HEADER]: `${name}/${headerVersion(version)}` };
+}
+/**
+ * The worker's stamp, `synap-worker/<version>`: sent ONLY by `synap worker` on
+ * its own orient poll. The pod records, per key, the last time a request
+ * carried it (`servedAt`): proof that a process serves that agent, which a key
+ * merely being used is not. Interactive commands and the MCP bridge never send
+ * it, or every use of a key would read as "a worker runs".
+ */
+export const RUNNER_HEADER = "X-Synap-Runner";
+/** `{ "X-Synap-Runner": "synap-worker/<version>" }`; the version is the package's. */
+export function workerRunnerHeader(version = cliBuild().version) {
+    return { [RUNNER_HEADER]: `synap-worker/${headerVersion(version)}` };
+}
+/**
+ * Which OS process of a conversation calls (`<host>:<pid>:<startedAtMs>`), and
+ * what that runner is doing (`busy` | `idle` | `needs_permission` |
+ * `needs_answer` (a question or a plan dialog) | `ended`).
+ * The pod records both on the conversation's `session_runners` rows; a pod
+ * that reads neither ignores them. synap-bridge sends the state the same way.
+ */
+export const PROCESS_HEADER = "X-Synap-Process";
+export const RUNNER_STATE_HEADER = "X-Synap-Runner-State";
+/**
+ * Which MODEL a run uses and which PROVIDER serves it: facts the client
+ * reports, never identity (pod decision 5e7c77dc). The pod keeps a provider
+ * slug it knows (anthropic, bedrock, vertex, foundry, openai, openrouter, zai,
+ * deepseek) and reads any other word as `other`; it drops a model id that is
+ * not an id. Send nothing rather than a guess: absent reads unknown, never
+ * "anthropic". Never send a URL. A pod that reads neither ignores them.
+ */
+export const MODEL_HEADER = "X-Synap-Model";
+export const MODEL_PROVIDER_HEADER = "X-Synap-Model-Provider";
+/** The pod's model-id rule (`parseReportedModel`, @synap-core/types/agents): an id, at most 128 chars, never a URL. */
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/@[\]-]{0,127}$/;
+/** A model id the pod will keep, else undefined (`<synthetic>`, a URL, junk). */
+export function reportableModel(model) {
+    const id = model?.trim();
+    return id && MODEL_ID.test(id) && !id.includes("://") ? id : undefined;
+}
+/** `{ X-Synap-Model?, X-Synap-Model-Provider? }`: each only when known. */
+export function modelHeaders(model, provider) {
+    const id = reportableModel(model);
+    const slug = provider?.trim().toLowerCase();
+    return {
+        ...(id ? { [MODEL_HEADER]: id } : {}),
+        ...(slug && /^[a-z0-9-]{1,32}$/.test(slug) ? { [MODEL_PROVIDER_HEADER]: slug } : {}),
+    };
+}
+/**
+ * THE process identity format, `<host>:<pid>:<startedAtMs>` (the pod's
+ * `parseProcessIdentity`): the host with every character outside
+ * `[A-Za-z0-9._-]` made `-`, at most 255, `computer` when empty. `synap worker`
+ * (`runProcessIdentity`), the stdio MCP bridge (`claudeCodeProcess`) and the
+ * synap-bridge mod (`processIdentity`, `hooks/lib.ts`, byte for byte, tested on
+ * the same fixture) all format through it, so one Claude Code process is one
+ * runner row on the pod.
+ */
+export function processIdentity(hostname, pid, startedAtMs) {
+    const host = hostname.replace(/[^A-Za-z0-9._-]/g, "-").slice(0, 255) || "computer";
+    return `${host}:${pid}:${Math.trunc(startedAtMs)}`;
+}
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/**
+ * `ps -o lstart=` read in UTC with the C locale (`Mon Nov  2 13:09:07 2026`,
+ * BSD and procps alike) -> epoch ms; undefined for anything else. Parsed field
+ * by field, never by `Date.parse`, as the synap-bridge mod parses it.
+ */
+export function lstartMs(text) {
+    const m = /^[A-Z][a-z]{2} ([A-Z][a-z]{2}) +(\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/.exec(text.trim());
+    if (!m)
+        return undefined;
+    const month = MONTHS.indexOf(m[1]);
+    if (month < 0)
+        return undefined;
+    const ms = Date.UTC(Number(m[6]), month, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]));
+    return Number.isFinite(ms) ? ms : undefined;
+}
+/** When `pid` started, from `ps` in UTC with the C locale; undefined when it cannot be read. */
+function psStartMs(pid) {
+    try {
+        const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+            env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2_000,
+        });
+        return lstartMs(out);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The Claude Code process this stdio MCP bridge serves: Claude Code spawns it
+ * directly, so it is the parent (`process.ppid`), started when `ps` says. Read
+ * once, at the bridge's start. Undefined when it cannot be read (no `ps`, an
+ * orphan): the header is then not sent, never guessed.
+ */
+export function claudeCodeProcess(read = {}) {
+    const pid = read.ppid ?? process.ppid;
+    if (!Number.isInteger(pid) || pid <= 1)
+        return undefined;
+    const startedAt = (read.startMs ?? psStartMs)(pid);
+    if (startedAt === undefined)
+        return undefined;
+    return processIdentity(read.hostname ?? os.hostname(), pid, startedAt);
+}
+/** The same two values in a request's `params._meta` (reverse-DNS vendor keys; `io.modelcontextprotocol/` is reserved). */
+export const CONVERSATION_META_KEY = "live.synap/conversation";
+export const CONVERSATION_CWD_META_KEY = "live.synap/conversationCwd";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** `claude-code:<uuid>` for the Claude Code conversation we run in, if any. */
 export function claudeCodeConversation(sessionId) {
     const id = sessionId?.trim();
     return id && UUID.test(id) ? `claude-code:${id.toLowerCase()}` : undefined;
 }
+const RUN_ID = /^[A-Za-z0-9_.-]{1,128}$/;
+/** One id per process, so every Hub call of one CLI run lands in one conversation. */
+const PROCESS_RUN_ID = randomUUID();
+/**
+ * `synap-cli:<id>` for a run outside Claude Code: `SYNAP_RUN_ID` when the caller
+ * names one (a multi-command script), else a UUID minted once per process. An
+ * unusable `SYNAP_RUN_ID` falls back to the process id rather than failing.
+ */
+export function cliConversation(env = process.env) {
+    const named = env.SYNAP_RUN_ID?.trim();
+    return `synap-cli:${named && RUN_ID.test(named) ? named : PROCESS_RUN_ID}`;
+}
 /**
  * The headers for `sessionId` (pass it explicitly: the CLI's live id is
  * `getClaudeSessionId()`, a stdio server's is its spawn env). Empty without a
- * real Claude Code id; the cwd rides only with a conversation.
+ * real Claude Code id the run names itself (`cliConversation`); the cwd rides
+ * only with a Claude Code conversation (the one a person can reopen).
  */
 export function conversationHeaders(sessionId, cwd = process.cwd()) {
     const conversation = claudeCodeConversation(sessionId);
     if (!conversation)
-        return {};
+        return { [CONVERSATION_HEADER]: cliConversation() };
     // HTTP header values must be ByteStrings; a non-ASCII cwd is dropped rather
     // than letting fetch throw and take the whole request down with it.
     return /^[\x20-\x7E]{1,1024}$/.test(cwd)
         ? { [CONVERSATION_HEADER]: conversation, [CONVERSATION_CWD_HEADER]: cwd }
         : { [CONVERSATION_HEADER]: conversation };
 }
+/**
+ * Every header the stdio MCP bridge sends: its client name, the conversation,
+ * and, with a Claude Code conversation, the Claude Code process it runs in
+ * (`claudeCodeProcess`, the same value the synap-bridge mod sends), so the
+ * pod's runner rows of that process are one, whichever door called.
+ */
+export function mcpBridgeHeaders(sessionId, cwd = process.cwd(), processId) {
+    const headers = { ...clientHeader("synap-cli-mcp"), ...conversationHeaders(sessionId, cwd) };
+    return processId && claudeCodeConversation(sessionId) ? { ...headers, [PROCESS_HEADER]: processId } : headers;
+}
 //# sourceMappingURL=conversation-headers.js.map

package/dist/lib/conversation-headers.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversation-headers.js","sourceRoot":"","sources":["../../src/lib/conversation-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAAsB,CAAC;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,0BAA0B,CAAC;AAElE,MAAM,IAAI,GAAG,iEAAiE,CAAC;AAE/E,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB,CAAC,SAA6B;IAClE,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC;IAC7B,OAAO,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA6B,EAC7B,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,MAAM,YAAY,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,CAAC,YAAY;QAAE,OAAO,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,oEAAoE;IACpE,OAAO,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC;QACtC,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC,uBAAuB,CAAC,EAAE,GAAG,EAAE;QACzE,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"conversation-headers.js","sourceRoot":"","sources":["../../src/lib/conversation-headers.ts"],"names":[],"mappings":"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"}

package/dist/lib/conversation-headers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/conversation-headers.test.js

@@ -0,0 +1,78 @@
+/**
+ * The process key (`X-Synap-Process`) the stdio MCP bridge sends for the
+ * Claude Code process it serves (sessions cockpit, plan 3884fadf C2). The
+ * synap-bridge mod sends the same key from inside Claude Code; the pod keys a
+ * runner row by it, so the two doors must format it byte for byte alike.
+ *
+ * ONE fixture, the same in synap-bridge (`tests/adapter.test.ts`,
+ * PROCESS_FIXTURE): host `devbox`, Claude Code's pid 4242, started
+ * Wed Oct 14 17:46:40 2026 UTC -> `devbox:4242:1792000000000`.
+ */
+import { execFileSync } from "node:child_process";
+import { describe, expect, it } from "vitest";
+import { claudeCodeProcess, lstartMs, mcpBridgeHeaders, PROCESS_HEADER, processIdentity, } from "./conversation-headers.js";
+import { runProcessIdentity } from "../commands/worker.js";
+const PROCESS_FIXTURE = { host: "devbox", pid: 4242, lstart: "Wed Oct 14 17:46:40 2026", key: "devbox:4242:1792000000000" };
+/** The pod's own check (`parseProcessIdentity`, backend request-write-context.ts). */
+const POD_PROCESS_RE = /^([A-Za-z0-9._-]{1,255}):(\d{1,10}):(\d{10,14})$/;
+const SID = "8c34a72b-b1c1-4c37-9c1f-02920b69ccb2";
+describe("the process key, one format for every door", () => {
+    it("formats the shared fixture as synap-bridge does, from ps's UTC text", () => {
+        const startedAt = lstartMs(`${PROCESS_FIXTURE.lstart}    \n`);
+        expect(startedAt).toBe(1_792_000_000_000);
+        expect(processIdentity(PROCESS_FIXTURE.host, PROCESS_FIXTURE.pid, startedAt)).toBe(PROCESS_FIXTURE.key);
+        expect(PROCESS_FIXTURE.key).toMatch(POD_PROCESS_RE);
+    });
+    it("is the worker's own format: runProcessIdentity goes through it", () => {
+        expect(runProcessIdentity(1_792_000_000_000, "devbox", 1)).toBe(processIdentity("devbox", 1, 1_792_000_000_000));
+        expect(processIdentity("MacBook Pro (2).local", 7, 1_792_000_000_000.9)).toBe("MacBook-Pro--2-.local:7:1792000000000");
+        expect(processIdentity("", 7, 1_792_000_000_000)).toBe("computer:7:1792000000000");
+    });
+    it("reads ps's padded day; a local, translated or partial text is no time, never a guess", () => {
+        expect(lstartMs("Mon Nov  2 13:09:07 2026")).toBe(Date.UTC(2026, 10, 2, 13, 9, 7));
+        for (const bad of ["lun.  2 nov 13:09:07 2026", "Nov  2 13:09:07 2026", "Mon Foo  2 13:09:07 2026", "2026-11-02T13:09:07Z", ""]) {
+            expect(lstartMs(bad)).toBeUndefined();
+        }
+    });
+});
+describe("claudeCodeProcess: the parent the stdio bridge serves", () => {
+    it("is the parent's pid and start on this host", () => {
+        const asked = [];
+        const key = claudeCodeProcess({
+            ppid: PROCESS_FIXTURE.pid,
+            hostname: PROCESS_FIXTURE.host,
+            startMs: (pid) => (asked.push(pid), lstartMs(PROCESS_FIXTURE.lstart)),
+        });
+        expect(key).toBe(PROCESS_FIXTURE.key);
+        expect(asked).toEqual([PROCESS_FIXTURE.pid]);
+    });
+    it("is undefined for an orphan or a start ps could not give", () => {
+        expect(claudeCodeProcess({ ppid: 1, hostname: "devbox", startMs: () => 1_792_000_000_000 })).toBeUndefined();
+        expect(claudeCodeProcess({ ppid: 4242, hostname: "devbox", startMs: () => undefined })).toBeUndefined();
+    });
+    it("reads the real parent through ps (this test runner's own parent), its start in UTC whatever the zone", () => {
+        const key = claudeCodeProcess();
+        // A CI sandbox without ps reads undefined, never a made-up key.
+        if (key === undefined)
+            return;
+        expect(key).toMatch(new RegExp(`^[A-Za-z0-9._-]+:${process.ppid}:\\d{13}$`));
+        // An independent reading: now minus ps's elapsed time ([[dd-]hh:]mm:ss), which no time zone moves.
+        const etime = execFileSync("ps", ["-o", "etime=", "-p", String(process.ppid)], { encoding: "utf8" }).trim();
+        const [days, clock] = etime.includes("-") ? etime.split("-") : ["0", etime];
+        const elapsedS = clock.split(":").map(Number).reduce((acc, n) => acc * 60 + n, 0) + Number(days) * 86_400;
+        const startedAt = Number(key.split(":").at(-1));
+        expect(Math.abs(startedAt - (Date.now() - elapsedS * 1000))).toBeLessThan(3_000);
+    });
+});
+describe("mcpBridgeHeaders sends the process with a Claude Code conversation only", () => {
+    it("adds X-Synap-Process beside the conversation", () => {
+        const h = mcpBridgeHeaders(SID, "/x", PROCESS_FIXTURE.key);
+        expect(h[PROCESS_HEADER]).toBe(PROCESS_FIXTURE.key);
+        expect(h["X-Synap-Conversation"]).toBe(`claude-code:${SID}`);
+    });
+    it("sends none without a process, or outside Claude Code", () => {
+        expect(PROCESS_HEADER in mcpBridgeHeaders(SID, "/x")).toBe(false);
+        expect(PROCESS_HEADER in mcpBridgeHeaders(undefined, "/x", PROCESS_FIXTURE.key)).toBe(false);
+    });
+});
+//# sourceMappingURL=conversation-headers.test.js.map

package/dist/lib/conversation-headers.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-headers.test.js","sourceRoot":"","sources":["../../src/lib/conversation-headers.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/credential-class.d.ts

@@ -28,7 +28,7 @@
  * blocked), classification is deliberately three-valued and the guard is
  * belt-and-braces:
  *   • `agent`   — positive agent signal → refuse locally, before the network call.
- *   • `human`   — positive human signal (`user_pat`) → never blocked.
+ *   • `human`   — positive human signal (`user_pat` NOT owned by an agent user) → never blocked.
  *   • `unknown` — no signal → PROCEED, and translate the server's 403 after the
  *                 fact (`isAgentReviewRejection`). The server stays authoritative.
  *
@@ -39,7 +39,7 @@
  * self-approval / undo risk"). So `synap proposals reject` genuinely WORKS for
  * an agent credential and must NOT be guarded here.
  */
-import { type HubConfig } from "./hub-client.js";
+import { HubError, type HubConfig } from "./hub-client.js";
 /**
  * Shape of `GET /api/hub/auth/status`. Mirrors the fields the route returns
  * (`rest/auth.ts:140-157`). `keyType` and `workspaceId` are optional because
@@ -58,9 +58,36 @@ export interface AuthStatus {
     isActive?: boolean;
     keyType?: string | null;
     workspaceId?: string | null;
+    /**
+     * What the key may touch — its grant (pod ≥ owner-app-connect-key; absent
+     * on older pods, null when the pod read no grant for the request).
+     */
+    access?: KeyAccess | null;
+}
+/** `/auth/status` `access`: the calling key's grant, ids and patterns only. */
+export interface KeyAccess {
+    isFullAccess: boolean;
+    /** "full access", or what limits it ("limited to 1 space (<id>)"). */
+    summary: string;
+    scopes: Array<{
+        permissions: string[];
+        workspaceIds: string[] | null;
+        projectIds: string[] | null;
+        entityIds: string[] | null;
+    }>;
+    clientId: string | null;
 }
 /** Introspect a key. `apiKey` overrides `cfg.apiKey` (used by `whoami` to probe both sides of a divergence). */
 export declare function fetchAuthStatus(cfg: HubConfig, apiKey?: string): Promise<AuthStatus>;
+/**
+ * WHO this key is — the agent principal, for recognising the agent's OWN
+ * posts (a room message carries it as `routedTeammateId`). Never the acting
+ * user sent to the pod: that is `resolveUserId` (/users/me), which for an
+ * agent key answers the linked HUMAN. The id recorded with the key
+ * (`cfg.agentUserId`) wins; else the pod's key-owner answer (/auth/status),
+ * cached per key. For a person's own key both questions answer the person.
+ */
+export declare function resolveAgentUserId(cfg: HubConfig): Promise<string>;
 /**
  * Shape of `GET /api/hub/users/me` (`hub-protocol/rest/users.ts:36-46`).
  *
@@ -105,6 +132,17 @@ export declare function classifyActiveCredential(cfg: HubConfig): Promise<Review
  * as its own error.
  */
 export declare function isAgentReviewRejection(err: unknown): boolean;
+/**
+ * Did the pod refuse this approve because it must be reviewed on its page?
+ *
+ * `proposals.approve` answers a page-only proposal (one whose approval turns a
+ * skill, automation or rule on) with CONFLICT, which the Hub door sends as a
+ * bare 409 `{ error: <sentence> }` and no machine code. So: 409, and the
+ * sentence is the pod's own ("Open it to approve: …"), shown as it came.
+ */
+export declare function isReviewOnItsPageRefusal(err: unknown): boolean;
+/** Say the pod's sentence and print the page that can approve it, never the raw 409. */
+export declare function renderReviewOnItsPage(id: string, cfg: HubConfig, err: HubError): void;
 /** The `synap://` deep link the desktop app registers — `synap open proposal <id>` sends exactly this (open.ts:36-38). */
 export declare function proposalDeepLink(id: string): string;
 /** The pod's web review page for a bare id — the same route `bridge-setup.ts:894` and `statusline.ts:425` print. */