@herbertgao/pi-extensions 2026.8.8 → 2026.8.10

package/node_modules/resume-from/dist/import/landing/lander.js

@@ -0,0 +1,133 @@
+import { LandingFailure } from "./errors.js";
+import { buildHandover, describeSession } from "./handover.js";
+import { buildMarker } from "./marker.js";
+/** The one landing level that moves the user in (FR-43, FR-44). */
+const SWITCH_LEVEL = "create-and-switch";
+const RETRY = "Fix the cause, then run the import again.";
+const COMMIT_NEXT_STEP = {
+    "path-exists": "Nothing was created and nothing existing was touched. Remove or rename that path, then run the import again.",
+    "not-writable": "Nothing was created. Give the target home write permission, then run the import again.",
+    "write-failed": "Nothing was created. Check the free space and the permissions of the target home, then run the import again.",
+};
+function reasonOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * A rejection is only treated as a CommitError when its refusal is one this
+ * module knows a next step for. Anything else gets the generic next step
+ * instead of an interpolated "undefined" (FR-56).
+ */
+function asCommitError(cause) {
+    if (typeof cause !== "object" || cause === null || !("refusal" in cause))
+        return null;
+    const { refusal } = cause;
+    return typeof refusal === "string" && Object.hasOwn(COMMIT_NEXT_STEP, refusal)
+        ? cause
+        : null;
+}
+function commitNextStep(refused) {
+    if (refused === null)
+        return `Nothing was created. ${RETRY}`;
+    if (refused.remainingPaths !== undefined && refused.remainingPaths.length > 0) {
+        return `Cleanup was incomplete. Inspect these paths, then run the import again: ${refused.remainingPaths.join(", ")}.`;
+    }
+    return COMMIT_NEXT_STEP[refused.refusal];
+}
+function failAfterCommit(createdPaths, stage, what, home) {
+    const preserved = createdPaths.length === 0
+        ? `No paths were created in ${home}.`
+        : `The committed paths were preserved because automatic removal could delete replacements. Inspect them before retrying: ${createdPaths.join(", ")}.`;
+    return new LandingFailure(stage, `${what} ${preserved} ${RETRY}`);
+}
+async function runLanding(plan, adapter, committer, runtime, importedAt, buildCommand) {
+    const home = plan.target.home;
+    const target = plan.target.agent;
+    // Second gate: the preview should already have stopped this plan (FR-33).
+    if (plan.blockedReason !== null) {
+        throw new LandingFailure("serialize", 
+        // blockedReason ends in a sentence and carries the cause-specific advice (FR-33, FR-56).
+        `The plan cannot be imported: ${plan.blockedReason} Nothing was written to ${home}. ${RETRY}`);
+    }
+    const capabilities = adapter.capabilities();
+    const marker = buildMarker(plan, importedAt);
+    const session = {
+        provenance: plan.provenance,
+        turns: plan.turns,
+    };
+    let serialized;
+    try {
+        serialized = adapter.serialize(session, plan.target, marker);
+    }
+    catch (cause) {
+        throw new LandingFailure("serialize", `The ${target} adapter could not turn the plan into its own session format: ${reasonOf(cause)}. Nothing was written to ${home}. ${RETRY}`);
+    }
+    if (serialized.files.length !== 1) {
+        throw new LandingFailure("serialize", `The ${target} adapter produced ${serialized.files.length} files for one session. Exactly one file is required for atomic placement, so nothing was written to ${home}. Report this as an adapter bug.`);
+    }
+    let defects;
+    try {
+        defects = adapter.validate(serialized);
+    }
+    catch (cause) {
+        throw new LandingFailure("validate", `The ${target} adapter could not check the new session: ${reasonOf(cause)}. Nothing was written to ${home}. ${RETRY}`);
+    }
+    if (defects.length > 0) {
+        const summary = defects.map((defect) => `${defect.path}: ${defect.message}`).join("; ");
+        throw new LandingFailure("validate", `The new session is not valid for ${target}, so it was not placed: ${summary}. Nothing was written to ${home}. Report this as a bug, then run the import again once the adapter is fixed.`, { defects });
+    }
+    let createdPaths;
+    try {
+        ({ createdPaths } = await committer.commit(home, serialized.files));
+    }
+    catch (cause) {
+        const refused = asCommitError(cause);
+        const where = refused?.path ? ` (path: ${refused.path})` : "";
+        const next = commitNextStep(refused);
+        throw new LandingFailure("commit", `Creating the new session in ${home} failed: ${reasonOf(cause)}${where} ${next}`);
+    }
+    let stored;
+    try {
+        stored = await adapter.readBack(home, serialized.sessionId);
+    }
+    catch (cause) {
+        throw failAfterCommit(createdPaths, "read-back", `The new session in ${home} could not be read back: ${reasonOf(cause)}.`, home);
+    }
+    if (stored.sessionId !== serialized.sessionId) {
+        throw failAfterCommit(createdPaths, "read-back", `${target} read back session ${stored.sessionId} instead of the new session ${serialized.sessionId}.`, home);
+    }
+    if (stored.itemCount !== serialized.itemCount) {
+        throw failAfterCommit(createdPaths, "read-back", `${target} stored ${stored.itemCount} of the ${serialized.itemCount} items that were sent, so the session is incomplete.`, home);
+    }
+    if (!stored.openable) {
+        throw failAfterCommit(createdPaths, "read-back", `${target} could not open the new session ${serialized.sessionId}.`, home);
+    }
+    const ref = { agent: target, home, id: serialized.sessionId };
+    const landed = {
+        ref,
+        itemsSent: serialized.itemCount,
+        itemsStored: stored.itemCount,
+        marker,
+    };
+    const handover = () => buildHandover(buildCommand, target, serialized.sessionId);
+    if (capabilities.landing !== SWITCH_LEVEL) {
+        return { ...landed, switched: false, handover: handover() };
+    }
+    let outcome;
+    try {
+        outcome = await adapter.switchTo(home, serialized.sessionId, runtime);
+    }
+    catch (cause) {
+        // The session is valid, so it is kept: destroying it would destroy work.
+        throw new LandingFailure("switch", `The new session was created and is valid, but moving you into it failed: ${reasonOf(cause)}. The session was kept. Open it yourself: ${handover().command}`);
+    }
+    // A declined move is not a failure: the session stays and the user opens it later.
+    return outcome.switched
+        ? { ...landed, switched: true, handover: null }
+        : { ...landed, switched: false, handover: handover() };
+}
+export function createSessionLander(options = {}) {
+    const buildCommand = options.handoverCommand ?? describeSession;
+    return {
+        land: (plan, adapter, committer, runtime, importedAt) => runLanding(plan, adapter, committer, runtime, importedAt, buildCommand),
+    };
+}

