@herbertgao/pi-extensions 2026.8.9 → 2026.8.10

package/node_modules/resume-from/dist/adapters/pi/redaction.js

@@ -0,0 +1,132 @@
+/**
+ * Credential redaction — shared implementation kept in three adapter subfolders.
+ *
+ * Files:
+ *   src/adapters/claude-code/redaction.ts
+ *   src/adapters/codex/redaction.ts
+ *   src/adapters/pi/redaction.ts
+ *
+ * These three files are byte-identical by design. A fix in one MUST be applied to all three.
+ * src/adapters/boundary.test.ts asserts byte equality and will fail if they drift.
+ *
+ * Why not a single shared module: src/adapters/contract.ts is types-only (no behaviour). A
+ * platform service would be imported as behaviour, and T-ROO-7 requires adapter-to-platform
+ * cross-module imports to go through contract.js — which can only export types, not functions.
+ */
+/** Stable replacement used for credentials that must not cross an adapter boundary. */
+export const REDACTED_VALUE = "[REDACTED]";
+const ENVIRONMENT_KEYS = new Set(["env", "environment", "environmentvariables"]);
+const SENSITIVE_KEYS = new Set([
+    "authorization",
+    "clientsecret",
+    "cookie",
+    "credentials",
+    "password",
+    "passwd",
+    "privatekey",
+    "proxyauthorization",
+    "secret",
+    "setcookie",
+    "signingkey",
+    "token",
+]);
+const PRIVATE_KEY_PATTERN = /-----BEGIN ([A-Z0-9 ]*PRIVATE KEY)-----[\s\S]*?-----END \1-----/g;
+const AUTHORIZATION_PATTERN = /(\b(?:authorization|proxy-authorization)\s*:\s*)(?:Bearer|Basic)\s+[^\s,;]+/gi;
+const API_HEADER_PATTERN = /(\b(?:x-api-key|api-key|x-auth-token)\s*:\s*)[^\s,;]+/gi;
+const CREDENTIAL_PATTERN = /\b(?:sk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{12,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{30,})\b/g;
+const ASSIGNMENT_PATTERN = /\b([A-Za-z_][A-Za-z0-9_]*)(\s*=\s*)("[^"\r\n]*"|'[^'\r\n]*'|[^\s;&|]+)/g;
+const FLAG_PATTERN = /(--(?:api[-_]?key|access[-_]?token|auth[-_]?token|token|password|passwd|secret|client[-_]?secret|private[-_]?key))(=|\s+)("[^"\r\n]*"|'[^'\r\n]*'|[^\s;&|]+)/gi;
+const USER_CREDENTIAL_PATTERN = /(^|[\s;&|])(-u|--user)(=|\s+)("[^"\r\n]*"|'[^'\r\n]*'|[^\s;&|]+)/g;
+const URI_USERINFO_PATTERN = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/:@]+):([^\s/@]+)@/gi;
+// Unquoted value requires a structural delimiter or line/string end following it, OR a digit
+// somewhere in the token (C-RED-1: "token: expired" is plain English and stays, while
+// "password: hunter2 # prod" carries a credential that must not cross even mid-line).
+const JSON_LIKE_PATTERN = /(["']?)([A-Za-z_][A-Za-z0-9_-]*)\1(\s*:\s*)("[^"\r\n]*"|'[^'\r\n]*'|[^\s,;}]+(?=[,;}]|[\r\n]|$)|[^\s,;}]*\d[^\s,;}]*)/g;
+function normalizedKey(key) {
+    return key.toLowerCase().replaceAll(/[^a-z0-9]/g, "");
+}
+function isSensitiveKey(key) {
+    const normalized = normalizedKey(key);
+    return (SENSITIVE_KEYS.has(normalized) ||
+        normalized.endsWith("apikey") ||
+        normalized.endsWith("accesskey") ||
+        normalized.endsWith("password") ||
+        normalized.endsWith("privatekey") ||
+        normalized.endsWith("secret") ||
+        normalized.endsWith("token"));
+}
+function redactEnvironmentValue(value) {
+    if (Array.isArray(value))
+        return value.map(redactEnvironmentValue);
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.keys(value).map((key) => [
+            key,
+            redactEnvironmentValue(value[key]),
+        ]));
+    }
+    return value === undefined ? undefined : REDACTED_VALUE;
+}
+function redactSensitiveArray(values) {
+    const redacted = values.map(redactSensitiveStructure);
+    for (let index = 0; index < values.length - 1; index += 1) {
+        const flag = values[index];
+        if (typeof flag === "string" &&
+            (flag.trim() === "-u" || flag.trim() === "--user") &&
+            typeof values[index + 1] === "string") {
+            redacted[index + 1] = REDACTED_VALUE;
+        }
+    }
+    return redacted;
+}
+/**
+ * Redact credentials in JSON-like tool inputs without changing the caller's value.
+ * Adapter-specific parsing stays in each adapter; this function only handles secret values.
+ */
+export function redactSensitiveStructure(value) {
+    if (typeof value === "string")
+        return redactSensitiveText(value);
+    if (Array.isArray(value))
+        return redactSensitiveArray(value);
+    if (typeof value !== "object" || value === null)
+        return value;
+    const redacted = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (isSensitiveKey(key)) {
+            redacted[key] = REDACTED_VALUE;
+        }
+        else if ((normalizedKey(key) === "user" || normalizedKey(key) === "username") &&
+            typeof child === "string" &&
+            child.includes(":")) {
+            redacted[key] = REDACTED_VALUE;
+        }
+        else if (ENVIRONMENT_KEYS.has(normalizedKey(key))) {
+            redacted[key] = redactEnvironmentValue(child);
+        }
+        else {
+            redacted[key] = redactSensitiveStructure(child);
+        }
+    }
+    return redacted;
+}
+/** Redact recognizable credentials from shell commands, headers, and unstructured arguments. */
+export function redactSensitiveText(text) {
+    return text
+        .replace(PRIVATE_KEY_PATTERN, REDACTED_VALUE)
+        .replace(AUTHORIZATION_PATTERN, `$1${REDACTED_VALUE}`)
+        .replace(API_HEADER_PATTERN, `$1${REDACTED_VALUE}`)
+        .replace(FLAG_PATTERN, `$1$2${REDACTED_VALUE}`)
+        .replace(USER_CREDENTIAL_PATTERN, `$1$2$3${REDACTED_VALUE}`)
+        .replace(URI_USERINFO_PATTERN, `$1$2:${REDACTED_VALUE}@`)
+        .replace(ASSIGNMENT_PATTERN, (match, key, separator) => isSensitiveKey(key) ? `${key}${separator}${REDACTED_VALUE}` : match)
+        .replace(JSON_LIKE_PATTERN, (match, quote, key, separator) => isSensitiveKey(key) ? `${quote}${key}${quote}${separator}${REDACTED_VALUE}` : match)
+        .replace(CREDENTIAL_PATTERN, REDACTED_VALUE);
+}
+/** Redact a source-recorded argument string, preserving valid JSON when it is JSON. */
+export function redactSensitiveArgumentsText(text) {
+    try {
+        return JSON.stringify(redactSensitiveStructure(JSON.parse(text)));
+    }
+    catch {
+        return redactSensitiveText(text);
+    }
+}

