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

package/dist/workspace/projects.js

@@ -0,0 +1,274 @@
+import { MANAGED_WORKTREE } from '../project-paths.js';
+import { defined } from '../core/defined.js';
+import { realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { PROJECT_TAGS_MAX, PROJECT_TAG_MAX_LENGTH } from '../contract/index.js';
+import { projectWebhooks, redactWebhook } from './webhooks.js';
+import { forgeKindOfRemote, forgeWebRoot } from '../server/forge/index.js';
+import { createRootProbeCache } from './root-probe-cache.js';
+import { getRepoInfo } from '../server/git.js';
+import { mergeWriteWorkspaceConfig, loadWorkspaceConfig, } from './config.js';
+/**
+ * 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 const RESERVED_PROJECT_IDS = new Set([
+    'default',
+    'new',
+    'settings',
+    'api',
+    'p',
+    'assets',
+]);
+/** Slug length cap — mirrors `PROJECT_ID_RE` (1 head char + up to 63 more). */
+const SLUG_MAX = 64;
+/**
+ * `basename(root)` → slug base: lowercase, runs of `[^a-z0-9-]` become one
+ * `-`, edge dashes trimmed so the result matches `^[a-z0-9][a-z0-9-]{0,63}$`.
+ * A degenerate basename (e.g. `日本語/`) falls back to `project` rather than
+ * ever escaping the slug shape.
+ */
+function slugBase(root) {
+    const base = basename(root)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, SLUG_MAX);
+    return base || 'project';
+}
+/**
+ * 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 function allocateProjectSlug(root, taken) {
+    const used = new Set(RESERVED_PROJECT_IDS);
+    for (const id of taken)
+        used.add(id);
+    const base = slugBase(root);
+    if (!used.has(base))
+        return base;
+    for (let n = 2;; n++) {
+        const suffix = `-${n}`;
+        const candidate = `${base.slice(0, SLUG_MAX - suffix.length)}${suffix}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+}
+/**
+ * Realpath-normalize a root: resolves symlinks and drops trailing slashes, so
+ * every spelling of the same directory dedupes to one registry entry. A path
+ * that cannot be realpath'd (doesn't exist yet, unreadable) degrades to plain
+ * `resolve()` — registration callers guard existence; this module never throws
+ * over it.
+ */
+async function normalizeRoot(root) {
+    try {
+        return await realpath(root);
+    }
+    catch {
+        return resolve(root);
+    }
+}
+/** True when `path` sits inside a cezar task worktree (`…/.ai/cezar/worktrees/…`). */
+function isInsideTaskWorktree(path) {
+    return MANAGED_WORKTREE.test(`${path.replaceAll('\\', '/')}/`);
+}
+/**
+ * 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 async function shouldRegisterProject(repoRoot) {
+    const real = await normalizeRoot(repoRoot);
+    if (isInsideTaskWorktree(real) || isInsideTaskWorktree(resolve(repoRoot)))
+        return false;
+    const home = await normalizeRoot(homedir());
+    return real !== home;
+}
+/**
+ * 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 async function registerProject(root, source = 'local', home) {
+    const real = await normalizeRoot(root);
+    const now = new Date().toISOString();
+    let entry;
+    let added = false;
+    await mergeWriteWorkspaceConfig((config) => {
+        const existing = config.projects.find((p) => p.root === real);
+        if (existing) {
+            existing.lastOpenedAt = now;
+            entry = existing;
+            return;
+        }
+        added = true;
+        entry = {
+            id: allocateProjectSlug(real, config.projects.map((p) => p.id)),
+            root: real,
+            name: basename(real),
+            addedAt: now,
+            lastOpenedAt: now,
+            source,
+        };
+        config.projects.push(entry);
+    }, home);
+    // The mutator always runs, so `entry` is always set — this satisfies TS.
+    if (!entry)
+        throw new Error('registerProject: merge-write did not run the mutator');
+    if (added)
+        invalidateProjectProbe(real);
+    return entry;
+}
+/**
+ * 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 function normalizeProjectTags(tags) {
+    if (!tags)
+        return undefined;
+    const bySpelling = new Map();
+    for (const raw of tags) {
+        const tag = raw.trim().slice(0, PROJECT_TAG_MAX_LENGTH);
+        if (!tag)
+            continue;
+        const key = tag.toLowerCase();
+        if (!bySpelling.has(key))
+            bySpelling.set(key, tag);
+        if (bySpelling.size >= PROJECT_TAGS_MAX)
+            break;
+    }
+    const normalized = [...bySpelling.values()].sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
+    return normalized.length > 0 ? normalized : 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 function toProjectListEntry(project, probe) {
+    const { webhook: _legacy, webhooks: _stored, ...rest } = project;
+    const webhooks = projectWebhooks(project);
+    const task = webhooks.find((entry) => entry.tasks);
+    return defined({
+        ...rest,
+        ...probe,
+        ...(task
+            ? {
+                webhook: {
+                    url: task.url,
+                    tokenSet: Boolean(task.token),
+                    ...(task.triggers === undefined ? {} : { triggers: task.triggers }),
+                },
+            }
+            : {}),
+        ...(webhooks.length > 0 ? { webhooks: webhooks.map(redactWebhook) } : {}),
+    });
+}
+/** Probe TTL — long enough to coalesce a burst of sidebar renders, short
+ *  enough that a deleted repo shows as `missing` on the next real look. */
+const PROBE_TTL_MS = 5_000;
+const probeCache = createRootProbeCache({ compute: computeProbe, now: () => Date.now(), ttlMs: PROBE_TTL_MS });
+export function invalidateProjectProbe(root) {
+    probeCache.invalidate(root);
+}
+/** Test hook: drop cached probes so status changes are visible immediately. */
+export function clearProjectProbeCache() {
+    probeCache.clear();
+}
+async function computeProbe(root) {
+    try {
+        if (!(await stat(root)).isDirectory())
+            return { status: 'missing' };
+    }
+    catch {
+        return { status: 'missing' };
+    }
+    try {
+        // `.git` may be a dir (normal clone) or a file (worktree/submodule) —
+        // a bare stat covers both without shelling out.
+        await stat(join(root, '.git'));
+    }
+    catch {
+        return { status: 'not-git' };
+    }
+    // Branch and forge are best-effort garnish: getRepoInfo never throws (null
+    // on e.g. an unborn HEAD), and a repo without either is still status ok.
+    const info = await getRepoInfo(root);
+    const forge = forgeKindOfRemote(info?.remote);
+    // Free: `getRepoInfo` already ran for the branch, and the remote is already parsed for `forge`.
+    const repoUrl = forgeWebRoot(info?.remote);
+    return {
+        status: 'ok',
+        ...(info?.branch ? { branch: info.branch } : {}),
+        ...(forge ? { forge } : {}),
+        ...(repoUrl ? { repoUrl } : {}),
+    };
+}
+async function probeRoot(root) {
+    return probeCache.get(root);
+}
+/**
+ * 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 async function probeProjectStatus(root) {
+    return probeRoot(root);
+}
+export async function listProjects(selector, home) {
+    const config = await loadWorkspaceConfig(home.workspaceConfig);
+    const projects = selector
+        ? config.projects.filter((project) => project.id === selector.projectId)
+        : config.projects;
+    return Promise.all(projects.map(async (project) => toProjectListEntry(project, await probeRoot(project.root))));
+}
+/**
+ * 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 async function removeProject(id, home) {
+    let removed = false;
+    let removedRoot;
+    await mergeWriteWorkspaceConfig((config) => {
+        removedRoot = config.projects.find((p) => p.id === id)?.root;
+        const next = config.projects.filter((p) => p.id !== id);
+        removed = next.length !== config.projects.length;
+        config.projects = next;
+    }, home);
+    if (removedRoot)
+        invalidateProjectProbe(removedRoot);
+    return removed;
+}
+//# sourceMappingURL=projects.js.map

package/dist/workspace/projects.js.map

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

package/dist/workspace/root-probe-cache.d.ts

@@ -0,0 +1,10 @@
+/** Completed values and flights share a slot. Replacing a slot fences late writes. */
+export declare function createRootProbeCache<T>({ compute, now, ttlMs }: {
+    compute: (root: string) => Promise<T>;
+    now: () => number;
+    ttlMs: number;
+}): {
+    get(root: string): Promise<T>;
+    invalidate(root: string): void;
+    clear(): void;
+};