package/node_modules/resume-from/dist/import/landing/marker.d.ts

@@ -0,0 +1,9 @@
+import type { ProvenanceMarker, TransferPlan } from "./contract.js";
+/** One line naming what the rules removed (FR-47). Never more than one line. */
+export declare function summariseDrops(plan: TransferPlan): string;
+/**
+ * The provenance marker the user sees (FR-47). `lines` renders the same facts
+ * in the order they must be shown; where they are shown is the adapter's
+ * declared capability (FR-48), not this module's decision.
+ */
+export declare function buildMarker(plan: TransferPlan, importedAt: string): ProvenanceMarker;

package/node_modules/resume-from/dist/import/landing/marker.js

@@ -0,0 +1,46 @@
+const NOTHING_DROPPED = "Nothing was dropped: the whole session crossed over.";
+const DROPPED_PREFIX = "Dropped on import: ";
+const PART_SEPARATOR = "; ";
+function counted(amount, one, many) {
+    return `${amount} ${amount === 1 ? one : many}`;
+}
+/** One line naming what the rules removed (FR-47). Never more than one line. */
+export function summariseDrops(plan) {
+    const parts = [];
+    if (plan.droppedTurnCount > 0)
+        parts.push(counted(plan.droppedTurnCount, "turn", "turns"));
+    if (plan.bodiesDropped > 0) {
+        parts.push(counted(plan.bodiesDropped, "tool result body", "tool result bodies"));
+    }
+    const brokenTails = plan.drops.filter((drop) => drop.reason === "broken-tail").length;
+    if (brokenTails === 1)
+        parts.push("an incomplete trailing tool call");
+    if (brokenTails > 1)
+        parts.push(`${brokenTails} incomplete trailing tool calls`);
+    if (parts.length === 0)
+        return NOTHING_DROPPED;
+    return `${DROPPED_PREFIX}${parts.join(PART_SEPARATOR)}.`;
+}
+/**
+ * The provenance marker the user sees (FR-47). `lines` renders the same facts
+ * in the order they must be shown; where they are shown is the adapter's
+ * declared capability (FR-48), not this module's decision.
+ */
+export function buildMarker(plan, importedAt) {
+    const { ref } = plan.provenance;
+    const droppedSummary = summariseDrops(plan);
+    return {
+        sourceAgent: ref.agent,
+        sourceHome: ref.home,
+        sourceSessionId: ref.id,
+        importedAt,
+        droppedSummary,
+        lines: [
+            `Imported from ${ref.agent}`,
+            `Source home: ${ref.home}`,
+            `Source session: ${ref.id}`,
+            `Imported at: ${importedAt}`,
+            droppedSummary,
+        ],
+    };
+}

