@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/workspace/migrations.d.ts

@@ -0,0 +1,37 @@
+import type { Home } from '../home/home.ts';
+export { mergeWriteWorkspaceUiState } from './ui-state.ts';
+/**
+ * Idempotent, additive workspace-config migrations. Preserve per-repo files and degrade on
+ * failure. Use the shared merge writer, with its bounded concurrency guarantees. Run-database
+ * migrations belong to runs/run-database.ts, not this module.
+ */
+export interface WorkspaceMigration {
+    /** `schemaVersion` this migration produces. */
+    to: number;
+    /** Stable id for the warning line, e.g. `'001-workspace-config'`. */
+    id: string;
+    /** The migration body — MUST be idempotent (see module docs). */
+    run(ctx: {
+        home: string;
+        bootRepoRoot: string | null;
+    }, paths: Home): Promise<void>;
+}
+/** All known migrations. Kept in ascending `to` order; `runMigrations` sorts
+ *  defensively anyway. */
+export declare const WORKSPACE_MIGRATIONS: readonly WorkspaceMigration[];
+/**
+ * Run every pending workspace migration — called at boot before anything else
+ * touches `~/.cezar`. Reads `schemaVersion` (absent file or key → 0, which
+ * means "run everything" — safe because every migration is idempotent), runs
+ * each migration with `to > current` in ascending order, and persists the new
+ * `schemaVersion` after EACH one, so a crash resumes exactly where it left
+ * off. A failing migration logs ONE warning and stops the chain (later
+ * migrations may depend on earlier ones); boot proceeds degraded on in-memory
+ * defaults. Never throws.
+ *
+ * `migrations` is injectable for tests only; production callers pass nothing.
+ */
+export declare function runMigrations(opts: {
+    bootRepoRoot: string | null;
+    home: Home;
+}, migrations?: readonly WorkspaceMigration[]): Promise<void>;

package/dist/workspace/migrations.js

