@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/commands/scan.js

@@ -0,0 +1,238 @@
+/**
+ * `mnemom scan`: a read-only local scan of GitHub PR metadata. Runs entirely on this machine; nothing is
+ * uploaded in this build. The share-level prompt gates what a later upload step may send, and the chosen
+ * payload is printed so the user sees exactly what would leave. Pure logic is exported so each reject
+ * arm is unit-testable without Commander (same pattern as commands/usage.ts).
+ */
+import { isValidRepoSlug, resolveCredential, } from "../lib/scan/credential.js";
+import { failureText } from "../lib/scan/failure.js";
+import { runLocalScan } from "../lib/scan/scan.js";
+import { askInput, askSelect } from "../lib/prompt.js";
+import { isSpendTiersEnabled, NOT_ENABLED_MSG, parseMonthlySpendUsd, selectSpend, SPEND_INVALID_MSG, SPEND_NO_TERMINAL_MSG, } from "../lib/scan/spend/spend-tiers.js";
+import { ADMIN_KEY_ENV, AnthropicUsageError, fetchMeasuredUsage, isAdminKeyShape, usageFailureText, } from "../lib/scan/spend/anthropic-usage.js";
+import { getAuthInfo } from "../lib/auth.js";
+import { listMyOrgs } from "../lib/api.js";
+import { fetchRecordTotals, isOrgId, } from "../lib/scan/record.js";
+import { RECORD_NO_ORG_NOTE, renderRecordSection } from "../lib/scan/report.js";
+import { buildEmailBody, buildEmailReport, DRY_RUN_MSG, UNAVAILABLE_MSG, failureMessage, ReportEmailError, sendReportEmail, } from "../lib/scan/report-email.js";
+import { buildSharePayload, parseShareLevel, promptShareLevel, } from "../lib/scan/share.js";
+/** Parses repeated/comma-separated `--repo owner/name`. Returns null on any invalid slug. */
+export function parseRepoFlags(raw) {
+    const out = (raw ?? [])
+        .flatMap((r) => r.split(","))
+        .map((r) => r.trim())
+        .filter(Boolean);
+    return out.length > 0 && out.every(isValidRepoSlug) ? out : null;
+}
+const EMAIL = /^[^\s@]{1,64}@[^\s@]{1,255}\.[^\s@]{2,63}$/;
+export const isEmail = (v) => typeof v === "string" && v.length <= 320 && EMAIL.test(v.trim());
+/** The runner's email (mnemom login, else asked) and the CTO's (flag, else "are you the CTO?"). */
+export async function resolveRecipients(o) {
+    if (o.ctoEmail !== undefined && !isEmail(o.ctoEmail))
+        throw new Error("--cto-email must be a valid email address");
+    let runner = o.runnerEmail ?? getAuthInfo()?.email ?? "";
+    if (!isEmail(runner))
+        runner = (await askInput("Your email (the report is sent to you):")).trim();
+    if (!isEmail(runner))
+        throw new Error("a valid runner email is required");
+    runner = runner.trim();
+    if (o.ctoEmail !== undefined)
+        return { runner_email: runner, cto_email: o.ctoEmail.trim() };
+    const isCto = await askSelect("Are you the CTO?", ["Yes, I am the CTO", "No, someone else is"]);
+    if (isCto === null)
+        throw new Error("--cto-email is required when you are not the CTO");
+    if (isCto.startsWith("Yes"))
+        return { runner_email: runner, cto_email: runner };
+    const cto = (await askInput("CTO email (the report is sent to them too):")).trim();
+    if (!isEmail(cto))
+        throw new Error("--cto-email is required when you are not the CTO");
+    return { runner_email: runner, cto_email: cto };
+}
+/** The CTO's figure in USD, or null for none. Throws fixed text only; the input is never echoed. */
+export async function resolveSelfReportedSpend(o) {
+    if (o.monthlySpend === undefined && !o.noAnthropicUsage)
+        return null;
+    if (!isSpendTiersEnabled(o.env))
+        throw new Error(NOT_ENABLED_MSG);
+    let text = o.monthlySpend;
+    if (text === undefined) {
+        if (!(o.isTty ?? process.stdin.isTTY))
+            throw new Error(SPEND_NO_TERMINAL_MSG);
+        text = await askInput("Approximate monthly AI spend in USD (blank to skip; kept in memory only):");
+        if (text.trim() === "")
+            return null;
+    }
+    const n = parseMonthlySpendUsd(text);
+    if (n === null)
+        throw new Error(SPEND_INVALID_MSG);
+    return n;
+}
+export const NO_ADMIN_KEY_TERMINAL_MSG = "Set ANTHROPIC_ADMIN_KEY (there is no terminal to ask on).";
+export const TIER1_FALLBACK_NOTE = "Tier 1 skipped: falling back to the next tier.";
+/**
+ * Tier 1: read measured usage with the CTO's Anthropic admin key, locally. The key comes from
+ * ANTHROPIC_ADMIN_KEY or a masked prompt (--anthropic-admin-key; never a value on argv), lives only in this
+ * call, and goes only to api.anthropic.com. Returns null for "no key" and for every failure, after printing a
+ * fixed sentence: the key, the thrown value and the response never reach the terminal. The caller then falls
+ * back to tier 2, then tier 3.
+ */
+export async function resolveMeasuredUsage(o, period) {
+    if (o.anthropicAdminKey && !isSpendTiersEnabled(o.env))
+        throw new Error(NOT_ENABLED_MSG);
+    if (!isSpendTiersEnabled(o.env) || o.noAnthropicUsage)
+        return null;
+    // An explicit typed figure is the user's choice of tier 2: an ambient env key must not override it.
+    if (o.monthlySpend !== undefined && !o.anthropicAdminKey)
+        return null;
+    let key = (o.env ?? process.env)[ADMIN_KEY_ENV];
+    if (o.anthropicAdminKey) {
+        if (!(o.isTty ?? process.stdin.isTTY))
+            throw new Error(NO_ADMIN_KEY_TERMINAL_MSG);
+        key = await askInput("Anthropic admin key (kept in memory only, sent only to Anthropic):", true);
+    }
+    if (key === undefined || key.trim() === "")
+        return null;
+    if (!isAdminKeyShape(key)) {
+        console.log(usageFailureText("key_invalid"));
+        console.log(TIER1_FALLBACK_NOTE);
+        return null;
+    }
+    try {
+        return await fetchMeasuredUsage(key, period, o.anthropicDeps);
+    }
+    catch (e) {
+        console.log(usageFailureText(e instanceof AnthropicUsageError ? e.reason : "upstream"));
+        console.log(TIER1_FALLBACK_NOTE);
+        return null;
+    }
+}
+/**
+ * --org is optional only because it can be inferred: the report is emailed on every scan, so the scan
+ * needs an org. Inference uses the signed-in user's own memberships (GET /v1/orgs, personal org
+ * excluded): exactly one org is used; none, several, or a failed read stops the scan loudly BEFORE any
+ * scan work, naming the fix. It never guesses between orgs and never skips the email.
+ */
+export async function resolveScanOrg(o) {
+    if (o.org !== undefined) {
+        if (!isOrgId(o.org))
+            throw new Error(INVALID_ORG_MSG);
+        return o.org;
+    }
+    let orgs;
+    try {
+        orgs = (await (o.listOrgs ?? listMyOrgs)()).filter((x) => !x.is_personal);
+    }
+    catch {
+        throw new Error("Could not look up your org to email the report to. Sign in with `mnemom login`, or pass --org <org_id>.");
+    }
+    if (orgs.length === 1 && isOrgId(orgs[0].org_id))
+        return orgs[0].org_id;
+    if (orgs.length === 0)
+        throw new Error("You belong to no organization, so the report has nowhere to be emailed from. Pass --org <org_id>.");
+    throw new Error(`You belong to ${orgs.length} organizations; pass --org <org_id> (${orgs.map((x) => x.org_id).join(", ")}).`);
+}
+export const INVALID_ORG_MSG = "--org must be an org id like org-1a2b3c4d.";
+/**
+ * The Record read for the preview: null when the flag gate is off (no read, no output, as before).
+ * With the gate on and no --org it is a note, not a guess. 404 becomes a note; 401/403 throw
+ * RecordAuthError (fail closed); every other failure becomes a fixed note. Nothing is stored.
+ */
+export async function resolveRecordOutcome(o) {
+    if (!isSpendTiersEnabled(o.env))
+        return null;
+    if (o.org === undefined)
+        return "no_org";
+    if (!isOrgId(o.org))
+        throw new Error(INVALID_ORG_MSG);
+    return fetchRecordTotals(o.org, o.recordDeps);
+}
+export async function scanCommand(o) {
+    if (o.share !== undefined && parseShareLevel(o.share) === null) {
+        throw new Error("--share must be one of: summary, full, none");
+    }
+    if (o.repos.length === 0)
+        throw new Error("--repo owner/name is required (repeatable)");
+    // The report is emailed on every scan, so resolve the org before any scan work; failure is loud.
+    const emailOrg = await resolveScanOrg(o);
+    if (o.ctoEmail !== undefined && !isEmail(o.ctoEmail))
+        throw new Error("--cto-email must be a valid email address");
+    const selfReported = await resolveSelfReportedSpend(o);
+    const now = o.now ?? Date.now;
+    const end = new Date(now()).toISOString().slice(0, 10);
+    const period = o.period ?? { start: end, end };
+    const measured = await resolveMeasuredUsage(o, period);
+    const credential = o.credential ?? (await resolveCredential().catch(() => null));
+    if (!credential)
+        throw new Error(failureText("credential"));
+    // Before the local scan: a refused credential fails closed without spending the GitHub reads.
+    const record = await resolveRecordOutcome(o);
+    const outcome = await runLocalScan({ credential, now, ...o.deps }, { repos: o.repos, period });
+    if (outcome.status === "withheld")
+        throw new Error(`Scan withheld: ${failureText(outcome.reason)}`);
+    const { result } = outcome;
+    console.log("Local scan (read-only)");
+    console.log(`PRs examined: ${result.totals.examined} of ${result.totals.prs} merged (${result.coverage.windowStart} to ${result.coverage.windowEnd})`);
+    console.log(`Coverage: ${result.coverage.complete ? "complete" : `partial${result.coverage.stoppedBy ? ` (stopped by ${result.coverage.stoppedBy})` : ""}`}`);
+    // Flag off: the line as before. Flag on: the tier chosen, or no line at all when evidence is thin.
+    const tiers = isSpendTiersEnabled(o.env);
+    const spend = tiers
+        ? selectSpend({
+            measuredUsd: measured?.usd ?? o.anthropicUsageUsd,
+            over200kShare: measured ? measured.over200kShare : o.anthropicOver200kShare,
+            selfReportedUsd: selfReported,
+            estimate: result.spend,
+        })
+        : null;
+    const spendLine = spend ? spend.line : result.spend.line;
+    if (spendLine !== null)
+        console.log(spendLine);
+    if (record === "no_org")
+        console.log(RECORD_NO_ORG_NOTE);
+    else if (record !== null)
+        for (const line of renderRecordSection(record))
+            console.log(line);
+    const level = parseShareLevel(o.share) ?? (await promptShareLevel());
+    // Every successful scan emails the report to the person who ran it, at every share level, no opt-out.
+    // Mnemom keeps nothing from a share=none send (the server sends the email and does nothing else).
+    const emailFailure = await emailReport(o, emailOrg, result, level, period, spend);
+    if (level === "none") {
+        console.log("Share level: nothing. No share payload is built; Mnemom keeps nothing (the report email is only sent to you).");
+        if (emailFailure)
+            throw new ReportEmailError(emailFailure);
+        return;
+    }
+    const payload = buildSharePayload(level, result, await resolveRecipients(o), spend ? (spend.shareable ? spend.line : null) : undefined);
+    console.log(`Share level: ${level}. Upload is not wired in this build; this is what would be sent:`);
+    console.log(JSON.stringify(payload, null, 2));
+    if (emailFailure)
+        throw new ReportEmailError(emailFailure);
+}
+/**
+ * Emails the report. Loud on every failure: prints the reason name, never the server's words, and
+ * returns it so the caller exits non-zero after the local report is shown.
+ */
+async function emailReport(o, org, result, level, period, spend) {
+    const fail = (f) => {
+        console.log(failureMessage(f));
+        return f;
+    };
+    const report = buildEmailReport(result, {
+        orgId: org,
+        period,
+        now: o.now ?? Date.now,
+        sendSpendRange: spend ? spend.shareable && spend.tier === 3 : true,
+    });
+    const body = buildEmailBody(report, level, result.coverage.complete, o.ctoEmail?.trim());
+    const outcome = await sendReportEmail(org, body, o.emailDeps);
+    if (outcome.status === "failed")
+        return fail(outcome.reason);
+    if (outcome.status === "unavailable") {
+        // Org Scan is off by default: the gate's 404 is not a failure and must not break the scan.
+        console.log(UNAVAILABLE_MSG);
+        return null;
+    }
+    console.log(outcome.status === "dry_run"
+        ? DRY_RUN_MSG
+        : `Report emailed to you (${outcome.recipients} recipient${outcome.recipients === 1 ? "" : "s"}).`);
+    return null;
+}