package/node_modules/resume-from/dist/adapters/pi/serialize.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Writing a canonical session into a new Pi session file (FR-41).
+ *
+ * Two shapes were deliberately not used:
+ *
+ * - a `compaction` entry for a summary turn. Pi's `buildContextEntries` treats the latest
+ *   compaction as authoritative and drops everything before its `firstKeptEntryId`, so a
+ *   summary written that way would hide every imported turn from the model.
+ * - a `toolCall` content block for a tool-call turn. Pi — and the provider behind it —
+ *   expects a matching `toolResult`, and FR-24 dropped the body that result would need.
+ *   An imported tool call is therefore one assistant text entry carrying its outcome line,
+ *   which also gives T-PI-4 its "one message entry per canonical turn".
+ */
+import type { CanonicalSession, ProvenanceMarker, SerializedSession, TargetProfile } from "./contract.js";
+export interface PiSerializeDeps {
+    /** The repository the new session belongs to. Pi buckets its sessions by it. */
+    cwd(): string;
+    now(): Date;
+    newSessionId(): string;
+    newEntryId(): string;
+}
+export declare function serializeSession(session: CanonicalSession, target: TargetProfile, marker: ProvenanceMarker, deps: PiSerializeDeps): SerializedSession;

package/node_modules/resume-from/dist/adapters/pi/serialize.js