@@ -0,0 +1,149 @@
+import { logPrefix } from '../home/display.js';
+import { readProjectPath } from '../project-paths.js';
+import { readFile } from 'node:fs/promises';
+import { readHomeFile } from '../home/store.js';
+import { workspaceUiStateSchema } from '../contract/index.js';
+import { readUiState } from '../ui-state.js';
+import { loadWorkspaceConfig, mergeWriteWorkspaceConfig } from './config.js';
+import { mergeWriteWorkspaceUiState } from './ui-state.js';
+// Step 1.4 exported the global ui-state merge-write from here; step 2.7 moved
+// it to its cleaner home (src/workspace/ui-state.ts, next to the read path the
+// workspace routes share). Re-exported so existing importers keep working.
+export { mergeWriteWorkspaceUiState } from './ui-state.js';
+/** Tolerant raw-JSON read: missing/unreadable/malformed/non-object → null. */
+async function readRawObject(path, homeFile = false) {
+    try {
+        return asObject(JSON.parse(homeFile ? readHomeFile(path) : await readFile(path, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+function asObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * The boot repo's `.ai/cezar/config.json` resource keys, read RAW (not through
+ * `loadConfig`) so only values the user explicitly set are imported — a
+ * defaulted value must not masquerade as a preference. Bounds mirror the
+ * workspace `resources` schema; out-of-range values are simply not imported.
+ */
+async function readRepoResourceKeys(repoRoot) {
+    const raw = await readRawObject(readProjectPath(repoRoot, 'config.json'));
+    const out = {};
+    const maxParallel = raw?.maxParallel;
+    if (typeof maxParallel === 'number' && Number.isInteger(maxParallel) && maxParallel >= 1 && maxParallel <= 16) {
+        out.maxParallel = maxParallel;
+    }
+    const memoryLimitMb = raw?.memoryLimitMb;
+    if (typeof memoryLimitMb === 'number' &&
+        Number.isInteger(memoryLimitMb) &&
+        memoryLimitMb >= 0 &&
+        memoryLimitMb <= 1_048_576) {
+        out.memoryLimitMb = memoryLimitMb;
+    }
+    return out;
+}
+/**
+ * Migration 001 — `schemaVersion 0 → 1`, the "current version up" migration:
+ *
+ * 1. Create `~/.cezar/config.json` with defaults if absent (the merge-write
+ *    does this even when there is nothing to import).
+ * 2. Booting inside a repo: import its `maxParallel`/`memoryLimitMb` into
+ *    workspace `resources`, and its `appearance`/`notifications` ui-state
+ *    keys into `~/.cezar/ui-state.json`. Keys already set globally are NEVER
+ *    overwritten — presence is checked against the RAW global file (before
+ *    defaults are applied), which is exactly what makes a crash-interrupted
+ *    re-run safe: the first pass writes the keys, the re-run sees them set.
+ * 3. Every per-repo file is left untouched in place, so an older cezar run in
+ *    the same repo keeps working off its local copies.
+ *
+ * Registering the boot repo is NOT part of the migration — the normal boot
+ * flow owns registration (single owner, no divergent `addedAt`/`source`).
+ */
+const migration001 = {
+    to: 1,
+    id: '001-workspace-config',
+    async run({ bootRepoRoot }, paths) {
+        // Raw presence check BEFORE the first write: after any merge-write the
+        // global file contains every defaulted key, so "already set globally"
+        // must be decided against what the user's file held coming in.
+        const rawGlobal = await readRawObject(paths.workspaceConfig, true);
+        const rawResources = asObject(rawGlobal?.resources);
+        const imported = bootRepoRoot ? await readRepoResourceKeys(bootRepoRoot) : {};
+        await mergeWriteWorkspaceConfig((config) => {
+            if (imported.maxParallel !== undefined && rawResources?.maxParallel === undefined) {
+                config.resources.maxParallel = imported.maxParallel;
+            }
+            if (imported.memoryLimitMb !== undefined && rawResources?.memoryLimitMb === undefined) {
+                config.resources.memoryLimitMb = imported.memoryLimitMb;
+            }
+        }, paths);
+        if (!bootRepoRoot)
+            return;
+        const repoUiState = await readUiState(bootRepoRoot);
+        // The two prefs that went GLOBAL at step 3.5, read out of the per-repo bag and validated with
+        // the DESTINATION's own field schemas. `notifications` is not named by the per-repo contract
+        // at all (it left at 3.5), so it arrives through the open catchall as `unknown` — parsing it
+        // here is what makes it assignable, and it is also the honest thing: `GET /workspace/ui-state`
+        // promises these two keys' shapes, so a hand-edited value must not be promoted into the global
+        // file unchecked. A value that does not parse is simply not imported — never a failed boot.
+        const shape = workspaceUiStateSchema.shape;
+        const importable = {};
+        const appearance = shape.appearance.safeParse(repoUiState.appearance);
+        if (appearance.success && appearance.data !== undefined)
+            importable.appearance = appearance.data;
+        const notifications = shape.notifications.safeParse(repoUiState.notifications);
+        if (notifications.success && notifications.data !== undefined) {
+            importable.notifications = notifications.data;
+        }
+        if (Object.keys(importable).length === 0)
+            return; // nothing to import — don't create the file
+        await mergeWriteWorkspaceUiState((state) => {
+            for (const [key, value] of Object.entries(importable)) {
+                if (state[key] === undefined)
+                    state[key] = value;
+            }
+        }, paths);
+    },
+};
+/** All known migrations. Kept in ascending `to` order; `runMigrations` sorts
+ *  defensively anyway. */
+export const WORKSPACE_MIGRATIONS = [migration001];
+/**
+ * Run every pending workspace migration — called at boot before anything else
+ * touches `~/.cezar`. Reads `schemaVersion` (absent file or key → 0, which
+ * means "run everything" — safe because every migration is idempotent), runs
+ * each migration with `to > current` in ascending order, and persists the new
+ * `schemaVersion` after EACH one, so a crash resumes exactly where it left
+ * off. A failing migration logs ONE warning and stops the chain (later
+ * migrations may depend on earlier ones); boot proceeds degraded on in-memory
+ * defaults. Never throws.
+ *
+ * `migrations` is injectable for tests only; production callers pass nothing.
+ */
+export async function runMigrations(opts, migrations = WORKSPACE_MIGRATIONS) {
+    const resolvedHome = opts.home;
+    const home = resolvedHome.root;
+    const ordered = [...migrations].sort((a, b) => a.to - b.to);
+    let current = (await loadWorkspaceConfig(resolvedHome.workspaceConfig)).schemaVersion;
+    for (const migration of ordered) {
+        if (migration.to <= current)
+            continue;
+        try {
+            await migration.run({ home, bootRepoRoot: opts.bootRepoRoot }, resolvedHome);
+            const written = await mergeWriteWorkspaceConfig((config) => {
+                config.schemaVersion = Math.max(config.schemaVersion, migration.to);
+            }, resolvedHome);
+            current = written.schemaVersion;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`${logPrefix()} workspace migration ${migration.id} failed (${message}) — booting with in-memory defaults`);
+            return;
+        }
+    }
+}
+//# sourceMappingURL=migrations.js.map

package/dist/workspace/migrations.js.map

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

package/dist/workspace/projects-cli.d.ts

@@ -0,0 +1,27 @@
+import type { Home } from '../home/home.ts';
+/**
+ * `cezar projects` (spec 2026-07-20-multi-project-workspace, step 5.2) — the
+ * terminal twin of Settings → Projects, for the operator who is on a server (or
+ * an ssh session) and has no cockpit in front of them.
+ *
+ * It talks to `~/.cezar/config.json` through `./projects.js` directly, NOT over
+ * HTTP: the whole point is that it works with no server running, on a box where
+ * the cockpit is behind an nginx login. `CEZ_HOME` therefore selects which
+ * workspace it operates on, exactly as it does for `serve`.
+ */
+export interface ProjectsCommandIo {
+    log: (line: string) => void;
+    error: (line: string) => void;
+}
+/**
+ * Run one `projects` subcommand. Returns the process exit code (0 ok, 1 for a
+ * usage error, an unknown id, or a folder the registration guards refuse) so
+ * `src/index.ts` can assign it to `process.exitCode` like every other command.
+ */
+export declare function runProjectsCommand(args: string[], opts: {
+    home: Home;
+    defaultRoot: string;
+    bootProjectId?: string | undefined;
+    env?: NodeJS.ProcessEnv;
+    io?: ProjectsCommandIo;
+}): Promise<number>;

package/dist/workspace/projects-cli.js

@@ -0,0 +1,175 @@
+import { productName } from '../home/display.js';
+import { commandText } from '../home/command.js';
+import { productEnv } from '../core/product-env.js';
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { workspaceConfigPath } from '../paths.js';
+import { loadWorkspaceConfig, mergeWriteWorkspaceConfig } from './config.js';
+import { listProjects, normalizeProjectTags, registerProject, removeProject, shouldRegisterProject, } from './projects.js';
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+const USAGE = commandText(`usage:
+  cez projects [list]          list the registered projects
+  cez projects add [<dir>]     register a folder (default: --repo, else cwd)
+  cez projects remove|rm <id>  drop a registry entry (the repo is untouched)
+  cez projects tag <id> [<tag>…]
+                               set the grouping tags of a project (none clears them)
+
+  add/remove/tag are unavailable when CEZ_SINGLE_PROJECT=1`);
+const SINGLE_PROJECT_ADD_ERROR = 'single-project mode is enabled; adding projects is disabled';
+const SINGLE_PROJECT_REMOVE_ERROR = 'single-project mode is enabled; removing projects is disabled';
+const SINGLE_PROJECT_EDIT_ERROR = 'single-project mode is enabled; editing projects is disabled';
+/**
+ * Run one `projects` subcommand. Returns the process exit code (0 ok, 1 for a
+ * usage error, an unknown id, or a folder the registration guards refuse) so
+ * `src/index.ts` can assign it to `process.exitCode` like every other command.
+ */
+export async function runProjectsCommand(args, opts) {
+    const io = opts.io ?? defaultIo;
+    const singleProject = productEnv('SINGLE_PROJECT', (opts.env ?? process.env)) === '1';
+    const [sub = 'list', ...rest] = args;
+    switch (sub) {
+        case 'list':
+            return listCommand(io, singleProject, opts.bootProjectId, opts.home);
+        case 'add':
+            if (singleProject) {
+                io.error(SINGLE_PROJECT_ADD_ERROR);
+                return 1;
+            }
+            return addCommand(rest[0] ? resolve(rest[0]) : opts.defaultRoot, io, opts.home);
+        case 'remove':
+        case 'rm':
+            if (singleProject) {
+                io.error(SINGLE_PROJECT_REMOVE_ERROR);
+                return 1;
+            }
+            return removeCommand(rest[0], io, opts.home);
+        case 'tag':
+            if (singleProject) {
+                io.error(SINGLE_PROJECT_EDIT_ERROR);
+                return 1;
+            }
+            return tagCommand(rest[0], rest.slice(1), io, opts.home);
+        default:
+            io.error(`unknown projects subcommand: ${sub}\n`);
+            io.error(USAGE);
+            return 1;
+    }
+}
+/** `ok` shows the branch when git could name one; the other states say why. */
+function statusLabel(entry) {
+    if (entry.status === 'missing')
+        return 'missing';
+    if (entry.status === 'not-git')
+        return 'not a git repo';
+    return entry.branch ?? 'ok';
+}
+/** Same ✓/✗ vocabulary the `serve` banner uses for its environment checks. */
+function statusMark(status) {
+    return status === 'missing' ? '✗' : status === 'not-git' ? '·' : '✓';
+}
+async function listCommand(io, singleProject, bootProjectId, home) {
+    const projects = bootProjectId
+        ? await listProjects({ projectId: bootProjectId }, home)
+        : singleProject
+            ? []
+            : await listProjects(undefined, home);
+    if (projects.length === 0) {
+        io.log('\n  no projects registered yet');
+        io.log(commandText('  start the cockpit in a repo (npx cezarion) or add one: cez projects add <dir>\n'));
+        return 0;
+    }
+    const idWidth = Math.max(...projects.map((p) => p.id.length));
+    const labelWidth = Math.max(...projects.map((p) => statusLabel(p).length));
+    io.log('');
+    for (const project of projects) {
+        const label = statusLabel(project).padEnd(labelWidth);
+        // Tags trail the path rather than taking a column of their own: most projects have none,
+        // and a mostly-empty column would cost every row width to say nothing.
+        const tags = project.tags?.length ? `  [${project.tags.join(' ')}]` : '';
+        io.log(`  ${statusMark(project.status)} ${project.id.padEnd(idWidth)}  ${label}  ${project.root}${tags}`);
+    }
+    io.log(`\n  ${projects.length} project(s) — registry: ${workspaceConfigPath(undefined, home)}\n`);
+    return 0;
+}
+async function addCommand(root, io, home) {
+    try {
+        if (!(await stat(root)).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        io.error(`not a directory: ${root}`);
+        return 1;
+    }
+    // Same guards `serve`/`run` apply at boot: a task worktree or `$HOME` itself
+    // is served happily but never registered, and asking for it explicitly does
+    // not buy an exemption.
+    if (!(await shouldRegisterProject(root))) {
+        io.error(`refusing to register ${root} — ${productName('cezar')} task worktrees and your home directory are not projects`);
+        return 1;
+    }
+    const known = new Set((await loadWorkspaceConfig(home.workspaceConfig)).projects.map((p) => p.id));
+    const entry = await registerProject(root, undefined, home);
+    // Registration dedupes by realpath, so a second `add` of the same folder
+    // (or a symlink to it) reports the entry that already exists.
+    io.log(known.has(entry.id) ? `  = ${entry.id} (already registered)  ${entry.root}` : `  + ${entry.id}  ${entry.root}`);
+    return 0;
+}
+async function removeCommand(id, io, home) {
+    if (!id) {
+        io.error(USAGE);
+        return 1;
+    }
+    // Unlike `DELETE /api/projects/:projectId`, there is no boot-project refusal
+    // here: that rule exists because a running server would break its own
+    // sidebar, and the CLI runs with no server and no boot project. Removing the
+    // repo you normally serve is therefore allowed — and self-healing, since the
+    // next `cezar serve` in it registers it again (said in the note below).
+    if (!(await removeProject(id, home))) {
+        io.error(`unknown project: ${id}`);
+        return 1;
+    }
+    io.log(`  - ${id} (registry entry only — the repo and its .ai/cezar/ are untouched)`);
+    return 0;
+}
+/**
+ * `cezar projects tag <id> [<tag>…]` — the terminal twin of the Tags cell in
+ * Settings → Projects.
+ *
+ * Replaces the WHOLE list, like the PATCH route does, and for the same reason:
+ * the caller always knows the full set, and an add-one/remove-one grammar would
+ * be a merge protocol with no one to merge against. No tags at all clears them.
+ * Normalization is the shared `normalizeProjectTags`, so a tag typed here and a
+ * tag typed in the cockpit are stored identically.
+ */
+async function tagCommand(id, tags, io, home) {
+    if (!id) {
+        io.error(USAGE);
+        return 1;
+    }
+    const normalized = normalizeProjectTags(tags);
+    let known = false;
+    await mergeWriteWorkspaceConfig((config) => {
+        const entry = config.projects.find((project) => project.id === id);
+        if (!entry)
+            return;
+        known = true;
+        // Mutated in place so `.passthrough()` keys on the entry survive, and the key
+        // is DELETED rather than set to `[]`: an untagged project stores nothing.
+        if (normalized === undefined)
+            delete entry.tags;
+        else
+            entry.tags = normalized;
+    }, home);
+    if (!known) {
+        io.error(`unknown project: ${id}`);
+        return 1;
+    }
+    io.log(normalized === undefined
+        ? `  = ${id} (no tags)`
+        : `  = ${id}  [${normalized.join(' ')}]`);
+    return 0;
+}
+//# sourceMappingURL=projects-cli.js.map

package/dist/workspace/projects-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects-cli.js","sourceRoot":"","sources":["../../src/workspace/projects-cli.ts"],"names":[],"mappings":"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"}

package/dist/workspace/projects.d.ts

@@ -0,0 +1,131 @@
+import type { Home } from '../home/home.ts';
+import type { ProjectWebhook, WebhookTrigger } from '../contract/index.js';
+import { type ForgeKind } from '../server/forge/index.ts';
+import { type WorkspaceProject } from './config.ts';
+/**
+ * Registry operations: canonical-root registration and slug allocation through merge writes,
+ * cached status probes, and unregister-only removal. Atomic replacement does not serialize
+ * concurrent merges; removing a registry entry never deletes project files.
+ */
+/**
+ * Slugs the allocator must never hand out: `default` is the reserved alias
+ * for the boot project, the rest are the cockpit shell's own top-level path
+ * segments. A repo named `default/` becomes `default-2` and can never shadow
+ * the alias or a route.
+ */
+export declare const RESERVED_PROJECT_IDS: ReadonlySet<string>;
+/**
+ * Allocate a unique slug for `root`: the slug base, deduplicated against
+ * `taken` ids AND the reserved ids with a numeric suffix (`api`, `api-2`,
+ * `api-3`, …). Suffixed candidates stay within the 64-char cap by truncating
+ * the base, never the suffix.
+ */
+export declare function allocateProjectSlug(root: string, taken: Iterable<string>): string;
+/**
+ * Registration guard (spec 2026-07-20-multi-project-workspace, "Boot flow"):
+ * auto-registration is suppressed — the process still serves the folder
+ * normally, it just doesn't pollute the registry — when the resolved
+ * `repoRoot` is:
+ *
+ * - inside any `…/.ai/cezar/worktrees/…` path (task worktrees and nested
+ *   `cez` invocations — the same nesting reality the `CEZ_TODOS_FILE=''`
+ *   guard in `workflows/run.ts` acknowledges), checked on both the raw and
+ *   realpath'd spelling so neither a symlinked prefix nor a literal one
+ *   slips through; or
+ * - the user's home directory itself (realpath-compared, so a symlinked
+ *   `$HOME` still matches).
+ */
+export declare function shouldRegisterProject(repoRoot: string): Promise<boolean>;
+/**
+ * Register `root` in the workspace registry (idempotent). Known root (by
+ * realpath) → bump its `lastOpenedAt` and return the existing entry, id and
+ * all. Unknown → allocate a slug and append a new entry via merge-write.
+ */
+export declare function registerProject(root: string, source: 'local' | 'checkout' | undefined, home: Home): Promise<WorkspaceProject>;
+/**
+ * The ONE spelling rule for project tags — applied on every write, never on read.
+ *
+ * Trimmed, empties dropped, over-long ones truncated, deduped CASE-INSENSITIVELY (the first
+ * spelling wins, so `Storefront` typed before `storefront` keeps its capital), capped at
+ * `PROJECT_TAGS_MAX`, and sorted so two projects tagged with the same set store and render the
+ * same list. Case-insensitive dedupe is what makes tags usable as a grouping key: `API` and `api`
+ * grouping into two columns of the same thing is the whole failure this prevents.
+ *
+ * Returns `undefined` — never `[]` — for an empty result, because the registry stores nothing for
+ * an untagged project and `delete entry.tags` is what the writers then do.
+ */
+export declare function normalizeProjectTags(tags: readonly string[] | null | undefined): string[] | undefined;
+export type ProjectStatus = 'ok' | 'missing' | 'not-git';
+/** `Omit` would collapse the registry's passthrough index signature and drop every known key;
+ *  a key-remapped homomorphic type keeps them. */
+type WorkspaceProjectWithoutWebhook = {
+    [K in keyof WorkspaceProject as K extends 'webhook' | 'webhooks' ? never : K]: WorkspaceProject[K];
+};
+export interface ProjectListEntry extends WorkspaceProjectWithoutWebhook {
+    /** The task webhook (#589), token redacted: the wire only says whether one is set. `triggers`
+     *  only when stored (hearsay-tools/cezarion#1356). */
+    webhook?: {
+        url: string;
+        tokenSet: boolean;
+        triggers?: WebhookTrigger[];
+    };
+    /** Every project webhook, tokens redacted (hearsay-tools/cezarion#1576). `webhook` above is the
+     *  first of them with task notifications on. */
+    webhooks?: ProjectWebhook[];
+    /** `missing` = root gone/unreadable; `not-git` = exists but no `.git`. */
+    status: ProjectStatus;
+    /** Current branch when cheaply available (omitted e.g. on an unborn HEAD). */
+    branch?: string;
+    /** Which forge the root's remote belongs to (#698) — classified from the
+     *  remote URL alone, no `gh` probe. Omitted when there is no forge remote.
+     *  The sidebar gates each project group's GitHub tab on this, instead of on
+     *  the boot folder's health-level forge answer. */
+    forge?: ForgeKind;
+    /** The remote's web root (`https://github.com/owner/repo`), rebuilt from the
+     *  parsed remote so it can never carry credentials. What lets a cross-project
+     *  surface link a reference the run knows only by NUMBER — the global Tasks
+     *  page has one row per project and so cannot use any single repo's base. */
+    repoUrl?: string;
+}
+export interface RootProbe {
+    status: ProjectStatus;
+    branch?: string | undefined;
+    forge?: ForgeKind | undefined;
+    repoUrl?: string | undefined;
+}
+/**
+ * One registry entry as it may leave the server: the webhook token is swapped for `tokenSet`
+ * (#589). Every route and CLI that prints an entry goes through here — the registry is
+ * `.passthrough()`, so spreading a raw entry onto the wire is how a secret would leak.
+ */
+export declare function toProjectListEntry(project: WorkspaceProject, probe: RootProbe): ProjectListEntry;
+export declare function invalidateProjectProbe(root: string): void;
+/** Test hook: drop cached probes so status changes are visible immediately. */
+export declare function clearProjectProbeCache(): void;
+/**
+ * One root's `status` (+`branch`) through the same TTL cache `listProjects`
+ * uses. Exported for `POST /api/projects` (step 4.2): the register route
+ * answers with the freshly registered entry and must hand the cockpit the
+ * SAME shape the list route does — one project, one shape, whichever route
+ * produced it.
+ */
+export declare function probeProjectStatus(root: string): Promise<RootProbe>;
+/**
+ * Registry entries in stored order, each with its `status` (+`branch` when
+ * available). Probes run concurrently and are TTL-cached per root. A
+ * `missing` project is only ever *listed* — callers must never instantiate a
+ * context for it.
+ */
+export interface ProjectListSelector {
+    /** Return only this registry id without mutating or pruning other rows. */
+    projectId: string;
+}
+export declare function listProjects(selector: ProjectListSelector | undefined, home: Home): Promise<ProjectListEntry[]>;
+/**
+ * Remove `id` from the registry. Returns false when no such entry exists.
+ * Pure unregistration: nothing inside the repo (worktrees, `.ai/cezar/`,
+ * run history) is touched — re-registering the same root later gets a fresh
+ * slug but finds all its state intact.
+ */
+export declare function removeProject(id: string, home: Home): Promise<boolean>;
+export {};