package/dist/workspace/root-probe-cache.js

@@ -0,0 +1,43 @@
+import { resolve } from 'node:path';
+/** Completed values and flights share a slot. Replacing a slot fences late writes. */
+export function createRootProbeCache({ compute, now, ttlMs }) {
+    const slots = new Map();
+    let epoch = 0;
+    return {
+        get(root) {
+            const key = resolve(root);
+            let slot = slots.get(key);
+            if (!slot) {
+                slot = { generation: 0 };
+                slots.set(key, slot);
+            }
+            if (slot.value && now() - slot.value.at < ttlMs)
+                return Promise.resolve(slot.value.result);
+            if (slot.flight)
+                return slot.flight;
+            const current = slot;
+            const generation = current.generation;
+            const startedEpoch = epoch;
+            const valid = () => epoch === startedEpoch && slots.get(key) === current && current.generation === generation;
+            const flight = Promise.resolve().then(() => compute(key)).then((result) => {
+                if (valid())
+                    current.value = { at: now(), result };
+                return result;
+            }).finally(() => {
+                if (valid())
+                    delete current.flight;
+            });
+            current.flight = flight;
+            return flight;
+        },
+        invalidate(root) {
+            const key = resolve(root);
+            const slot = slots.get(key);
+            if (slot)
+                slot.generation++;
+            slots.delete(key);
+        },
+        clear() { epoch++; slots.clear(); },
+    };
+}
+//# sourceMappingURL=root-probe-cache.js.map

