wicked-crew 0.7.27 → 0.7.29

package/README.md

@@ -30,7 +30,15 @@ installs/updates the whole wicked-\* family, crew included.
 serves the bundled **wicked-studio** browser console same-origin — open the URL and you have the
 control room: launch and steer runs, answer human gates, browse projects and evidence, watch live
 engine events. Durable state (runs, evidence, event log) lives in `~/.wicked-crew/` (`--db`
-overrides).
+overrides). Governance evidence — conformance claims, phase transitions, rule lifecycle — lands in
+`<core db>.governance/governance.db` (`--governance-db` / `WICKED_CREW_GOVERNANCE_DB` override; an
+inherited `WICKED_ESTATE_DB` is honoured — the emit seam is SQLite-only, so a URL-form value such as
+`postgres://…` in your shell refuses boot until `--governance-db` names a SQLite file); events the
+engine cannot store dead-letter to
+`<core db>.governance/emit-outbox.ndjson` by default (under the state home, not HOME; an explicit
+`WICKED_APPS_EMIT_DEADLETTER` is honoured), are counted on
+`GET /api/v1/diagnostics` → `governance` (a `governance.deadletter` finding), and are drained back
+with `wicked-crew governance replay <outbox>`.
 
 ## Quickstart
 

package/dist/api/chat-scope.d.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 type { CoreAdapter } from '../core/adapter.js';
+import type { ChatScope, RepoEntry } from '../core/types.js';
+import { type ProjectGraphBindingDecision } from '../projects/graph.js';
+/** The scope a `POST /chats` asked for, after body validation. `repoRefs` is `repoRef` merged in. */
+export interface ChatScopeRequest {
+    chatId: string;
+    projectId?: string;
+    /** Registry ids or names; empty when the caller named none. */
+    repoRefs: string[];
+}
+/** What the engine is handed for the chat — the wire shape of `chatOpen`'s `scopeJson` plus `cwd`. */
+export interface EngineChatScope {
+    cwd: string;
+    codeGraphDb: string | null;
+    readRoots: string[];
+}
+export type ChatScopeResolution = {
+    ok: true;
+    scope: ChatScope;
+    engine: EngineChatScope;
+} | {
+    ok: false;
+    status: 400 | 404 | 409;
+    error: string;
+    missing?: string[];
+};
+/** The reads the resolver needs — injectable so the resolver is testable without an engine. */
+export interface ChatScopeDeps {
+    listRepos(): Promise<RepoEntry[]>;
+    /** The `crew.repo` member refs of a project, in attach order. */
+    projectRepoRefs(projectId: string): Promise<string[]>;
+    /** The project-graph decision for a chat — repo-bound when exactly one repo is in scope. */
+    bindProjectGraph(projectId: string, repoRef: string | undefined): Promise<ProjectGraphBindingDecision>;
+    /** Where chat scratch roots live. Default {@link chatScratchBase}. */
+    scratchBase?: string;
+    /** Where a registered root the daemon cannot resolve — and that is NOT in this chat's scope nor
+     *  lexically near the base — is noted instead of refusing the open (hardening, W7). */
+    log?: (msg: string) => void;
+}
+/**
+ * `<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 declare function chatScratchBase(): string;
+/** The production deps over a live adapter. */
+export declare function chatScopeDeps(adapter: CoreAdapter): ChatScopeDeps;
+/**
+ * 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 declare function resolveChatScope(req: ChatScopeRequest, deps: ChatScopeDeps): Promise<ChatScopeResolution>;
+/**
+ * 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 declare function chatScopeStatement(chatId: string, scope: ChatScope): string;
+/**
+ * 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 declare function prepareChatScratch(chatId: string, scope: ChatScope): void;
+/**
+ * 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 declare function reapStaleChatNamespaces(parent?: string): string[];
+/**
+ * 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 declare function removeChatScratch(cwd: string, base?: string): void;
+/** One chat id's lifecycle slot in the index — see {@link ChatScopeIndex}. */
+type ChatSlot = 
+/** An open is in flight: reserved synchronously before the route's first `await`. */
+{
+    state: 'reserved';
+    token: number;
+}
+/** The chat is open; its scratch root exists and its seats are reading the statement there. */
+ | {
+    state: 'live';
+    scope: ChatScope;
+}
+/** `DELETE` ran: the root is already gone, and the id stays taken until the engine's own
+ *  `chatClosed` for it is observed (or the grace timer gives up) — so a delayed close can never
+ *  land on a chat that reused the id, and a reuse cannot race the close. */
+ | {
+    state: 'closing';
+    timer: ReturnType<typeof setTimeout>;
+};
+/**
+ * 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 declare class ChatScopeIndex {
+    readonly base: string;
+    private readonly closeGraceMs;
+    private readonly slots;
+    private nextToken;
+    /** `base`: where this daemon's chat scratch roots live — the resolver is handed the SAME base. */
+    constructor(base?: string, closeGraceMs?: number);
+    /** Live, reserved or closing — every state in which the id is not free. */
+    has(chatId: string): boolean;
+    /** The state the id is in, for the route's refusal wording. */
+    stateOf(chatId: string): ChatSlot['state'] | 'free';
+    /** Reserve `chatId` for an open in flight; `null` when it is live, reserved or closing. */
+    reserve(chatId: string): number | null;
+    /** Give a reservation back (the open failed before `set`) — only the holder's own. */
+    release(chatId: string, token: number): void;
+    /**
+     * 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: string, token: number): void;
+    /** 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: string, scope: ChatScope, token: number): boolean;
+    /** The scope of a LIVE chat; `undefined` while reserved, closing or unknown. */
+    get(chatId: string): ChatScope | 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: string): ChatScope | 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: string): void;
+    /** Forget the chat and remove its scratch root at once — no closing window (tests, teardown). */
+    delete(chatId: string): ChatScope | undefined;
+}
+export {};
+//# sourceMappingURL=chat-scope.d.ts.map

package/dist/api/chat-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-scope.d.ts","sourceRoot":"","sources":["../../src/api/chat-scope.ts"],"names":[],"mappings":"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"}