@@ -0,0 +1,87 @@
+/**
+ * Writing a canonical session into a new Pi session file (FR-41).
+ *
+ * Two shapes were deliberately not used:
+ *
+ * - a `compaction` entry for a summary turn. Pi's `buildContextEntries` treats the latest
+ *   compaction as authoritative and drops everything before its `firstKeptEntryId`, so a
+ *   summary written that way would hide every imported turn from the model.
+ * - a `toolCall` content block for a tool-call turn. Pi — and the provider behind it —
+ *   expects a matching `toolResult`, and FR-24 dropped the body that result would need.
+ *   An imported tool call is therefore one assistant text entry carrying its outcome line,
+ *   which also gives T-PI-4 its "one message entry per canonical turn".
+ */
+import { join } from "node:path";
+import { emptyUsage, IMPORTED_API, IMPORTED_MODEL, IMPORTED_PROVIDER, MARKER_CUSTOM_TYPE, PI_SESSION_VERSION, sessionDirFor, sessionFileName, toIsoUtc, } from "./format.js";
+/** A turn with no visible text at all. The shape still needs one entry (T-PI-4). */
+const EMPTY_TURN_TEXT = "(empty turn)";
+function turnText(turn) {
+    const text = turn.kind === "tool-call" ? (turn.toolCall?.outcomeLine ?? "") : turn.text;
+    return text.trim().length > 0 ? text : EMPTY_TURN_TEXT;
+}
+export function serializeSession(session, target, marker, deps) {
+    const cwd = deps.cwd();
+    const sessionId = deps.newSessionId();
+    const createdAt = deps.now().toISOString();
+    const fallbackTime = toIsoUtc(session.provenance.updatedAt) ?? createdAt;
+    const header = {
+        type: "session",
+        version: PI_SESSION_VERSION,
+        id: sessionId,
+        timestamp: createdAt,
+        cwd,
+    };
+    const entries = [];
+    let parentId = null;
+    const chain = (entry, timestamp) => {
+        const id = deps.newEntryId();
+        entries.push({ ...entry, id, parentId, timestamp });
+        parentId = id;
+    };
+    // The marker first: Pi stores and shows it, and never sends it to the model (FR-47, FR-48).
+    chain({
+        type: "custom",
+        customType: MARKER_CUSTOM_TYPE,
+        data: {
+            sourceAgent: marker.sourceAgent,
+            sourceHome: marker.sourceHome,
+            sourceSessionId: marker.sourceSessionId,
+            importedAt: marker.importedAt,
+            droppedSummary: marker.droppedSummary,
+            lines: marker.lines,
+        },
+    }, createdAt);
+    for (const turn of session.turns) {
+        const timestamp = toIsoUtc(turn.timestamp) ?? fallbackTime;
+        const epoch = Date.parse(timestamp);
+        const text = turnText(turn);
+        if (turn.role === "user") {
+            const message = {
+                role: "user",
+                content: [{ type: "text", text }],
+                timestamp: epoch,
+            };
+            chain({ type: "message", message }, timestamp);
+            continue;
+        }
+        const message = {
+            role: "assistant",
+            content: [{ type: "text", text }],
+            api: IMPORTED_API,
+            provider: IMPORTED_PROVIDER,
+            model: IMPORTED_MODEL,
+            // Zero is honest — importing spent no tokens — and it is what C-11 demands: the
+            // object must be there, with numbers Pi can add up.
+            usage: emptyUsage(),
+            stopReason: "stop",
+            timestamp: epoch,
+        };
+        chain({ type: "message", message }, timestamp);
+    }
+    const lines = [header, ...entries].map((entry) => JSON.stringify(entry));
+    const file = {
+        absolutePath: join(sessionDirFor(target.home, cwd), sessionFileName(createdAt, sessionId)),
+        bytes: Buffer.from(`${lines.join("\n")}\n`, "utf8"),
+    };
+    return { sessionId, files: [file], itemCount: entries.length };
+}

