@zq-silk/yui 0.0.0

package/dist/storage/taskStore.js

@@ -0,0 +1,1032 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { validateConfiguredAgent } from "../agent/agent.js";
+import { reconciliationIntervalMilliseconds } from "../config/yuiConfig.js";
+import { validateInputRequest } from "../input/inputRequest.js";
+import { validateRoleSessionSet } from "../executor/agentExecutor.js";
+import { validateTaskMessage } from "../message/message.js";
+import { validateAgentRun } from "../run/agentRun.js";
+import { validateRepository } from "../repository/repository.js";
+import { validateGlobalRole, validateTaskRole } from "../role/role.js";
+import { validateTask } from "../task/task.js";
+import { validateRoleWorkspace } from "../worktree/roleWorkspace.js";
+import { writeTextFileAtomically } from "./durableFile.js";
+import { requireStorageSchema } from "./storageSchema.js";
+export const STORAGE_STATE_FILE = "state.json";
+const STORAGE_LOCK_DIRECTORY = ".state.lock";
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_RETRY_MS = 10;
+export const COMPLETION_SHELLS = ["bash", "zsh", "fish"];
+export class FileTaskStore {
+    rootDir;
+    #transaction = null;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+        requireStorageSchema(rootDir);
+    }
+    rootDirectory() { return this.rootDir; }
+    transaction(execute) {
+        if (this.#transaction !== null)
+            return synchronousResult(execute(this));
+        return this.#withWriteLock(() => {
+            const state = this.#readState();
+            this.#transaction = { state, baseRevision: state.revision, dirty: false };
+            try {
+                const result = synchronousResult(execute(this));
+                if (this.#transaction.dirty)
+                    this.#commit(state, this.#transaction.baseRevision);
+                return result;
+            }
+            finally {
+                this.#transaction = null;
+            }
+        });
+    }
+    getConfig() { return clone(this.#state().config); }
+    saveConfig(config) {
+        const stored = versioned(config, 1, "Yui config");
+        validateYuiConfig(stored);
+        this.#mutate((state) => { state.config = stored; });
+    }
+    saveConfiguredAgent(agent) {
+        const stored = identified(agent, 2, "id", agent.id, "Configured Agent");
+        validateConfiguredAgent(stored);
+        this.#mutate((state) => { state.configuredAgents[stored.id] = stored; });
+    }
+    createConfiguredAgentIfAbsent(agent) {
+        return this.transaction((store) => {
+            if (store.getConfiguredAgent(agent.id) !== null)
+                return null;
+            store.saveConfiguredAgent(agent);
+            return clone(agent);
+        });
+    }
+    updateConfiguredAgent(id, patch, now) {
+        return this.transaction((store) => {
+            const existing = store.getConfiguredAgent(id);
+            if (existing === null)
+                return null;
+            const candidate = versioned({
+                ...existing,
+                ...clone(patch),
+                updatedAt: now.toISOString()
+            }, 2, "Configured Agent");
+            const unchanged = isDeepStrictEqual({ ...existing, updatedAt: candidate.updatedAt }, candidate);
+            if (unchanged)
+                return { status: "unchanged", agent: existing };
+            store.saveConfiguredAgent(candidate);
+            return { status: "updated", agent: candidate };
+        });
+    }
+    listConfiguredAgents() { return values(this.#state().configuredAgents, "id"); }
+    getConfiguredAgent(id) { return optional(this.#state().configuredAgents[id]); }
+    removeConfiguredAgent(id) {
+        return this.#remove((state) => state.configuredAgents, id);
+    }
+    nextRepositoryId() {
+        return this.#nextGlobalId("repository", (state) => Object.keys(state.repositories));
+    }
+    saveRepository(repository) {
+        const stored = identified(repository, 1, "id", repository.id, "Repository");
+        validateRepository(stored);
+        this.#mutate((state) => { state.repositories[stored.id] = stored; });
+    }
+    createRepositoryIfAbsent(repository) {
+        return this.transaction((store) => {
+            if (store.getRepository(repository.id) !== null)
+                return null;
+            if (store.listRepositories().some((entry) => (entry.name === repository.name || entry.path === repository.path)))
+                return null;
+            store.saveRepository(repository);
+            return clone(repository);
+        });
+    }
+    listRepositories() { return values(this.#state().repositories, "id"); }
+    getRepository(id) { return optional(this.#state().repositories[id]); }
+    removeRepository(id) {
+        return this.transaction((store) => {
+            if (store.listTasks().some((task) => task.repositoryId === id)) {
+                throw new StorageRecordError(`Repository is still used by a Task: ${id}`);
+            }
+            return this.#remove((state) => state.repositories, id);
+        });
+    }
+    saveGlobalRole(role) {
+        const stored = identified(role, 2, "name", role.name, "Global Role");
+        validateGlobalRole(stored);
+        const sessions = this.getGlobalRoleSessionSet(stored.name);
+        if (sessions !== null)
+            assertSessionsMatchRole(sessions, stored);
+        this.#mutate((state) => { state.globalRoles[stored.name] = stored; });
+    }
+    saveGlobalRoleWithSessionSet(role, sessions) {
+        const storedRole = identified(role, 2, "name", role.name, "Global Role");
+        validateGlobalRole(storedRole);
+        const storedSessions = sessions === null ? null : globalSessions(sessions);
+        if (storedSessions !== null)
+            assertSessionsMatchRole(storedSessions, storedRole);
+        this.transaction(() => {
+            this.#mutate((state) => {
+                state.globalRoles[storedRole.name] = storedRole;
+                if (storedSessions === null)
+                    delete state.globalRoleSessionSets[storedRole.name];
+                else
+                    state.globalRoleSessionSets[storedRole.name] = storedSessions;
+            });
+        });
+    }
+    createGlobalRoleIfAbsent(role) {
+        return this.transaction((store) => {
+            if (store.getGlobalRole(role.name) !== null)
+                return null;
+            store.saveGlobalRole(role);
+            return clone(role);
+        });
+    }
+    listGlobalRoles() { return values(this.#state().globalRoles, "name"); }
+    getGlobalRole(name) { return optional(this.#state().globalRoles[name]); }
+    removeGlobalRole(name) {
+        return this.transaction(() => {
+            const removed = this.#remove((state) => state.globalRoles, name);
+            this.#mutate((state) => { delete state.globalRoleSessionSets[name]; });
+            return removed;
+        });
+    }
+    getGlobalRoleSessionSet(name) {
+        return optional(this.#state().globalRoleSessionSets[name]);
+    }
+    listGlobalRoleSessionSets() {
+        return values(this.#state().globalRoleSessionSets, (set) => set.owner.roleName);
+    }
+    saveGlobalRoleSessionSet(sessions) {
+        const stored = globalSessions(sessions);
+        const role = this.getGlobalRole(stored.owner.roleName);
+        if (role === null)
+            throw new StorageRecordError(`Global Role not found: ${stored.owner.roleName}`);
+        assertSessionsMatchRole(stored, role);
+        this.#mutate((state) => { state.globalRoleSessionSets[stored.owner.roleName] = stored; });
+    }
+    nextTaskId() { return this.#nextGlobalId("task", (state) => Object.keys(state.tasks)); }
+    saveTask(task) {
+        const stored = validateTask(identified(task, 1, "id", task.id, "Task"));
+        this.#mutate((state) => {
+            if (stored.repositoryId !== undefined && state.repositories[stored.repositoryId] === undefined) {
+                throw new StorageRecordError(`Task Repository not found: ${stored.repositoryId}`);
+            }
+            const aggregate = state.tasks[stored.id] ?? emptyStoredTask(stored);
+            aggregate.task = stored;
+            state.tasks[stored.id] = aggregate;
+        });
+    }
+    listTasks() { return values(this.#state().tasks, (aggregate) => aggregate.task.id).map((entry) => clone(entry.task)); }
+    getTask(id) { return optional(this.#state().tasks[id]?.task); }
+    getTaskBrief(taskId) {
+        return optional(this.#state().tasks[taskId]?.brief ?? undefined);
+    }
+    saveTaskBrief(taskId, brief) {
+        const stored = storedTaskBrief(brief);
+        this.#requireTaskForWrite(taskId);
+        this.#mutate((state) => { state.tasks[taskId].brief = stored; });
+    }
+    clearTaskBrief(taskId) {
+        this.#requireTaskForWrite(taskId);
+        this.#mutate((state) => { state.tasks[taskId].brief = null; });
+    }
+    saveRole(taskId, role) {
+        const aggregate = this.#requireTaskForWrite(taskId);
+        const stored = identified(role, 2, "name", role.name, "Task Role");
+        if (stored.taskId !== taskId)
+            throw new StorageRecordError(`Task Role belongs to another Task: ${stored.taskId}`);
+        validateTaskRole(stored);
+        const sessions = this.getRoleSessionSet(taskId, stored.name);
+        if (sessions !== null)
+            assertSessionsMatchRole(sessions, stored);
+        this.#mutate((state) => { state.tasks[aggregate.task.id].roles[stored.name] = stored; });
+    }
+    listRoles(taskId) { return values(this.#requireTask(taskId).roles, "name"); }
+    getRole(taskId, name) { return optional(this.#state().tasks[taskId]?.roles[name]); }
+    saveTaskRoleWithSessionSet(role, sessions) {
+        const storedRole = identified(role, 2, "name", role.name, "Task Role");
+        validateTaskRole(storedRole);
+        const storedSessions = taskSessions(sessions);
+        assertSessionsMatchRole(storedSessions, storedRole);
+        this.transaction(() => {
+            this.#requireTaskForWrite(storedRole.taskId);
+            this.#mutate((state) => {
+                state.tasks[storedRole.taskId].roles[storedRole.name] = storedRole;
+                state.tasks[storedRole.taskId].roleSessionSets[storedRole.name] = storedSessions;
+            });
+        });
+    }
+    removeTaskRole(taskId, name) {
+        return this.transaction(() => {
+            const aggregate = this.#requireTask(taskId);
+            if (aggregate.roleWorkspaces[name] !== undefined) {
+                throw new StorageRecordError(`Task Role workspace must be cleaned before removing the Role: ${taskId}/${name}`);
+            }
+            const removed = this.#remove(() => aggregate.roles, name);
+            this.#mutate(() => { delete aggregate.roleSessionSets[name]; delete aggregate.activeRuns[name]; });
+            return removed;
+        });
+    }
+    saveRoleWorkspace(taskId, workspace) {
+        const aggregate = this.#requireTaskForWrite(taskId);
+        const stored = clone(workspace);
+        validateRoleWorkspace(stored);
+        if (stored.taskId !== taskId) {
+            throw new StorageRecordError(`RoleWorkspace belongs to another Task: ${stored.taskId}`);
+        }
+        if (aggregate.roles[stored.roleName] === undefined) {
+            throw new StorageRecordError(`Task Role not found: ${taskId}/${stored.roleName}`);
+        }
+        if (aggregate.task.repositoryId !== stored.repositoryId) {
+            throw new StorageRecordError(`RoleWorkspace Repository does not match Task: ${taskId}/${stored.roleName}`);
+        }
+        this.#mutate((state) => {
+            state.tasks[taskId].roleWorkspaces[stored.roleName] = stored;
+        });
+    }
+    listRoleWorkspaces(taskId) {
+        return values(this.#requireTask(taskId).roleWorkspaces, "roleName");
+    }
+    getRoleWorkspace(taskId, roleName) {
+        return optional(this.#state().tasks[taskId]?.roleWorkspaces[roleName]);
+    }
+    removeRoleWorkspace(taskId, roleName) {
+        this.#requireTaskForWrite(taskId);
+        return this.#remove((state) => state.tasks[taskId].roleWorkspaces, roleName);
+    }
+    getRoleSessionSet(taskId, roleName) {
+        return optional(this.#state().tasks[taskId]?.roleSessionSets[roleName]);
+    }
+    getTaskRoleSessionSet(taskId, roleName) {
+        return this.getRoleSessionSet(taskId, roleName);
+    }
+    listRoleSessionSets(taskId) {
+        return values(this.#requireTask(taskId).roleSessionSets, (set) => set.owner.roleName);
+    }
+    saveRoleSessionSet(sessions) {
+        const stored = taskSessions(sessions);
+        const taskId = stored.owner.taskId;
+        this.#requireTaskForWrite(taskId);
+        const role = this.getRole(taskId, stored.owner.roleName);
+        if (role === null)
+            throw new StorageRecordError(`Task Role not found: ${taskId}/${stored.owner.roleName}`);
+        assertSessionsMatchRole(stored, role);
+        this.#mutate((state) => { state.tasks[taskId].roleSessionSets[stored.owner.roleName] = stored; });
+    }
+    saveTaskRoleSessionSet(sessions) { this.saveRoleSessionSet(sessions); }
+    getRoleSession(taskId, roleName) {
+        const set = this.getRoleSessionSet(taskId, roleName);
+        return set === null ? null : optional(set.sessions[set.activeAgentId]);
+    }
+    nextWorkItemId(_taskId) { return this.#nextGlobalId("work-item", (state) => allKeys(state, "workItems")); }
+    getWorkItem(taskId, id) { return optional(this.#state().tasks[taskId]?.workItems[id]); }
+    findWorkItem(id) { return findUnique(this.#state(), "workItems", id, "Work item"); }
+    listWorkItems(taskId) { return values(this.#requireTask(taskId).workItems, "id"); }
+    saveWorkItem(taskId, item) {
+        const stored = identified(item, 1, "id", item.id, "Work item");
+        if (stored.taskId !== taskId)
+            throw new StorageRecordError(`Work item belongs to another Task: ${stored.taskId}`);
+        this.#requireTaskForWrite(taskId);
+        this.#mutate((state) => { state.tasks[taskId].workItems[stored.id] = stored; });
+    }
+    nextAgentRunId(_taskId) { return this.#nextGlobalId("agent-run", (state) => allKeys(state, "agentRuns")); }
+    getAgentRun(taskId, id) { return optional(this.#state().tasks[taskId]?.agentRuns[id]); }
+    findAgentRun(id) { return findUnique(this.#state(), "agentRuns", id, "Agent run"); }
+    listAgentRuns(taskId) { return values(this.#requireTask(taskId).agentRuns, "id"); }
+    saveAgentRun(run) {
+        const stored = identified(run, 1, "id", run.id, "Agent run");
+        validateAgentRun(stored);
+        this.#requireTaskForWrite(stored.taskId);
+        this.#mutate((state) => { state.tasks[stored.taskId].agentRuns[stored.id] = stored; });
+    }
+    getActiveAgentRun(taskId, roleName) {
+        const aggregate = this.#state().tasks[taskId];
+        const pointer = aggregate?.activeRuns[roleName];
+        if (aggregate === undefined || pointer === undefined)
+            return null;
+        const run = aggregate.agentRuns[pointer.runId];
+        if (run === undefined)
+            throw new StorageRecordError(`Active Agent run pointer is dangling: ${taskId}/${roleName}`);
+        return clone(run);
+    }
+    saveActiveAgentRun(run) {
+        if (run.status !== "active")
+            throw new StorageRecordError(`Active Agent run must have active status: ${run.id}`);
+        this.transaction((store) => {
+            const current = store.getActiveAgentRun(run.taskId, run.roleName);
+            if (current !== null && current.id !== run.id) {
+                throw new StorageRecordError(`Role already has an active Agent run: ${run.taskId}/${run.roleName}`);
+            }
+            store.saveAgentRun(run);
+            this.#mutate((state) => {
+                state.tasks[run.taskId].activeRuns[run.roleName] = { schemaVersion: 1, runId: run.id };
+            });
+        });
+    }
+    clearActiveAgentRun(taskId, roleName) {
+        this.#mutate((state) => { const task = state.tasks[taskId]; if (task !== undefined)
+            delete task.activeRuns[roleName]; });
+    }
+    nextMessageId(_taskId) { return this.#nextGlobalId("message", (state) => allKeys(state, "messages")); }
+    saveMessage(taskId, message) {
+        validateTaskMessage(message);
+        this.#saveTaskRecord(taskId, "messages", message, "Message");
+    }
+    listMessages(taskId) { return values(this.#requireTask(taskId).messages, "id"); }
+    nextInputRequestId(_taskId) {
+        return this.#nextGlobalId("input", (state) => allKeys(state, "inputRequests"));
+    }
+    saveInputRequest(taskId, request) {
+        const stored = validateInputRequest(request);
+        if (stored.taskId !== taskId) {
+            throw new StorageRecordError(`Input request belongs to another Task: ${stored.taskId}`);
+        }
+        this.#mutate((state) => {
+            const aggregate = requireTaskFromState(state, taskId);
+            const owner = taskRecordOwner(state, "inputRequests", stored.id);
+            if (owner !== null && owner !== taskId) {
+                throw new StorageRecordError(`Input request already exists in another Task: ${stored.id}`);
+            }
+            const existing = aggregate.inputRequests[stored.id];
+            if (existing === undefined && stored.status !== "open") {
+                throw new StorageRecordError(`Input request must start open: ${stored.id}`);
+            }
+            if (existing !== undefined && !isValidInputRequestTransition(existing, stored)) {
+                throw new StorageRecordError(`Input request cannot be overwritten: ${stored.id}`);
+            }
+            aggregate.inputRequests[stored.id] = stored;
+        });
+    }
+    getInputRequest(taskId, requestId) {
+        return optional(this.#state().tasks[taskId]?.inputRequests[requestId]);
+    }
+    findInputRequest(requestId) {
+        return findUnique(this.#state(), "inputRequests", requestId, "Input request");
+    }
+    listInputRequests(taskId) {
+        return values(this.#requireTask(taskId).inputRequests, "id");
+    }
+    listAllInputRequests() {
+        return Object.values(this.#state().tasks)
+            .flatMap((aggregate) => Object.values(aggregate.inputRequests).map(clone))
+            .sort((left, right) => numericCompare(left.id, right.id));
+    }
+    nextDecisionId(_taskId) {
+        return this.#nextGlobalId("decision", (state) => allKeys(state, "decisions"));
+    }
+    saveDecision(taskId, decision) {
+        const stored = storedDecision(decision);
+        if (stored.taskId !== taskId) {
+            throw new StorageRecordError(`Decision belongs to another Task: ${stored.taskId}`);
+        }
+        this.#mutate((state) => {
+            const aggregate = requireTaskFromState(state, taskId);
+            const owner = taskRecordOwner(state, "decisions", stored.id);
+            if (owner !== null && owner !== taskId) {
+                throw new StorageRecordError(`Decision already exists in another Task: ${stored.id}`);
+            }
+            const existing = aggregate.decisions[stored.id];
+            if (existing === undefined && stored.status !== "active") {
+                throw new StorageRecordError(`Decision must start active: ${stored.id}`);
+            }
+            if (existing !== undefined && !isValidDecisionSupersession(existing, stored)) {
+                throw new StorageRecordError(`Decision cannot be overwritten: ${stored.id}`);
+            }
+            aggregate.decisions[stored.id] = stored;
+        });
+    }
+    listDecisions(taskId) {
+        return values(this.#requireTask(taskId).decisions, "id");
+    }
+    getDecision(taskId, decisionId) {
+        return this.#requireTask(taskId).decisions[decisionId] ?? null;
+    }
+    nextMilestoneId(_taskId) {
+        return this.#nextGlobalId("milestone", (state) => allKeys(state, "milestones"));
+    }
+    saveMilestone(taskId, milestone) {
+        const stored = storedMilestone(milestone);
+        if (stored.taskId !== taskId) {
+            throw new StorageRecordError(`Milestone belongs to another Task: ${stored.taskId}`);
+        }
+        this.#mutate((state) => {
+            const aggregate = requireTaskFromState(state, taskId);
+            if (taskRecordOwner(state, "milestones", stored.id) !== null) {
+                throw new StorageRecordError(`Milestone already exists: ${stored.id}`);
+            }
+            aggregate.milestones[stored.id] = stored;
+        });
+    }
+    listMilestones(taskId) {
+        return values(this.#requireTask(taskId).milestones, "id");
+    }
+    getMilestone(taskId, milestoneId) {
+        return this.#requireTask(taskId).milestones[milestoneId] ?? null;
+    }
+    nextEventId(_taskId) { return this.#nextGlobalId("event", (state) => allKeys(state, "events")); }
+    saveEvent(taskId, event) {
+        const stored = storedTaskEvent(event);
+        this.#mutate((state) => {
+            const aggregate = requireTaskFromState(state, taskId);
+            if (taskRecordOwner(state, "events", stored.id) !== null) {
+                throw new StorageRecordError(`Task event already exists: ${stored.id}`);
+            }
+            aggregate.events[stored.id] = stored;
+        });
+    }
+    listEvents(taskId) { return values(this.#requireTask(taskId).events, "id"); }
+    getPendingWakeup(taskId) { return optional(this.#state().tasks[taskId]?.pendingWakeup ?? undefined); }
+    listPendingWakeups() {
+        return Object.values(this.#state().tasks).flatMap((task) => task.pendingWakeup === null ? [] : [clone(task.pendingWakeup)]).sort((a, b) => numericCompare(a.taskId, b.taskId));
+    }
+    savePendingWakeup(value) { this.#saveSingleton(value.taskId, "pendingWakeup", value, "Pending wakeup"); }
+    clearPendingWakeup(taskId) { this.#clearSingleton(taskId, "pendingWakeup"); }
+    getLeaderFailure(taskId) { return optional(this.#state().tasks[taskId]?.leaderFailure ?? undefined); }
+    saveLeaderFailure(value) { this.#saveSingleton(value.taskId, "leaderFailure", value, "Leader failure"); }
+    clearLeaderFailure(taskId) { this.#clearSingleton(taskId, "leaderFailure"); }
+    getOperatorNotification(taskId) { return optional(this.#state().tasks[taskId]?.operatorNotification ?? undefined); }
+    saveOperatorNotification(value) { this.#saveSingleton(value.taskId, "operatorNotification", value, "Operator notification"); }
+    clearOperatorNotification(taskId) { this.#clearSingleton(taskId, "operatorNotification"); }
+    #saveSingleton(taskId, key, value, label) {
+        const stored = identified(value, 1, "taskId", taskId, label);
+        this.#requireTaskForWrite(taskId);
+        this.#mutate((state) => { state.tasks[taskId][key] = stored; });
+    }
+    #clearSingleton(key, field) {
+        this.#mutate((state) => { if (state.tasks[key] !== undefined)
+            state.tasks[key][field] = null; });
+    }
+    #saveTaskRecord(taskId, key, value, label) {
+        const record = versioned(value, 1, label);
+        this.#requireTaskForWrite(taskId);
+        this.#mutate((state) => {
+            if (taskRecordOwner(state, key, record.id) !== null) {
+                throw new StorageRecordError(`${label} already exists: ${record.id}`);
+            }
+            state.tasks[taskId][key][record.id] = clone(value);
+        });
+    }
+    #requireTask(taskId) {
+        const aggregate = this.#state().tasks[taskId];
+        if (aggregate === undefined)
+            throw new StorageRecordError(`Task not found: ${taskId}`);
+        return aggregate;
+    }
+    #requireTaskForWrite(taskId) { return this.#requireTask(taskId); }
+    #state() { return this.#transaction?.state ?? this.#readState(); }
+    #mutate(execute) { this.#mutateResult((state) => { execute(state); }); }
+    #mutateResult(execute) {
+        if (this.#transaction !== null) {
+            const result = execute(this.#transaction.state);
+            this.#transaction.dirty = true;
+            return result;
+        }
+        return this.#withWriteLock(() => {
+            const state = this.#readState();
+            const result = execute(state);
+            this.#commit(state, state.revision);
+            return result;
+        });
+    }
+    #remove(select, id) {
+        return this.#mutateResult((state) => {
+            const records = select(state);
+            if (records[id] === undefined)
+                return false;
+            delete records[id];
+            return true;
+        });
+    }
+    #nextGlobalId(prefix, collect) {
+        const pattern = new RegExp(`^${prefix}-(\\d+)$`);
+        const maximum = collect(this.#state()).reduce((max, id) => {
+            const match = pattern.exec(id);
+            return match === null ? max : Math.max(max, Number.parseInt(match[1], 10));
+        }, 0);
+        return `${prefix}-${maximum + 1}`;
+    }
+    #readState() {
+        requireStorageSchema(this.rootDir);
+        const path = join(this.rootDir, STORAGE_STATE_FILE);
+        if (!existsSync(path))
+            return emptyState();
+        return parseState(readFileSync(path, "utf8"));
+    }
+    #commit(state, expectedRevision) {
+        const current = this.#readState();
+        if (current.revision !== expectedRevision) {
+            throw new StorageConflictError(`Storage changed concurrently (expected revision ${expectedRevision}, found ${current.revision}).`);
+        }
+        state.revision = expectedRevision + 1;
+        const content = `${JSON.stringify(state, null, 2)}\n`;
+        parseState(content);
+        writeTextFileAtomically(join(this.rootDir, STORAGE_STATE_FILE), content);
+    }
+    #withWriteLock(execute) {
+        const release = acquireStorageLock(this.rootDir);
+        try {
+            return execute();
+        }
+        finally {
+            release();
+        }
+    }
+}
+export class StorageRecordError extends Error {
+    constructor(message) { super(message); this.name = "StorageRecordError"; }
+}
+export class StorageConflictError extends Error {
+    constructor(message) { super(message); this.name = "StorageConflictError"; }
+}
+export function resolveYuiHome(env) {
+    return env.YUI_HOME === undefined || env.YUI_HOME.length === 0
+        ? join(homedir(), ".yui")
+        : resolve(env.YUI_HOME);
+}
+export function ensureYuiHome(rootDir) { mkdirSync(rootDir, { recursive: true, mode: 0o700 }); }
+function emptyState() {
+    return { schemaVersion: 1, revision: 0, config: { schemaVersion: 1 }, configuredAgents: {}, repositories: {}, globalRoles: {}, globalRoleSessionSets: {}, tasks: {} };
+}
+function emptyStoredTask(task) {
+    return {
+        schemaVersion: 1,
+        task,
+        brief: null,
+        roles: {},
+        roleWorkspaces: {},
+        roleSessionSets: {},
+        workItems: {},
+        agentRuns: {},
+        activeRuns: {},
+        messages: {},
+        inputRequests: {},
+        decisions: {},
+        milestones: {},
+        events: {},
+        pendingWakeup: null,
+        leaderFailure: null,
+        operatorNotification: null
+    };
+}
+function parseState(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new StorageRecordError(`Invalid ${STORAGE_STATE_FILE}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const state = object(parsed, "Storage state");
+    exact(state, ["schemaVersion", "revision", "config", "configuredAgents", "repositories", "globalRoles", "globalRoleSessionSets", "tasks"], "Storage state");
+    if (state.schemaVersion !== 1 || !Number.isInteger(state.revision) || state.revision < 0)
+        throw new StorageRecordError("Storage state schemaVersion/revision is invalid.");
+    const result = clone(state);
+    result.config = versioned(result.config, 1, "Yui config");
+    validateYuiConfig(result.config);
+    parseMap(result.configuredAgents, (value, key) => {
+        const agent = identified(value, 2, "id", key, "Configured Agent");
+        validateConfiguredAgent(agent);
+        return agent;
+    }, "configuredAgents");
+    parseMap(result.repositories, (value, key) => {
+        const repository = identified(value, 1, "id", key, "Repository");
+        validateRepository(repository);
+        return repository;
+    }, "repositories");
+    parseMap(result.globalRoles, (value, key) => {
+        const role = identified(value, 2, "name", key, "Global Role");
+        validateGlobalRole(role);
+        return role;
+    }, "globalRoles");
+    parseMap(result.globalRoleSessionSets, (value, key) => { const set = globalSessions(value); if (set.owner.roleName !== key)
+        throw new StorageRecordError(`Global Role session set identity is inconsistent: ${key}`); return set; }, "globalRoleSessionSets");
+    parseMap(result.tasks, (value, key) => parseStoredTask(value, key), "tasks");
+    for (const [name, role] of Object.entries(result.globalRoles)) {
+        const sessions = result.globalRoleSessionSets[name];
+        if (sessions !== undefined)
+            assertSessionsMatchRole(sessions, role);
+    }
+    for (const name of Object.keys(result.globalRoleSessionSets)) {
+        if (result.globalRoles[name] === undefined) {
+            throw new StorageRecordError(`Global Role session set has no Role: ${name}`);
+        }
+    }
+    for (const aggregate of Object.values(result.tasks)) {
+        if (aggregate.task.repositoryId !== undefined
+            && result.repositories[aggregate.task.repositoryId] === undefined) {
+            throw new StorageRecordError(`Task Repository not found: ${aggregate.task.id}/${aggregate.task.repositoryId}`);
+        }
+        for (const [name, role] of Object.entries(aggregate.roles)) {
+            const sessions = aggregate.roleSessionSets[name];
+            if (sessions !== undefined)
+                assertSessionsMatchRole(sessions, role);
+            const workspace = aggregate.roleWorkspaces[name];
+            if (workspace !== undefined && workspace.path !== role.workspace) {
+                throw new StorageRecordError(`Task Role workspace path is inconsistent: ${aggregate.task.id}/${name}`);
+            }
+        }
+        for (const name of Object.keys(aggregate.roleSessionSets)) {
+            if (aggregate.roles[name] === undefined) {
+                throw new StorageRecordError(`Task Role session set has no Role: ${aggregate.task.id}/${name}`);
+            }
+        }
+        for (const [name, workspace] of Object.entries(aggregate.roleWorkspaces)) {
+            if (aggregate.roles[name] === undefined) {
+                throw new StorageRecordError(`RoleWorkspace has no Task Role: ${aggregate.task.id}/${name}`);
+            }
+            if (aggregate.task.repositoryId !== workspace.repositoryId) {
+                throw new StorageRecordError(`RoleWorkspace Repository does not match Task: ${aggregate.task.id}/${name}`);
+            }
+        }
+    }
+    assertGloballyUniqueTaskRecordIds(result, "inputRequests", "Input request");
+    assertGloballyUniqueTaskRecordIds(result, "decisions", "Decision");
+    assertGloballyUniqueTaskRecordIds(result, "milestones", "Milestone");
+    assertGloballyUniqueTaskRecordIds(result, "events", "Task event");
+    assertGloballyUniqueTaskRecordIds(result, "messages", "Message");
+    return result;
+}
+function parseStoredTask(value, taskId) {
+    const aggregate = object(value, `Task aggregate ${taskId}`);
+    exact(aggregate, ["schemaVersion", "task", "brief", "roles", "roleWorkspaces", "roleSessionSets", "workItems", "agentRuns", "activeRuns", "messages", "inputRequests", "decisions", "milestones", "events", "pendingWakeup", "leaderFailure", "operatorNotification"], `Task aggregate ${taskId}`);
+    versioned(aggregate, 1, `Task aggregate ${taskId}`);
+    validateTask(identified(aggregate.task, 1, "id", taskId, "Task"));
+    if (aggregate.brief !== null)
+        storedTaskBrief(aggregate.brief);
+    parseMap(aggregate.roles, (record, key) => { const role = identified(record, 2, "name", key, "Task Role"); if (role.taskId !== taskId)
+        throw new StorageRecordError(`Task Role belongs to another Task: ${role.taskId}`); validateTaskRole(role); return role; }, "roles");
+    parseMap(aggregate.roleWorkspaces, (record, key) => {
+        const workspace = identified(record, 1, "roleName", key, "RoleWorkspace");
+        if (workspace.taskId !== taskId) {
+            throw new StorageRecordError(`RoleWorkspace belongs to another Task: ${workspace.taskId}`);
+        }
+        validateRoleWorkspace(workspace);
+        return workspace;
+    }, "roleWorkspaces");
+    parseMap(aggregate.roleSessionSets, (record, key) => { const set = taskSessions(record); if (set.owner.taskId !== taskId || set.owner.roleName !== key)
+        throw new StorageRecordError(`Task Role session set identity is inconsistent: ${taskId}/${key}`); return set; }, "roleSessionSets");
+    parseMap(aggregate.workItems, (record, key) => { const item = identified(record, 1, "id", key, "Work item"); if (item.taskId !== taskId)
+        throw new StorageRecordError(`Work item belongs to another Task: ${item.taskId}`); return item; }, "workItems");
+    parseMap(aggregate.agentRuns, (record, key) => { const run = identified(record, 1, "id", key, "Agent run"); if (run.taskId !== taskId)
+        throw new StorageRecordError(`Agent run belongs to another Task: ${run.taskId}`); validateAgentRun(run); return run; }, "agentRuns");
+    parseMap(aggregate.activeRuns, (record, key) => {
+        const pointer = versioned(record, 1, `Active run ${key}`);
+        const run = typeof pointer.runId === "string" ? aggregate.agentRuns[pointer.runId] : undefined;
+        if (run === undefined || run.status !== "active" || run.roleName !== key) {
+            throw new StorageRecordError(`Active run pointer is invalid: ${taskId}/${key}`);
+        }
+        return pointer;
+    }, "activeRuns");
+    parseMap(aggregate.messages, (record, key) => {
+        const message = identified(record, 1, "id", key, "Message");
+        validateTaskMessage(message);
+        return message;
+    }, "messages");
+    parseMap(aggregate.inputRequests, (record, key) => {
+        const request = validateInputRequest(record);
+        if (request.id !== key) {
+            throw new StorageRecordError(`Input request identity is inconsistent: ${key}.`);
+        }
+        if (request.taskId !== taskId) {
+            throw new StorageRecordError(`Input request belongs to another Task: ${request.taskId}`);
+        }
+        return request;
+    }, "inputRequests");
+    parseMap(aggregate.decisions, (record, key) => {
+        const decision = storedDecision(record);
+        if (decision.id !== key)
+            throw new StorageRecordError(`Decision identity is inconsistent: ${key}.`);
+        if (decision.taskId !== taskId) {
+            throw new StorageRecordError(`Decision belongs to another Task: ${decision.taskId}`);
+        }
+        return decision;
+    }, "decisions");
+    parseMap(aggregate.milestones, (record, key) => {
+        const milestone = storedMilestone(record);
+        if (milestone.id !== key)
+            throw new StorageRecordError(`Milestone identity is inconsistent: ${key}.`);
+        if (milestone.taskId !== taskId) {
+            throw new StorageRecordError(`Milestone belongs to another Task: ${milestone.taskId}`);
+        }
+        return milestone;
+    }, "milestones");
+    parseMap(aggregate.events, (record, key) => {
+        const event = storedTaskEvent(record);
+        if (event.id !== key)
+            throw new StorageRecordError(`Task event identity is inconsistent: ${key}.`);
+        return event;
+    }, "events");
+    for (const [key, label] of [["pendingWakeup", "Pending wakeup"], ["leaderFailure", "Leader failure"], ["operatorNotification", "Operator notification"]]) {
+        const record = aggregate[key];
+        if (record !== null)
+            identified(record, 1, "taskId", taskId, label);
+    }
+    return aggregate;
+}
+function validateYuiConfig(config) {
+    try {
+        reconciliationIntervalMilliseconds(config.reconciliationIntervalSeconds);
+    }
+    catch (error) {
+        throw new StorageRecordError(error instanceof Error ? error.message : "Yui reconciliation interval is invalid.");
+    }
+}
+function globalSessions(value) {
+    const set = versioned(value, 1, "Global Role session set");
+    if (set.owner?.scope !== "global" || typeof set.owner.roleName !== "string")
+        throw new StorageRecordError("Global Role session owner is invalid.");
+    validateSessions(set.sessions);
+    validateRoleSessionSet(set);
+    return set;
+}
+function taskSessions(value) {
+    const set = versioned(value, 1, "Task Role session set");
+    if (set.owner?.scope !== "task" || typeof set.owner.taskId !== "string" || typeof set.owner.roleName !== "string")
+        throw new StorageRecordError("Task Role session owner is invalid.");
+    validateSessions(set.sessions);
+    validateRoleSessionSet(set);
+    return set;
+}
+function validateSessions(sessions) {
+    parseMap(sessions, (record, key) => identified(record, 1, "agentId", key, "Role Agent session"), "sessions");
+}
+function assertSessionsMatchRole(sessions, role) {
+    validateRoleSessionSet(sessions);
+    if (sessions.owner.roleName !== role.name || sessions.activeAgentId !== role.activeAgentId) {
+        throw new StorageRecordError(`Role session set does not match Role: ${role.name}`);
+    }
+    if ("taskId" in role && (sessions.owner.scope !== "task" || sessions.owner.taskId !== role.taskId)) {
+        throw new StorageRecordError(`Task Role session owner is inconsistent: ${role.taskId}/${role.name}`);
+    }
+    if (!("taskId" in role) && sessions.owner.scope !== "global") {
+        throw new StorageRecordError(`Global Role session owner is inconsistent: ${role.name}`);
+    }
+    for (const [agentId, session] of Object.entries(sessions.sessions)) {
+        const binding = role.agentBindings[agentId];
+        if (binding === undefined || binding.adapterId !== session.adapterId) {
+            throw new StorageRecordError(`Role Agent session has no matching binding: ${role.name}/${agentId}`);
+        }
+    }
+}
+function storedTaskBrief(value) {
+    const brief = versioned(value, 1, "Task Brief");
+    exact(brief, ["schemaVersion", "objective", "boundaries", "currentFocus", "leaderSummary", "updatedAt", "updatedBy"], "Task Brief");
+    requireNormalizedText(brief.objective, "Task Brief objective");
+    requireNormalizedText(brief.currentFocus, "Task Brief current focus");
+    requireNormalizedText(brief.leaderSummary, "Task Brief leader summary");
+    requireNormalizedText(brief.updatedBy, "Task Brief updatedBy");
+    if (!Array.isArray(brief.boundaries)) {
+        throw new StorageRecordError("Task Brief boundaries must be an array.");
+    }
+    const boundaries = brief.boundaries.map((boundary) => (requireNormalizedText(boundary, "Task Brief boundary")));
+    if (new Set(boundaries).size !== boundaries.length) {
+        throw new StorageRecordError("Task Brief boundaries must be unique.");
+    }
+    requireTimestamp(brief.updatedAt, "Task Brief updatedAt");
+    return brief;
+}
+function storedDecision(value) {
+    const decision = versioned(value, 1, "Decision");
+    const baseFields = [
+        "schemaVersion", "id", "taskId", "title", "rationale", "status", "createdAt", "updatedAt"
+    ];
+    if (decision.status === "active") {
+        exact(decision, baseFields, "Decision");
+    }
+    else if (decision.status === "superseded") {
+        exact(decision, [...baseFields, "supersededReason", "supersededAt"], "Decision");
+        requireNormalizedText(decision.supersededReason, "Decision supersededReason");
+        requireTimestamp(decision.supersededAt, "Decision supersededAt");
+        if (decision.supersededAt !== decision.updatedAt) {
+            throw new StorageRecordError("Decision supersededAt must match updatedAt.");
+        }
+    }
+    else {
+        throw new StorageRecordError(`Decision status is invalid: ${String(decision.status)}.`);
+    }
+    requireRecordIdentity(decision.id, "Decision id");
+    requireRecordIdentity(decision.taskId, "Decision Task id");
+    requireNormalizedText(decision.title, "Decision title");
+    requireNormalizedText(decision.rationale, "Decision rationale");
+    requireTimestamp(decision.createdAt, "Decision createdAt");
+    requireTimestamp(decision.updatedAt, "Decision updatedAt");
+    if (Date.parse(decision.updatedAt) < Date.parse(decision.createdAt)) {
+        throw new StorageRecordError("Decision updatedAt cannot precede createdAt.");
+    }
+    return decision;
+}
+function storedMilestone(value) {
+    const milestone = versioned(value, 1, "Milestone");
+    exact(milestone, ["schemaVersion", "id", "taskId", "title", "summary", "createdBy", "createdAt"], "Milestone");
+    requireRecordIdentity(milestone.id, "Milestone id");
+    requireRecordIdentity(milestone.taskId, "Milestone Task id");
+    requireNormalizedText(milestone.title, "Milestone title");
+    requireNormalizedText(milestone.summary, "Milestone summary");
+    if (milestone.createdBy !== "leader") {
+        throw new StorageRecordError("Milestone createdBy must be leader.");
+    }
+    requireTimestamp(milestone.createdAt, "Milestone createdAt");
+    return milestone;
+}
+function storedTaskEvent(value) {
+    const event = versioned(value, 1, "Task event");
+    exact(event, ["schemaVersion", "id", "type", "payload", "createdAt"], "Task event");
+    requireRecordIdentity(event.id, "Task event id");
+    requireNormalizedText(event.type, "Task event type");
+    const payload = object(event.payload, "Task event payload");
+    for (const [key, payloadValue] of Object.entries(payload)) {
+        requireRecordIdentity(key, "Task event payload key");
+        if (typeof payloadValue !== "string" || payloadValue.includes("\0")) {
+            throw new StorageRecordError(`Task event payload value is invalid: ${key}.`);
+        }
+    }
+    requireTimestamp(event.createdAt, "Task event createdAt");
+    return event;
+}
+function isValidDecisionSupersession(existing, candidate) {
+    return existing.status === "active"
+        && candidate.status === "superseded"
+        && candidate.id === existing.id
+        && candidate.taskId === existing.taskId
+        && candidate.title === existing.title
+        && candidate.rationale === existing.rationale
+        && candidate.createdAt === existing.createdAt
+        && Date.parse(candidate.updatedAt) >= Date.parse(existing.updatedAt);
+}
+function isValidInputRequestTransition(existing, candidate) {
+    if (existing.status !== "open" || candidate.status === "open")
+        return false;
+    return candidate.id === existing.id
+        && candidate.taskId === existing.taskId
+        && isDeepStrictEqual(candidate.requester, existing.requester)
+        && candidate.question === existing.question
+        && isDeepStrictEqual(candidate.choices, existing.choices)
+        && isDeepStrictEqual(candidate.blockedRefs, existing.blockedRefs)
+        && isDeepStrictEqual(candidate.policy, existing.policy)
+        && candidate.createdAt === existing.createdAt
+        && Date.parse(candidate.updatedAt) >= Date.parse(existing.updatedAt);
+}
+function requireTaskFromState(state, taskId) {
+    const aggregate = state.tasks[taskId];
+    if (aggregate === undefined)
+        throw new StorageRecordError(`Task not found: ${taskId}`);
+    return aggregate;
+}
+function taskRecordOwner(state, key, id) {
+    for (const [taskId, aggregate] of Object.entries(state.tasks)) {
+        if (aggregate[key][id] !== undefined)
+            return taskId;
+    }
+    return null;
+}
+function assertGloballyUniqueTaskRecordIds(state, key, label) {
+    const owners = new Map();
+    for (const [taskId, aggregate] of Object.entries(state.tasks)) {
+        for (const id of Object.keys(aggregate[key])) {
+            const owner = owners.get(id);
+            if (owner !== undefined) {
+                throw new StorageRecordError(`${label} id is duplicated across Tasks: ${id} (${owner}, ${taskId}).`);
+            }
+            owners.set(id, taskId);
+        }
+    }
+}
+function requireRecordIdentity(value, label) {
+    const normalized = requireNormalizedText(value, label);
+    if (["__proto__", "prototype", "constructor", ".", ".."].includes(normalized)
+        || /[\/\\\0]/.test(normalized)) {
+        throw new StorageRecordError(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireNormalizedText(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new StorageRecordError(`${label} is invalid.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new StorageRecordError(`${label} is required.`);
+    if (normalized !== value)
+        throw new StorageRecordError(`${label} must be normalized.`);
+    return normalized;
+}
+function requireTimestamp(value, label) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new StorageRecordError(`${label} is invalid.`);
+    }
+    return value;
+}
+function parseMap(value, parse, label) {
+    const records = object(value, label);
+    for (const [key, entry] of Object.entries(records))
+        parse(entry, key);
+}
+function versioned(value, schemaVersion, label) {
+    assertJsonValue(value, label);
+    const record = object(value, label);
+    if (record.schemaVersion !== schemaVersion)
+        throw new StorageRecordError(`${label} must use schemaVersion ${schemaVersion}.`);
+    return clone(record);
+}
+function identified(value, schemaVersion, key, expected, label) {
+    const record = versioned(value, schemaVersion, label);
+    if (record[key] !== expected)
+        throw new StorageRecordError(`${label} identity is inconsistent: ${expected}.`);
+    return record;
+}
+function object(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new StorageRecordError(`${label} must be an object.`);
+    return value;
+}
+function exact(value, expected, label) {
+    const allowed = new Set(expected);
+    const unknown = Object.keys(value).find((key) => !allowed.has(key));
+    if (unknown !== undefined)
+        throw new StorageRecordError(`${label} has unknown field: ${unknown}.`);
+    const missing = expected.find((key) => !Object.hasOwn(value, key));
+    if (missing !== undefined)
+        throw new StorageRecordError(`${label} is missing field: ${missing}.`);
+}
+function assertJsonValue(value, label, seen = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number" && Number.isFinite(value))
+        return;
+    if (typeof value !== "object")
+        throw new StorageRecordError(`${label} contains a non-JSON value.`);
+    if (seen.has(value))
+        throw new StorageRecordError(`${label} contains a cycle.`);
+    seen.add(value);
+    if (Array.isArray(value))
+        for (const entry of value)
+            assertJsonValue(entry, label, seen);
+    else
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined)
+                throw new StorageRecordError(`${label} contains undefined at ${key}.`);
+            assertJsonValue(entry, label, seen);
+        }
+    seen.delete(value);
+}
+function clone(value) { assertJsonValue(value, "Stored value"); return JSON.parse(JSON.stringify(value)); }
+function optional(value) { return value === undefined ? null : clone(value); }
+function values(records, identity) {
+    return Object.values(records).map(clone).sort((left, right) => numericCompare(typeof identity === "function" ? identity(left) : String(left[identity]), typeof identity === "function" ? identity(right) : String(right[identity])));
+}
+function numericCompare(left, right) { return left.localeCompare(right, undefined, { numeric: true }); }
+function allKeys(state, key) { return Object.values(state.tasks).flatMap((task) => Object.keys(task[key])); }
+function findUnique(state, key, id, label) {
+    const matches = Object.values(state.tasks).flatMap((task) => task[key][id] === undefined ? [] : [task[key][id]]);
+    if (matches.length > 1)
+        throw new StorageRecordError(`${label} id is ambiguous: ${id}`);
+    return matches[0] === undefined ? null : clone(matches[0]);
+}
+function synchronousResult(value) { if (typeof value === "object" && value !== null && "then" in value)
+    throw new StorageRecordError("FileTaskStore transactions must be synchronous."); return value; }
+function acquireStorageLock(rootDir) {
+    ensureYuiHome(rootDir);
+    const lock = join(rootDir, STORAGE_LOCK_DIRECTORY);
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    while (true) {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            writeFileSync(join(lock, "owner"), `${process.pid}\n`, { mode: 0o600 });
+            return () => { rmSync(lock, { recursive: true, force: true }); };
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+            reclaimDeadLock(lock);
+            if (Date.now() >= deadline)
+                throw new StorageConflictError(`Timed out waiting for storage lock: ${lock}`);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MS);
+        }
+    }
+}
+function reclaimDeadLock(lock) {
+    try {
+        const age = Date.now() - statSync(lock).mtimeMs;
+        if (age < 1_000)
+            return;
+        const pid = Number.parseInt(readFileSync(join(lock, "owner"), "utf8"), 10);
+        if (Number.isInteger(pid) && processIsAlive(pid))
+            return;
+        rmSync(lock, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            return;
+    }
+}
+function processIsAlive(pid) { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (error) {
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+} }