@symbols-cli/cli 0.0.1

package/dist/sync/paths.js

@@ -0,0 +1,447 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// ⭐ ONE OF THE TWO FILES THAT CARRY THE RISK. The other is `diff.ts`.
+//
+// Everything here answers one question: **given a path the SERVER supplied, may
+// we write it, and where exactly?**
+//
+// That framing matters. The adversary is not the user and not the local agent —
+// the agent runs as the same uid and can write anywhere directly, so no check
+// here constrains it. The parties these rules defend against are:
+//
+//   * **the server**, if it is ever compromised. `project_files.path` is stored
+//     text, reachable through REST `create_file`, which applies NO path screen.
+//     One compromised server otherwise becomes persistent code execution in every
+//     user's home directory, simultaneously. Server-side the blast radius was one
+//     sandboxed container; client-side it inverts.
+//   * **imported content** — a forked community notebook carries attacker-authored
+//     file paths verbatim.
+//
+// Four separate classes, and it takes all four:
+//
+//   1. ESCAPE — `..`, absolute paths, NUL, symlinked parents. Keeps writes inside
+//      the project root.
+//   2. CONFIG-BEARING PATHS (S2) — the dangerous files live INSIDE the root, so
+//      class 1 does not touch them. `.claude/settings.json` is creatable today via
+//      REST and becomes project-scope Claude Code config after sync:
+//      `permissions.allow` silently widens what the agent may do without
+//      prompting, and hooks execute commands.
+//   3. COLLISIONS (F3) — Postgres holds `A.py` and `a.py` as two rows; default
+//      APFS is case- AND normalization-insensitive, so both land on ONE file and
+//      the survivor's content is then pushed to both rows. Silent, no deletes,
+//      circuit-breaker blind.
+//   4. TERMINAL INJECTION — `safe_dirname` passes `\x1b` through, so a hostile
+//      notebook name becomes an escape-sequence-injecting directory.
+//
+// ⚠ ORDERING IS LOAD-BEARING: normalization (casefold + NFC) runs BEFORE the
+// deny-list, not after. `.Claude/settings.json` on APFS and an NFD-encoded `.git`
+// both walk straight through an ASCII comparison, and both resolve to the
+// dangerous file on disk.
+import { promises as fs } from "node:fs";
+import { resolve, sep, join, dirname, basename } from "node:path";
+// ── ignore rules, ported verbatim from odin_notebook_writeback.rs:86-119 ─────
+//
+// Each entry was learned from an incident; this is not a tidy-up list.
+const IGNORE_SEGMENTS = new Set([
+    ".git",
+    "node_modules",
+    "__pycache__",
+    ".ipynb_checkpoints",
+    ".venv",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".cache",
+]);
+/**
+ * Editor scratch names (vim/emacs/gedit write-temp + backup dances).
+ *
+ * Ignoring them keeps junk rows out AND makes the backup-rename dance degrade to
+ * a plain upsert of the real file. `4913` is vim's write-probe: it creates and
+ * deletes that exact filename to test writability, and a sync that treats it as
+ * user content produces a create/delete pair on every single save.
+ */
+export function isEditorTemp(base) {
+    return (base.endsWith("~") ||
+        base.endsWith(".swp") ||
+        base.endsWith(".swo") ||
+        base.startsWith(".#") ||
+        (base.startsWith("#") && base.endsWith("#")) ||
+        base === "4913" ||
+        base.startsWith(".goutputstream-"));
+}
+/**
+ * The conflict sidecar suffix.
+ *
+ * ⚠ MUST STAY IN STEP WITH `diff.ts::conflictSidecarPath`, which builds the
+ * name. It is not imported from there because `paths.ts` is the lower layer and
+ * a cycle between the two files that carry the risk is worse than a coupling
+ * a test can pin — `paths.test.mjs` asserts the round trip
+ * (`isConflictSidecar(conflictSidecarPath(x))`) for a spread of names, so a
+ * change to either one that does not change the other fails immediately.
+ */
+const CONFLICT_MARKER = ".server";
+/**
+ * Is this one of the server-copy files a conflict leaves behind?
+ *
+ * ⚠ FOUND BY THE SOAK, and it was a compounding bug: the sidecar is written
+ * INSIDE the project, so the next sweep walked it, pushed it, and created a
+ * `strategy.server.py` row on the server. From there it spread — the row came
+ * back to every other machine, the local sidecar was rewritten each time the
+ * conflict was re-evaluated (making it diverge from its own pushed copy), and a
+ * conflict on the sidecar would have produced `strategy.server.server.py`.
+ *
+ * The cost is that a user's genuine `api.server.py` is not synced. That is
+ * accepted rather than hidden: `up.ts` already writes `*.server.*` into the
+ * project `.gitignore`, so the naming was committed to before this.
+ */
+export function isConflictSidecar(rel) {
+    const base = rel.split("/").pop() ?? rel;
+    // ⚠ TWO SHAPES, because `conflictSidecarPath` produces two.
+    //
+    //   with an extension:    strategy.py  -> strategy.server.py   (infixed)
+    //   without one:          no-extension -> no-extension.server  (appended)
+    //   leading dot:          .env         -> .env.server          (appended —
+    //                         a leading dot is the whole name, not an extension)
+    //
+    // The first version checked only the infixed shape, and the round-trip test
+    // caught `no-extension.server` on its first run. That is the coupling this
+    // pair exists to keep honest.
+    if (base.endsWith(CONFLICT_MARKER))
+        return true;
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0)
+        return false;
+    return base.slice(0, dot).endsWith(CONFLICT_MARKER);
+}
+export function shouldIgnore(rel) {
+    if (rel.split("/").some((seg) => IGNORE_SEGMENTS.has(seg)))
+        return true;
+    const base = rel.split("/").pop() ?? rel;
+    // Our own write-temp files. A crashed pull can leave one behind, and syncing
+    // it would create a junk server row named after a pid and a timestamp.
+    if (base.startsWith(".symbols-tmp-"))
+        return true;
+    if (isConflictSidecar(rel))
+        return true;
+    return isEditorTemp(base);
+}
+// ── files this CLI (or Claude Code) OWNS, in both directions ─────────────────
+/**
+ * Paths that are never synced either way, because something local writes them.
+ *
+ * ⚠ THIS IS A DIFFERENT QUESTION FROM `isWritableTarget`, and conflating them
+ * was a real bug: an earlier version ran the S2 deny-list over the whole path
+ * universe, so `<root>/.symbols/project.json` — a file this CLI had just written
+ * itself — was reported as a quarantined config-bearing path on EVERY sweep of
+ * EVERY project. A permanent frozen entry that is always there is worse than no
+ * report at all: it trains the user to stop reading `symbols status`, which is
+ * the one surface a real conflict shows up on.
+ *
+ * The two questions:
+ *
+ *   `isCliManaged`      "is this ours, so neither side should sync it?"
+ *                       -> excluded from the diff entirely
+ *   `isWritableTarget`  "may SERVER-SUPPLIED content be written here?"
+ *                       -> the S2 security backstop, enforced at the writer
+ *
+ * Both still apply to `.claude/**` and `.symbols/**`, which is defence in depth,
+ * not duplication: the first stops us fighting our own files, the second stops a
+ * compromised server planting one.
+ *
+ * ⚠ `CLAUDE.md` is here for a reason the plan names as an open gap: it is *also*
+ * a legal `project_files` row, and "which wins is undefined". Defined here — the
+ * LOCAL managed block wins, and a server row at that path is SURFACED as a frozen
+ * path rather than silently dropped, which is what the plan asks for.
+ */
+export function isCliManaged(rel) {
+    const norm = normalizeForCompare(rel);
+    const segments = norm.split("/").filter(Boolean);
+    if (segments.some((s) => s === ".symbols" || s === ".claude"))
+        return true;
+    const base = segments[segments.length - 1] ?? "";
+    return base === "claude.md" || base === ".mcp.json";
+}
+// ── S2: config-bearing paths ─────────────────────────────────────────────────
+/**
+ * ⚠ THE DENY-LIST IS THE SECONDARY CONTROL, NOT THE PRIMARY ONE.
+ *
+ * A deny-list is unwinnable as an enumeration. An adversarial review named six
+ * paths an earlier draft missed — every one of them a file some tool EXECUTES
+ * when it appears inside a project root:
+ *
+ *   `conftest.py`        runs on pytest collection
+ *   `sitecustomize.py`   runs at interpreter start
+ *   `*.pth`              runs at interpreter start
+ *   `.envrc`             direnv auto-executes it on `cd`
+ *   `.vscode/tasks.json` runs on open, depending on trust settings
+ *   `Makefile`           one `make` away
+ *   `package.json`       `scripts` run on install/test
+ *   `CLAUDE.md` ANYWHERE Claude Code reads it in every directory, not just root
+ *
+ * Naming five invites the sixth to be the incident. So the posture inverts: the
+ * primary control is `isWritableTarget` below, an ALLOW-LIST that quarantines
+ * anything not plainly inert. This list exists to give a precise reason for the
+ * most dangerous refusals, and as defence in depth if the allow-list is ever
+ * loosened.
+ */
+const DENIED_EXACT = new Set([
+    ".mcp.json",
+    "claude.md",
+    ".envrc",
+    "conftest.py",
+    "sitecustomize.py",
+    "makefile",
+    "package.json",
+    ".gitattributes",
+    ".gitmodules",
+]);
+const DENIED_PREFIX_SEGMENTS = [".claude", ".symbols", ".git", ".vscode", ".idea", ".config"];
+const DENIED_SUFFIX = [".pth"];
+/**
+ * Normalise a path for COMPARISON only — never for writing.
+ *
+ * Casefold + NFC, matching what a default macOS APFS volume does when it decides
+ * two names are the same file. Comparing raw bytes here is the F3 bug: the
+ * server's two distinct rows collapse to one file and the check never fires.
+ */
+export function normalizeForCompare(rel) {
+    // ⚠ CASEFOLD, NOT `.toLowerCase()`. The difference is a security hole, and it
+    // was PROVEN on this project's own target filesystem:
+    //
+    //     ".ſymbols".toLowerCase()  ===  ".ſymbols"      // U+017F LATIN SMALL LONG S
+    //     APFS:  writing `.ſymbols/x`  OVERWRITES  `.symbols/x`
+    //
+    // So a server-supplied path spelled with a long s walked straight through the
+    // S2 deny-list — `.symbols` was blocked, `.ſymbols` was not — and landed
+    // inside the CLI's OWN ledger directory. It also blinded the F3 collision
+    // detector, which is what stops two server rows overwriting one local file.
+    // Verified by writing both paths on this machine and reading the survivor.
+    //
+    // `.toLowerCase()` is a locale-ish lowercase, not Unicode case folding: it
+    // leaves ſ, fi and the Kelvin sign alone. JavaScript exposes no `toCasefold`,
+    // so NFKC does the compatibility work (ſ→s, fi→fi, K→K) and the lowercase
+    // does the rest; applied twice because NFKC can yield uppercase.
+    //
+    // NFKC groups MORE aggressively than APFS actually does. That is the correct
+    // direction for both consumers: this function only ever decides "deny" or
+    // "freeze as a collision", so over-grouping refuses more and never less.
+    // Under-grouping is what lets a write through.
+    return rel.normalize("NFKC").toLowerCase().normalize("NFKC").toLowerCase();
+}
+/**
+ * May server content be written to this project-relative path?
+ *
+ * ALLOW-LIST FIRST (the primary control), deny-list second (the precise reason).
+ */
+export function isWritableTarget(rel) {
+    // Normalise BEFORE any comparison. See the ordering note at the top.
+    const norm = normalizeForCompare(rel);
+    const segments = norm.split("/").filter(Boolean);
+    if (segments.length === 0)
+        return { ok: false, reason: "empty path" };
+    for (const seg of segments) {
+        if (DENIED_PREFIX_SEGMENTS.includes(seg)) {
+            return {
+                ok: false,
+                reason: `'${seg}/' holds configuration a tool executes; server content is never written there`,
+            };
+        }
+    }
+    const base = segments[segments.length - 1] ?? "";
+    if (DENIED_EXACT.has(base)) {
+        return { ok: false, reason: `'${base}' is executed or read as configuration` };
+    }
+    if (DENIED_SUFFIX.some((s) => base.endsWith(s))) {
+        return { ok: false, reason: `'${base}' runs at Python interpreter start` };
+    }
+    // `CLAUDE.md` in ANY directory, not only the root — Claude Code reads the
+    // nearest one on every path. The exact-match table catches the basename, which
+    // is what makes this correct at any depth.
+    return { ok: true };
+}
+// ── class 1: escape ──────────────────────────────────────────────────────────
+/** Windows reserved device names. Writing `CON.py` on Windows opens a device. */
+const RESERVED = new Set([
+    "con", "prn", "aux", "nul",
+    "com1", "com2", "com3", "com4", "com5", "com6", "com7", "com8", "com9",
+    "lpt1", "lpt2", "lpt3", "lpt4", "lpt5", "lpt6", "lpt7", "lpt8", "lpt9",
+]);
+/**
+ * Strip control characters from a server-supplied name.
+ *
+ * `safe_dirname` passes `\x1b` through, so a notebook named with an escape
+ * sequence becomes a directory that rewrites the user's terminal when listed —
+ * and worse, one whose displayed name differs from its real one.
+ */
+export function stripControl(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\x00-\x1f\x7f-\x9f]/g, "");
+}
+/**
+ * Resolve a project-relative server path to an absolute local one, or refuse.
+ *
+ * Purely lexical — it does NOT touch the filesystem, so it is cheap enough to run
+ * on every path of a 5,000-file project. The filesystem checks (symlinked
+ * parents, `O_NOFOLLOW`) are `assertNoSymlinkedParents` and the writer's job.
+ */
+export function resolveInRoot(root, rel) {
+    if (rel.includes("\0"))
+        return { ok: false, reason: "path contains NUL" };
+    if (rel !== stripControl(rel)) {
+        return { ok: false, reason: "path contains control characters" };
+    }
+    if (rel.startsWith("/") || /^[a-zA-Z]:/.test(rel)) {
+        return { ok: false, reason: "absolute paths are never accepted from the server" };
+    }
+    const segments = rel.split(/[/\\]/).filter((s) => s.length > 0 && s !== ".");
+    if (segments.length === 0)
+        return { ok: false, reason: "empty path" };
+    for (const seg of segments) {
+        if (seg === "..")
+            return { ok: false, reason: "'..' is never accepted from the server" };
+        // Reserved names are refused on every platform, not just Windows: the row
+        // would otherwise sync fine on macOS and become unwritable the moment the
+        // same account is opened on a Windows machine.
+        const stem = (seg.split(".")[0] ?? "").toLowerCase();
+        if (RESERVED.has(stem)) {
+            return { ok: false, reason: `'${seg}' is a reserved device name` };
+        }
+        if (seg.endsWith(" ") || seg.endsWith(".")) {
+            return { ok: false, reason: `'${seg}' ends with a space or dot (unwritable on Windows)` };
+        }
+    }
+    const absRoot = resolve(root);
+    const abs = resolve(absRoot, segments.join(sep));
+    // The prefix assert, with the separator. Without the trailing `sep`,
+    // `/home/u/Symbols/ProjectEvil` passes a prefix test against
+    // `/home/u/Symbols/Project`.
+    if (abs !== absRoot && !abs.startsWith(absRoot + sep)) {
+        return { ok: false, reason: "resolves outside the project root" };
+    }
+    return { ok: true, abs };
+}
+/**
+ * Refuse if any parent component is a symlink.
+ *
+ * `resolveInRoot` is lexical, so it cannot see that `<root>/data` is a symlink to
+ * `/tmp`. `lstat` each component — NOT `stat`, which follows the link and reports
+ * the target, defeating the check entirely.
+ *
+ * Not TOCTOU-proof, and deliberately not: the only process positioned to win that
+ * race is the same-uid agent, which can already write anywhere directly. This
+ * defends against a symlink the SERVER caused to exist, or one an imported
+ * project shipped.
+ */
+export async function assertNoSymlinkedParents(root, abs) {
+    const absRoot = resolve(root);
+    const rel = abs.slice(absRoot.length).split(sep).filter(Boolean);
+    let cursor = absRoot;
+    // Every component EXCEPT the final one — the final one is handled by the
+    // writer, which opens with O_NOFOLLOW and compares fstat to lstat.
+    for (const seg of rel.slice(0, -1)) {
+        cursor = join(cursor, seg);
+        try {
+            const st = await fs.lstat(cursor);
+            if (st.isSymbolicLink()) {
+                return { ok: false, reason: `'${cursor}' is a symlink; refusing to write through it` };
+            }
+        }
+        catch (err) {
+            // ENOENT is expected and fine — the directory has not been created yet.
+            if (err.code !== "ENOENT") {
+                return { ok: false, reason: `cannot stat '${cursor}': ${err.message}` };
+            }
+            // Nothing below a missing directory can be a symlink either.
+            return { ok: true };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Find server paths that would collide on a case- or normalization-insensitive
+ * filesystem.
+ *
+ * Run over the WHOLE project path set before writing anything. The caller must
+ * FREEZE every path in a returned group — never pick a winner. Picking one means
+ * the survivor's content is pushed back to the other row, silently replacing a
+ * file the user never touched, with no delete for the circuit breaker to catch.
+ */
+export function findCollisions(paths) {
+    const byNorm = new Map();
+    for (const p of paths) {
+        const key = normalizeForCompare(p);
+        const list = byNorm.get(key);
+        if (list)
+            list.push(p);
+        else
+            byNorm.set(key, [p]);
+    }
+    const out = [];
+    for (const [normalized, group] of byNorm) {
+        // >1 DISTINCT path mapping to one key. The same path twice is a duplicate
+        // row, not a collision, and freezing on it would be a false positive.
+        const distinct = [...new Set(group)];
+        if (distinct.length > 1)
+            out.push({ normalized, paths: distinct.sort() });
+    }
+    return out.sort((a, b) => a.normalized.localeCompare(b.normalized));
+}
+// ── project directory naming ─────────────────────────────────────────────────
+/**
+ * Port of `safe_dirname` (odin_notebook_writeback.rs:123-145) — **plus the
+ * control-character strip the original lacks**.
+ *
+ * ⚠ The dirname is computed SERVER-SIDE (`GET /api/cli/projects`) and this is the
+ * client's verification copy, not the authority. It exists so a client can detect
+ * a server that returns a dirname inconsistent with the name — which is what a
+ * path-injection attempt looks like from here.
+ */
+export function safeDirname(name, fallback) {
+    const replaced = stripControl(name).replace(/[/\\]/g, "-");
+    const collapsed = replaced.replace(/\s+/g, " ");
+    const trimmed = collapsed.replace(/^[. ]+/, "").replace(/[. ]+$/, "");
+    const truncated = [...trimmed].slice(0, 120).join("");
+    return truncated.length > 0 ? truncated : fallback;
+}
+/**
+ * The `-2`/`-3` dedupe, which lives SEPARATELY from `safe_dirname` in the server
+ * (`materialize_all:1371-1382`) and is easy to miss when porting.
+ *
+ * ⚠ MIRRORS THE SERVER EXACTLY, INCLUDING TWO THINGS THAT LOOK LIKE BUGS:
+ *
+ * 1. **The comparison is case-SENSITIVE and un-normalized** — the server holds
+ *    `used` as a plain `HashSet<String>` and tests `used.contains(&nm)`. So `A`
+ *    and `a` are NOT deduped: both keep their own name, and they then collide on
+ *    a case-insensitive filesystem. That is correct to reproduce, because the
+ *    dirname must match what the server computed. The collision is F3's problem
+ *    and `findCollisions` is what catches it — using normalized keys HERE would
+ *    hide it while silently disagreeing with the server about the directory name.
+ *    An earlier draft did exactly that.
+ *
+ * 2. **The suffix is probed, not counted.** The server loops
+ *    `while used.contains(nm) { nm = base-i; i += 1 }`, so an existing literal
+ *    `X-2` is skipped over. A per-name counter (the obvious implementation)
+ *    returns `X-2` for the second `X` and collides with the real `X-2`.
+ *    Case: `["X", "X-2", "X"]` -> server `["X", "X-2", "X-3"]`; a counter gives
+ *    `["X", "X-2", "X-2"]`.
+ *
+ * ⚠ The server iterates `ORDER BY created_at, id`, so DELETING ONE NOTEBOOK
+ * RENAMES ITS SAME-NAMED SIBLINGS' DIRECTORIES. Not a bug to fix here — it is
+ * behaviour doctor must expect and the conformance matrix must cover.
+ */
+export function dedupeDirnames(names) {
+    const used = new Set();
+    return names.map((base) => {
+        let nm = base;
+        let i = 2;
+        while (used.has(nm)) {
+            nm = `${base}-${i}`;
+            i += 1;
+        }
+        used.add(nm);
+        return nm;
+    });
+}
+export { basename, dirname };

package/dist/sync/protect.js

@@ -0,0 +1,108 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// Regime- and widget-backed files, marked read-only BEFORE the agent touches
+// them.
+//
+// ## Why this is pre-emptive rather than reactive
+//
+// The server already refuses: `DELETE /api/notebooks/files/{id}` and a renaming
+// PATCH both 409 when the file backs a live regime or widget
+// (`routes/project_files.rs:144-151`, `:522-523`). So a purely reactive client
+// is *safe* — it just eats the 409 and restores the file.
+//
+// It is still the wrong shape, for one reason the plan states directly: the
+// agent should learn **why** before deleting, not after. A 409 arrives as an
+// opaque failure in the middle of a sweep; a `0o444` file and a named line in
+// `CLAUDE.md` arrive before the agent has formed the intent. The difference
+// matters most on the case this exists for — a strategy file backing a LIVE
+// regime, where "the delete failed" and "the delete was prevented" read the same
+// in a transcript but only one of them tells the agent to stop.
+//
+// ## The read-only mark is a SPEED BUMP, never a control
+//
+// `chmod 0444` stops nothing: the agent runs as the same uid and can `chmod +w`
+// in one command. It is a signal to a well-behaved tool (editors refuse, `rm`
+// prompts), and it must never be described as containment — the same discipline
+// the plan applies to `symbols curl`'s flag denylist.
+//
+// The ACTUAL protection is, in order:
+//   1. the server's 409 (authoritative, and the only one an attacker cannot skip)
+//   2. the local restore in `reconcile` when that 409 arrives
+//   3. this mark, and the `CLAUDE.md` line naming it
+import { promises as fs } from "node:fs";
+import { artifacts } from "./api.js";
+/**
+ * Fetch the protected set for a notebook.
+ *
+ * ⚠ A FAILURE HERE MUST NOT BE READ AS "NOTHING IS PROTECTED". Returning an
+ * empty map on error would silently downgrade every protected file to writable
+ * on any transient blip — the same "a failed read is not an affirmative absence"
+ * rule that governs deletes (`settle_vanish:513-519`). So this throws, and the
+ * caller decides; `reconcile` treats it as a reason to keep the previous marks.
+ */
+export async function fetchProtected(notebookId) {
+    const raw = await artifacts(notebookId);
+    // The route wraps the map: `{"artifacts": {path: [...]}}`
+    // (`routes/project_files.rs:719`). Tolerate both shapes rather than guessing,
+    // because guessing wrong yields an empty set, which is the unsafe direction.
+    const map = raw && typeof raw === "object" && "artifacts" in raw
+        ? (raw.artifacts ?? {})
+        : raw;
+    const out = [];
+    for (const [path, entries] of Object.entries(map ?? {})) {
+        for (const e of entries ?? []) {
+            // The server's keys are raw `source_file_path` values, which carry the
+            // canonical leading slash. Normalise to the project-relative form the rest
+            // of the engine uses, or nothing will ever match.
+            const rel = path.replace(/^\/+/, "");
+            out.push({
+                path: rel,
+                kind: e.type,
+                name: e.name,
+                // ⚠ Widgets have NO `status` key (`routes/project_files.rs:689-692`,
+                // `:711-714`) while regimes do (`:667-671`). Under
+                // `exactOptionalPropertyTypes` an explicit `undefined` is not the same as
+                // an absent key, so it is spread conditionally rather than assigned.
+                ...(e.status === undefined ? {} : { status: e.status }),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Apply (or lift) the read-only mark.
+ *
+ * Never throws for a missing file: a protected row whose local copy has not been
+ * materialized yet is normal on a first sync, and failing the whole sweep for it
+ * would make the first run of a project with one live regime fail entirely.
+ */
+export async function applyReadOnly(abs, readOnly) {
+    try {
+        const st = await fs.stat(abs);
+        if (!st.isFile())
+            return;
+        // Preserve the group/other bits the user has; only the write bits move.
+        const mode = readOnly ? st.mode & ~0o222 : st.mode | 0o200;
+        if (mode !== st.mode)
+            await fs.chmod(abs, mode);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
+/**
+ * The paths to name in `CLAUDE.md`, sorted and de-duplicated.
+ *
+ * ⚠ THERE IS DELIBERATELY NO SECOND RENDERER HERE. An earlier draft of this file
+ * formatted its own markdown section, which would have been a second copy of a
+ * decision `skills/claude-md.ts::renderManagedBody` already makes — and the
+ * managed block has exactly one writer for the same reason `diff.ts` does. This
+ * returns data; that file decides how it reads.
+ */
+export function protectedPaths(entries) {
+    return [...new Set(entries.map((e) => e.path))].sort();
+}