package/node_modules/resume-from/dist/import/pipeline.d.ts

@@ -0,0 +1,17 @@
+import type { AgentAdapter, FileCommitter, ImportConfig, ImportPipeline, PreviewBuilder, SessionFinder, SessionLander, TokenEstimator, TransferRules } from "./contract.js";
+/** The four stages, and the services they are driven with. `wiring.ts` builds them. */
+export interface PipelineStages {
+    finder: SessionFinder;
+    rules: TransferRules;
+    /** A preview builder that reads the repository the request names. */
+    previewFor(repoRoot: string): PreviewBuilder;
+    lander: SessionLander;
+    /** Every adapter the composition root constructed. This module only looks one up. */
+    adapters: readonly AgentAdapter[];
+    config: ImportConfig;
+    estimator: TokenEstimator;
+    committer: FileCommitter;
+    /** ISO-8601 UTC. Only the landing reads it, so a preview and a commit agree (FR-47). */
+    now(): string;
+}
+export declare function createPipelineFromStages(stages: PipelineStages): ImportPipeline;

package/node_modules/resume-from/dist/import/pipeline.js

@@ -0,0 +1,134 @@
+// The three operations every host drives, and the order of the four stages behind them.
+// Nothing here knows an agent: the source adapter comes from the chosen session and the
+// target adapter from the target profile (FR-6, FR-60).
+import { confirmationMatches, confirmationToken } from "./confirmation.js";
+import { ImportFailure, reasonOf } from "./errors.js";
+/** The role a target adapter must declare to receive an import (FR-59). */
+const TARGET_ROLE = "target";
+const PREVIEW_AGAIN = "Preview it again, then confirm.";
+const IMPORT_AGAIN = "Fix the cause, then run the import again.";
+function scopeOf(request) {
+    return {
+        repoRoot: request.repoRoot,
+        onlyAgent: request.onlyAgent,
+        onlyHome: request.onlyHome,
+    };
+}
+/**
+ * The adapter that receives the import. This lookup is the only place `AgentId` decides
+ * anything in this module, and a lookup is not a branch on the pair (FR-59, FR-60).
+ */
+function targetAdapter(adapters, target) {
+    const found = adapters.filter((adapter) => adapter.capabilities().agent === target.agent);
+    if (found.length === 0) {
+        throw new ImportFailure("target", `There is no adapter for "${target.agent}", so an import cannot be sent to it. Run the import from an agent the tool supports, or add an adapter for "${target.agent}".`);
+    }
+    const usable = found.find((adapter) => adapter.capabilities().roles.includes(TARGET_ROLE));
+    if (!usable) {
+        throw new ImportFailure("target", `The "${target.agent}" adapter cannot receive an import: it declares the role(s) ${found[0]?.capabilities().roles.join(", ")} and not "${TARGET_ROLE}". Choose a target agent whose adapter has the "${TARGET_ROLE}" role.`);
+    }
+    return usable;
+}
+/** A rejection carrying what the landing already explained (FR-50, FR-56). */
+function isLandingError(cause) {
+    return cause instanceof Error && "stage" in cause && "defects" in cause;
+}
+export function createPipelineFromStages(stages) {
+    async function resolve(request) {
+        try {
+            return await stages.finder.resolve(scopeOf(request), request.selection);
+        }
+        catch (cause) {
+            throw new ImportFailure("discovery", `The session could not be chosen: ${reasonOf(cause)}`, {
+                cause,
+            });
+        }
+    }
+    async function load(descriptor) {
+        try {
+            return await stages.finder.load(descriptor);
+        }
+        catch (cause) {
+            throw new ImportFailure("discovery", `The source session ${descriptor.ref.id} could not be read: ${reasonOf(cause)}. Nothing was written. Check that ${descriptor.filePath} still exists and can be read, then run the import again.`, { cause });
+        }
+    }
+    /**
+     * Resolve, load, apply the rules, build the report. `commit` runs exactly this again
+     * rather than taking a plan from the host: the numbered-list hosts of FR-10 are separate
+     * processes, and a plan cannot travel between them.
+     */
+    async function compute(request) {
+        const descriptor = await resolve(request);
+        const session = await load(descriptor);
+        let plan;
+        try {
+            plan = stages.rules.apply(session, request.target, stages.config, stages.estimator);
+        }
+        catch (cause) {
+            throw new ImportFailure("plan", `What to carry over could not be decided for session ${descriptor.ref.id}: ${reasonOf(cause)}. Nothing was written. ${IMPORT_AGAIN}`, { cause });
+        }
+        let report;
+        try {
+            report = await stages.previewFor(request.repoRoot).build(plan);
+        }
+        catch (cause) {
+            throw new ImportFailure("preview", `The preview of session ${descriptor.ref.id} could not be built: ${reasonOf(cause)}. Nothing was written. ${IMPORT_AGAIN}`, { cause });
+        }
+        const token = confirmationToken(descriptor, plan, report);
+        return {
+            descriptor,
+            plan,
+            report: { ...report, confirmationToken: token },
+        };
+    }
+    return {
+        async list(request) {
+            try {
+                return await stages.finder.list(scopeOf(request));
+            }
+            catch (cause) {
+                throw new ImportFailure("discovery", `The sessions of this repository could not be listed: ${reasonOf(cause)}. Check that ${request.repoRoot} is readable, then run the list again.`, { cause });
+            }
+        },
+        async preview(request) {
+            // Refused here as well as in commit, so a host is told about an impossible
+            // target before it shows the user a preview it could never confirm.
+            targetAdapter(stages.adapters, request.target);
+            // A blocked plan still produces a report: the user is told why it cannot run (FR-33).
+            return (await compute(request)).report;
+        },
+        async commit(request, runtime, suppliedToken) {
+            const adapter = targetAdapter(stages.adapters, request.target);
+            const { descriptor, plan, report } = await compute(request);
+            if (!confirmationMatches(report.confirmationToken, suppliedToken)) {
+                throw new ImportFailure("confirmation", `The source session or preview changed after confirmation. Nothing was written to ${request.target.home}. ${PREVIEW_AGAIN}`);
+            }
+            if (plan.blockedReason !== null) {
+                // blockedReason already ends in a sentence and carries the cause-specific
+                // advice (FR-33, FR-56); this adds only what the pipeline alone knows.
+                throw new ImportFailure("blocked", `The import cannot run: ${plan.blockedReason} Nothing was written to ${request.target.home}. ${PREVIEW_AGAIN}`);
+            }
+            // The freshness check. The listing reports when the source file last moved; the plan
+            // carries when the content it was built from was last recorded. A file that moved past
+            // its own last turn is a session the user has not seen (FR-20, FR-56).
+            if (descriptor.updatedAt !== plan.provenance.updatedAt) {
+                throw new ImportFailure("source-changed", `The source session ${descriptor.ref.id} changed after the preview: ${descriptor.filePath} was last written at ${descriptor.updatedAt}, and the conversation the preview showed ends at ${plan.provenance.updatedAt}. Nothing was written. ${PREVIEW_AGAIN}`);
+            }
+            try {
+                return await stages.lander.land(plan, adapter, stages.committer, runtime, stages.now());
+            }
+            catch (cause) {
+                // The landing states what failed and what to do next for every one of its stages;
+                // anything else reaching here is a defect and gets the generic next step (FR-56).
+                const known = isLandingError(cause);
+                const message = known
+                    ? cause.message
+                    : `The import could not be placed in ${request.target.home}: ${reasonOf(cause)}. ${IMPORT_AGAIN}`;
+                throw new ImportFailure("landing", message, {
+                    cause,
+                    defects: known ? cause.defects : [],
+                });
+            }
+        },
+    };
+}