package/node_modules/resume-from/dist/adapters/pi/validate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The check that exists because of C-11 (FR-50).
+ *
+ * Pi reads six numbers of an assistant message's `usage` object without a guard —
+ * `usage.input`, `usage.output`, `usage.cacheRead`, `usage.cacheWrite`,
+ * `usage.totalTokens` and `usage.cost.total`. A missing `usage` stops Pi with
+ * `TypeError: Cannot read properties of undefined (reading 'input')`, and it happens
+ * after the file is already in the user's home. So the check runs before placement,
+ * on the bytes, on every message, and it reports every defect it finds.
+ *
+ * Zero is a valid value. `Number.isFinite` is the test, never truthiness.
+ */
+import type { SerializedSession, ValidationDefect } from "./contract.js";
+export declare function validateSerialized(serialized: SerializedSession): ValidationDefect[];

package/node_modules/resume-from/dist/adapters/pi/validate.js

@@ -0,0 +1,134 @@
+/**
+ * The check that exists because of C-11 (FR-50).
+ *
+ * Pi reads six numbers of an assistant message's `usage` object without a guard —
+ * `usage.input`, `usage.output`, `usage.cacheRead`, `usage.cacheWrite`,
+ * `usage.totalTokens` and `usage.cost.total`. A missing `usage` stops Pi with
+ * `TypeError: Cannot read properties of undefined (reading 'input')`, and it happens
+ * after the file is already in the user's home. So the check runs before placement,
+ * on the bytes, on every message, and it reports every defect it finds.
+ *
+ * Zero is a valid value. `Number.isFinite` is the test, never truthiness.
+ */
+import { asHeader, isRecord } from "./format.js";
+/** The fields Pi dereferences without a guard (C-11). */
+const REQUIRED_USAGE_NUMBERS = [
+    "input",
+    "output",
+    "cacheRead",
+    "cacheWrite",
+    "totalTokens",
+];
+const CRASH = "Pi reads this without a guard and stops with an uncaught TypeError (C-11)";
+function usageDefects(usage, path) {
+    if (!isRecord(usage)) {
+        return [
+            {
+                path,
+                message: `assistant message has no usage object. ${CRASH}`,
+            },
+        ];
+    }
+    const defects = [];
+    for (const field of REQUIRED_USAGE_NUMBERS) {
+        if (!Number.isFinite(usage[field])) {
+            defects.push({
+                path: `${path}/${field}`,
+                message: `usage.${field} is not a number. ${CRASH}`,
+            });
+        }
+    }
+    const cost = usage.cost;
+    if (!isRecord(cost)) {
+        defects.push({ path: `${path}/cost`, message: `usage.cost is not an object. ${CRASH}` });
+    }
+    else if (!Number.isFinite(cost.total)) {
+        defects.push({
+            path: `${path}/cost/total`,
+            message: `usage.cost.total is not a number. ${CRASH}`,
+        });
+    }
+    return defects;
+}
+export function validateSerialized(serialized) {
+    const defects = [];
+    if (serialized.files.length === 0) {
+        return [{ path: "files", message: "a Pi session needs one session file, and none was made" }];
+    }
+    let storedItems = 0;
+    for (const [fileIndex, file] of serialized.files.entries()) {
+        const prefix = serialized.files.length > 1 ? `files/${fileIndex}/` : "";
+        const lines = file.bytes
+            .toString("utf8")
+            .split("\n")
+            .filter((line) => line.trim().length > 0);
+        if (lines.length === 0) {
+            defects.push({ path: `${prefix}items`, message: "the session file is empty" });
+            continue;
+        }
+        for (const [index, line] of lines.entries()) {
+            const path = `${prefix}items/${index}`;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                defects.push({ path, message: "the line is not JSON, so Pi would skip or misread it" });
+                continue;
+            }
+            if (index === 0) {
+                const header = asHeader(value);
+                if (!header) {
+                    defects.push({
+                        path,
+                        message: "the first line is not a Pi session header, so Pi cannot open the file",
+                    });
+                }
+                else if (header.id !== serialized.sessionId) {
+                    defects.push({
+                        path: `${path}/id`,
+                        message: `the header id ${header.id} is not the session id ${serialized.sessionId}`,
+                    });
+                }
+                continue;
+            }
+            storedItems += 1;
+            if (!isRecord(value) || typeof value.type !== "string" || value.type.length === 0) {
+                defects.push({ path, message: "the entry has no type, so Pi cannot place it" });
+                continue;
+            }
+            if (typeof value.id !== "string" || value.id.length === 0) {
+                defects.push({ path: `${path}/id`, message: "the entry has no id, so Pi's tree breaks" });
+            }
+            if (!(typeof value.parentId === "string" || value.parentId === null)) {
+                defects.push({
+                    path: `${path}/parentId`,
+                    message: "the entry has no parentId, so Pi's tree breaks",
+                });
+            }
+            if (typeof value.timestamp !== "string" || Number.isNaN(Date.parse(value.timestamp))) {
+                defects.push({
+                    path: `${path}/timestamp`,
+                    message: "the entry has no ISO-8601 timestamp",
+                });
+            }
+            if (value.type !== "message")
+                continue;
+            const message = isRecord(value.message) ? value.message : null;
+            if (!message) {
+                defects.push({ path: `${path}/message`, message: "the message entry carries no message" });
+                continue;
+            }
+            if (message.role !== "assistant")
+                continue;
+            defects.push(...usageDefects(message.usage, `${path}/usage`));
+        }
+    }
+    if (storedItems !== serialized.itemCount) {
+        defects.push({
+            path: "itemCount",
+            message: `the session promises ${serialized.itemCount} items and the bytes hold ${storedItems}`,
+        });
+    }
+    return defects;
+}

