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

package/dist/workspace/semaphore.js

@@ -0,0 +1,196 @@
+import { MANAGED_WORKTREE } from '../project-paths.js';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { DEFAULT_MONITORING_WAKE_MINUTES, loadWorkspaceConfig } from './config.js';
+/** Realpath-normalize a root the same way the registry does
+ *  (`workspace/projects.ts` `normalizeRoot`), but synchronously — this answers
+ *  a manager's hot-path lookup and must not `await`. A path that cannot be
+ *  realpath'd degrades to `resolve()`, matching the registry's own fallback. */
+function normalizeRootSync(root) {
+    try {
+        return realpathSync(root);
+    }
+    catch {
+        return resolve(root);
+    }
+}
+/** A cockpit booted from one of cezar's own task worktrees still belongs to
+ *  the registry project that owns `.ai/cezar/worktrees/`. Auto-registration
+ *  intentionally suppresses those worktrees, so the owner root is the only
+ *  registry key their manager can inherit a project ceiling from. */
+function taskWorktreeOwnerRoot(root) {
+    const markerAt = `${root.replaceAll('\\', '/')}/`.search(MANAGED_WORKTREE);
+    return markerAt === -1 ? undefined : root.slice(0, markerAt);
+}
+const DEFAULT_LIMITS = {
+    maxParallel: 2,
+    maxMonitoringSessions: 2,
+    monitoringWakeIntervalMinutes: DEFAULT_MONITORING_WAKE_MINUTES,
+    autoResumeOnUsageLimit: true,
+    memoryLimitMb: null,
+};
+/** Production loader: the `resources` slice of `~/.cezar/config.json`
+ *  (schema-defaulted, so a missing/corrupt file yields the zero-config
+ *  2 parallel / 2 monitoring / 5-minute wake / no memory cap),
+ *  plus the per-project `maxParallel` overrides built into a root→limit map.
+ *  The registry `root` is already realpath-normalized (`registerProject`), so
+ *  the keys match `normalizeRootSync`'s output at lookup time. */
+async function loadResourceLimits(home) {
+    const { resources, projects } = await loadWorkspaceConfig(home.workspaceConfig);
+    const projectLimits = new Map();
+    for (const project of projects) {
+        if (typeof project.maxParallel === 'number')
+            projectLimits.set(project.root, project.maxParallel);
+    }
+    return {
+        maxParallel: resources.maxParallel,
+        maxMonitoringSessions: resources.maxMonitoringSessions,
+        monitoringWakeIntervalMinutes: resources.monitoringWakeIntervalMinutes,
+        autoResumeOnUsageLimit: resources.autoResumeOnUsageLimit,
+        memoryLimitMb: resources.memoryLimitMb,
+        projectLimits,
+    };
+}
+export class WorkspaceSemaphore {
+    participants = new Set();
+    load;
+    limits;
+    /** A `release()` sweep is in flight — see `pendingRelease`. */
+    broadcasting = false;
+    /** 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. */
+    pendingRelease = false;
+    constructor(options) {
+        this.load = options.load ?? (() => loadResourceLimits(options.home));
+        this.limits = { ...DEFAULT_LIMITS, ...options.initial };
+    }
+    /** Join the shared counter. Returns the unregister handle — the manager's
+     *  `dispose()` must call it so a torn-down project stops counting. */
+    register(participant) {
+        this.participants.add(participant);
+        return () => this.participants.delete(participant);
+    }
+    /** Slots held across EVERY registered manager (waiting runs excluded by
+     *  each participant — the #347 rule). */
+    busy() {
+        let total = 0;
+        for (const participant of this.participants)
+            total += participant.busySlots();
+        return total;
+    }
+    /** Cached workspace-wide parallel cap. */
+    maxParallel() {
+        return this.limits.maxParallel;
+    }
+    maxMonitoringSessions() {
+        return this.limits.maxMonitoringSessions ?? 2;
+    }
+    /** 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() {
+        const configured = this.limits.monitoringWakeIntervalMinutes;
+        return configured === undefined ? DEFAULT_MONITORING_WAKE_MINUTES : configured;
+    }
+    /** 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() {
+        return this.limits.autoResumeOnUsageLimit ?? true;
+    }
+    /** Cached per-task memory ceiling (MiB), or null for no limit. */
+    memoryLimitMb() {
+        return this.limits.memoryLimitMb;
+    }
+    /**
+     * 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() {
+        const deadline = new Set();
+        const inFlight = new Set();
+        for (const participant of this.participants) {
+            const holds = participant.accountHolds?.();
+            if (!holds)
+                continue;
+            for (const key of holds.deadline)
+                deadline.add(key);
+            for (const key of holds.inFlight)
+                inFlight.add(key);
+        }
+        return { deadline, inFlight };
+    }
+    /**
+     * 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.
+     */
+    async release() {
+        if (this.broadcasting) {
+            this.pendingRelease = true;
+            return;
+        }
+        this.broadcasting = true;
+        try {
+            do {
+                this.pendingRelease = false;
+                const ordered = [...this.participants]
+                    .map((participant) => ({
+                    participant,
+                    // Wakes of started runs go first, oldest first (hearsay-tools/cezarion#1236).
+                    wake: participant.oldestWakeAt?.() ?? Number.MAX_SAFE_INTEGER,
+                    // Empty queues sort last — they have nothing to claim the slot with.
+                    since: participant.oldestQueuedAt() ?? Number.MAX_SAFE_INTEGER,
+                }))
+                    .sort((a, b) => a.wake - b.wake || a.since - b.since);
+                for (const { participant } of ordered)
+                    await participant.pump();
+            } while (this.pendingRelease);
+        }
+        finally {
+            this.broadcasting = false;
+        }
+    }
+    /**
+     * 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) {
+        const normalized = normalizeRootSync(repoRoot);
+        const projectLimits = this.limits.projectLimits;
+        const direct = projectLimits?.get(normalized);
+        const ownerRoot = direct === undefined ? taskWorktreeOwnerRoot(normalized) : undefined;
+        const override = direct ?? (ownerRoot === undefined ? undefined : projectLimits?.get(ownerRoot));
+        return override ?? this.maxParallel();
+    }
+    /**
+     * 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.
+     */
+    async refresh() {
+        try {
+            this.limits = await this.load();
+        }
+        catch {
+            // keep the last good snapshot
+        }
+        // A raised cap is capacity appearing everywhere at once — same sweep.
+        await this.release();
+    }
+}
+//# sourceMappingURL=semaphore.js.map

