@papillon6814/copi 0.1.0 → 0.2.1

package/LICENSE.unicode

@@ -0,0 +1,39 @@
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 1991-2026 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.

package/README.md

@@ -5,9 +5,9 @@
 ## Status and requirements
 
 - Package: `@papillon6814/copi`; command: `copi`.
-- macOS only; Node.js 22.19.0 or newer.
-- The package is not published yet. Do not rely on the npm install command below until publication is announced.
-- If published, install with `npm install --global @papillon6814/copi`.
+- macOS only (saving resources into the library requires Apple Silicon / arm64); Node.js 22.19.0 or newer.
+- Install with `npm install --global @papillon6814/copi`. npm creates the `copi` command.
+- Version 0.1.0 predates the catalog v2 `sources` layout. Use 0.2.0 or newer with a migrated library.
 - An older, unrelated tool may already provide a `copi` command. Check `command -v copi` before installing globally; resolve any command-name conflict deliberately.
 
 For a local checkout, run `npm install --ignore-scripts`, `npm run build`, then `node dist/src/cli.js help`.
@@ -16,22 +16,74 @@ For a local checkout, run `npm install --ignore-scripts`, `npm run build`, then
 
 ```text
 copi setup
+copi manage
 copi groups
 copi list
 copi apply <group> [target]
 copi apply <group> [target] --dry-run
+copi migrate [--dry-run]
+copi migrate --resolve [--dry-run]
 copi help
 ```
 
 `setup` requires an interactive terminal. It asks which locations may be searched and asks for explicit authorization before searching. Selecting the entire `HOME` is broad: it can inspect supported resources throughout that directory, including Pi profiles and the configured Pi agent directory. Selecting the current project scopes discovery to that project. The wizard then lets you choose individual resources, review masked previews, assign each saved resource to one or more groups, and confirm before anything is copied into the library. Declining authorization performs no search.
 
+`manage` requires both stdin and stdout to be an interactive TTY. Choose saved resources and groups by name; UUID input is not required and normal screens identify resources by display name, kind, groups and destination. It provides masked viewing, terminal text editing, display-name changes, separate destination changes, source refresh, group management and apply. Running without arguments, or with `help`, `--help` or `-h`, still shows help.
+
+Resource display names and group names are each unique across the library, in separate namespaces. Comparison uses `trim → NFKC → Unicode 17.0.0 default full case folding → NFKC` (not locale-specific); display names and body text are not automatically normalized or rewritten. For example, `Ａ` and `a`, or `Straße` and `STRASSE`, conflict within one namespace. Legacy duplicate catalogs remain readable: use **Resolve name conflicts** to rename them manually. Until resolved, only listing, masked viewing and conflict resolution are allowed; no automatic renaming occurs.
+
 `groups` lists groups in a non-interactive terminal; group changes require a TTY and are saved only after confirmation. `list` is read-only. `apply --dry-run` prints the planned paths, masked text diffs, and warnings without changing the target. A real apply requires a TTY and confirmation.
 