package/node_modules/resume-from/dist/bin.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * The command binary. The Codex prompt file and the Claude Code slash-command file call it
+ * (C-1, FR-10), and it is a process wrapper and nothing more: read the two facts only the
+ * caller knows, hand the rest to the host, print what came back.
+ *
+ * The shim states which agent the binary is running inside. This file never guesses it from the
+ * environment, and never checks the name against a list of its own — an unknown agent is the
+ * registry's error to raise, with the agents it does know in the message (FR-56). That is what
+ * keeps FR-57's "one new folder and one line" true of this file too.
+ */
+export declare const HELP_TEXT = "Usage: resume-from --target-agent <agent> [--target-home <path>] -- [<source-agent>] [<row> | <session-id> | <file-path>] [options]\n\nSelectors:\n  no selector       List sessions available for the current repository.\n  <row>             Select a numbered row from that list (1 or greater).\n  <session-id>      Select an exact session ID.\n  <file-path>       Select a session file by absolute, relative or ~/ path.\n\nOptions:\n  --agent <name>    Filter source sessions: pi, codex, claude, or claude-code.\n  --home <path>     Search one source home, even one outside the configuration.\n  --confirm <token> Import the exact selection and preview identified by the token.\n  --target-agent    Target host ID; normally supplied by the installed plugin.\n  --target-home     Target agent home; omit to use that agent's default.\n  -h, --help        Show this help.\n\nExamples:\n  resume-from --target-agent codex --\n  resume-from --target-agent codex -- claude 2\n  resume-from --target-agent claude-code -- session-id\n  resume-from --target-agent codex -- ~/sessions/session.jsonl";
+/** The invocation split in two: what the shim states, and what the user typed. */
+export interface ShimArgs {
+    /** The agent the shim is running inside. Null when it did not say (FR-56). */
+    targetAgent: string | null;
+    /** The home that agent is running, or null to use the adapter's declared default (FR-3). */
+    targetHome: string | null;
+    /** Everything else, in the order it was given. The host's own parser reads it. */
+    rest: string[];
+}
+export type ShimArgsResult = {
+    ok: true;
+    value: ShimArgs;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Both forms of both flags are accepted (`--flag value` and `--flag=value`) because a shim is a
+ * text file a user edits. A flag with no value is left for the caller to report rather than
+ * silently swallowing the argument that follows it.
+ */
+export declare function readShimArgs(argv: string[]): ShimArgsResult;
+export declare function main(argv: string[], cwd: string): Promise<number>;

package/node_modules/resume-from/dist/bin.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * The command binary. The Codex prompt file and the Claude Code slash-command file call it
+ * (C-1, FR-10), and it is a process wrapper and nothing more: read the two facts only the
+ * caller knows, hand the rest to the host, print what came back.
+ *
+ * The shim states which agent the binary is running inside. This file never guesses it from the
+ * environment, and never checks the name against a list of its own — an unknown agent is the
+ * registry's error to raise, with the agents it does know in the message (FR-56). That is what
+ * keeps FR-57's "one new folder and one line" true of this file too.
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { runCommandBinary } from "./index.js";
+const TARGET_AGENT = "--target-agent";
+const TARGET_HOME = "--target-home";
+const USER_ARGUMENTS = "--";
+const USAGE = `Usage: resume-from ${TARGET_AGENT} <agent> [${TARGET_HOME} <path>] ${USER_ARGUMENTS} ` +
+    "[<source-agent>] [<row> | <session-id> | <file-path>] [options]";
+export const HELP_TEXT = `${USAGE}
+
+Selectors:
+  no selector       List sessions available for the current repository.
+  <row>             Select a numbered row from that list (1 or greater).
+  <session-id>      Select an exact session ID.
+  <file-path>       Select a session file by absolute, relative or ~/ path.
+
+Options:
+  --agent <name>    Filter source sessions: pi, codex, claude, or claude-code.
+  --home <path>     Search one source home, even one outside the configuration.
+  --confirm <token> Import the exact selection and preview identified by the token.
+  --target-agent    Target host ID; normally supplied by the installed plugin.
+  --target-home     Target agent home; omit to use that agent's default.
+  -h, --help        Show this help.
+
+Examples:
+  resume-from --target-agent codex --
+  resume-from --target-agent codex -- claude 2
+  resume-from --target-agent claude-code -- session-id
+  resume-from --target-agent codex -- ~/sessions/session.jsonl`;
+/**
+ * Both forms of both flags are accepted (`--flag value` and `--flag=value`) because a shim is a
+ * text file a user edits. A flag with no value is left for the caller to report rather than
+ * silently swallowing the argument that follows it.
+ */
+export function readShimArgs(argv) {
+    let targetAgent = null;
+    let targetHome = null;
+    const separator = argv.indexOf(USER_ARGUMENTS);
+    if (separator < 0) {
+        return {
+            ok: false,
+            problem: `${USER_ARGUMENTS} is missing after the shim-owned target flags.`,
+        };
+    }
+    const trusted = argv.slice(0, separator);
+    const rest = argv.slice(separator + 1);
+    for (let index = 0; index < trusted.length; index += 1) {
+        const arg = trusted[index];
+        if (arg === undefined)
+            continue;
+        const named = [TARGET_AGENT, TARGET_HOME].find((flag) => arg === flag || arg.startsWith(`${flag}=`));
+        if (named === undefined) {
+            return {
+                ok: false,
+                problem: `Unexpected shim argument before ${USER_ARGUMENTS}: ${arg}.`,
+            };
+        }
+        const inline = arg.startsWith(`${named}=`);
+        const value = inline ? arg.slice(named.length + 1) : trusted[index + 1];
+        if (value === undefined || value === "" || value.startsWith("-")) {
+            return { ok: false, problem: `${named} needs one non-empty value.` };
+        }
+        if (!inline)
+            index += 1;
+        if (named === TARGET_AGENT) {
+            if (targetAgent !== null) {
+                return {
+                    ok: false,
+                    problem: `${TARGET_AGENT} was given twice by the shim.`,
+                };
+            }
+            targetAgent = value;
+        }
+        else {
+            if (targetHome !== null) {
+                return {
+                    ok: false,
+                    problem: `${TARGET_HOME} was given twice by the shim.`,
+                };
+            }
+            targetHome = value;
+        }
+    }
+    return { ok: true, value: { targetAgent, targetHome, rest } };
+}
+export async function main(argv, cwd) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(`${HELP_TEXT}\n`);
+        return 0;
+    }
+    const parsed = readShimArgs(argv);
+    if (!parsed.ok) {
+        process.stderr.write(`${parsed.problem}\n${USAGE}\nRun resume-from --help for details.\n`);
+        return 2;
+    }
+    const { targetAgent, targetHome, rest } = parsed.value;
+    if (targetAgent === null) {
+        process.stderr.write(`${TARGET_AGENT} is missing: the shim that calls this binary states which agent it is ` +
+            `running inside, because guessing it would import into the wrong agent.\n${USAGE}\n` +
+            "Run resume-from --help for selectors, options, and examples.\n");
+        return 2;
+    }
+    const outcome = await runCommandBinary({
+        argv: rest,
+        cwd,
+        // Unchecked on purpose: the registry knows which agents exist and says so (FR-56).
+        targetAgent: targetAgent,
+        targetHome: targetHome,
+    });
+    for (const line of outcome.stdout)
+        process.stdout.write(`${line}\n`);
+    for (const line of outcome.stderr)
+        process.stderr.write(`${line}\n`);
+    return outcome.exitCode;
+}
+/**
+ * Run only when this file is the program. `realpathSync` because the installed binary is reached
+ * through a symlink in `node_modules/.bin`, and the unresolved path would never match.
+ * `process.exitCode` rather than `process.exit`, so the streams above are flushed.
+ */
+const invokedPath = process.argv[1];
+if (invokedPath !== undefined && realpathSync(invokedPath) === fileURLToPath(import.meta.url)) {
+    process.exitCode = await main(process.argv.slice(2), process.cwd());
+}