package/node_modules/resume-from/dist/import/preview/builder.d.ts

@@ -0,0 +1,6 @@
+import type { PreviewBuilder, RepoReader } from "./contract.js";
+/**
+ * Builds the preview from a plan and the repository state read at the moment of the call.
+ * It writes nothing (FR-16) and renders one shape for every direction (FR-21).
+ */
+export declare function createPreviewBuilder(repo: RepoReader, cwd: string): PreviewBuilder;

package/node_modules/resume-from/dist/import/preview/builder.js

@@ -0,0 +1,76 @@
+import { formatTokens, oneLine, plural } from "./format.js";
+import { planWarnings, repoWarning, sortWarnings } from "./warnings.js";
+/** Paths are longer than titles and are not shortened to the same length. */
+const MAX_PATH_LENGTH = 160;
+const MAX_REASON_LENGTH = 200;
+const UNTITLED = "(untitled)";
+// Each blockedReason now carries its own cause-specific advice (FR-33, FR-56), so no
+// single fallback string is accurate for all block causes.
+function headerLines(plan) {
+    const source = plan.provenance.ref;
+    const title = oneLine(plan.provenance.title) || UNTITLED;
+    return [
+        `Source: ${source.agent} — ${title} (${oneLine(source.home, MAX_PATH_LENGTH)})`,
+        `Target: ${plan.target.agent} (${oneLine(plan.target.home, MAX_PATH_LENGTH)})`,
+        countLine(plan),
+    ];
+}
+/** FR-17: both counts, and both come from the plan. */
+function countLine(plan) {
+    const kept = plan.keptTurnCount;
+    const crossing = kept === 0
+        ? "Nothing would cross over"
+        : `${kept} ${plural(kept, "turn crosses", "turns cross")} over`;
+    return plan.droppedTurnCount > 0 ? `${crossing}, ${plan.droppedTurnCount} dropped` : crossing;
+}
+/** FR-35. A plan that dropped nothing produces no line at all — never "0 turns dropped". */
+function dropLines(plan) {
+    const lines = [];
+    const budgetDrops = plan.drops.filter((drop) => drop.reason === "budget").length;
+    if (budgetDrops > 0) {
+        lines.push(`${budgetDrops} older ${plural(budgetDrops, "turn", "turns")} dropped`);
+    }
+    if (plan.bodiesDropped > 0) {
+        lines.push(`${plan.bodiesDropped} tool result ${plural(plan.bodiesDropped, "body", "bodies")} dropped`);
+    }
+    return lines;
+}
+function blockedLines(blockedReason) {
+    if (blockedReason === null)
+        return [];
+    return [`✖ The import cannot run: ${oneLine(blockedReason, MAX_REASON_LENGTH)}`];
+}
+/**
+ * Builds the preview from a plan and the repository state read at the moment of the call.
+ * It writes nothing (FR-16) and renders one shape for every direction (FR-21).
+ */
+export function createPreviewBuilder(repo, cwd) {
+    return {
+        async build(plan) {
+            const collected = planWarnings(plan);
+            const fromRepo = await repoWarning(plan, repo, cwd);
+            if (fromRepo !== null)
+                collected.push(fromRepo);
+            const warnings = sortWarnings(collected);
+            const header = headerLines(plan);
+            const budgetLine = `Budget: ${formatTokens(plan.estimatedTokens)} tokens of a ${formatTokens(plan.target.windowTokens)} window`;
+            const drops = dropLines(plan);
+            const blocked = plan.blockedReason !== null;
+            return {
+                headerLines: header,
+                budgetLine,
+                warnings,
+                dropLines: drops,
+                blocked,
+                blockedReason: plan.blockedReason,
+                lines: [
+                    ...header,
+                    budgetLine,
+                    ...warnings.map((warning) => warning.line),
+                    ...drops,
+                    ...blockedLines(plan.blockedReason),
+                ],
+            };
+        },
+    };
+}

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

