wicked-crew 0.7.28 → 0.7.29

package/dist/api/chat-scope.js

@@ -0,0 +1,724 @@
+/**
+ * Chat scope (crew#502, acceptance finding F-067): WHAT a chat's seats can see, decided up front
+ * and stated — to the seats and to the caller.
+ *
+ * `POST /chats` used to set the seats' cwd only when `repoRef` was sent, and the engine fell back
+ * to `current_dir()` — the DAEMON's working directory. Studio's GroupChat never sent `repoRef`, so
+ * every chat explored wherever `wicked-crew serve` had been started from (a customer's `$HOME`),
+ * with no estate MCP, no repo list and no statement of the scope; "chat with all 9 repos" worked
+ * only because the acceptance rig started the daemon from the parent of `repos/`, and the seats
+ * browsed the rig's other clones and the INSTALLED package's `.d.ts` files as if they were sources.
+ *
+ * The scope is a first-class input now: a PROJECT (default: every registered `crew.repo` member)
+ * or an explicit repo list. From it this module derives the three things the engine is handed
+ * (`wicked-core-ts chatOpen(chatId, clis, cwd, scopeJson)`):
+ *
+ *   - `cwd`         — a PRIVATE SCRATCH ROOT of the chat's own, under THIS daemon's per-process
+ *                     namespace (`<os tmp>/wicked-crew-chats/<pid>-<random>/<chatId>`, see
+ *                     {@link chatScratchBase}), never a repo and never the daemon's cwd. Relative
+ *                     writes land there and the
+ *                     OS sandbox, where the seat's config arms it, contains writes to it — the
+ *                     repos are READ. Deliberately NOT under the state home: the engine's worker
+ *                     fence denies `Read/Edit/Write(<state home>/**)` to every seat (wicked-core
+ *                     `execute_wrapped::deny_rules`), so a seat whose cwd sat there could not read
+ *                     its own working directory — and a new state-home store needs core's registry
+ *                     (`tests/fixtures/state-home-subtrees.json`) released first.
+ *   - `readRoots`   — the scoped repos' REGISTERED root paths (the run worktree read-roots idea,
+ *                     applied to live repos): advertised to a claude seat as the SDK's
+ *                     `additionalDirectories`, recorded on every seat (`GET /chats`).
+ *   - `codeGraphDb` — the graph the seats' READ-ONLY estate MCP is bound to: the project's
+ *                     co-located graph (`resolveProjectGraphBinding`, DES-GROUNDING-001 — the SAME
+ *                     seam governed runs get) when the chat is filed into a project; a single
+ *                     repo's own graph otherwise; none for several repos with no project.
+ *
+ * and STATES it: an `AGENTS.md` + `CLAUDE.md` in the scratch root (every seat CLI reads its cwd's
+ * instructions file — claude `CLAUDE.md`; codex, pi, opencode and copilot `AGENTS.md`) names the
+ * repos, their paths, the read-only rule and the grounding, so a seat that starts in an empty
+ * directory knows exactly what it was pointed at; the same {@link ChatScope} rides the
+ * `POST /chats` response and `GET /chats/:id` for the UI (studio's New Chat).
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { codeGraphDb } from '../core/repoPaths.js';
+import { resolveProjectGraphBinding } from '../projects/graph.js';
+let processScratchBase;
+/**
+ * `<os tmp>/wicked-crew-chats/<pid>-<random>` — THIS daemon's own namespace, minted once per
+ * process (Copilot, #518): a shared `<os tmp>/wicked-crew-chats/<chatId>` could already exist from
+ * another daemon running as the same OS user, which would pass every ownership check, overwrite the
+ * live chat's statement and remove its root. Chats do not survive a daemon restart (the engine's pool
+ * is in memory), so a stale namespace left by a crashed daemon holds nothing live. See the module
+ * doc for why the base is not the state home.
+ */
+export function chatScratchBase() {
+    processScratchBase ??= join(tmpdir(), 'wicked-crew-chats', `${process.pid}-${randomBytes(4).toString('hex')}`);
+    return processScratchBase;
+}
+/**
+ * The real path of `p` even when `p` does not exist yet: its longest EXISTING ancestor is
+ * canonicalized and the remaining segments re-appended — so a path under a symlinked temp dir
+ * (macOS: `/var/folders/…` → `/private/var/folders/…`) compares equal to one that was resolved
+ * through the link, whether or not the leaf has been created.
+ */
+function realish(p) {
+    let cur = resolve(p);
+    const tail = [];
+    for (;;) {
+        try {
+            const real = realpathSync(cur);
+            return tail.length === 0 ? real : join(real, ...tail.reverse());
+        }
+        catch (err) {
+            // Only a MISSING component walks up (hardening, W7): EACCES, ELOOP, ENOTDIR and friends mean
+            // the path exists but cannot be resolved — the caller decides whether that refuses the open.
+            if (err.code !== 'ENOENT')
+                throw err;
+            const parent = dirname(cur);
+            if (parent === cur)
+                return resolve(p);
+            tail.push(basename(cur));
+            cur = parent;
+        }
+    }
+}
+/** Lexical containment/equality of two resolved-but-not-canonicalized paths. */
+function lexicallyOverlaps(a, b) {
+    const ra = resolve(a);
+    const rb = resolve(b);
+    return ra === rb || ra.startsWith(rb + sep) || rb.startsWith(ra + sep);
+}
+/** Whether `a` and `b` are the same directory or one contains the other, judged on real paths. */
+function overlaps(a, b) {
+    const ra = realish(a);
+    const rb = realish(b);
+    return ra === rb || ra.startsWith(rb + sep) || rb.startsWith(ra + sep);
+}
+/**
+ * ANY registered root that contains, or sits inside, the scratch base breaks the "private, never a
+ * repo" guarantee (Copilot, #518): the seat's cwd would be part of a live repository — whether or
+ * not that repository is in this chat's scope — and, when it is, that read root would expose every
+ * sibling chat's scratch directory. Judged over EVERY registered repo, on every branch (scoped or
+ * not). Refused as a 409 — it is an operator setup conflict (a repo registered under the OS temp
+ * dir, or a daemon whose TMPDIR sits under a checkout), not a caller error.
+ */
+function refuseOverlap(repos, base, inScope, log) {
+    for (const r of repos) {
+        let clash;
+        try {
+            clash = overlaps(r.root_path, base);
+        }
+        catch (err) {
+            // A root that EXISTS but cannot be resolved (EACCES, ELOOP, an unmounted volume …). NARROWED
+            // (independent review, W7): it refuses the open only when it is IN this chat's scope — the
+            // seats would be pointed at a root nobody can prove safe — or when its lexical spelling
+            // already overlaps the base; an unrelated unresolvable repo is noted and does not block
+            // every chat on the daemon.
+            if (inScope.has(r.id) || lexicallyOverlaps(r.root_path, base)) {
+                return {
+                    ok: false,
+                    status: 409,
+                    error: `repo '${r.name}' at ${r.root_path} cannot be resolved (${message(err)}), so the chat ` +
+                        'scratch base cannot be proven outside it; fix the registration or the mount first.',
+                };
+            }
+            log(`chat scope: registered repo '${r.name}' at ${r.root_path} cannot be resolved (${message(err)}); not in scope, continuing`);
+            continue;
+        }
+        if (clash) {
+            return {
+                ok: false,
+                status: 409,
+                error: `repo '${r.name}' is registered at ${r.root_path}, which overlaps this daemon's chat ` +
+                    `scratch base ${base}; a chat's scratch root can never sit inside a repository (nor a ` +
+                    'repository inside the scratch base) — register the repo elsewhere or set TMPDIR for the daemon.',
+            };
+        }
+    }
+    return null;
+}
+/** The production deps over a live adapter. */
+export function chatScopeDeps(adapter) {
+    return {
+        listRepos: () => adapter.listRepos(),
+        projectRepoRefs: async (projectId) => (await adapter.projectMembers(projectId))
+            .filter((m) => m.member_kind === 'crew.repo')
+            .map((m) => m.member_ref),
+        bindProjectGraph: (projectId, repoRef) => resolveProjectGraphBinding(adapter, projectId, repoRef),
+    };
+}
+/** The route's own id rule, re-applied here: the id becomes ONE path segment under the base. */
+const CHAT_ID = /^[A-Za-z0-9._-]+$/;
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function row(r) {
+    return { id: r.id, name: r.name, rootPath: r.root_path };
+}
+/**
+ * Decide a chat's scope. Never throws on a caller error: an unknown repo is a 404 naming EVERY
+ * missing ref (not just the first), a chat id that cannot name a scratch directory is a 400. A
+ * graph that cannot be bound degrades to "no graph" WITH the reason — the same posture as a run
+ * launch (`resolveProjectGraphBinding` never indexes; a refresh is an explicit act).
+ */
+export async function resolveChatScope(req, deps) {
+    const base = resolve(deps.scratchBase ?? chatScratchBase());
+    const cwd = resolve(base, req.chatId);
+    // `..` and `.` pass the route's character class; a resolved cwd that is not strictly INSIDE the
+    // base (one segment down) is refused before anything is created.
+    if (!CHAT_ID.test(req.chatId) ||
+        !cwd.startsWith(base + sep) ||
+        cwd.slice(base.length + 1).includes(sep)) {
+        return {
+            ok: false,
+            status: 400,
+            error: `chatId ${JSON.stringify(req.chatId)} cannot name a chat scratch directory`,
+        };
+    }
+    const repos = await deps.listRepos();
+    const log = deps.log ?? (() => undefined);
+    const refs = [...new Set(req.repoRefs)];
+    if (refs.length > 0) {
+        const found = [];
+        const missing = [];
+        for (const ref of refs) {
+            const byId = repos.find((r) => r.id === ref);
+            if (byId !== undefined) {
+                if (!found.some((f) => f.id === byId.id))
+                    found.push(byId);
+                continue;
+            }
+            // A NAME is a human spelling, not an identifier: two checkouts can share one (Copilot,
+            // #518). One match resolves; several are refused naming the ids — the same rule the
+            // interactive grounding resolver applies — never "whichever row came first".
+            const byName = repos.filter((r) => r.name === ref);
+            if (byName.length > 1) {
+                return {
+                    ok: false,
+                    status: 400,
+                    error: `repoRef '${ref}' is ambiguous — ${byName.length} registered repos share that name ` +
+                        `(${byName.map((r) => `'${r.id}' at ${r.root_path}`).join(', ')}); name the repo by id.`,
+                };
+            }
+            if (byName.length === 1) {
+                if (!found.some((f) => f.id === byName[0].id))
+                    found.push(byName[0]);
+            }
+            else {
+                missing.push(ref);
+            }
+        }
+        if (missing.length > 0) {
+            return {
+                ok: false,
+                status: 404,
+                error: `Repo ${missing.map((m) => `'${m}'`).join(', ')} not found`,
+                missing,
+            };
+        }
+        // Every registered repo, with THIS chat's repos in scope: the base must not be part of any.
+        const overlap = refuseOverlap(repos, base, new Set(found.map((r) => r.id)), log);
+        if (overlap !== null)
+            return overlap;
+        const graph = await graphForRepos(found, req.projectId, deps);
+        return ok({
+            kind: 'repos',
+            ...(req.projectId !== undefined ? { projectId: req.projectId } : {}),
+            repos: found.map(row),
+            cwd,
+            graph: graph.wire,
+            dangling: [],
+        }, graph.dbPath, found);
+    }
+    if (req.projectId !== undefined) {
+        const memberRefs = await deps.projectRepoRefs(req.projectId);
+        const found = [];
+        const dangling = [];
+        for (const ref of memberRefs) {
+            const repo = repos.find((r) => r.id === ref);
+            if (repo === undefined)
+                dangling.push(ref);
+            else
+                found.push(repo);
+        }
+        const overlap = refuseOverlap(repos, base, new Set(found.map((r) => r.id)), log);
+        if (overlap !== null)
+            return overlap;
+        const decision = await bindOrExplain(deps, req.projectId, undefined);
+        return ok({
+            kind: 'project',
+            projectId: req.projectId,
+            repos: found.map(row),
+            cwd,
+            graph: graphWire(decision),
+            dangling,
+        }, decision.binding?.dbPath ?? null, found);
+    }
+    const overlap = refuseOverlap(repos, base, new Set(), log);
+    if (overlap !== null)
+        return overlap;
+    return ok({
+        kind: 'none',
+        repos: [],
+        cwd,
+        graph: {
+            bound: false,
+            reason: 'the chat names no project and no repos, so its seats see only their own scratch root ' +
+                'and no code graph; pass projectId or repoRefs to scope it.',
+        },
+        dangling: [],
+    }, null, []);
+}
+function ok(scope, dbPath, repos) {
+    return {
+        ok: true,
+        scope,
+        // Read roots ride RESOLVED (independent review, item 5): a registry spelling with a trailing
+        // separator or a `.` segment would otherwise reach the engine's validator verbatim.
+        engine: { cwd: scope.cwd, codeGraphDb: dbPath, readRoots: repos.map((r) => resolve(r.root_path)) },
+    };
+}
+async function bindOrExplain(deps, projectId, repoRef) {
+    try {
+        return await deps.bindProjectGraph(projectId, repoRef);
+    }
+    catch (err) {
+        // Resolving the binding is an ENHANCEMENT to the chat; a failure is stated, never fatal.
+        return {
+            binding: null,
+            reason: `the project graph binding could not be resolved (${message(err)}). ` +
+                'This chat gets no code graph.',
+        };
+    }
+}
+/**
+ * The wire half of a binding decision. `repoLabel` (the estate label the project graph indexes a
+ * repo under — set by a REPO-BOUND decision) rides along for the UI and the statement; the engine
+ * side needs only `dbPath`: a run hands the label so the engine can confirm the graph holds ITS
+ * worktree, and a chat has no worktree — the decision already confirmed the graph holds the repo
+ * (Copilot, #518).
+ */
+function graphWire(decision) {
+    return {
+        bound: decision.binding !== null,
+        reason: decision.reason,
+        ...(decision.binding?.repoLabel !== undefined ? { repoLabel: decision.binding.repoLabel } : {}),
+    };
+}
+async function graphForRepos(repos, projectId, deps) {
+    if (projectId !== undefined) {
+        // Filed into a project: the project's co-located graph, repo-bound when there is exactly one
+        // repo (so the binding confirms the graph HOLDS it, as a repo-bound run does).
+        const decision = await bindOrExplain(deps, projectId, repos.length === 1 ? repos[0].id : undefined);
+        if (decision.binding !== null || repos.length !== 1) {
+            return { wire: graphWire(decision), dbPath: decision.binding?.dbPath ?? null };
+        }
+        // The project declined to bind ONE repo (not a member, not indexed yet, …): its reason says
+        // "uses its own repo's code graph", so DO that — the same existence-checked fallback the
+        // no-project path takes — rather than hand the engine no graph behind a reason that promises
+        // one (Copilot, #518). Both reasons are kept: why the project graph was declined, and what
+        // the chat actually got.
+        const own = ownGraph(repos[0]);
+        return {
+            wire: { bound: own.wire.bound, reason: `${decision.reason} ${own.wire.reason}` },
+            dbPath: own.dbPath,
+        };
+    }
+    if (repos.length === 1) {
+        return ownGraph(repos[0]);
+    }
+    return {
+        wire: {
+            bound: false,
+            reason: `${repos.length} repos and no project: there is no co-located graph to bind. File the ` +
+                'chat into a project (projectId) whose graph is refreshed to ground it across repos; ' +
+                'this chat gets no code graph.',
+        },
+        dbPath: null,
+    };
+}
+/** A single repo's OWN graph — bound only when the registered graph file exists. */
+function ownGraph(only) {
+    try {
+        const dbPath = codeGraphDb(only);
+        // The registry field says WHERE the repo's graph lives, not that it was ever built
+        // (Copilot, #518): a repo indexed by nothing would otherwise be reported as grounded while
+        // the estate MCP answers "not found" about everything. Existence is the honest floor here
+        // (the project path gets the same from `projectGraphStatus`).
+        if (!existsSync(dbPath)) {
+            return {
+                wire: {
+                    bound: false,
+                    reason: `'${only.name}' has no code graph built yet (nothing at its registered graph path); ` +
+                        'index the repo (wicked-estate index / onboarding) to ground this chat. This chat gets none.',
+                },
+                dbPath: null,
+            };
+        }
+        return {
+            wire: { bound: true, reason: `bound to '${only.name}'s own code graph.` },
+            dbPath,
+        };
+    }
+    catch (err) {
+        return {
+            wire: {
+                bound: false,
+                reason: `'${only.name}' has no resolvable code graph (${message(err)}); this chat gets none.`,
+            },
+            dbPath: null,
+        };
+    }
+}
+/**
+ * The statement every seat reads on start — written as BOTH `AGENTS.md` (codex, pi, opencode,
+ * copilot) and `CLAUDE.md` (claude) into the scratch root. Plain prose, repo paths verbatim: the
+ * seat is in an empty directory and this is how it learns what it was pointed at.
+ */
+export function chatScopeStatement(chatId, scope) {
+    const lines = [
+        '# Chat scope',
+        '',
+        `This directory is the scratch root of wicked-crew chat \`${chatId}\`. It is the ONLY place you may write.`,
+        '',
+    ];
+    if (scope.repos.length === 0 && scope.kind === 'project') {
+        // A project whose every `crew.repo` member is dangling (or that has none): filed, but nothing
+        // readable — say exactly that, never "opened without a project" (Copilot, #518).
+        lines.push('## Repositories in scope', '', `None readable. This chat is filed into project \`${scope.projectId ?? ''}\`, but no registered`, 'repository of that project could be resolved' +
+            (scope.dangling.length > 0
+                ? ` (members whose repository is no longer registered: ${scope.dangling.map((d) => `\`${d}\``).join(', ')}).`
+                : ' (it has no `crew.repo` member).'), 'Answer from general knowledge, and say plainly that no repository is readable if asked about code.', '');
+    }
+    else if (scope.repos.length === 0) {
+        lines.push('## Repositories in scope', '', 'None. This chat was opened without a project or repo scope: answer from general knowledge,', 'and say plainly that no repository is in scope if asked about code.', '');
+    }
+    else {
+        lines.push('## Repositories in scope (READ-ONLY)', '', ...scope.repos.map((r) => `- **${r.name}** (\`${r.id}\`): \`${r.rootPath}\``), '', 'Explore and answer questions about these repositories by reading them at the paths above.', 'Cite files by their full path. Do NOT modify, create or delete anything inside them — this', 'chat is read-only exploration; write scratch files only under this directory. Nothing', 'outside these repositories and this directory is in scope.', '');
+    }
+    if (scope.dangling.length > 0 && scope.repos.length > 0) {
+        lines.push(`Project members whose repository is no longer registered (not readable): ${scope.dangling
+            .map((d) => `\`${d}\``)
+            .join(', ')}.`, '');
+    }
+    lines.push('## Code graph', '');
+    lines.push(scope.graph.bound
+        ? 'A READ-ONLY wicked-estate MCP server over the code graph is attached to this session: use its ' +
+            'search / blast-radius / lineage tools to find symbols and relationships before grepping. ' +
+            (scope.graph.repoLabel !== undefined
+                ? `The repository is indexed under the label \`${scope.graph.repoLabel}\`. `
+                : '') +
+            `(${scope.graph.reason})`
+        : `No code graph is attached: ${scope.graph.reason}`, '');
+    if (scope.projectId !== undefined) {
+        lines.push('## Project', '', `This chat is filed into project \`${scope.projectId}\`.`, '');
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Create the chat's scratch root (private) and write the scope statement into it. Throws on an
+ * unwritable temp — the route reports that rather than opening seats with no working directory.
+ *
+ * The root lives under the shared system temp dir, where another local user can pre-place an
+ * entry under a predictable name (Copilot, #518) — so nothing here follows a link or trusts an
+ * existing entry: the base and the root must be REAL directories (never symlinks), an existing
+ * root must be OWNED by this process's user (POSIX), the mode is ENFORCED with `chmod` (mkdir's
+ * `mode` applies only on creation), and each instruction file is unlinked before it is written
+ * exclusively (`wx`) so a planted link cannot redirect the write.
+ */
+export function prepareChatScratch(chatId, scope) {
+    const base = resolve(scope.cwd, '..');
+    // The WHOLE chain below the OS temp dir is created and validated one segment at a time (Copilot,
+    // #518): a recursive mkdir would follow a planted symlink at `<tmp>/wicked-crew-chats` (the
+    // parent every daemon's namespace shares) and create the "private" root inside its target. The
+    // OS temp dir itself is trusted as the platform's (macOS's `/var -> /private/var` is root-owned).
+    const stop = resolve(tmpdir());
+    const chain = [];
+    for (let dir = base; dir !== stop && dirname(dir) !== dir; dir = dirname(dir))
+        chain.unshift(dir);
+    if (chain.length === 0 || !base.startsWith(stop + sep)) {
+        throw new Error(`refusing chat scratch base ${base}: not below the OS temp dir ${stop}`);
+    }
+    for (const dir of chain) {
+        // Non-recursive on purpose (a recursive mkdir resolves the whole parent chain through any
+        // link): an existing segment is fine — `EEXIST` alone is ignored (independent review, W3) —
+        // and EVERY segment, existing or not, must then be a real directory owned by this user.
+        try {
+            mkdirSync(dir, { recursive: false, mode: 0o700 });
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        assertRealOwnedDirectory(dir, 'chat scratch base');
+    }
+    // Only a root THIS call created is removed on a later failure — a pre-existing entry (a planted
+    // directory the ownership check refuses) is never deleted on its planter's behalf (Copilot,
+    // #518). `created` is the non-recursive mkdir's OWN verdict (hardening, W-TOCTOU): a separate
+    // `existsSync` left a window in which another same-user process could create the root between
+    // the check and the mkdir and then lose it to this invocation's cleanup.
+    let created = false;
+    try {
+        mkdirSync(scope.cwd, { recursive: false, mode: 0o700 });
+        created = true;
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    try {
+        assertRealOwnedDirectory(scope.cwd, 'chat scratch root');
+        chmodSync(scope.cwd, 0o700);
+        const statement = chatScopeStatement(chatId, scope);
+        for (const name of ['AGENTS.md', 'CLAUDE.md']) {
+            const file = join(scope.cwd, name);
+            rmSync(file, { force: true }); // removes a planted LINK itself, never its target
+            writeFileSync(file, statement, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        }
+    }
+    catch (err) {
+        if (created)
+            removeChatScratch(scope.cwd, base);
+        throw err;
+    }
+}
+/** `path` must be a real directory (no link), owned by this user where the platform can tell. */
+function assertRealOwnedDirectory(path, what) {
+    const meta = lstatSync(path);
+    if (meta.isSymbolicLink()) {
+        throw new Error(`refusing ${what} ${path}: it is a symlink`);
+    }
+    if (!meta.isDirectory()) {
+        throw new Error(`refusing ${what} ${path}: not a directory`);
+    }
+    if (process.platform !== 'win32' && typeof process.getuid === 'function') {
+        const uid = statSync(path).uid;
+        if (uid !== process.getuid()) {
+            throw new Error(`refusing ${what} ${path}: owned by uid ${uid}, not this daemon's user`);
+        }
+    }
+}
+/**
+ * Reap the scratch namespaces of DEAD daemons (independent review, W6): every sibling
+ * `<pid>-<hex>` directory under the shared parent whose pid no longer exists is removed — judged
+ * with the same checks as {@link removeChatScratch} (a real directory, never a link, owned by this
+ * user). This daemon's own namespace, a live pid, a pid this user may not signal (another user's
+ * daemon), and anything not shaped like a namespace are left alone. Never throws; returns the
+ * removed namespaces. Called once at daemon boot.
+ */
+export function reapStaleChatNamespaces(parent = dirname(chatScratchBase())) {
+    const removed = [];
+    let entries;
+    try {
+        if (lstatSync(parent).isSymbolicLink())
+            return removed;
+        entries = readdirSync(parent);
+    }
+    catch {
+        return removed;
+    }
+    for (const name of entries) {
+        const m = /^(\d+)-[0-9a-f]+$/.exec(name);
+        if (m === null)
+            continue;
+        const pid = Number(m[1]);
+        if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid)
+            continue;
+        try {
+            process.kill(pid, 0); // alive (or at least present): keep
+            continue;
+        }
+        catch (err) {
+            if (err.code !== 'ESRCH')
+                continue; // EPERM: someone else's; keep
+        }
+        const dir = join(parent, name);
+        try {
+            const meta = lstatSync(dir);
+            if (meta.isSymbolicLink() || !meta.isDirectory())
+                continue;
+            if (process.platform !== 'win32' && typeof process.getuid === 'function' && statSync(dir).uid !== process.getuid()) {
+                continue;
+            }
+            rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+            removed.push(dir);
+        }
+        catch {
+            // vanished or unreadable meanwhile: leave it
+        }
+    }
+    return removed;
+}
+/**
+ * Remove a chat's scratch root — fail closed (Copilot, #518): the base must be a REAL directory
+ * (a planted `<tmp>/wicked-crew-chats` link would make a lexical prefix test pass and the
+ * recursive removal follow it), the target must sit DIRECTLY under the base by realpath, must not
+ * itself be a link, and must be owned by this user. Anything else is left alone: a wrong guess
+ * here deletes someone else's files, so the policy is the same as `prepareChatScratch`'s.
+ */
+export function removeChatScratch(cwd, base = chatScratchBase()) {
+    // Every check AND the removal sit under one catch-all (Copilot, #518): a filesystem race between
+    // the checks and the removal (the entry replaced or gone) must leave the path untouched and the
+    // caller's lifecycle intact — never throw out of a `DELETE` or an engine `chatClosed`.
+    try {
+        if (lstatSync(base).isSymbolicLink())
+            return;
+        const baseReal = realpathSync(base);
+        const target = resolve(cwd);
+        const meta = lstatSync(target);
+        if (meta.isSymbolicLink() || !meta.isDirectory())
+            return;
+        if (realpathSync(dirname(target)) !== baseReal)
+            return;
+        if (process.platform !== 'win32' && typeof process.getuid === 'function' && statSync(target).uid !== process.getuid()) {
+            return;
+        }
+        rmSync(target, { recursive: true, force: true, maxRetries: 3 });
+    }
+    catch {
+        // no base, already gone, or unresolvable: nothing of ours is provably here — leave it
+    }
+}
+/**
+ * The daemon's live chat scopes, keyed by chat id — in memory, like the engine's own chat pool (a
+ * daemon restart loses both). A small state machine (Copilot, #518) rather than a map, because the
+ * open is asynchronous and the engine's close is an event:
+ *
+ *   - `reserve` claims an id SYNCHRONOUSLY (before the route's first `await`) and hands back a
+ *     token; `set` publishes the scope only if THAT reservation is still standing — an engine
+ *     `chatClosed` or a `DELETE` that cancelled it in the meantime makes `set` return `false`, and
+ *     the route tears the just-opened chat down instead of registering a scope for a closed one.
+ *   - `beginClose` (DELETE) removes the root at once and parks the id as `closing`; `closed` (the
+ *     engine's `chatClosed`) frees it. Until then a re-open of the same id is refused, so the
+ *     engine's close — which may be delivered after `DELETE` returns — can never delete a newer
+ *     chat's root, and a `chatClosed` for a merely reserved id cancels that open.
+ *   - a `closing` slot whose event never arrives (an engine without the event, a lost relay) is
+ *     freed after `closeGraceMs`; a late event after THAT is the documented residual (the engine's
+ *     `chatClosed` carries no per-open token).
+ */
+export class ChatScopeIndex {
+    base;
+    closeGraceMs;
+    slots = new Map();
+    nextToken = 1;
+    /** `base`: where this daemon's chat scratch roots live — the resolver is handed the SAME base. */
+    constructor(base = chatScratchBase(), closeGraceMs = 5000) {
+        this.base = base;
+        this.closeGraceMs = closeGraceMs;
+    }
+    /** Live, reserved or closing — every state in which the id is not free. */
+    has(chatId) {
+        return this.slots.has(chatId);
+    }
+    /** The state the id is in, for the route's refusal wording. */
+    stateOf(chatId) {
+        return this.slots.get(chatId)?.state ?? 'free';
+    }
+    /** Reserve `chatId` for an open in flight; `null` when it is live, reserved or closing. */
+    reserve(chatId) {
+        if (this.slots.has(chatId))
+            return null;
+        const token = this.nextToken++;
+        this.slots.set(chatId, { state: 'reserved', token });
+        return token;
+    }
+    /** Give a reservation back (the open failed before `set`) — only the holder's own. */
+    release(chatId, token) {
+        const slot = this.slots.get(chatId);
+        if (slot?.state === 'reserved' && slot.token === token)
+            this.slots.delete(chatId);
+    }
+    /**
+     * Abort an open that already reached the ENGINE (the route closed the engine chat again): the
+     * engine's `chatClosed` for this id is still on its way, so the id is parked as `closing` — not
+     * released — until that event (or the grace) frees it; a reuse in between would otherwise have
+     * its root removed by the late event (Copilot, #518). Only the holder's own reservation.
+     */
+    abortToClosing(chatId, token) {
+        const slot = this.slots.get(chatId);
+        if (slot?.state !== 'reserved' || slot.token !== token)
+            return;
+        const timer = setTimeout(() => {
+            if (this.slots.get(chatId)?.state === 'closing')
+                this.slots.delete(chatId);
+        }, this.closeGraceMs);
+        timer.unref?.();
+        this.slots.set(chatId, { state: 'closing', timer });
+    }
+    /** Publish the scope of a finished open. `false` when the reservation is gone (cancelled by a
+     *  close in the meantime): the caller must tear the chat down, nothing was recorded. */
+    set(chatId, scope, token) {
+        const slot = this.slots.get(chatId);
+        if (slot?.state !== 'reserved' || slot.token !== token)
+            return false;
+        this.slots.set(chatId, { state: 'live', scope });
+        return true;
+    }
+    /** The scope of a LIVE chat; `undefined` while reserved, closing or unknown. */
+    get(chatId) {
+        const slot = this.slots.get(chatId);
+        return slot?.state === 'live' ? slot.scope : undefined;
+    }
+    /**
+     * `DELETE /chats/:id`: remove the root now and park the id until the engine's `chatClosed` (or
+     * the grace) frees it. A reserved id is cancelled instead (the in-flight open cleans up on its
+     * failed `set`). Returns the scope that was live, if any.
+     */
+    beginClose(chatId) {
+        const slot = this.slots.get(chatId);
+        if (slot === undefined || slot.state === 'closing')
+            return undefined;
+        if (slot.state === 'live')
+            removeChatScratch(slot.scope.cwd, this.base);
+        // A RESERVED id is parked too, not freed (Copilot, #518): the in-flight open will find its
+        // reservation gone, tear the engine chat down and that close's `chatClosed` is still to come —
+        // a reuse before then would lose its own chat to it. The grace covers an open that never
+        // reached the engine (no event will ever come).
+        const timer = setTimeout(() => {
+            if (this.slots.get(chatId)?.state === 'closing')
+                this.slots.delete(chatId);
+        }, this.closeGraceMs);
+        timer.unref?.();
+        this.slots.set(chatId, { state: 'closing', timer });
+        return slot.state === 'live' ? slot.scope : undefined;
+    }
+    /**
+     * The engine's `chatClosed` for `chatId` (any reason): frees a closing id, removes and frees a
+     * live one (an engine-side reap), cancels a reservation (the open in flight tears down). Idempotent.
+     */
+    closed(chatId) {
+        const slot = this.slots.get(chatId);
+        if (slot === undefined)
+            return;
+        if (slot.state === 'reserved') {
+            // An open is in flight: its `set` will now fail and it tears its engine chat down, whose own
+            // `chatClosed` is still to come — park the id (as `beginClose` does) rather than free it, so a
+            // reuse in between cannot lose its chat to that teardown (hardening, Copilot seventh pass).
+            const timer = setTimeout(() => {
+                if (this.slots.get(chatId)?.state === 'closing')
+                    this.slots.delete(chatId);
+            }, this.closeGraceMs);
+            timer.unref?.();
+            this.slots.set(chatId, { state: 'closing', timer });
+            return;
+        }
+        if (slot.state === 'closing')
+            clearTimeout(slot.timer);
+        if (slot.state === 'live')
+            removeChatScratch(slot.scope.cwd, this.base);
+        this.slots.delete(chatId);
+    }
+    /** Forget the chat and remove its scratch root at once — no closing window (tests, teardown). */
+    delete(chatId) {
+        const slot = this.slots.get(chatId);
+        const scope = slot?.state === 'live' ? slot.scope : undefined;
+        if (slot?.state === 'closing')
+            clearTimeout(slot.timer);
+        this.slots.delete(chatId);
+        if (scope !== undefined)
+            removeChatScratch(scope.cwd, this.base);
+        return scope;
+    }
+}
+//# sourceMappingURL=chat-scope.js.map