package/node_modules/resume-from/dist/contract.d.ts

@@ -0,0 +1,10 @@
+import type { AgentId, AgentRuntime, HandoverInstruction, HomePath, HostWiring, ImportPipeline, ImportRequest, LandingResult, SelectionInput, SessionId, SessionRef, TargetProfile } from "./host/contract.js";
+export type { AgentId, AgentRuntime, HandoverInstruction, HomePath, HostWiring, ImportPipeline, ImportRequest, LandingResult, SelectionInput, SessionId, SessionRef, TargetProfile, };
+/** The package entry point (FR-57: adding an agent never changes this file). */
+export interface ResumeFrom {
+    /**
+     * Loads configuration, builds the agent list, and returns the host wiring.
+     * Called once by the command binary and once by the Pi extension.
+     */
+    createHost(): Promise<HostWiring>;
+}

package/node_modules/resume-from/dist/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/module.md — the Public Contract section is the normative home.
+// Declarations only: no behaviour, no defaults. If this file and module.md disagree,
+// the document wins and this file is corrected.
+export {};

package/node_modules/resume-from/dist/host/agents.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The agent list — the one place in the tree that knows which adapters exist (FR-57).
+ *
+ * It lives in the composition root rather than in `src/adapters/` because nothing depends on the
+ * composition root. A list inside `src/adapters/` would close the cycle
+ * list → `adapters/pi` → `import` → adapter port, and the Pi entry point could not exist.
+ *
+ * Adding an agent is a new folder under `src/adapters/`, a new value in `AgentId`, and one line
+ * below. There is no `switch` anywhere in this module for the same reason: a branch on the agent
+ * name would be a second place to edit.
+ */
+import type { AgentAdapter, EstimatorFamily } from "./contract.js";
+/** One agent, as the composition root needs it. */
+export interface AgentEntry {
+    /**
+     * Builds the adapter. Called once per process, after the configuration is loaded, so a
+     * rejected configuration constructs nothing (FR-56).
+     */
+    create(): AgentAdapter;
+    /**
+     * How tokens are counted for an import *into* this agent. The budget is a share of the target
+     * window (FR-30), so the counting rule is a property of the target. `AgentCapabilities` does
+     * not declare it, so it is stated here, where the implementation is already named — which
+     * keeps adding an agent a one-line change.
+     */
+    family: EstimatorFamily;
+}
+/** The agent list. Adding an agent adds one line here (FR-57). */
+export declare const AGENTS: readonly AgentEntry[];