package/dist/workspace/semaphore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.js","sourceRoot":"","sources":["../../src/workspace/semaphore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,+BAA+B,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAgCnF;;;gFAGgF;AAChF,SAAS,iBAAiB,CAAC,IAAY;IACrC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;qEAGqE;AACrE,SAAS,qBAAqB,CAAC,IAAY;IACzC,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC3E,OAAO,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC/D,CAAC;AA8CD,MAAM,cAAc,GAA4B;IAC9C,WAAW,EAAE,CAAC;IACd,qBAAqB,EAAE,CAAC;IACxB,6BAA6B,EAAE,+BAA+B;IAC9D,sBAAsB,EAAE,IAAI;IAC5B,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF;;;;;kEAKkE;AAClE,KAAK,UAAU,kBAAkB,CAAC,IAAU;IAC1C,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAChF,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,OAAO,CAAC,WAAW,KAAK,QAAQ;YAAE,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACpG,CAAC;IACD,OAAO;QACL,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,qBAAqB,EAAE,SAAS,CAAC,qBAAqB;QACtD,6BAA6B,EAAE,SAAS,CAAC,6BAA6B;QACtE,sBAAsB,EAAE,SAAS,CAAC,sBAAsB;QACxD,aAAa,EAAE,SAAS,CAAC,aAAa;QACtC,aAAa;KACd,CAAC;AACJ,CAAC;AAaD,MAAM,OAAO,kBAAkB;IACZ,YAAY,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC/C,IAAI,CAAyC;IACtD,MAAM,CAA0B;IACxC,+DAA+D;IACvD,YAAY,GAAG,KAAK,CAAC;IAC7B;iFAC6E;IACrE,cAAc,GAAG,KAAK,CAAC;IAE/B,YAAY,OAAkC;QAC5C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACrE,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1D,CAAC;IAED;0EACsE;IACtE,QAAQ,CAAC,WAAiC;QACxC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACrD,CAAC;IAED;6CACyC;IACzC,IAAI;QACF,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY;YAAE,KAAK,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;QAC9E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0CAA0C;IAC1C,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;IACjC,CAAC;IAED,qBAAqB;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,qBAAqB,IAAI,CAAC,CAAC;IAChD,CAAC;IAED;;;yEAGqE;IACrE,6BAA6B;QAC3B,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,6BAA6B,CAAC;QAC7D,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,UAAU,CAAC;IACjF,CAAC;IAED;6EACyE;IACzE,sBAAsB;QACpB,OAAO,IAAI,CAAC,MAAM,CAAC,sBAAsB,IAAI,IAAI,CAAC;IACpD,CAAC;IAED,kEAAkE;IAClE,aAAa;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;IACnC,CAAC;IAED;;;;;;;;;OASG;IACH,YAAY;QACV,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,WAAW,CAAC,YAAY,EAAE,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,QAAQ;gBAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpD,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,QAAQ;gBAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,GAAG,CAAC;gBACF,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;gBAC5B,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC;qBACnC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;oBACrB,WAAW;oBACX,8EAA8E;oBAC9E,IAAI,EAAE,WAAW,CAAC,YAAY,EAAE,EAAE,IAAI,MAAM,CAAC,gBAAgB;oBAC7D,qEAAqE;oBACrE,KAAK,EAAE,WAAW,CAAC,cAAc,EAAE,IAAI,MAAM,CAAC,gBAAgB;iBAC/D,CAAC,CAAC;qBACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;gBACxD,KAAK,MAAM,EAAE,WAAW,EAAE,IAAI,OAAO;oBAAE,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC;YAClE,CAAC,QAAQ,IAAI,CAAC,cAAc,EAAE;QAChC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC5B,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,kBAAkB,CAAC,QAAgB;QACjC,MAAM,UAAU,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;QAChD,MAAM,MAAM,GAAG,aAAa,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;QAC9C,MAAM,SAAS,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACvF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;QACjG,OAAO,QAAQ,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;IACxC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;QACD,sEAAsE;QACtE,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/workspace/ui-state.d.ts