@@ -0,0 +1,39 @@
+import type { DropReason, PinReason, TransferPlan, TurnDrop, TurnPin } from "../transfer/contract.js";
+export type { DropReason, PinReason, TransferPlan, TurnDrop, TurnPin };
+import type { CommitDistance, RepoIdentity, RepoReader } from "../../platform/repo/contract.js";
+export type { CommitDistance, RepoIdentity, RepoReader };
+import type { AgentId, CanonicalSession, CanonicalTurn, HomePath, RepoSnapshot, SessionId, SessionRef, SourceProvenance, TargetProfile, ToolCallRecord, ToolEffect, TurnKind, TurnRole } from "../../session/contract.js";
+export type { AgentId, CanonicalSession, CanonicalTurn, HomePath, RepoSnapshot, SessionId, SessionRef, SourceProvenance, TargetProfile, ToolCallRecord, ToolEffect, TurnKind, TurnRole, };
+/** What a warning is about. Repository warnings sort first (FR-19). */
+export type WarningKind = "repo-state" | "budget" | "broken-tail" | "capability";
+/** One warning line of the preview (FR-19). */
+export interface PreviewWarning {
+    kind: WarningKind;
+    /** The rendered line, ready to show. */
+    line: string;
+}
+/** Everything the user sees before confirming (FR-16 to FR-21). */
+export interface PreviewReport {
+    /** Opaque binding that must be returned unchanged to commit this exact preview (FR-20). */
+    confirmationToken: string;
+    /** Source, target, and the turn counts that cross and are dropped (FR-17). */
+    headerLines: string[];
+    /** For example "Budget: 34k tokens of a 200k window" (FR-18). */
+    budgetLine: string;
+    /** Repository warnings first (FR-19). */
+    warnings: PreviewWarning[];
+    /** For example "12 older turns dropped" (FR-35). */
+    dropLines: string[];
+    /** True when the import cannot run. Nothing may be written (FR-33). */
+    blocked: boolean;
+    /** Set when blocked is true. States what to change. */
+    blockedReason: string | null;
+    /** The whole preview, rendered. The same shape for all nine directions (FR-21). */
+    lines: string[];
+}
+/** Preview content before the pipeline binds it to a confirmation token. */
+export type PreviewContent = Omit<PreviewReport, "confirmationToken">;
+/** Builds the preview from a plan and the current repository state. */
+export interface PreviewBuilder {
+    build(plan: TransferPlan): Promise<PreviewContent>;
+}

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