package/node_modules/resume-from/dist/host/agents.js

@@ -0,0 +1,20 @@
+/**
+ * The agent list — the one place in the tree that knows which adapters exist (FR-57).
+ *
+ * It lives in the composition root rather than in `src/adapters/` because nothing depends on the
+ * composition root. A list inside `src/adapters/` would close the cycle
+ * list → `adapters/pi` → `import` → adapter port, and the Pi entry point could not exist.
+ *
+ * Adding an agent is a new folder under `src/adapters/`, a new value in `AgentId`, and one line
+ * below. There is no `switch` anywhere in this module for the same reason: a branch on the agent
+ * name would be a second place to edit.
+ */
+import { claudeCodeAdapter } from "../adapters/claude-code/index.js";
+import { codexAdapterFactory } from "../adapters/codex/index.js";
+import { piAdapterFactory } from "../adapters/pi/index.js";
+/** The agent list. Adding an agent adds one line here (FR-57). */
+export const AGENTS = [
+    { create: () => piAdapterFactory.create(), family: "claude" },
+    { create: () => codexAdapterFactory.create(), family: "gpt" },
+    { create: () => claudeCodeAdapter.create(), family: "claude" },
+];

package/node_modules/resume-from/dist/host/cli/args.d.ts

@@ -0,0 +1,21 @@
+import type { AgentId, HomePath, SelectionInput } from "./contract.js";
+export declare const USAGE = "Usage: /resume-from [<agent>] [<row> | <session-id> | <file-path>] [--home <path>] [--agent <name>] [--confirm <token>]";
+/** The one confirmation flag. `runner.ts` strips it from re-run hints with the same predicate. */
+export declare const CONFIRM_FLAG = "--confirm";
+/** True for both accepted forms: `--confirm <token>` and `--confirm=<token>`. */
+export declare function isConfirmFlag(arg: string): boolean;
+export interface ParsedArgs {
+    /** Null when the user asked for the list (FR-10). */
+    selection: SelectionInput | null;
+    onlyAgent: AgentId | null;
+    onlyHome: HomePath | null;
+    confirmationToken: string | null;
+}
+export type ParseResult = {
+    ok: true;
+    args: ParsedArgs;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function parseArgs(argv: string[], cwd: string): ParseResult;