@@ -0,0 +1,17 @@
+import type { Home } from '../home/home.ts';
+import type { WorkspaceUiState } from '../contract/index.js';
+export declare function readWorkspaceUiState(path: string, home?: Home): Promise<WorkspaceUiState>;
+/**
+ * Read-modify-write for `~/.cezar/ui-state.json`, written with the same atomic
+ * per-writer tmp+rename `0600` pattern (dir `0700`) as
+ * `mergeWriteWorkspaceConfig` (`atomicWriteJsonSync` — one shared writer, so
+ * the unique-tmp rule cannot drift between the two files). A missing or
+ * corrupt file merges from `{}`. The mutator may mutate its argument in place
+ * or return a replacement. Throws on write failure (e.g. a read-only home) —
+ * degrading is the caller's policy, per house rules.
+ *
+ * Path resolved once, before the `await`, for the same reason as
+ * `mergeWriteWorkspaceConfig`: a `CEZ_HOME` that changes mid-flight must not be
+ * able to send the read and the write to two different files.
+ */
+export declare function mergeWriteWorkspaceUiState(mutator: (state: WorkspaceUiState) => WorkspaceUiState | void, home: Home): Promise<WorkspaceUiState>;

package/dist/workspace/ui-state.js

@@ -0,0 +1,59 @@
+import { HomeStore, readHomeFile } from '../home/store.js';
+/**
+ * `~/.cezar/ui-state.json` — global GUI state, the workspace twin of the
+ * per-repo `.ai/cezar/ui-state.json` (spec 2026-07-20-multi-project-workspace,
+ * Data Model). Same split as `src/ui-state.ts`: this module owns the tolerant
+ * read and the atomic write; the schema and key cap live at the route boundary
+ * (`GET/PUT /api/workspace/ui-state`, step 2.7). The state is an opaque
+ * `.passthrough()`-style bag — cross-project prefs (appearance, notifications)
+ * live here; project-scoped prefs stay in each repo's own file. The obsolete
+ * `importedSkills` key is kept as opaque state and ignored: team skill switches live
+ * only in each project's file (hearsay-tools/cezarion#1494). Prefs that describe the
+ * BROWSER rather than the workspace (sidebar collapse, the last visited location)
+ * stay in that browser's localStorage.
+ */
+/** Read `~/.cezar/ui-state.json` on demand — never cached, never throws.
+ *  Missing, unreadable, malformed, or non-object all degrade to `{}`.
+ *
+ *  Typed by the CONTRACT (`WorkspaceUiState`) for the same reason as its per-repo twin in
+ *  `src/ui-state.ts`: `GET /api/v1/workspace/ui-state` answers this value verbatim, so a loose
+ *  record left the route naming no key. The schema is a `z.looseObject`, so unknown prefs keep
+ *  round-tripping (BACKWARD_COMPATIBILITY.md) — the type only adds the known names. */
+function readWorkspaceUiStateSync(path, home) {
+    try {
+        const parsed = JSON.parse(readHomeFile(path, home));
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function readWorkspaceUiState(path, home) {
+    return readWorkspaceUiStateSync(path, home);
+}
+/**
+ * Read-modify-write for `~/.cezar/ui-state.json`, written with the same atomic
+ * per-writer tmp+rename `0600` pattern (dir `0700`) as
+ * `mergeWriteWorkspaceConfig` (`atomicWriteJsonSync` — one shared writer, so
+ * the unique-tmp rule cannot drift between the two files). A missing or
+ * corrupt file merges from `{}`. The mutator may mutate its argument in place
+ * or return a replacement. Throws on write failure (e.g. a read-only home) —
+ * degrading is the caller's policy, per house rules.
+ *
+ * Path resolved once, before the `await`, for the same reason as
+ * `mergeWriteWorkspaceConfig`: a `CEZ_HOME` that changes mid-flight must not be
+ * able to send the read and the write to two different files.
+ */
+export async function mergeWriteWorkspaceUiState(mutator, home) {
+    const store = new HomeStore(home);
+    return store.transaction(() => {
+        const path = home.workspaceUiState;
+        const current = readWorkspaceUiStateSync(path, home);
+        const next = mutator(current) ?? current;
+        store.writeJson(path, next);
+        return next;
+    }, [home.workspaceUiState]);
+}
+//# sourceMappingURL=ui-state.js.map

package/dist/workspace/ui-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-state.js","sourceRoot":"","sources":["../../src/workspace/ui-state.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAG3D;;;;;;;;;;;;GAYG;AAEH;;;;;;uFAMuF;AACvF,SAAS,wBAAwB,CAAC,IAAY,EAAE,IAAW;IACzD,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC7D,OAAO,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAC5E,CAAC,CAAE,MAA2B;YAC9B,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAY,EAAE,IAAW;IAClE,OAAO,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,OAA6D,EAC7D,IAAU;IAEV,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC;QACnC,MAAM,OAAO,GAAG,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC;QACzC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAC9B,CAAC"}

package/dist/workspace/webhooks.d.ts

@@ -0,0 +1,40 @@
+import type { AgentWebhook, CreateProjectWebhookInput, ProjectWebhook, ProjectWebhookInput, UpdateProjectWebhookInput } from '../contract/index.js';
+import type { StoredProjectWebhook, WorkspaceProject } from './config.ts';
+/**
+ * A project's webhooks (hearsay-tools/cezarion#1576), read the same way whether the registry
+ * entry holds the `webhooks` list or the single `webhook` key a project stored before it.
+ *
+ * Upgrade: a `webhook` key with no `webhooks` list reads as one webhook named "Task webhook",
+ * task notifications on, closed to agents — exactly what it did before. The first write through
+ * `setProjectWebhooks` stores the list and deletes the old key, so the two never disagree.
+ */
+/** The id and name the pre-#1576 single webhook reads as. */
+export declare const LEGACY_WEBHOOK_ID = "task-webhook";
+export declare const LEGACY_WEBHOOK_NAME = "Task webhook";
+export declare function projectWebhooks(entry: WorkspaceProject | undefined): StoredProjectWebhook[];
+/** The webhooks that receive task notifications from runs with `notify` on. */
+export declare function taskWebhooks(entry: WorkspaceProject | undefined): StoredProjectWebhook[];
+/** Replace the list on a registry entry being written. An empty list removes both keys. */
+export declare function setProjectWebhooks(entry: WorkspaceProject, webhooks: StoredProjectWebhook[]): void;
+/** A new id, unused in `existing`. */
+export declare function newWebhookId(existing: readonly StoredProjectWebhook[]): string;
+/** Names are unique per project, ignoring case, so an agent can address a webhook by name. */
+export declare function nameTaken(webhooks: readonly StoredProjectWebhook[], name: string, exceptId?: string): boolean;
+/** The webhook an agent names, by id or by name (case-insensitive), when it is exposed to agents.
+ *  A webhook closed to agents resolves to nothing, exactly like an unknown one. */
+export declare function agentWebhook(entry: WorkspaceProject | undefined, ref: string): StoredProjectWebhook | undefined;
+/** What an agent may know about the webhooks exposed to it: never the URL or the token. */
+export declare function agentWebhooks(entry: WorkspaceProject | undefined): AgentWebhook[];
+/** One webhook as it leaves the server: the token is swapped for `tokenSet`. */
+export declare function redactWebhook(webhook: StoredProjectWebhook): ProjectWebhook;
+/** A webhook built from a create body. An omitted `tasks` or `agent` is off. */
+export declare function createdWebhook(existing: readonly StoredProjectWebhook[], input: CreateProjectWebhookInput): StoredProjectWebhook;
+/** Apply an edit body: each key only when named. The token is write-only, so an omitted token
+ *  keeps the stored one and `''` clears it; `''` clears the description the same way. */
+export declare function editedWebhook(current: StoredProjectWebhook, input: UpdateProjectWebhookInput): StoredProjectWebhook;
+/**
+ * The pre-#1576 `PATCH /projects/:id { webhook }` body, applied to the first webhook with task
+ * notifications on: `null` removes it, a value edits it, or adds "Task webhook" when there is
+ * none. An omitted `token` or `triggers` keeps the stored value, as it always did.
+ */
+export declare function applyTaskWebhookInput(entry: WorkspaceProject, input: ProjectWebhookInput | null): void;

package/dist/workspace/webhooks.js

@@ -0,0 +1,146 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * A project's webhooks (hearsay-tools/cezarion#1576), read the same way whether the registry
+ * entry holds the `webhooks` list or the single `webhook` key a project stored before it.
+ *
+ * Upgrade: a `webhook` key with no `webhooks` list reads as one webhook named "Task webhook",
+ * task notifications on, closed to agents — exactly what it did before. The first write through
+ * `setProjectWebhooks` stores the list and deletes the old key, so the two never disagree.
+ */
+/** The id and name the pre-#1576 single webhook reads as. */
+export const LEGACY_WEBHOOK_ID = 'task-webhook';
+export const LEGACY_WEBHOOK_NAME = 'Task webhook';
+export function projectWebhooks(entry) {
+    if (!entry)
+        return [];
+    if (entry.webhooks)
+        return entry.webhooks;
+    const legacy = entry.webhook;
+    if (!legacy)
+        return [];
+    return [{
+            id: LEGACY_WEBHOOK_ID,
+            name: LEGACY_WEBHOOK_NAME,
+            url: legacy.url,
+            ...(legacy.token ? { token: legacy.token } : {}),
+            tasks: true,
+            ...(legacy.triggers === undefined ? {} : { triggers: legacy.triggers }),
+            agent: false,
+        }];
+}
+/** The webhooks that receive task notifications from runs with `notify` on. */
+export function taskWebhooks(entry) {
+    return projectWebhooks(entry).filter((webhook) => webhook.tasks);
+}
+/** Replace the list on a registry entry being written. An empty list removes both keys. */
+export function setProjectWebhooks(entry, webhooks) {
+    delete entry.webhook;
+    if (webhooks.length === 0)
+        delete entry.webhooks;
+    else
+        entry.webhooks = webhooks;
+}
+/** A new id, unused in `existing`. */
+export function newWebhookId(existing) {
+    for (;;) {
+        const id = randomBytes(4).toString('hex');
+        if (!existing.some((webhook) => webhook.id === id))
+            return id;
+    }
+}
+/** Names are unique per project, ignoring case, so an agent can address a webhook by name. */
+export function nameTaken(webhooks, name, exceptId) {
+    const folded = name.trim().toLocaleLowerCase();
+    return webhooks.some((webhook) => webhook.id !== exceptId && webhook.name.toLocaleLowerCase() === folded);
+}
+/** The webhook an agent names, by id or by name (case-insensitive), when it is exposed to agents.
+ *  A webhook closed to agents resolves to nothing, exactly like an unknown one. */
+export function agentWebhook(entry, ref) {
+    const exposed = projectWebhooks(entry).filter((webhook) => webhook.agent);
+    const folded = ref.trim().toLocaleLowerCase();
+    return exposed.find((webhook) => webhook.id === ref) ?? exposed.find((webhook) => webhook.name.toLocaleLowerCase() === folded);
+}
+/** What an agent may know about the webhooks exposed to it: never the URL or the token. */
+export function agentWebhooks(entry) {
+    return projectWebhooks(entry)
+        .filter((webhook) => webhook.agent)
+        .map(({ id, name, description }) => ({ id, name, ...(description ? { description } : {}) }));
+}
+/** One webhook as it leaves the server: the token is swapped for `tokenSet`. */
+export function redactWebhook(webhook) {
+    return {
+        id: webhook.id,
+        name: webhook.name,
+        ...(webhook.description ? { description: webhook.description } : {}),
+        url: webhook.url,
+        tokenSet: Boolean(webhook.token),
+        tasks: webhook.tasks,
+        ...(webhook.triggers === undefined ? {} : { triggers: webhook.triggers }),
+        agent: webhook.agent,
+    };
+}
+/** A webhook built from a create body. An omitted `tasks` or `agent` is off. */
+export function createdWebhook(existing, input) {
+    return {
+        id: newWebhookId(existing),
+        name: input.name,
+        ...(input.description ? { description: input.description } : {}),
+        url: input.url,
+        ...(input.token ? { token: input.token } : {}),
+        tasks: input.tasks ?? false,
+        ...(input.triggers === undefined ? {} : { triggers: input.triggers }),
+        agent: input.agent ?? false,
+    };
+}
+/** Apply an edit body: each key only when named. The token is write-only, so an omitted token
+ *  keeps the stored one and `''` clears it; `''` clears the description the same way. */
+export function editedWebhook(current, input) {
+    const next = { ...current };
+    if (input.name !== undefined)
+        next.name = input.name;
+    if (input.description !== undefined) {
+        if (input.description)
+            next.description = input.description;
+        else
+            delete next.description;
+    }
+    if (input.url !== undefined)
+        next.url = input.url;
+    if (input.token !== undefined) {
+        if (input.token)
+            next.token = input.token;
+        else
+            delete next.token;
+    }
+    if (input.tasks !== undefined)
+        next.tasks = input.tasks;
+    if (input.triggers !== undefined)
+        next.triggers = input.triggers;
+    if (input.agent !== undefined)
+        next.agent = input.agent;
+    return next;
+}
+/**
+ * The pre-#1576 `PATCH /projects/:id { webhook }` body, applied to the first webhook with task
+ * notifications on: `null` removes it, a value edits it, or adds "Task webhook" when there is
+ * none. An omitted `token` or `triggers` keeps the stored value, as it always did.
+ */
+export function applyTaskWebhookInput(entry, input) {
+    const webhooks = [...projectWebhooks(entry)];
+    const index = webhooks.findIndex((webhook) => webhook.tasks);
+    if (input === null) {
+        if (index >= 0)
+            webhooks.splice(index, 1);
+    }
+    else if (index >= 0) {
+        webhooks[index] = editedWebhook(webhooks[index], input);
+    }
+    else {
+        let name = LEGACY_WEBHOOK_NAME;
+        for (let n = 2; nameTaken(webhooks, name); n += 1)
+            name = `${LEGACY_WEBHOOK_NAME} ${n}`;
+        webhooks.push(createdWebhook(webhooks, { ...input, name, tasks: true }));
+    }
+    setProjectWebhooks(entry, webhooks);
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/workspace/webhooks.js.map

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

package/dist/worktree-manifest.d.ts

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+/**
+ * The record of every path cezar wrote into a task worktree (hearsay-tools/cezarion#1814), for
+ * every module that writes there (`.ai/ast-grep/rules/worktree-write-outside-manifest.yml` names
+ * them). It lives in the worktree's private git dir, so it dies with the worktree and nothing in
+ * the tree (a tool, a diff, autosave) sees it. A writer replaces or removes a path only while the
+ * manifest lists it for that writer and the path still is what cezar left there, so a file the
+ * agent changed or added stays. A missing or unreadable manifest lists nothing: every file stays.
+ */
+export declare const MANIFEST_FILE = "cezar-manifest.json";
+/** The skills-only record before hearsay-tools/cezarion#1814: imported for paths the manifest
+ *  does not list, then removed once a manifest holding them is saved. */
+export declare const LEGACY_SKILLS_MANIFEST_FILE = "cezar-skills.json";
+export type ManifestWriter = 'skills' | 'seed';
+export type EntryKind = 'link' | 'copy' | 'generated' | 'team-copy' | 'ignore-file' | 'file';
+/** Unknown keys stay, so a rewrite keeps what a newer cezar of the same version added. */
+declare const entrySchema: z.ZodObject<{
+    path: z.ZodString;
+    writer: z.ZodString;
+    kind: z.ZodString;
+    skill: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    identity: z.ZodString;
+    alternate: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type ManifestEntry = z.infer<typeof entrySchema>;
+interface Loaded {
+    /** Top-level keys this cezar does not know, written back unchanged. */
+    extra: Record<string, unknown>;
+    skillsExtra: Record<string, unknown>;
+    entries: ManifestEntry[];
+    roots: string[];
+    /** A legacy record was imported: it is removed after the manifest that holds it is saved. */
+    legacy: boolean;
+}
+/** What is at `path` now, comparable with a recorded identity; null when nothing is there. */
+export declare function identityOf(path: string): Promise<string | null>;
+/** The identity `identityOf` reads from a regular file holding `content`. */
+export declare function fileIdentity(content: string | Buffer, executable?: boolean): string;
+/** The identity a copy of the file at `source` reads as: its bytes and executable bit, through a link. */
+export declare function copyIdentity(source: string): Promise<string>;
+/** Thrown when the platform refuses a link, so a writer can fall back to a copy. */
+export declare class LinkRefused extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * What a write leaves at a path. `staged` is a path the caller built in `stagingDir()`; every
+ * other kind is built here, so a writer imports no file-changing function of its own.
+ */
+export type EntryContent = {
+    type: 'link';
+    target: string;
+    linkType?: 'dir' | 'file' | 'junction';
+} | {
+    type: 'file';
+    text: string;
+} | {
+    type: 'file';
+    copyOf: string;
+} | {
+    type: 'dir';
+    files: ReadonlyArray<{
+        name: string;
+        text: string;
+    } | {
+        name: string;
+        copyOf: string;
+    } | {
+        name: string;
+        linkTo: string;
+    }>;
+} | {
+    type: 'copy';
+    from: string;
+} | {
+    type: 'staged';
+    path: string;
+};
+export interface EntryMeta {
+    kind: EntryKind;
+    skill?: string;
+    source?: string;
+}
+/** The steps of one write, in order. Tests stop a pass at one, as a crash would. */
+export type WriteBoundary = 'staged' | 'pending' | 'cleared' | 'placed' | 'removed';
+export interface WorktreeFilesOptions {
+    /** Injected in tests to exercise the copy fallback. */
+    symlink?: (target: string, path: string, type?: 'dir' | 'file' | 'junction') => Promise<void>;
+    /** Tests only: runs at each boundary of a write; a throw ends the pass there. */
+    faults?: (boundary: WriteBoundary, path: string) => void | Promise<void>;
+}
+/**
+ * Who may write a path, for one writer. `ours`: listed, and still what cezar left. `free`:
+ * nothing there. `theirs`: changed since, or never listed; the writer drops any entry and never
+ * touches it. `kept`: never touched and never dropped (an interrupted write that no longer matches,
+ * a kind or identity this cezar cannot check, another writer's path). `outside`: its parent dir
+ * leads out of the worktree.
+ */
+export interface PathState {
+    owner: 'ours' | 'free' | 'theirs' | 'kept' | 'outside';
+    current: string | null;
+    entry: ManifestEntry | undefined;
+}
+/**
+ * One writer's view of a worktree's manifest for one pass. A write runs stage, pending, clear,
+ * place, record: a crash leaves the old copy, nothing, or the new copy, each of which the next
+ * pass reads as cezar's and repairs.
+ */
+export declare class WorktreeFiles {
+    readonly worktree: string;
+    private readonly root;
+    private readonly gitDir;
+    private readonly writer;
+    private readonly loaded;
+    private readonly options;
+    private readonly byPath;
+    private readonly staged;
+    private swept;
+    private legacy;
+    roots: string[];
+    constructor(worktree: string, root: string, gitDir: string, writer: ManifestWriter, loaded: Loaded, options: WorktreeFilesOptions);
+    /** This writer's entries. */
+    entries(): ManifestEntry[];
+    entry(path: string): ManifestEntry | undefined;
+    present(path: string): Promise<boolean>;
+    inspect(path: string): Promise<PathState>;
+    /**
+     * An imported `tree:` identity, checked in its older encoding, which has no lengths: one tree can
+     * read the same as another. A match proves the path unchanged only for a single file, or for a
+     * dir holding only `SKILL.md` where cezar wrote just that. Then the entry is recorded again as
+     * `current`. Any other match is kept: it may be cezar's copy or the agent's edit. Null when
+     * nothing matched, so the path has changed.
+     */
+    private checkLegacy;
+    /** A new dir in the private git dir to build an entry in; removed when the pass ends. */
+    stagingDir(): Promise<string>;
+    /**
+     * Write `content` at `path`, which must be free or cezar's. Returns the identity it left. The
+     * pending entry is saved before the path changes; a file replaces a file in one rename. Returns
+     * null when the agent wrote at the path while the entry was staged: the path stays the agent's,
+     * with no entry.
+     */
+    put(path: string, content: EntryContent, meta: EntryMeta): Promise<string | null>;
+    /** Record what is already at `path` as cezar's: an interrupted write that finished. */
+    record(path: string, meta: EntryMeta, identity: string): void;
+    /** Remove `path` while it is cezar's. The caller's next `save()` drops the entry. */
+    remove(path: string): Promise<boolean>;
+    /** Drop this writer's entry for `path`; nothing at the path changes. */
+    forget(path: string): void;
+    /** Replace the manifest in one step: a crash leaves the old one or the new one, never half. */
+    save(): Promise<void>;
+    close(): Promise<void>;
+    /** The entry that replaces this writer's entry for `path`, if any: it keeps that entry's unknown fields. */
+    private newEntry;
+    private fault;
+    private link;
+    private build;
+}
+/**
+ * Run `pass` with `writer`'s view of the worktree's manifest. `fallback` when the worktree has no
+ * private git dir, or a newer cezar wrote a manifest version this one cannot read: then this cezar
+ * writes nothing there and leaves the file alone.
+ */
+export declare function withWorktreeFiles<T>(worktree: string, writer: ManifestWriter, options: WorktreeFilesOptions, fallback: T, pass: (files: WorktreeFiles) => Promise<T>): Promise<T>;
+export {};