package/dist/workspace/root-probe-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-probe-cache.js","sourceRoot":"","sources":["../../src/workspace/root-probe-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,sFAAsF;AACtF,MAAM,UAAU,oBAAoB,CAAI,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAI5D;IAEC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IACtC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO;QACL,GAAG,CAAC,IAAY;YACd,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1B,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;gBAAC,IAAI,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;gBAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAAC,CAAC;YAC9D,IAAI,IAAI,CAAC,KAAK,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC3F,IAAI,IAAI,CAAC,MAAM;gBAAE,OAAO,IAAI,CAAC,MAAM,CAAC;YACpC,MAAM,OAAO,GAAG,IAAI,CAAC;YACrB,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;YACtC,MAAM,YAAY,GAAG,KAAK,CAAC;YAC3B,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,KAAK,KAAK,YAAY,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,IAAI,OAAO,CAAC,UAAU,KAAK,UAAU,CAAC;YAC9G,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;gBACxE,IAAI,KAAK,EAAE;oBAAE,OAAO,CAAC,KAAK,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,CAAC;gBACnD,OAAO,MAAM,CAAC;YAChB,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;gBACd,IAAI,KAAK,EAAE;oBAAE,OAAO,OAAO,CAAC,MAAM,CAAC;YACrC,CAAC,CAAC,CAAC;YACH,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,UAAU,CAAC,IAAY;YACrB,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,IAAI;gBAAE,IAAI,CAAC,UAAU,EAAE,CAAC;YAC5B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;QACD,KAAK,KAAW,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;KAC1C,CAAC;AACJ,CAAC"}

package/dist/workspace/semaphore.d.ts