@@ -0,0 +1,4 @@
+// GENERATED from src/import/preview/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/import/preview/format.d.ts

@@ -0,0 +1,19 @@
+/** How the preview writes numbers, commits and untrusted text. Nothing here reads a plan. */
+/** The thousands abbreviation of FR-18: 34000 becomes "34k", 840 stays "840". */
+export declare function formatTokens(tokens: number): string;
+/** The short commit form the preview shows. */
+export declare function shortCommit(commit: string): string;
+/**
+ * True when two commits name the same one, whether abbreviated or full. A prefix match
+ * needs at least a short commit on both sides: source text is untrusted, and "9" must
+ * not silence the warning that the tree moved.
+ */
+export declare function sameCommit(left: string, right: string): boolean;
+/**
+ * One line in, one line out. Source titles and paths are attacker-controlled text
+ * (FR-60): folding newlines and control characters is what stops a session title
+ * from forging a preview line of its own.
+ */
+export declare function oneLine(text: string, maxLength?: number): string;
+/** Singular or plural, chosen by the count. */
+export declare function plural(count: number, one: string, many: string): string;

package/node_modules/resume-from/dist/import/preview/format.js

@@ -0,0 +1,45 @@
+/** How the preview writes numbers, commits and untrusted text. Nothing here reads a plan. */
+const THOUSAND = 1000;
+const SHORT_COMMIT_LENGTH = 7;
+const MAX_TEXT_LENGTH = 80;
+/** The thousands abbreviation of FR-18: 34000 becomes "34k", 840 stays "840". */
+export function formatTokens(tokens) {
+    const value = Math.max(0, Math.round(tokens));
+    return value >= THOUSAND ? `${Math.round(value / THOUSAND)}k` : String(value);
+}
+/** The short commit form the preview shows. */
+export function shortCommit(commit) {
+    return commit.replace(/\s+/gu, "").slice(0, SHORT_COMMIT_LENGTH);
+}
+/**
+ * True when two commits name the same one, whether abbreviated or full. A prefix match
+ * needs at least a short commit on both sides: source text is untrusted, and "9" must
+ * not silence the warning that the tree moved.
+ */
+export function sameCommit(left, right) {
+    const a = left.replace(/\s+/gu, "").toLowerCase();
+    const b = right.replace(/\s+/gu, "").toLowerCase();
+    if (a === "" || b === "")
+        return false;
+    if (a === b)
+        return true;
+    if (a.length < SHORT_COMMIT_LENGTH || b.length < SHORT_COMMIT_LENGTH)
+        return false;
+    return a.startsWith(b) || b.startsWith(a);
+}
+/**
+ * One line in, one line out. Source titles and paths are attacker-controlled text
+ * (FR-60): folding newlines and control characters is what stops a session title
+ * from forging a preview line of its own.
+ */
+export function oneLine(text, maxLength = MAX_TEXT_LENGTH) {
+    const flat = text
+        .replace(/\p{Cc}/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+    return flat.length > maxLength ? `${flat.slice(0, maxLength)}…` : flat;
+}
+/** Singular or plural, chosen by the count. */
+export function plural(count, one, many) {
+    return count === 1 ? one : many;
+}

package/node_modules/resume-from/dist/import/preview/index.d.ts

@@ -0,0 +1,2 @@
+export { createPreviewBuilder } from "./builder.js";
+export type { PreviewBuilder, PreviewContent, PreviewReport, PreviewWarning, WarningKind, } from "./contract.js";

package/node_modules/resume-from/dist/import/preview/index.js

@@ -0,0 +1 @@
+export { createPreviewBuilder } from "./builder.js";

package/node_modules/resume-from/dist/import/preview/warnings.d.ts

@@ -0,0 +1,11 @@
+import type { PreviewWarning, RepoReader, TransferPlan } from "./contract.js";
+/** Orders warnings by kind, keeping the order they were added within one kind. */
+export declare function sortWarnings(warnings: PreviewWarning[]): PreviewWarning[];
+/**
+ * Compares the source commit with the current HEAD (FR-37, FR-38). A repository that
+ * cannot be read, or a commit this tree does not have, is said to be unknown — never
+ * guessed and never left out (FR-36). None of these block (FR-39).
+ */
+export declare function repoWarning(plan: TransferPlan, repo: RepoReader, cwd: string): Promise<PreviewWarning | null>;
+/** The warnings that come from the plan alone. */
+export declare function planWarnings(plan: TransferPlan): PreviewWarning[];

package/node_modules/resume-from/dist/import/preview/warnings.js

@@ -0,0 +1,80 @@
+import { formatTokens, plural, sameCommit, shortCommit } from "./format.js";
+/** Repository warnings sort first (FR-19); the rest follow this order. */
+const KIND_ORDER = ["repo-state", "budget", "broken-tail", "capability"];
+const NOT_KNOWN = "not known here";
+const GLYPH = "⚠";
+/** Orders warnings by kind, keeping the order they were added within one kind. */
+export function sortWarnings(warnings) {
+    return [...warnings].sort((a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind));
+}
+function repoState(line) {
+    return { kind: "repo-state", line };
+}
+/** "(14 commits ahead)", "(3 commits behind)", or "" when the tree did not move. */
+function describeGap({ ahead, behind }) {
+    const commits = (count) => `${count} ${plural(count, "commit", "commits")}`;
+    if (ahead > 0 && behind > 0)
+        return ` (${commits(ahead)} ahead, ${behind} behind)`;
+    if (ahead > 0)
+        return ` (${commits(ahead)} ahead)`;
+    if (behind > 0)
+        return ` (${commits(behind)} behind)`;
+    return "";
+}
+/**
+ * Compares the source commit with the current HEAD (FR-37, FR-38). A repository that
+ * cannot be read, or a commit this tree does not have, is said to be unknown — never
+ * guessed and never left out (FR-36). None of these block (FR-39).
+ */
+export async function repoWarning(plan, repo, cwd) {
+    const unreadable = repoState(`${GLYPH} The repository state could not be read, so the source commit is ${NOT_KNOWN}.`);
+    let identity;
+    try {
+        identity = await repo.identify(cwd);
+    }
+    catch {
+        return unreadable;
+    }
+    const sourceCommit = plan.provenance.repo.commit;
+    if (sourceCommit === null || sourceCommit.trim() === "") {
+        return repoState(`${GLYPH} The source session did not record a commit, so the repository state is ${NOT_KNOWN}.`);
+    }
+    const source = shortCommit(sourceCommit);
+    if (identity.root === null) {
+        return repoState(`${GLYPH} Source ran at ${source}. This directory is not a repository, so the repository state is ${NOT_KNOWN}.`);
+    }
+    if (identity.head === null) {
+        return repoState(`${GLYPH} Source ran at ${source}. This repository has no commit yet, so the repository state is ${NOT_KNOWN}.`);
+    }
+    if (sameCommit(sourceCommit, identity.head))
+        return null;
+    const head = shortCommit(identity.head);
+    let distance;
+    try {
+        distance = await repo.distanceFrom(sourceCommit);
+    }
+    catch {
+        return unreadable;
+    }
+    if (!distance.known) {
+        return repoState(`${GLYPH} Source ran at ${source}, which is ${NOT_KNOWN}. The tree is now at ${head}.`);
+    }
+    return repoState(`${GLYPH} Source ran at ${source}. The tree is now at ${head}${describeGap(distance)}.`);
+}
+/** The warnings that come from the plan alone. */
+export function planWarnings(plan) {
+    const warnings = [];
+    if (plan.estimatedTokens > plan.budgetTokens) {
+        warnings.push({
+            kind: "budget",
+            line: `${GLYPH} The import is ${formatTokens(plan.estimatedTokens)} tokens, over its ${formatTokens(plan.budgetTokens)} budget.`,
+        });
+    }
+    if (plan.brokenTailDropped) {
+        warnings.push({
+            kind: "broken-tail",
+            line: `${GLYPH} The last tool call was incomplete and was dropped.`,
+        });
+    }
+    return warnings;
+}