-Groups contain resource IDs, not merged documents. The same saved resource may belong to multiple groups. `copi` copies files byte-for-byte; it does not split, rewrite, merge, or run resource contents. It does not install dependencies or apply global-only resources to a project. Review every proposed change.
+Pi automatically loads only context files (`AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, `CLAUDE.MD`) and `.pi/SYSTEM.md` / `.pi/APPEND_SYSTEM.md`. When a group applies another instruction (for example `RULES.md`) and no context file at the project root mentions its path, `apply` warns. It offers to append one reference line per instruction (`- 作業を始める前に \`RULES.md\` を読み、その指示に従うこと。`) to the root context file Pi prefers (`AGENTS.override.md` first); if no root context file exists, it offers to create `AGENTS.md`. The offer is a separate default-no approval; declining still applies the other files. An existing file is backed up privately before the append. `--dry-run` prints the same warning and diff. No reference is offered when the file Pi prefers is a symbolic link, not a regular file, not UTF-8, or larger than 1 MB, or when the same group also places a root context file (matched case-insensitively); the warning then shows the line to add yourself. Only the project root is checked; parent directories and the Pi agent directory are not.
+
+`migrate --dry-run` and `migrate --resolve --dry-run` are read-only and may run without a TTY. A mutating `migrate` or `migrate --resolve` requires both stdin and stdout to be a TTY. Reviews print the complete masked diff, then ask for whole-review approval (default no), a separate default-no approval for each sensitive path, and a final default-no confirmation. There is no `--yes` flag. Refusal, EOF, Ctrl-C, blocked state, usage errors, and non-TTY mutation exit with status 1; ready dry-runs, successful operations and a resolution that is not needed exit with status 0.
+
+Ordinary `migrate` adopts only eligible existing `sources` content and keeps a verified backup. If an internal migration lock or resolution record blocks it, the CLI points to `migrate --resolve --dry-run`; do not manually remove internal locks. Resolution is limited to eligible post-switch adopted-source edits: it confirms the reviewed edit, preserves source bytes, retains the verified backup, and removes only owned internal migration leftovers. `migrate --resolve` never falls back to ordinary migration. It does not rewrite the catalog, sources or items, distribute resources, or delete items. A blocked review stops while preserving edits and remaining artifacts; a new review may be needed after a cleanup interruption. Never use an older `copi` binary while resolution artifacts remain. v4 journals do not have the start inventory required for this procedure and remain on the existing recovery/hold-stop path. A migration backup is not general history or a restore feature. Migration, item deletion, main integration and publishing require separate approval. Migration (M) and items deletion (D) each require separate approval from one another.
+
+### Migration support limits and safe-stop guide
+
+R4 migration is adopt-only. `copi migrate --dry-run` may show a `ready` preview for an item backed only by legacy `items`, but items-only content and new `sources` additions are not supported. Commit rejects such a plan before writing; a `ready` preview is not proof that migration can be committed. Migration succeeds only when every selected payload can be adopted from eligible content already in `sources`.
+
+The packaged native source-placement helper is currently built for macOS arm64. Every product entry point that needs exclusive native placement declares that requirement and performs a read-only check for the supported platform, packaged helper, and filesystem capability before creating or changing any library path, transaction lock, stage, or journal. If the platform or helper is unsupported, the filesystem does not advertise the required operation, or its capability cannot be determined, the request stops before the first filesystem write; no ordinary rename or copy fallback is used. For a library that does not yet exist, the filesystem check uses its nearest existing directory ancestor. This placement limit does not by itself prohibit read-only commands.
+
+`StorageTransactions.run` requires TypeScript callers to explicitly declare whether native placement is required. The internal `#commitNewItems` boundary repeats the check so a direct adapter call from JavaScript cannot bypass it by omitting the option or passing `false`. Such an internal misuse may briefly acquire a transaction lock and root lease before rejection; it writes no content payload, stage, or journal, then cleans the lock and releases the lease. Product entry points preflight before that lock or lease is created.
+
+During an operation, do not move, rename, or replace the library root, `sources/`, or a saved item's management directory. This rule is about management directories, not ordinary content edits: editing a regular source file, an editor's file replacement, and skill file additions and removals are supported ordinary-edit cases. Do not treat a managed-directory move or replacement as an ordinary edit.
+
+For a migration stopped by an internal transaction lock or resolution record, first run `copi migrate --resolve --dry-run`. It is read-only. If it reports `ready`, review the complete masked diff; only then may you run `copi migrate --resolve` for the separate default-no whole-review, per-sensitive-path, and final confirmations. If the preview reports `blocked`, leave the edits and remaining artifacts in place. A v4 journal lacks the start inventory; unknown journal versions and incomplete or malformed states that the current build cannot verify remain held. An interrupted cleanup is eligible only when the current build explicitly verifies it and presents a `ready` review.
+
+If rollback leaves an existing `.migration-backups/` namespace, ordinary migration prepare is blocked because the backup is preserved and not adopted automatically. This is not a retry or restore path: never manually remove, move, or restore a migration backup or move the library contents. An offline preservation check of a real library is a separate read-only activity requiring separate explicit approval for that exact scope; neither a dry-run nor an earlier migration approval grants it. Such a check is not authorization to alter, move, restore, or delete anything, and it must not be reported as a successful migration.
+
+Do not hand-edit or remove internal migration-management files: `.copi-transaction` stage/journal files, `.copi-transaction-recovery` claims, or `.copi-migration-resolution.json`. A stage/journal rehash is a known LIMIT, not proof of authorization or custody; same-user manual changes to these internal files and manual edits to a completed resolution record are outside the protection boundary. `privateRevisionHash` is checked only against a same-process issued plan at commit; it is not a durable authentication key. The claim-absent/record-present window after claim removal and before completed-record unlink remains unsafe for older binaries; do not run one until all resolution artifacts are gone.
+
+If ordinary source edits occur during interrupted cleanup, recovery can hold-stop and preserve them. When a further pass is eligible, it requires a fresh review and new generation with fresh whole-review, per-sensitive-path, and final approvals; never replay an earlier approval. Out-of-scope changes remain held rather than overwritten.
+
+Groups contain resource IDs, not merged documents. The same saved resource may belong to multiple groups. Import and apply copy files byte-for-byte; they do not automatically split, rewrite, merge, or run resource contents. It does not install dependencies or apply global-only resources to a project. Review every proposed change.
+
+## Editing and refreshing saved copies
+
+A typical flow is `setup` → `manage` → select a resource by name → **Edit saved text** → **Rename display name** → **Refresh from source** → **Manage groups** → **Apply group**. Each change has its own review/confirmation; selecting a menu entry is not permission to save.
+
+The terminal editor works only on existing registered UTF-8 files inside the saved copy, up to **1_000_000 bytes** (1 MB), including the resulting edited bytes. Binary/NUL content, unsupported encodings and larger files are refused with a reason. It supports Japanese text, multiline bracketed paste, blank lines, cursor movement and scrolling:
+
+- `Ctrl-S`: submit the in-memory text for masked diff review; this does **not** save yet.
+- `Esc`, `Ctrl-C` or `Ctrl-D`: cancel; interruption leaves unconfirmed changes unsaved.
+- `Enter`: newline; arrow keys: move; `Home` / `End`: line start/end.
+- `Ctrl-Home` / `Ctrl-End`: document start/end; `PgUp` / `PgDn`: scroll; Backspace / Delete: remove text.
+
+Saving requires diff approval, fresh approval for each detected sensitive file in the fixed prepared bytes, and final confirmation. Normal views and diffs are masked. Before editing a detected sensitive file, a separate individual approval warns that its **raw text** may expose secrets on the screen, scrollback or terminal recordings. That exposure approval is not save approval. Detection is heuristic and may miss secrets. A checksum mismatch or concurrent change stops saving rather than silently repairing or overwriting the saved copy.
+
+Renaming changes the display name only: the internal ID, file names, body (including embedded agent names), destination and group references stay unchanged. Destination changes are a separate operation. Text editing cannot add/delete files or rename internal files.
+
+Refresh reads an explicitly permitted same-kind source (a directory tree for a skill; a regular file for other kinds). If the original is unavailable, select a new absolute source path or cancel; the saved copy remains available. No HOME or parent tree is searched implicitly. Registered package origins can be rediscovered only in explicitly selected and authorized locations; arbitrary source paths gain no exclusion exception. After masked diff review, inspection and individual sensitive-file approvals, refresh replaces the **whole** saved copy, including bundle file additions/removals and mode changes. All copi-only edits are lost, not merged. ID, display name, savedAt, destination and **all** group memberships are retained. Neither editing nor refresh writes back to the original.
+
+There is **no change history, restore feature or automatic merge**. Private apply backups for replaced project files are not saved-copy version history. Applying global settings, automatic dependency installation and content transformation remain outside scope.
+
+Japanese/paste/caret functionality is covered by automated CLI/PTY tests; real-device IME, paste and visual caret-width verification is outside this acceptance scope and has not been performed. The minimum Node 22.19.0 version itself and other operating systems have not been verified by these checks.
 
 ## Private storage and sensitive data
 