@@ -0,0 +1,147 @@
+import type { Home } from '../home/home.ts';
+/**
+ * Shared host resource limits and cached workspace settings for every RunManager. Managers own
+ * slot accounting; refresh reloads limits and pumps all managers. Per-project ceilings are
+ * additional limits.
+ */
+/** The cached `resources` slice run enforcement consults. */
+export interface WorkspaceResourceLimits {
+    /** Workspace-wide cap on concurrently *running* agent runs. */
+    maxParallel: number;
+    /** Durable monitoring sessions that do not consume active-task capacity. */
+    maxMonitoringSessions?: number;
+    /** Automatic monitoring re-check cadence in minutes. Default ON at
+     *  `DEFAULT_MONITORING_WAKE_MINUTES`; explicit `null` means stay parked; absent means
+     *  "this loader predates the key" and reads as the default. */
+    monitoringWakeIntervalMinutes?: number | null | undefined;
+    /** Resume a run stopped by a provider usage limit when that limit resets. Default ON. */
+    autoResumeOnUsageLimit?: boolean;
+    /** Per-task process-tree memory ceiling in MiB; null = no limit. */
+    memoryLimitMb: number | null;
+    /**
+     * Per-project concurrency ceilings, keyed by realpath-normalized project
+     * root (the registry stores normalized `root`). A root absent from the map
+     * inherits the workspace `maxParallel`. Optional so older `load` stubs that
+     * only return the resource slice keep working — an absent map means "no
+     * project has an override", i.e. every project inherits.
+     */
+    projectLimits?: ReadonlyMap<string, number>;
+}
+/**
+ * The two kinds of usage-limit hold an account can be under, kept apart because they bind
+ * different work (spec 2026-08-03-auto-resume-after-usage-limit):
+ *
+ *  - `deadline` — a run is parked on a reset instant that has not arrived. The window is known to
+ *    be shut, so this blocks EVERYTHING on that account, resumes included.
+ *  - `inFlight` — a resume is running right now, re-testing the window. Nothing is proven yet, so
+ *    this blocks fresh work but NOT other resumes: a resume blocked by a resume is the deadlock
+ *    that stopped a live workspace dead.
+ */
+export interface AccountHolds {
+    deadline: ReadonlySet<string>;
+    inFlight: ReadonlySet<string>;
+}
+/** One manager's seam into the shared counter. */
+export interface SemaphoreParticipant {
+    /** Slots this manager currently holds. The #347 exemption lives in the
+     *  participant's own accounting: `waiting` runs are already subtracted. */
+    busySlots(): number;
+    /** Kick the manager's queue — capacity may have appeared. Awaited by
+     *  `release()` so the manager taking a freed slot has registered it before
+     *  the next participant evaluates capacity. */
+    pump(): void | Promise<void>;
+    /** Epoch ms of this manager's oldest queued run, or null when its queue is
+     *  empty — `release()`'s ordering key, so a freed slot goes to the
+     *  workspace's longest-waiting run instead of whichever manager happens to
+     *  have registered first. */
+    oldestQueuedAt(): number | null;
+    /** Epoch ms of the oldest wake of a started run in this manager's queue, or null for none
+     *  (hearsay-tools/cezarion#1236). A manager holding a wake is pumped before any manager whose
+     *  queue holds only unstarted runs. Optional so a stub participant sorts as before. */
+    oldestWakeAt?(): number | null;
+    /**
+     * Agent accounts this participant is holding, by KIND (spec
+     * 2026-08-03-auto-resume-after-usage-limit, `RunManager.accountHolds`).
+     *
+     * Workspace-scoped for the same reason the parallel cap is: a limit closes an ACCOUNT, and one
+     * account can be driving tasks in several projects at once. Optional so a stub participant —
+     * and any caller that predates the hold — keeps working; absent simply holds nothing.
+     */
+    accountHolds?(): AccountHolds;
+}
+export interface WorkspaceSemaphoreOptions {
+    home: Home;
+    /** Snapshot source for `refresh()` — tests inject a stub; production keeps
+     *  the `~/.cezar/config.json` reader. */
+    load?: () => Promise<WorkspaceResourceLimits>;
+    /** Starting cache, before any `refresh()` — defaults to the workspace
+     *  schema's own defaults (`maxParallel: 2`, no memory limit), so a manager
+     *  constructed without boot wiring behaves like a fresh workspace. */
+    initial?: Partial<WorkspaceResourceLimits>;
+}
+export declare class WorkspaceSemaphore {
+    private readonly participants;
+    private readonly load;
+    private limits;
+    /** A `release()` sweep is in flight — see `pendingRelease`. */
+    private broadcasting;
+    /** A slot freed DURING a sweep. The in-flight sweep may already have pumped
+     *  the manager that should get it, so re-run rather than drop the wakeup. */
+    private pendingRelease;
+    constructor(options: WorkspaceSemaphoreOptions);
+    /** Join the shared counter. Returns the unregister handle — the manager's
+     *  `dispose()` must call it so a torn-down project stops counting. */
+    register(participant: SemaphoreParticipant): () => void;
+    /** Slots held across EVERY registered manager (waiting runs excluded by
+     *  each participant — the #347 rule). */
+    busy(): number;
+    /** Cached workspace-wide parallel cap. */
+    maxParallel(): number;
+    maxMonitoringSessions(): number;
+    /** Cadence for automatic monitoring re-checks, or null when the operator chose "park
+     *  until resumed". Deliberately NOT `?? DEFAULT`: `null` is a real user choice and
+     *  `null ?? 5` would silently override it (#810). Only an ABSENT key — an older `load`
+     *  stub, a partial `initial` — falls back to the shipped default. */
+    monitoringWakeIntervalMinutes(): number | null;
+    /** Whether a usage-limit stop schedules its own resume. Absent (an older `load` stub, a config
+     *  written before the key existed) reads as ON — the shipped default. */
+    autoResumeOnUsageLimit(): boolean;
+    /** Cached per-task memory ceiling (MiB), or null for no limit. */
+    memoryLimitMb(): number | null;
+    /**
+     * Every agent account held across the WHOLE workspace, by kind — the union of what each manager
+     * reports (spec 2026-08-03-auto-resume-after-usage-limit). A `pump()` consults this before
+     * starting a queued run, so a limit hit in one project also stops the same account being walked
+     * into the wall from another.
+     *
+     * Asked live rather than cached: the underlying answer is derived from run records that change
+     * on every schedule, resume and cancel, and a stale snapshot here would either stall a queue
+     * whose window has reopened or leak a stampede through one that has not.
+     */
+    accountHolds(): AccountHolds;
+    /**
+     * Pump all managers after capacity is released, prioritizing wakes then oldest queued work.
+     * Await pumps sequentially so each claimed slot is counted before the next check. Ineligible
+     * queues do not block other managers.
+     */
+    release(): Promise<void>;
+    /**
+     * The effective per-project concurrency cap for a manager's repo root: the
+     * project's own `maxParallel` if set in the registry, else the workspace cap
+     * (`maxParallel()`). Answered from the cached snapshot — the class's
+     * no-per-tick-file-read invariant is preserved; the only syscall is a
+     * `realpathSync` to key the lookup the same way the registry normalizes
+     * `root` (once per `pump()`, alongside the existing `getRepoInfo` stat). A
+     * root with no registry entry (an ad-hoc run outside the registry) has no
+     * override and inherits the workspace cap.
+     */
+    projectMaxParallel(repoRoot: string): number;
+    /**
+     * The workspace resource-cache hook: re-read the config and pump every
+     * registered manager, so a config change takes effect without a restart.
+     * Called at boot and by `PUT /api/workspace/config` (step 2.7). A failed
+     * read keeps the last good cache — enforcement never degrades to unlimited
+     * because the file was momentarily unreadable.
+     */
+    refresh(): Promise<void>;
+}