@event4u/agent-switch 1.0.0

package/dist/sessions.js

@@ -0,0 +1,543 @@
+/**
+ * Session inventory + per-session transfer ("takeover") between Claude profiles.
+ *
+ * Ground truth (docs + upstream issues, re-verified in scripts/spikes/): a
+ * Claude Code session is one file — `<config>/projects/<encoded-cwd>/<id>.jsonl`
+ * (plus an optional `<id>/` checkpoint subdir). An ACCOUNT handoff keeps the
+ * cwd constant, so the encoded project dir is identical in source and target
+ * profile; a takeover is moving that file between two same-named dirs and
+ * resuming under the target's CLAUDE_CONFIG_DIR.
+ *
+ * Iron rules (roadmap: road-to-session-handoff):
+ *   - Transcripts are OPAQUE, version-unstable blobs FOR TRANSFER. The only
+ *     read in THIS module is `readSessionHeader` — first line, capped,
+ *     try/catch. There are exactly TWO sanctioned body readers, both guarded +
+ *     capped + fenced + degraded-mode, and NO others: read-only TELEMETRY
+ *     (context/token counts, `src/telemetry.ts`, road-to-agent-switch-session-
+ *     telemetry gate D0) and read-only PREVIEW (the first few conversation
+ *     turns for the GUI list, `src/session-preview.ts`, ADR-002). No other
+ *     module parses a transcript body.
+ *   - Transfers are copy → verify → delete (the `migrateLegacyLayout`
+ *     precedent): no step ever leaves zero copies of a transcript.
+ *   - Index files (`sessions-index.json`, `history.jsonl`) are never written —
+ *     their format is not ours. Resume-by-id is the supported path.
+ *   - Same-id divergence is forbidden by construction: move by default,
+ *     `--fork-session` forced on keep-source, collision = hard refusal.
+ */
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { liveSessionPids } from "./api.js";
+/** The documented encoding of a project cwd into its transcript dir name:
+ *  every non-alphanumeric character of the absolute path becomes `-`. */
+export function encodeProjectDir(cwd) {
+    return cwd.replace(/[^A-Za-z0-9]/g, "-");
+}
+/** Best-effort metadata from a transcript's FIRST line only. The line is
+ *  capped (a >64 KiB first line counts as unparseable), the parse is fenced,
+ *  and absence degrades to nulls — the format is internal and version-unstable,
+ *  so a failed parse must never fail a listing. */
+const HEADER_CAP = 64 * 1024;
+export function readSessionHeader(file) {
+    const none = { cwd: null, summary: null };
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+    }
+    catch {
+        return none;
+    }
+    try {
+        const buf = Buffer.alloc(HEADER_CAP);
+        const n = fs.readSync(fd, buf, 0, HEADER_CAP, 0);
+        const chunk = buf.subarray(0, n).toString("utf8");
+        const nl = chunk.indexOf("\n");
+        if (nl < 0 && n === HEADER_CAP)
+            return none; // first line larger than the cap
+        const line = nl >= 0 ? chunk.slice(0, nl) : chunk;
+        const parsed = JSON.parse(line);
+        return {
+            cwd: typeof parsed?.cwd === "string" ? parsed.cwd : null,
+            summary: typeof parsed?.summary === "string" ? parsed.summary : null,
+        };
+    }
+    catch {
+        return none;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Recent sessions of one profile config dir, newest first, capped at `limit`.
+ *  Pure directory scan — works on seeded fakes, shared trees, and win32. */
+export function listSessions(configDir, limit) {
+    const projects = path.join(configDir, "projects");
+    let dirs;
+    try {
+        dirs = fs.readdirSync(projects, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const d of dirs) {
+        // A shared-history tree links `projects/` itself, not its children — but be
+        // tolerant of either; only descend into directories (or links to them).
+        const dirPath = path.join(projects, d.name);
+        let entries;
+        try {
+            if (!fs.statSync(dirPath).isDirectory())
+                continue;
+            entries = fs.readdirSync(dirPath);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith(".jsonl"))
+                continue;
+            const file = path.join(dirPath, entry);
+            let st;
+            try {
+                st = fs.statSync(file);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            const header = readSessionHeader(file);
+            rows.push({
+                sessionId: entry.slice(0, -".jsonl".length),
+                projectDir: d.name,
+                cwd: header.cwd,
+                summary: header.summary,
+                mtimeMs: st.mtimeMs,
+                birthtimeMs: st.birthtimeMs || st.mtimeMs,
+                live: false,
+                file,
+            });
+        }
+    }
+    rows.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return rows.slice(0, limit);
+}
+/** A live pid's working directory, without elevated rights. Verified in
+ *  scripts/spikes/g04: `/proc/<pid>/cwd` on linux, `lsof -d cwd` on darwin
+ *  (works for same-user processes; claude/codex are node binaries, whose
+ *  env/cwd are readable — unlike Apple platform binaries). win32: null
+ *  (recent-only inventory there, per roadmap). */
+export function pidCwd(pid) {
+    try {
+        if (process.platform === "linux")
+            return fs.readlinkSync(`/proc/${pid}/cwd`);
+        if (process.platform === "darwin") {
+            const out = execFileSync("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            const m = /^n(.+)$/m.exec(out);
+            return m ? m[1] : null;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return null;
+}
+/**
+ * Mark the sessions that belong to a live Claude process: a row is live when
+ * its profile has a live pid whose cwd encodes to the row's project dir AND
+ * the row is that dir's newest transcript (a running session appends to the
+ * newest file; older siblings in the same dir are history).
+ */
+export function markLive(configDir, rows, cwdOf = pidCwd) {
+    const pids = liveSessionPids(configDir);
+    if (pids.length === 0)
+        return;
+    const liveDirs = new Set();
+    for (const pid of pids) {
+        const cwd = cwdOf(pid);
+        if (cwd)
+            liveDirs.add(encodeProjectDir(cwd));
+    }
+    if (liveDirs.size === 0)
+        return;
+    const newestPerDir = new Map();
+    for (const r of rows) {
+        const seen = newestPerDir.get(r.projectDir);
+        if (!seen || r.mtimeMs > seen.mtimeMs)
+            newestPerDir.set(r.projectDir, r);
+    }
+    for (const [dir, row] of newestPerDir) {
+        if (liveDirs.has(dir))
+            row.live = true;
+    }
+}
+/** Where a session id lives inside ONE profile config dir, or null. */
+export function locateSession(configDir, sessionId) {
+    const projects = path.join(configDir, "projects");
+    let dirs;
+    try {
+        dirs = fs.readdirSync(projects);
+    }
+    catch {
+        return null;
+    }
+    for (const d of dirs) {
+        const jsonl = path.join(projects, d, `${sessionId}.jsonl`);
+        if (!fs.existsSync(jsonl))
+            continue;
+        const sub = path.join(projects, d, sessionId);
+        return {
+            configDir,
+            projectDir: d,
+            jsonl,
+            checkpointDir: fs.existsSync(sub) && fs.statSync(sub).isDirectory() ? sub : null,
+        };
+    }
+    return null;
+}
+/** Do two profiles share one history tree (`share on --history`)? Then the
+ *  transcript is already visible on the target and file ops would be self-moves
+ *  — the takeover degrades to just the resume command. */
+export function sharedHistory(srcConfigDir, tgtConfigDir) {
+    try {
+        const a = fs.realpathSync(path.join(srcConfigDir, "projects"));
+        const b = fs.realpathSync(path.join(tgtConfigDir, "projects"));
+        return a === b;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Transfer one session's files from its source location into the target
+ * profile. copy → verify → delete-source (unless keepSource): the checkpoint
+ * subdir first, the transcript LAST — the transcript is the resume trigger, so
+ * any crash mid-way leaves the source fully resumable. Verification is
+ * existence + byte size for the transcript (the blob is never read).
+ *
+ * Throws on a target collision — the caller surfaces it; an existing target
+ * file under the same id is a divergence about to happen, never overwritten.
+ */
+export function transferSession(loc, tgtConfigDir, keepSource) {
+    const tgtProj = path.join(tgtConfigDir, "projects", loc.projectDir);
+    const tgtJsonl = path.join(tgtProj, path.basename(loc.jsonl));
+    if (fs.existsSync(tgtJsonl)) {
+        throw new Error(`target already has a transcript for this session id (${tgtJsonl}) — refusing to overwrite`);
+    }
+    const actions = [];
+    fs.mkdirSync(tgtProj, { recursive: true, mode: 0o700 });
+    if (loc.checkpointDir) {
+        const tgtSub = path.join(tgtProj, path.basename(loc.checkpointDir));
+        fs.cpSync(loc.checkpointDir, tgtSub, { recursive: true });
+        if (!fs.existsSync(tgtSub))
+            throw new Error(`checkpoint copy failed verification: ${tgtSub}`);
+        actions.push(`copied checkpoint dir ${path.basename(loc.checkpointDir)}/`);
+    }
+    fs.copyFileSync(loc.jsonl, tgtJsonl);
+    const srcSize = fs.statSync(loc.jsonl).size;
+    const tgtSize = fs.statSync(tgtJsonl).size;
+    if (srcSize !== tgtSize) {
+        // Bad copy: remove the partial target; the source is untouched.
+        fs.rmSync(tgtJsonl, { force: true });
+        throw new Error(`transcript copy failed verification (${srcSize} != ${tgtSize} bytes)`);
+    }
+    actions.push(`copied transcript (${srcSize} bytes, verified)`);
+    if (!keepSource) {
+        fs.rmSync(loc.jsonl, { force: true });
+        if (loc.checkpointDir)
+            fs.rmSync(loc.checkpointDir, { recursive: true, force: true });
+        actions.push("removed source copy (move complete)");
+    }
+    else {
+        actions.push("kept source (fork mode)");
+    }
+    return { actions, targetJsonl: tgtJsonl };
+}
+/** Remove the transfer copy that carries the ORIGINAL session id from the
+ *  target after a keep-source fork: the fork got its own id, so the vehicle
+ *  file must go, or two profiles would own the same id (the g02 trap). */
+export function cleanupForkVehicle(tgtConfigDir, projectDir, sessionId) {
+    const proj = path.join(tgtConfigDir, "projects", projectDir);
+    fs.rmSync(path.join(proj, `${sessionId}.jsonl`), { force: true });
+    fs.rmSync(path.join(proj, sessionId), { recursive: true, force: true });
+}
+// ---------- per-session delete (Claude: files; Codex: native command) ---------
+//
+// Delete turns the latent takeover path-traversal (a raw id joined into an fs
+// path) into DIRECT destruction, so a strict id gate runs before any fs access,
+// and a realpath-prefix assertion is defense-in-depth behind it. Claude has no
+// native session-delete, so deletion is a file op — trash-move by default
+// (recoverable), true rm only on `purge`. Codex owns its store (.zst/indexes),
+// so codex deletion is delegated to the native CLI, never a manual rollout rm.
+/** Canonical UUID (both providers id sessions this way). */
+const SESSION_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** Strict session-id gate — a canonical UUID only. Rejects `/`, `\`, `..`, and
+ *  anything else before the id is ever joined into a filesystem path. MUST be
+ *  the first call on the `sessions rm` / `restore` path. */
+export function assertValidSessionId(id) {
+    if (typeof id !== "string" || !SESSION_ID_RE.test(id)) {
+        throw new Error(`invalid session id ${JSON.stringify(String(id))} — expected a canonical UUID`);
+    }
+}
+/** Defense-in-depth: the resolved target must live inside `rootDir` after
+ *  symlink resolution, or we refuse to touch it. Both paths must exist. */
+function assertInside(rootDir, target) {
+    const root = fs.realpathSync(rootDir);
+    const resolved = fs.realpathSync(target);
+    const rel = path.relative(root, resolved);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`refusing to operate on a path outside ${rootDir}: ${target}`);
+    }
+}
+const TRASH_DIRNAME = ".agent-switch-trash";
+const TRASH_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** Move a file/dir into `dest`, falling back to copy→verify→delete across a
+ *  device boundary (rename fails EXDEV). */
+function moveInto(src, dest, isDir) {
+    try {
+        fs.renameSync(src, dest);
+        return;
+    }
+    catch (e) {
+        if (e.code !== "EXDEV")
+            throw e;
+    }
+    if (isDir) {
+        fs.cpSync(src, dest, { recursive: true });
+        fs.rmSync(src, { recursive: true, force: true });
+    }
+    else {
+        fs.copyFileSync(src, dest);
+        if (fs.statSync(src).size !== fs.statSync(dest).size) {
+            fs.rmSync(dest, { force: true });
+            throw new Error(`trash move failed verification: ${dest}`);
+        }
+        fs.rmSync(src, { force: true });
+    }
+}
+/**
+ * Delete one Claude session. Ordering is ALWAYS checkpoint-dir first, transcript
+ * LAST — a crash mid-delete then leaves a locatable, still-resumable session
+ * (`locateSession` keys on `<id>.jsonl`) rather than an orphaned checkpoint.
+ * Default is a recoverable trash-move into `<config>/.agent-switch-trash/`;
+ * `purge` does the true irreversible `fs.rmSync`. `now` is injectable for tests.
+ */
+export function deleteSession(loc, opts = {}) {
+    const projectsRoot = path.join(loc.configDir, "projects");
+    assertInside(projectsRoot, loc.jsonl);
+    if (loc.checkpointDir)
+        assertInside(projectsRoot, loc.checkpointDir);
+    const removed = [];
+    const residue = [];
+    if (opts.purge) {
+        if (loc.checkpointDir) {
+            try {
+                fs.rmSync(loc.checkpointDir, { recursive: true, force: true });
+                removed.push(loc.checkpointDir);
+            }
+            catch {
+                residue.push(loc.checkpointDir);
+            }
+        }
+        try {
+            fs.rmSync(loc.jsonl, { force: true });
+            removed.push(loc.jsonl);
+        }
+        catch {
+            residue.push(loc.jsonl);
+        }
+        return { mode: "purge", trashId: null, removed, residue };
+    }
+    const id = path.basename(loc.jsonl, ".jsonl");
+    const trashId = `${opts.now ?? Date.now()}-${id}`;
+    const dest = path.join(loc.configDir, TRASH_DIRNAME, trashId);
+    const destProj = path.join(dest, "projects", loc.projectDir);
+    fs.mkdirSync(destProj, { recursive: true, mode: 0o700 });
+    if (loc.checkpointDir) {
+        moveInto(loc.checkpointDir, path.join(destProj, path.basename(loc.checkpointDir)), true);
+        removed.push(loc.checkpointDir);
+    }
+    moveInto(loc.jsonl, path.join(destProj, path.basename(loc.jsonl)), false);
+    removed.push(loc.jsonl);
+    const manifest = {
+        id,
+        projectDir: loc.projectDir,
+        hadCheckpoint: loc.checkpointDir !== null,
+        trashedAt: new Date(opts.now ?? Date.now()).toISOString(),
+    };
+    fs.writeFileSync(path.join(dest, "manifest.json"), JSON.stringify(manifest, null, 2));
+    return { mode: "trash", trashId, removed, residue };
+}
+/** Restore a trashed Claude session back to its origin. Refuses if a live
+ *  transcript already occupies the id (never silently overwrites). */
+export function restoreSession(configDir, trashId) {
+    const dest = path.join(configDir, TRASH_DIRNAME, trashId);
+    const manifest = JSON.parse(fs.readFileSync(path.join(dest, "manifest.json"), "utf8"));
+    const backProj = path.join(configDir, "projects", manifest.projectDir);
+    const backJsonl = path.join(backProj, `${manifest.id}.jsonl`);
+    if (fs.existsSync(backJsonl)) {
+        throw new Error(`cannot restore: ${backJsonl} already exists`);
+    }
+    fs.mkdirSync(backProj, { recursive: true, mode: 0o700 });
+    const trashProj = path.join(dest, "projects", manifest.projectDir);
+    if (manifest.hadCheckpoint) {
+        moveInto(path.join(trashProj, manifest.id), path.join(backProj, manifest.id), true);
+    }
+    moveInto(path.join(trashProj, `${manifest.id}.jsonl`), backJsonl, false);
+    fs.rmSync(dest, { recursive: true, force: true });
+    return { restored: backJsonl };
+}
+/** Drop trashed sessions older than the TTL. Best-effort; `now`/`ttlMs`
+ *  injectable for tests. Returns how many trash entries were removed. */
+export function sweepTrash(configDir, now = Date.now(), ttlMs = TRASH_TTL_MS) {
+    const trash = path.join(configDir, TRASH_DIRNAME);
+    let entries;
+    try {
+        entries = fs.readdirSync(trash, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    let swept = 0;
+    for (const d of entries) {
+        if (!d.isDirectory())
+            continue;
+        const ts = Number(d.name.split("-")[0]);
+        if (Number.isFinite(ts) && now - ts > ttlMs) {
+            fs.rmSync(path.join(trash, d.name), { recursive: true, force: true });
+            swept++;
+        }
+    }
+    return swept;
+}
+/** Does a Claude trash entry with this id exist in this profile? (Lets the CLI
+ *  find which profile owns a trash-id without re-deriving the trash path.) */
+export function trashedSessionExists(configDir, trashId) {
+    return fs.existsSync(path.join(configDir, TRASH_DIRNAME, trashId, "manifest.json"));
+}
+/** Native codex session action → argv. Spawned with `CODEX_HOME` set to the
+ *  profile config dir; codex owns its store, so we never rm rollouts by hand.
+ *  NB: codex exits 0 even when the id is not found — the caller inspects output. */
+export function codexSessionCommand(action, sessionId) {
+    return [action, sessionId];
+}
+// ---------- Codex parity (verified in scripts/spikes/g03: outcome (a)) --------
+//
+// Codex CLI's on-disk layout differs from Claude Code's: a session is one
+// date-partitioned rollout file — `<config>/sessions/YYYY/MM/DD/rollout-<ISO8601
+// timestamp>-<uuid>.jsonl` (optionally `.jsonl.zst`) — with no encoded-cwd
+// project dir and no checkpoint subdir. The session id is the trailing UUID in
+// the filename. g03 confirmed outcome (a): a rollout MOVED into another
+// authenticated CODEX_HOME (preserving the date-partitioned relative path)
+// resumes immediately by id — full takeover parity, no index rebuild.
+//
+// Same iron rules as Claude: transcripts are opaque (never read here), transfers
+// are copy → verify → delete, resume-by-id is the supported path. Codex fork
+// (`--keep-source`) has NO verified spike, so codex takeover is MOVE-ONLY — the
+// caller refuses keep-source rather than risk same-id divergence.
+/** The trailing UUID of a codex rollout filename, or null. Anchored on the
+ *  `.jsonl[.zst]` tail so the ISO8601 timestamp earlier in the name (which also
+ *  contains hyphen-separated digits) can never be mistaken for the id. */
+export function codexSessionId(filename) {
+    const m = /-([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\.jsonl(?:\.zst)?$/.exec(filename);
+    return m ? m[1] : null;
+}
+/** All rollout files under a codex home's `sessions/` tree, as [absPath, dirent-relative].
+ *  Bounded recursive scan of the date partitions; tolerant of a missing tree. */
+function walkCodexRollouts(sessionsDir) {
+    const out = [];
+    const stack = [sessionsDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                stack.push(full);
+            }
+            else if (e.isFile() && codexSessionId(e.name) !== null) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+/** Recent codex sessions of one home, newest first, capped at `limit`. The
+ *  rollout blob is never read (format is opaque + version-unstable), so `cwd`
+ *  and `summary` are null; `projectDir` carries the date-partition path for
+ *  display parity with the Claude listing. */
+export function listCodexSessions(configDir, limit) {
+    const sessionsDir = path.join(configDir, "sessions");
+    const rows = [];
+    for (const file of walkCodexRollouts(sessionsDir)) {
+        const id = codexSessionId(path.basename(file));
+        if (id === null)
+            continue;
+        let st;
+        try {
+            st = fs.statSync(file);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isFile())
+            continue;
+        rows.push({
+            sessionId: id,
+            projectDir: path.relative(sessionsDir, path.dirname(file)),
+            cwd: null,
+            summary: null,
+            mtimeMs: st.mtimeMs,
+            birthtimeMs: st.birthtimeMs || st.mtimeMs,
+            live: false,
+            file,
+        });
+    }
+    rows.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return rows.slice(0, limit);
+}
+/** Where a codex session id lives inside ONE home, or null. */
+export function locateCodexSession(configDir, sessionId) {
+    const sessionsDir = path.join(configDir, "sessions");
+    for (const file of walkCodexRollouts(sessionsDir)) {
+        if (codexSessionId(path.basename(file)) === sessionId) {
+            return { configDir, rollout: file, rel: path.relative(configDir, file) };
+        }
+    }
+    return null;
+}
+/**
+ * Move one codex rollout into the target home, preserving its date-partitioned
+ * relative path. copy → verify (byte size) → delete-source, mirroring
+ * `transferSession`. Move-only: codex fork is unverified, so there is no
+ * keep-source path here (the caller refuses it) — a same-id copy in two homes
+ * would be exactly the divergence the move avoids. Throws on a target collision.
+ */
+export function transferCodexSession(loc, tgtConfigDir) {
+    const tgtRollout = path.join(tgtConfigDir, loc.rel);
+    if (fs.existsSync(tgtRollout)) {
+        throw new Error(`target already has a rollout for this session id (${tgtRollout}) — refusing to overwrite`);
+    }
+    fs.mkdirSync(path.dirname(tgtRollout), { recursive: true, mode: 0o700 });
+    const actions = [];
+    fs.copyFileSync(loc.rollout, tgtRollout);
+    const srcSize = fs.statSync(loc.rollout).size;
+    const tgtSize = fs.statSync(tgtRollout).size;
+    if (srcSize !== tgtSize) {
+        fs.rmSync(tgtRollout, { force: true });
+        throw new Error(`rollout copy failed verification (${srcSize} != ${tgtSize} bytes)`);
+    }
+    actions.push(`copied rollout (${srcSize} bytes, verified)`);
+    fs.rmSync(loc.rollout, { force: true });
+    actions.push("removed source copy (move complete)");
+    return { actions, targetJsonl: tgtRollout };
+}

package/dist/settings-inherit.js

@@ -0,0 +1,81 @@
+/**
+ * Seed a Claude profile's permission allowlist from the user's GLOBAL Claude
+ * settings (~/.claude/settings.json).
+ *
+ * agent-switch runs each profile under its own CLAUDE_CONFIG_DIR, so Claude Code
+ * reads THAT profile's settings.json and never the global one. A freshly-`add`ed
+ * profile therefore starts with none of the globally-approved command
+ * permissions and re-prompts for each (`import` is unaffected — it copies the
+ * whole ~/.claude, settings.json included). This copies (unions) the global
+ * `permissions` into a profile — at create time, and via a backfill command for
+ * existing profiles.
+ *
+ * Scope: ONLY `permissions` is inherited. Hooks are managed per-profile by
+ * hooks.ts; theme / model / statusLine are deliberately profile-own. The global
+ * file is only ever READ here — it is never modified, so a profile can never
+ * clobber the source allowlist (unlike a shared symlink + `share sync`).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readSettings } from "./hooks.js";
+/** Union two string lists, global first, de-duplicated, order-preserving. */
+function union(a = [], b = []) {
+    return [...new Set([...a, ...b])];
+}
+/**
+ * Pure merge: the profile's permissions with the global allow/deny/ask lists
+ * unioned in. A profile's own grants are never dropped; a profile scalar
+ * (`defaultMode`) wins over the global. Returns null when the global carries no
+ * permissions to inherit (caller then leaves the profile untouched).
+ */
+export function mergePermissions(globalPerms, profilePerms) {
+    if (!globalPerms || typeof globalPerms !== "object")
+        return null;
+    // Nothing to inherit unless the global actually carries a grant list.
+    const globalHasGrants = (globalPerms.allow?.length ?? 0) + (globalPerms.deny?.length ?? 0) + (globalPerms.ask?.length ?? 0) > 0;
+    if (!globalHasGrants)
+        return null;
+    const p = profilePerms && typeof profilePerms === "object" ? profilePerms : {};
+    const merged = { ...p };
+    const allow = union(globalPerms.allow, p.allow);
+    if (allow.length)
+        merged.allow = allow;
+    const deny = union(globalPerms.deny, p.deny);
+    if (deny.length)
+        merged.deny = deny;
+    const ask = union(globalPerms.ask, p.ask);
+    if (ask.length)
+        merged.ask = ask;
+    const defaultMode = p.defaultMode ?? globalPerms.defaultMode;
+    if (defaultMode !== undefined)
+        merged.defaultMode = defaultMode;
+    return merged;
+}
+/** Pure: a NEW profile settings object with the global permissions inherited.
+ *  Returns the input unchanged when there is nothing to inherit. */
+export function withInheritedPermissions(profileSettings, globalSettings) {
+    const merged = mergePermissions(globalSettings?.permissions, profileSettings?.permissions);
+    if (!merged)
+        return profileSettings;
+    return { ...profileSettings, permissions: merged };
+}
+/**
+ * Seed `profileConfigDir/settings.json` permissions from
+ * `globalConfigDir/settings.json`. Reads both, writes only the profile. Degraded
+ * mode: a missing/garbage global settings file → no-op (readSettings returns
+ * {}). The global file is never written. Idempotent — a second run over an
+ * already-seeded profile reports `changed: false`.
+ */
+export function inheritPermissions(profileConfigDir, globalConfigDir) {
+    const globalSettings = readSettings(globalConfigDir);
+    const before = readSettings(profileConfigDir);
+    const next = withInheritedPermissions(before, globalSettings);
+    const afterAllow = (next.permissions?.allow ?? []).length;
+    const beforeAllow = (before.permissions?.allow ?? []).length;
+    if (JSON.stringify(next) === JSON.stringify(before)) {
+        return { changed: false, allowCount: afterAllow, addedAllow: 0 };
+    }
+    fs.mkdirSync(profileConfigDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(profileConfigDir, "settings.json"), JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    return { changed: true, allowCount: afterAllow, addedAllow: afterAllow - beforeAllow };
+}