package/dist/durable/flock.d.ts

@@ -0,0 +1,26 @@
+export type LockResult = {
+    ok: true;
+    fd: number;
+} | {
+    ok: false;
+    reason: "held" | "error";
+    detail: string;
+};
+/** The helper commands, tried in order. Each locks fd 3 and exits 0 (taken), 3 (held), else error. */
+export declare const FLOCK_HELPERS: readonly (readonly string[])[];
+export interface FlockDeps {
+    openSync: (p: string, flags: string, mode: number) => number;
+    closeSync: (fd: number) => void;
+    mkdirSync: (p: string, opts: {
+        recursive: true;
+        mode: number;
+    }) => unknown;
+    run: (argv: readonly string[], fd: number) => number | null;
+    exists: (p: string) => boolean;
+}
+export declare const defaultFlockDeps: FlockDeps;
+/**
+ * Take an exclusive non-blocking flock on `lockPath` (created 0600 in a 0700 directory). On success
+ * the returned fd must stay open for the life of the lock; closing it (or exiting) releases it.
+ */
+export declare function tryLockFile(lockPath: string, deps?: FlockDeps): LockResult;

package/dist/durable/flock.js

@@ -0,0 +1,80 @@
+// flock(2) LOCK_EX|LOCK_NB for the durable seat proxy's per-conversation lock (S1 proxyLockPath,
+// BACKBONE amendment 51, C13-R4).
+//
+// Node has no flock binding, so the lock is taken by a short-lived helper on an fd this process
+// opened and passes down: flock locks belong to the open file description, so the lock stays held
+// by this process's fd after the helper exits, is visible to `lsof -p <this pid>`, and is released
+// when this process exits for any reason (kill -9 included). The helper is the system perl
+// (Fcntl), present on every macOS; python3 is the fallback.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+/** The helper commands, tried in order. Each locks fd 3 and exits 0 (taken), 3 (held), else error. */
+export const FLOCK_HELPERS = [
+    [
+        "/usr/bin/perl",
+        "-MFcntl=:flock",
+        "-e",
+        'open(my $fh, "+<&=", 3) or exit 9; flock($fh, LOCK_EX|LOCK_NB) ? exit 0 : exit 3',
+    ],
+    [
+        "/usr/bin/python3",
+        "-I",
+        "-c",
+        "import fcntl,sys\ntry:\n fcntl.flock(3, fcntl.LOCK_EX|fcntl.LOCK_NB)\nexcept BlockingIOError:\n sys.exit(3)\nexcept Exception:\n sys.exit(9)",
+    ],
+];
+export const defaultFlockDeps = {
+    openSync: (p, flags, mode) => fs.openSync(p, flags, mode),
+    closeSync: (fd) => fs.closeSync(fd),
+    mkdirSync: (p, opts) => fs.mkdirSync(p, opts),
+    run: (argv, fd) => spawnSync(argv[0], argv.slice(1), {
+        stdio: ["ignore", "ignore", "ignore", fd],
+        timeout: 10_000,
+    }).status,
+    exists: (p) => fs.existsSync(p),
+};
+/**
+ * Take an exclusive non-blocking flock on `lockPath` (created 0600 in a 0700 directory). On success
+ * the returned fd must stay open for the life of the lock; closing it (or exiting) releases it.
+ */
+export function tryLockFile(lockPath, deps = defaultFlockDeps) {
+    let fd;
+    try {
+        deps.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+        fd = deps.openSync(lockPath, "a", 0o600);
+    }
+    catch (e) {
+        return { ok: false, reason: "error", detail: e.message };
+    }
+    // The fd is handed back only when the lock is taken; every other way out (held, no helper, a
+    // helper or the existence probe throwing) closes it here.
+    let taken = false;
+    try {
+        for (const helper of FLOCK_HELPERS) {
+            if (!deps.exists(helper[0]))
+                continue;
+            const status = deps.run(helper, fd);
+            if (status === 0) {
+                taken = true;
+                return { ok: true, fd };
+            }
+            if (status === 3)
+                return { ok: false, reason: "held", detail: "lock held" };
+        }
+        return { ok: false, reason: "error", detail: "no flock helper could take the lock" };
+    }
+    catch (e) {
+        return { ok: false, reason: "error", detail: e.message };
+    }
+    finally {
+        if (!taken) {
+            try {
+                deps.closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    }
+}

package/dist/durable/launch-spec.d.ts

@@ -83,6 +83,11 @@ export interface LauncherArgvSplit {
     launcherArgv: string[];
     passthrough: string[];
     yoloInjected: boolean;
+    /**
+     * The launcher's interactive Remote Control prefix (`--remote-control <name> [--name <name>]`,
+     * agent.ts launch): named as a dropped --remote-control, its session name never a positional.
+     */
+    rcInjected: boolean;
     /** The --session-id the launcher pinned, if any. */
     sessionId: string | null;
     /**
@@ -100,7 +105,8 @@ export interface LauncherArgvSplit {
 }
 /**
  * Split an original claude argv (after argv[0]) the way `mnemom agent` built it (buildCliArgs):
- * [--model v] [--effort v] [yolo] [--session-id id] [--plugin-dir dir] <passthrough>
+ * [--remote-control n [--name n]] [--model v] [--effort v] [yolo] [--session-id id]
+ * [--plugin-dir dir] <passthrough>
  * [--strict-mcp-config] [--mcp-config <v>]. `passthroughHint` (the tokens after the parent
  * launcher's `--`, read from its own argv) pins the split exactly when it occurs where the
  * layout allows; an empty hint (the parent was read and had no `--`) makes the shape read exact;

package/dist/durable/launch-spec.js

@@ -159,15 +159,21 @@ function isSubsequenceAt(hay, needle, at) {
 }
 /**
  * Split an original claude argv (after argv[0]) the way `mnemom agent` built it (buildCliArgs):
- * [--model v] [--effort v] [yolo] [--session-id id] [--plugin-dir dir] <passthrough>
+ * [--remote-control n [--name n]] [--model v] [--effort v] [yolo] [--session-id id]
+ * [--plugin-dir dir] <passthrough>
  * [--strict-mcp-config] [--mcp-config <v>]. `passthroughHint` (the tokens after the parent
  * launcher's `--`, read from its own argv) pins the split exactly when it occurs where the
  * layout allows; an empty hint (the parent was read and had no `--`) makes the shape read exact;
  * without a hint (null or absent) the prefix and suffix are read by shape and reported ambiguous.
  */
 export function splitLauncherArgv(argv, passthroughHint) {
-    // Prefix: launcher-injected flags in their fixed order.
+    // The RC launch puts its own `--remote-control <name> --name <name>` first.
     let i = 0;
+    const rcName = argv[1];
+    const rcInjected = argv[0] === REMOTE_CONTROL_FLAG && rcName !== undefined && readToken(rcName).flag === null;
+    if (rcInjected)
+        i = argv[2] === "--name" && argv[3] === rcName ? 4 : 2;
+    // Prefix: launcher-injected flags in their fixed order.
     const prefix = {};
     for (const [flag, arity] of LAUNCHER_PREFIX) {
         if (argv[i] !== flag)
@@ -230,6 +236,7 @@ export function splitLauncherArgv(argv, passthroughHint) {
         launcherArgv,
         passthrough,
         yoloInjected: prefix[YOLO_FLAG] === true,
+        rcInjected,
         sessionId: typeof prefix["--session-id"] === "string" ? prefix["--session-id"] : null,
         exact,
         ambiguous,
@@ -245,7 +252,7 @@ export function runningSourceInput(originalArgv, cwd, opts = {}) {
         userArgv: [...split.ambiguous, ...split.passthrough],
         yoloInjected: split.yoloInjected,
         // Names are deduplicated, so a --remote-control the user also passed is named once.
-        remoteControl: opts.remoteControl === true,
+        remoteControl: opts.remoteControl === true || split.rcInjected,
         cwd,
     };
 }

package/dist/durable/seat-proxy-entry.d.ts

@@ -0,0 +1,11 @@
+import { type ExperimentalPrefs } from "../lib/experimental.js";
+/** True when argv (after the node + script pair) names the seat proxy. */
+export declare function isSeatProxyArgv(argv: readonly string[]): boolean;
+export interface SeatProxyEntryDeps {
+    stored: () => ExperimentalPrefs | undefined;
+    stderr: (line: string) => void;
+    exit: (code: number) => void;
+    run: (argv: readonly string[]) => Promise<unknown>;
+}
+/** Gate, then run the proxy with the arguments after `seat-proxy`. */
+export declare function runSeatProxyEntry(argv: readonly string[], deps: SeatProxyEntryDeps): void;

package/dist/durable/seat-proxy-entry.js

@@ -0,0 +1,25 @@
+// Entry dispatch for the hidden `mnemom agent host seat-proxy` (C3). It bypasses commander (the
+// `agent` launcher's options would reject the proxy's flags, as with `agent slack`), the update
+// hook and the experimental migration, so the proxy's stdout carries only its READY line.
+//
+// Gate (BACKBONE Flags/CLI): the durable experimental feature, read from config.json only, like the
+// host daemon that spawns the proxy (resolveExperimental with an empty env; MNEMOM_EXPERIMENTAL is
+// never read here). Off: exit 2 with the gate message, no HTTP, no file under HOME, no process.
+import { gatedMessage, resolveExperimental } from "../lib/experimental.js";
+/** True when argv (after the node + script pair) names the seat proxy. */
+export function isSeatProxyArgv(argv) {
+    return argv[0] === "agent" && argv[1] === "host" && argv[2] === "seat-proxy";
+}
+/** Gate, then run the proxy with the arguments after `seat-proxy`. */
+export function runSeatProxyEntry(argv, deps) {
+    const on = resolveExperimental({ stored: deps.stored(), env: {} }).enabled.includes("durable");
+    if (!on) {
+        deps.stderr(`${gatedMessage("`mnemom agent host`", "durable")}\n`);
+        deps.exit(2);
+        return;
+    }
+    deps.run(argv.slice(3)).catch(() => {
+        deps.stderr("mnemom agent host seat-proxy: internal error\n");
+        deps.exit(1);
+    });
+}

package/dist/durable/seat-proxy.d.ts

@@ -0,0 +1,107 @@
+import http from "node:http";
+import type { Duplex } from "node:stream";
+import { TurnOrigins } from "../turn-origin.mjs";
+import { type LockResult } from "./flock.js";
+import { type SeatIdentity, type HelloRelay } from "./seat-socket.js";
+export declare const EXIT_CONFIG = 2;
+export declare const EXIT_LOCK_HELD = 3;
+export declare const EXIT_KEY_DEAD = 4;
+/**
+ * The drop reasons and exit reasons this proxy logs (the C13 test hooks name them). These are local
+ * literals, not S1 values: S1 freezes no drop-reason or exit-reason enum (gap
+ * c3-seat-proxy-enums-not-in-s1), so other pieces cannot import them yet.
+ */
+export type DropReason = "arm_missing" | "arm_unparseable" | "unattended_hold_off" | "unattended_fence_off" | "turn_wait_timeout" | "pre_first_prompt" | "no_session";
+export type ExitReason = "fenced_exit" | "revoked_exit" | "ended_exit";
+/** The most a dead-key-status (401/409/410) body is buffered to; a longer one is dropped, never truncated. */
+export declare const DEAD_BODY_CAP: number;
+/** The largest request body forwarded (the Messages API request limit); a larger one gets a local 413. */
+export declare const REQUEST_BODY_CAP: number;
+/**
+ * Client headers that never pass: hop-by-hop, proxy-authorization and every x-mnemom-* (the proxy
+ * sets the Mnemom ones from the lease). The provider credential (authorization, x-api-key) passes:
+ * the seat carries it exactly as `mnemom agent` does (dogfood B6 ruling, superseding C13-R2/R8).
+ */
+export declare function isStrippedClientHeader(name: string): boolean;
+export interface SeatProxyArgs {
+    conversation: string;
+    agentId: string;
+    door: URL;
+    cwd: string;
+    seat: SeatIdentity | null;
+    helloRelay: string | null;
+}
+/**
+ * Parse and validate the argv after `seat-proxy`. Errors name the option, never echo a value.
+ * `isDir` and `env` are injected so the check is pure.
+ */
+export declare function parseSeatProxyArgs(argv: readonly string[], env: Record<string, string | undefined>, isDir: (p: string) => boolean): {
+    ok: true;
+    args: SeatProxyArgs;
+} | {
+    ok: false;
+    error: string;
+};
+/** The first stdin line (CR stripped), or "" on EOF / timeout. Only the first line is ever read. */
+export declare function readKeyLine(stream: NodeJS.ReadableStream, timeoutMs?: number): Promise<string>;
+/** The arm verdict for one door response: forward, or the drop reason. */
+export declare function armVerdict(pathname: string, rawHeaders: readonly string[]): {
+    forward: true;
+} | {
+    forward: false;
+    reason: DropReason;
+};
+/** The dead-key signal in a door response (C13-R7), read from the JSON body's error.type. */
+export declare function deadKeyReason(status: number, body: string): ExitReason | null;
+/** Whether a request path is origin-form and free of dot segments (raw or percent-encoded). */
+export declare function isCleanOriginForm(url: string): boolean;
+export type Route = "messages" | "count_tokens" | "hello" | "telemetry" | "refused";
+/** Where a request goes: the two model POSTs are forwarded; startup paths are answered locally. */
+export declare function routeOf(method: string, pathname: string): Route;
+export interface SeatProxyDeps {
+    log: (line: string) => void;
+    exit: (code: number) => void;
+    turns: TurnOrigins;
+    requestId?: () => string;
+    /** Overrides REQUEST_BODY_CAP (tests). */
+    requestBodyCap?: number;
+    /** Overrides DEAD_BODY_CAP (tests). */
+    deadBodyCap?: number;
+}
+export interface SeatProxyState {
+    dead: ExitReason | null;
+}
+/** The request handler of a seat proxy for `cfg` with lease key `key`. */
+export declare function createSeatProxyHandler(cfg: SeatProxyArgs, key: string, deps: SeatProxyDeps, state?: SeatProxyState): (req: http.IncomingMessage, res: http.ServerResponse) => void;
+export interface SeatProxyMainDeps {
+    env: Record<string, string | undefined>;
+    stdin: NodeJS.ReadableStream;
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+    exit: (code: number) => void;
+    home: string;
+    isDir: (p: string) => boolean;
+    lock: (lockPath: string) => LockResult;
+    relayFor: (socketPath: string) => HelloRelay;
+    keyTimeoutMs?: number;
+    /** Loopback listen addresses (tests override them to exercise a failed bind). */
+    hostV4?: string;
+    hostV6?: string;
+}
+export declare function defaultMainDeps(): SeatProxyMainDeps;
+/**
+ * The 'connect' listener for a seat proxy's loopback servers: a CONNECT (a tunnel request, never
+ * origin-form) is refused with a 400 and the socket closed. Without a listener Node would drop the
+ * socket silently; this makes the refusal explicit and logged.
+ */
+export declare function refuseConnect(log: (line: string) => void): (req: http.IncomingMessage, socket: Duplex) => void;
+export interface RunningSeatProxy {
+    port: number;
+    socketPath: string;
+    close: () => Promise<void>;
+}
+/**
+ * `mnemom agent host seat-proxy …`: validate, read the key, take the conversation lock, listen,
+ * print READY. Resolves with the running proxy, or with an exit code it already passed to `exit`.
+ */
+export declare function seatProxyMain(argv: readonly string[], deps?: SeatProxyMainDeps): Promise<RunningSeatProxy | number>;