-Snapshots and the catalog are stored under `~/.copi/` with owner-only directory/file permissions. `copi` copies the selected source into its library; it does not modify or delete the original. Snapshots remain available if the original is later removed. The copied content retains its original license and ownership; the MIT license for `copi` does not apply to imported resources.
+Snapshots and the catalog are stored under `~/.copi/` with owner-only directory/file permissions: saved files are private `0600`. Original source modes are retained separately in snapshot descriptors/catalog reads and reproduced at the apply destination, not on the private saved inode. `copi` copies the selected source into its library; it does not modify or delete the original. Snapshots remain available if the original is later removed. The copied content retains its original license and ownership; the MIT license for `copi` does not apply to imported resources.
 
 Entire directories named `auth` are excluded; authentication-specific code may be missing, but other supported files in the resource are retained. Files named `auth.json`, `mcp-auth.json`, or `oauth.json`, `.env*` paths (including `.envrc` and `.env-production`), and repository/dependency/cache/history paths such as `.git`, `node_modules`, `.cache`, `.npm`, `cache`, `caches`, `history`, and `sessions` are excluded by the current resource filters. Do not use `copi` as a substitute for reviewing the files selected for copying.
 

package/dist/native/rename-exclusive-arm64.manifest.json

@@ -0,0 +1,12 @@
+{
+  "artifact": "rename-exclusive-arm64",
+  "sha256": "a8101d6b970dca67c3a3243b1bf49286ce4d26e463529e0bcca244704c98ae02",
+  "architecture": "arm64",
+  "platform": "darwin",
+  "protocolVersion": 1,
+  "deploymentTarget": "10.12",
+  "compiler": "/usr/bin/clang",
+  "compilerVersion": "Apple clang version 17.0.0 (clang-1700.6.3.2)",
+  "sdkPath": "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk",
+  "sdkVersion": "26.2"
+}

package/dist/src/apply.d.ts

@@ -23,17 +23,25 @@ export interface ApplyCollision {
     path: string;
     itemIds: string[];
 }
+export interface ApplyReferenceProposal {
+    path: string;
+    status: "new" | "append";
+    instructionPaths: string[];
+    preview: ApplyPreview;
+}
 export interface ApplyPlan {
     projectDir: string;
     files: ApplyFilePlan[];
     collisions: ApplyCollision[];
     warnings: InspectionWarning[];
     skippedItems: string[];
+    referenceProposal?: ApplyReferenceProposal;
 }
 export interface ApplyDecisions {
     collisions?: Record<string, string>;
     existing?: Record<string, "keep" | "replace" | "abort">;
     secretApprovals?: string[];
+    addReference?: boolean;
 }
 export interface ApplyBackup {
     path: string;
@@ -46,6 +54,7 @@ export interface ApplyResult {
     skippedItems: string[];
     backups: ApplyBackup[];
     cancelled: boolean;
+    referenceAdded?: string;
 }
 export declare function planApply(libraryDir: string, groupId: string, projectDir: string): Promise<ApplyPlan>;
 export declare function executeApply(libraryDir: string, plan: ApplyPlan, decisions: ApplyDecisions): Promise<ApplyResult>;

package/dist/src/apply.js

@@ -3,8 +3,10 @@ import { constants } from "node:fs";
 import { access, chmod, lstat, mkdir, open, readFile, realpath, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import { createTwoFilesPatch } from "diff";
-import { loadCatalog, readSnapshotFiles } from "./catalog.js";
+import { withSavedLibrary } from "./catalog.js";
 import { maskSensitiveText } from "./inspect.js";
+import { appendReferenceLines, chooseReferenceTarget, contextFileNames, isAutoLoadedInstruction, referenceLine, unreferencedPaths } from "./instruction-reference.js";
+import { assertNoNameConflicts } from "./names.js";
 const maxInspectionBytes = 1_000_000;
 const excludedNames = new Set([".git", ".cache", ".npm", "node_modules", "cache", "caches", "history", "sessions", "auth"]);
 const planState = new WeakMap();
@@ -168,20 +170,91 @@ function targetPath(item, filePath, fileCount) {
         throw new Error(`A file resource has an invalid snapshot layout: ${item.name}`);
     return item.destination.path;
 }
+async function readRootContextFiles(root) {
+    const files = new Map();
+    const seen = new Set();
+    for (const name of contextFileNames) {
+        const target = path.join(root, name);
+        const stat = await maybeLstat(target);
+        if (!stat || seen.has(stat.ino))
+            continue;
+        seen.add(stat.ino);
+        if (!stat.isFile()) {
+            files.set(name, "unusable");
+            continue;
+        }
+        const bytes = await readFile(target);
+        files.set(name, textFrom(bytes) === undefined ? "unusable" : { bytes, mode: stat.mode & 0o777, sha256: sha256(bytes) });
+    }
+    return files;
+}
+async function planInstructionReference(root, instructionPaths, candidates, warnings) {
+    const targets = instructionPaths.filter((value) => !isAutoLoadedInstruction(value));
+    if (targets.length === 0)
+        return undefined;
+    const current = await readRootContextFiles(root);
+    const lowerNames = new Set(contextFileNames.map((name) => name.toLowerCase()));
+    const planned = [...candidates.keys()].filter((key) => !key.includes("/") && lowerNames.has(key.toLowerCase()));
+    const plannedLower = new Set(planned.map((key) => key.toLowerCase()));
+    const texts = [];
+    for (const key of planned) {
+        for (const option of candidates.get(key)) {
+            const text = textFrom(option.bytes);
+            if (text !== undefined)
+                texts.push(text);
+        }
+    }
+    for (const name of contextFileNames) {
+        if (plannedLower.has(name.toLowerCase()))
+            continue;
+        const file = current.get(name);
+        if (file && file !== "unusable")
+            texts.push(textFrom(file.bytes));
+    }
+    const missing = unreferencedPaths(targets, texts);
+    if (missing.length === 0)
+        return undefined;
+    const targetName = chooseReferenceTarget([...current.keys(), ...planned]);
+    const existing = current.get(targetName);
+    const manual = planned.length > 0 || existing === "unusable";
+    for (const value of missing) {
+        const how = manual
+            ? `Add this line to ${targetName} yourself: ${referenceLine(value)}`
+            : `Approve the optional reference line for ${targetName} during apply, or add it yourself: ${referenceLine(value)}`;
+        addWarning(warnings, "instruction-not-loaded", `Pi does not load this instruction automatically and no root context file mentions it. ${how}`, value);
+    }
+    if (manual)
+        return undefined;
+    const before = existing; // "unusable" always sets manual, which returned above
+    const bytes = Buffer.from(appendReferenceLines(before ? textFrom(before.bytes) : undefined, missing), "utf8");
+    const candidate = { itemId: "copi-reference", bytes, mode: before?.mode ?? 0o644, sha256: sha256(bytes), sensitive: false, preview: { kind: "binary", summary: "" } };
+    candidate.preview = previewFor(targetName, candidate, before);
+    return {
+        proposal: { path: targetName, status: before ? "append" : "new", instructionPaths: missing, preview: candidate.preview },
+        path: targetName,
+        candidate,
+        before,
+    };
+}
 function candidateKey(candidate) {
     return `${candidate.sha256}:${candidate.mode}`;
 }
 export async function planApply(libraryDir, groupId, projectDir) {
-    const catalog = await loadCatalog(libraryDir);
+    return withSavedLibrary(libraryDir, async (state) => planApplyLocked(state, groupId, projectDir));
+}
+async function planApplyLocked(state, groupId, projectDir) {
+    const catalog = state.catalog;
+    assertNoNameConflicts(catalog);
     const group = catalog.groups.find((item) => item.id === groupId);
     if (!group)
         throw new Error(`Unknown group: ${groupId}`);
-    const storeRoot = await realpath(libraryDir);
+    const storeRoot = state.session.root;
     const project = await safeProjectRoot(projectDir);
     const warnings = [];
     const skippedItems = [];
     const candidates = new Map();
     const existing = new Map();
+    const instructionPaths = [];
     for (const itemId of group.itemIds) {
         const item = catalog.items.find((entry) => entry.id === itemId);
         if (!item)
@@ -191,7 +264,7 @@ export async function planApply(libraryDir, groupId, projectDir) {
             addWarning(warnings, "global-only", "This resource is saved for reference and cannot be applied to a project.", item.name);
             continue;
         }
-        const snapshotFiles = await readSnapshotFiles(storeRoot, item);
+        const snapshotFiles = state.files.get(item.id);
         for (const snapshot of snapshotFiles) {
             if (isExcludedSnapshotPath(snapshot.path)) {
                 addWarning(warnings, "private-path-skipped", "Authentication, environment, history, and cache files are not applied.", snapshot.path);
@@ -199,8 +272,10 @@ export async function planApply(libraryDir, groupId, projectDir) {
             }
             const destination = targetPath(item, snapshot.path, snapshotFiles.length);
             const relativePath = path.posix.normalize(destination);
-            if (!safeRelativePath(relativePath))
-                throw new Error(`Unsafe project destination in catalog: ${relativePath}`);
+            if (!safeRelativePath(relativePath) || isExcludedSnapshotPath(relativePath))
+                throw new Error(`Unsafe or private/excluded project destination in catalog: ${relativePath}`);
+            if (item.kind === "instruction")
+                instructionPaths.push(relativePath);
             const fileCandidates = candidates.get(relativePath) ?? [];
             const candidate = {
                 itemId: item.id,
@@ -246,14 +321,22 @@ export async function planApply(libraryDir, groupId, projectDir) {
             alternatives: uniqueCandidates.map(({ itemId, sensitive, preview }) => ({ itemId, sensitive, preview })),
         });
     }
-    const plan = { projectDir: project.canonical, files, collisions, warnings, skippedItems };
+    const reference = await planInstructionReference(project.canonical, instructionPaths, candidates, warnings);
+    if (reference)
+        existing.set(reference.path, reference.before);
+    const plan = reference
+        ? { projectDir: project.canonical, files, collisions, warnings, skippedItems, referenceProposal: reference.proposal }
+        : { projectDir: project.canonical, files, collisions, warnings, skippedItems };
+    await state.session.assertRevision(state.revision);
     planState.set(plan, {
+        revision: state.revision,
         libraryRoot: storeRoot,
         projectRoot: project.canonical,
         requestedProjectDir: project.requested,
         candidates: new Map([...candidates].map(([key, values]) => [key, [...new Map(values.map((candidate) => [candidateKey(candidate), candidate])).values()]])),
         existing,
         skippedItems: [...skippedItems],
+        ...(reference ? { reference: { path: reference.path, candidate: reference.candidate } } : {}),
     });
     return plan;
 }
@@ -372,11 +455,16 @@ async function writeSnapshotFile(root, relativePath, candidate) {
     }
 }
 export async function executeApply(libraryDir, plan, decisions) {
+    return withSavedLibrary(libraryDir, async (state) => executeApplyLocked(state, plan, decisions));
+}
+async function executeApplyLocked(state, plan, decisions) {
     const internal = planState.get(plan);
     if (!internal)
         throw new Error("Apply plan is not a verified plan created by planApply.");
-    if (await realpath(libraryDir) !== internal.libraryRoot)
+    if (state.session.root !== internal.libraryRoot)
         throw new Error("Apply plan belongs to a different copi library.");
+    assertNoNameConflicts(state.catalog);
+    await state.session.assertRevision(internal.revision);
     if (await realpath(internal.requestedProjectDir) !== internal.projectRoot)
         throw new Error("Project destination changed after planning.");
     const operations = [];
@@ -418,6 +506,14 @@ export async function executeApply(libraryDir, plan, decisions) {
         else
             operations.push({ path: relativePath, candidate });
     }
+    if (decisions.addReference === true) {
+        if (!internal.reference)
+            throw new Error("The apply plan has no reference proposal to add.");
+        const before = internal.existing.get(internal.reference.path);
+        operations.push(before
+            ? { path: internal.reference.path, candidate: internal.reference.candidate, before }
+            : { path: internal.reference.path, candidate: internal.reference.candidate });
+    }
     if (cancelled)
         return { written: [], kept: [], skippedItems: [...internal.skippedItems], backups: [], cancelled: true };
     for (const operation of operations) {
@@ -428,6 +524,7 @@ export async function executeApply(libraryDir, plan, decisions) {
         }
         await assertWritableParent(internal.projectRoot, operation.path);
     }
+    await state.session.assertRevision(internal.revision);
     const backups = await createBackupSet(internal.libraryRoot, operations);
     const written = [];
     for (const operation of operations) {
@@ -436,8 +533,12 @@ export async function executeApply(libraryDir, plan, decisions) {
         if ((current?.sha256 ?? undefined) !== (expected?.sha256 ?? undefined) || (current?.mode ?? undefined) !== (expected?.mode ?? undefined)) {
             throw new Error(`Destination changed during apply: ${operation.path}`);
         }
+        await state.session.assertRevision(internal.revision);
         await writeSnapshotFile(internal.projectRoot, operation.path, operation.candidate);
         written.push(operation.path);
     }
-    return { written, kept, skippedItems: [...internal.skippedItems], backups, cancelled: false };
+    const referenceAdded = internal.reference && written.includes(internal.reference.path) ? internal.reference.path : undefined;
+    return referenceAdded
+        ? { written, kept, skippedItems: [...internal.skippedItems], backups, cancelled: false, referenceAdded }
+        : { written, kept, skippedItems: [...internal.skippedItems], backups, cancelled: false };
 }

package/dist/src/catalog.d.ts

@@ -1,7 +1,10 @@
-import type { Catalog, InspectionResult, ResourceCandidate, SavedItem, SnapshotFileContents } from "./types.ts";
+import { type StorageRevision, type StorageSession } from "./storage-transaction.ts";
+import type { Catalog, InspectionResult, LegacySavedItem, ResourceCandidate, SavedItem, SnapshotFileContents, StoredCatalog } from "./types.ts";
 export interface ImportOptions {
     confirmed: boolean;
     groupIds: string[];
+    inspection?: PreparedInspection;
+    approvedSensitivePaths?: readonly string[];
 }
 declare const preparedResourceBrand: unique symbol;
 export interface PreparedResource {
@@ -28,12 +31,26 @@ export interface PreparedImportOptions extends ImportOptions {
     approvedSensitivePaths: readonly string[];
 }
 export declare function newCatalog(): Catalog;
+export declare function parseStoredCatalog(value: unknown): StoredCatalog;
+export declare function assertModernCatalog(catalog: StoredCatalog): asserts catalog is Catalog;
 export declare function prepareResource(candidate: ResourceCandidate): Promise<PreparedResource>;
 export declare function readPreparedResource(prepared: PreparedResource): PreparedResourceContents;
-export declare function loadCatalog(libraryDir: string): Promise<Catalog>;
+export declare function catalogBytes(catalog: Catalog): Buffer;
+export declare function loadCatalog(libraryDir: string): Promise<StoredCatalog>;
+export interface SavedLibraryState {
+    catalog: Catalog;
+    revision: StorageRevision;
+    files: Map<string, SnapshotFileContents[]>;
+    session: StorageSession;
+}
+/** Internal seam: a single lock, checked catalog and all snapshots; no recursive reader locking. */
+export declare function withSavedLibrary<T>(libraryDir: string, operation: (state: SavedLibraryState) => Promise<T>): Promise<T>;
 export declare function saveCatalog(libraryDir: string, catalog: Catalog): Promise<void>;
 export declare function importPreparedResource(libraryDir: string, prepared: PreparedResource, options: PreparedImportOptions): Promise<SavedItem | null>;
 export declare function importResource(libraryDir: string, candidate: ResourceCandidate, options: ImportOptions): Promise<SavedItem | null>;
-export declare function readSnapshotFiles(libraryDir: string, item: SavedItem): Promise<SnapshotFileContents[]>;
-export declare function listSnapshots(libraryDir: string): Promise<SavedItem[]>;
+export declare function readSnapshotFiles(libraryDir: string, item: SavedItem | LegacySavedItem): Promise<SnapshotFileContents[]>;
+/** Persist staged, explicit name-only changes together, so cancellation never partially resolves names. */
+export declare function saveNameChanges(libraryDir: string, before: Catalog, after: Catalog): Promise<void>;
+export declare function renameSavedItem(libraryDir: string, itemId: string, name: string): Promise<SavedItem>;
+export declare function listSnapshots(libraryDir: string): Promise<Array<LegacySavedItem | SavedItem>>;
 export {};