@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/managed-processes/managed-processes.js

@@ -0,0 +1,326 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { writeJsonFileAtomic } from "../atomic-file.js";
+import { execCommand } from "../../utils/spawn.js";
+const MANAGED_PROCESS_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5000;
+const MANAGED_PROCESS_FORCE_SHUTDOWN_TIMEOUT_MS = 1000;
+const MANAGED_PROCESS_EXIT_POLL_INTERVAL_MS = 50;
+const MANAGED_PROCESS_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+// `ps -o lstart` emits a fixed-width 24-char ctime stamp, e.g. "Sat Jun 20 10:30:40 2026".
+const POSIX_LSTART_WIDTH = 24;
+const ManagedProcessRecordSchema = z.object({
+    id: z.string().min(1),
+    owner: z.object({
+        provider: z.string().min(1),
+        kind: z.string().min(1),
+    }),
+    pid: z.number().int().positive(),
+    command: z.string().min(1),
+    args: z.array(z.string()),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+    identity: z.object({
+        commandLine: z.string().nullable(),
+        startedAt: z.string().nullable(),
+    }),
+    createdAt: z.string().min(1),
+});
+const WindowsProcessSnapshotSchema = z.object({
+    ProcessId: z.number().int().positive(),
+    CommandLine: z.string().nullable().optional(),
+    CreationDate: z.string().nullable().optional(),
+});
+export function createManagedProcessRegistry(options) {
+    return new FileBackedManagedProcessRegistry(options);
+}
+export function createSystemManagedProcessTable(options) {
+    return new SystemManagedProcessTable({
+        platform: options?.platform ?? process.platform,
+        commandRunner: options?.commandRunner ?? {
+            exec: execCommand,
+        },
+    });
+}
+class SystemManagedProcessTable {
+    constructor(options) {
+        this.platform = options.platform;
+        this.commandRunner = options.commandRunner;
+    }
+    async inspect(pid) {
+        if (!Number.isInteger(pid) || pid <= 0) {
+            return { status: "not-found" };
+        }
+        try {
+            return this.platform === "win32"
+                ? await this.inspectWindows(pid)
+                : await this.inspectPosix(pid);
+        }
+        catch (error) {
+            return { status: "error", error };
+        }
+    }
+    async inspectPosix(pid) {
+        let stdout;
+        try {
+            ({ stdout } = await this.commandRunner.exec("ps", [
+                "-ww",
+                "-p",
+                String(pid),
+                "-o",
+                "lstart=",
+                "-o",
+                "command=",
+            ]));
+        }
+        catch (error) {
+            // `ps -p <pid>` exits non-zero when no process matches the pid; a numeric
+            // exit code means ps ran and found nothing, distinct from ps failing to run.
+            return isCommandExitFailure(error) ? { status: "not-found" } : { status: "error", error };
+        }
+        const line = stdout.trimEnd();
+        if (!line) {
+            return { status: "not-found" };
+        }
+        const startedAt = line.slice(0, POSIX_LSTART_WIDTH).trim();
+        const commandLine = line.slice(POSIX_LSTART_WIDTH).trim();
+        return {
+            status: "alive",
+            snapshot: {
+                pid,
+                commandLine: commandLine || null,
+                startedAt: startedAt || null,
+            },
+        };
+    }
+    async inspectWindows(pid) {
+        const command = [
+            `$process = Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}';`,
+            "if ($process) { $process | Select-Object ProcessId,CommandLine,CreationDate | ConvertTo-Json -Compress }",
+        ].join(" ");
+        const { stdout } = await this.commandRunner.exec("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            command,
+        ]);
+        const trimmed = stdout.trim();
+        if (!trimmed) {
+            return { status: "not-found" };
+        }
+        const parsed = WindowsProcessSnapshotSchema.parse(JSON.parse(trimmed));
+        return {
+            status: "alive",
+            snapshot: {
+                pid,
+                commandLine: parsed.CommandLine ?? null,
+                startedAt: parsed.CreationDate ?? null,
+            },
+        };
+    }
+}
+class FileBackedManagedProcessRegistry {
+    constructor(options) {
+        this.directory = path.join(options.paseoHome, "runtime", "managed-processes");
+        this.processTable = options.processTable;
+        this.terminateProcess = options.terminateProcess;
+        this.logger = options.logger.child({ module: "managed-processes" });
+    }
+    async record(input) {
+        const inspection = await this.processTable.inspect(input.pid);
+        const snapshot = inspection.status === "alive" ? inspection.snapshot : null;
+        const record = {
+            id: randomUUID(),
+            owner: input.owner,
+            pid: input.pid,
+            command: input.command,
+            args: input.args,
+            metadata: input.metadata ?? {},
+            identity: {
+                commandLine: snapshot?.commandLine ?? null,
+                startedAt: snapshot?.startedAt ?? null,
+            },
+            createdAt: new Date().toISOString(),
+        };
+        await writeJsonFileAtomic(this.recordPath(record.id), record);
+        return record;
+    }
+    async remove(id) {
+        await fs.rm(this.recordPath(id), { force: true });
+    }
+    async list() {
+        const entries = await this.readEntries();
+        return entries.map((entry) => entry.record);
+    }
+    async reapStale() {
+        const result = {
+            checked: 0,
+            dead: 0,
+            mismatched: 0,
+            removed: 0,
+            terminated: 0,
+            errors: [],
+        };
+        for (const entry of await this.readEntries()) {
+            result.checked += 1;
+            try {
+                const inspection = await this.processTable.inspect(entry.record.pid);
+                if (inspection.status === "not-found") {
+                    await fs.rm(entry.path, { force: true });
+                    result.dead += 1;
+                    result.removed += 1;
+                    continue;
+                }
+                if (inspection.status === "error") {
+                    // Inspection failed, so we cannot tell whether the helper is still
+                    // alive. Keep the record and retry on the next reconcile rather than
+                    // orphaning a live process by deleting its record without killing it.
+                    const message = inspection.error instanceof Error ? inspection.error.message : String(inspection.error);
+                    result.errors.push({ id: entry.record.id, message });
+                    this.logger.warn({
+                        err: inspection.error,
+                        id: entry.record.id,
+                        pid: entry.record.pid,
+                        owner: entry.record.owner,
+                    }, "Could not inspect managed helper process; leaving record for next reconcile");
+                    continue;
+                }
+                const snapshot = inspection.snapshot;
+                if (!processIdentityMatches(entry.record, snapshot)) {
+                    await fs.rm(entry.path, { force: true });
+                    result.mismatched += 1;
+                    result.removed += 1;
+                    continue;
+                }
+                await this.terminateProcess(createPidTarget(entry.record.pid), {
+                    gracefulTimeoutMs: MANAGED_PROCESS_GRACEFUL_SHUTDOWN_TIMEOUT_MS,
+                    forceTimeoutMs: MANAGED_PROCESS_FORCE_SHUTDOWN_TIMEOUT_MS,
+                    onForceSignal: () => {
+                        this.logger.warn({
+                            pid: entry.record.pid,
+                            owner: entry.record.owner,
+                            timeoutMs: MANAGED_PROCESS_GRACEFUL_SHUTDOWN_TIMEOUT_MS,
+                        }, "Managed helper process did not exit after SIGTERM; sending SIGKILL");
+                    },
+                });
+                await fs.rm(entry.path, { force: true });
+                result.terminated += 1;
+                result.removed += 1;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                result.errors.push({ id: entry.record.id, message });
+                this.logger.warn({ err: error, id: entry.record.id, pid: entry.record.pid, owner: entry.record.owner }, "Failed to reap managed helper process");
+            }
+        }
+        return result;
+    }
+    recordPath(id) {
+        if (!MANAGED_PROCESS_ID_PATTERN.test(id)) {
+            throw new Error(`Invalid managed process record id: ${id}`);
+        }
+        return path.join(this.directory, `${id}.json`);
+    }
+    async readEntries() {
+        let fileNames;
+        try {
+            fileNames = await fs.readdir(this.directory);
+        }
+        catch (error) {
+            if (isNodeErrorWithCode(error, "ENOENT")) {
+                return [];
+            }
+            throw error;
+        }
+        const entries = [];
+        for (const fileName of fileNames) {
+            if (!fileName.endsWith(".json")) {
+                continue;
+            }
+            const filePath = path.join(this.directory, fileName);
+            try {
+                const raw = await fs.readFile(filePath, "utf8");
+                const parsed = ManagedProcessRecordSchema.parse(JSON.parse(raw));
+                entries.push({ path: filePath, record: parsed });
+            }
+            catch (error) {
+                // A single corrupt or partially-written record must not abort the whole
+                // reconcile and leave every other leftover un-reaped. Skip it.
+                this.logger.warn({ err: error, file: fileName }, "Skipping unreadable managed process record");
+            }
+        }
+        return entries;
+    }
+}
+function processIdentityMatches(record, snapshot) {
+    if (record.identity.startedAt && snapshot.startedAt) {
+        if (record.identity.startedAt !== snapshot.startedAt) {
+            return false;
+        }
+        return snapshot.commandLine ? commandLineMatchesRecord(record, snapshot.commandLine) : true;
+    }
+    if (record.identity.commandLine && snapshot.commandLine) {
+        return (normalizeCommandLine(record.identity.commandLine) ===
+            normalizeCommandLine(snapshot.commandLine));
+    }
+    return snapshot.commandLine ? commandLineMatchesRecord(record, snapshot.commandLine) : false;
+}
+function commandLineMatchesRecord(record, commandLine) {
+    // Require the command name and args as one contiguous run, not scattered
+    // tokens. Without exact process identity (lstart), a reused PID whose command
+    // line merely mentions "opencode", "serve" and the port elsewhere must not be
+    // mistaken for our leftover and killed.
+    const normalized = normalizeCommandLine(commandLine);
+    const commandName = path.basename(record.command).toLowerCase();
+    const signature = [commandName, ...record.args].map((token) => token.toLowerCase()).join(" ");
+    return normalized.includes(signature);
+}
+function normalizeCommandLine(commandLine) {
+    return commandLine.replace(/\s+/g, " ").trim().toLowerCase();
+}
+export function createPidTarget(pid) {
+    return {
+        pid,
+        exitCode: null,
+        signalCode: null,
+        kill(signal) {
+            process.kill(pid, signal);
+            return true;
+        },
+        // The reaper has no ChildProcess handle for a leftover from a previous
+        // daemon, so it observes exit by polling the pid. Without this, termination
+        // can never see a graceful SIGTERM exit and always waits out the full
+        // graceful+force window before escalating to SIGKILL.
+        once(_event, listener) {
+            const timer = setInterval(() => {
+                if (!isProcessAlive(pid)) {
+                    clearInterval(timer);
+                    listener();
+                }
+            }, MANAGED_PROCESS_EXIT_POLL_INTERVAL_MS);
+            timer.unref();
+        },
+    };
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isNodeErrorWithCode(error, "EPERM");
+    }
+}
+function isCommandExitFailure(error) {
+    // execFile rejects with a numeric `code` (the process exit status) when the
+    // command ran and exited non-zero; a string `code` (e.g. "ENOENT") means it
+    // never ran.
+    return typeof error?.code === "number";
+}
+function isNodeErrorWithCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+//# sourceMappingURL=managed-processes.js.map

package/dist/server/server/messages.d.ts

@@ -0,0 +1,9 @@
+import type { ManagedAgent } from "./agent/agent-manager.js";
+import type { AgentStreamEvent } from "./agent/agent-sdk-types.js";
+import type { AgentSnapshotPayload, AgentStreamEventPayload } from "@camerontaylor/paseo-protocol/messages";
+export * from "@camerontaylor/paseo-protocol/messages";
+export declare function serializeAgentSnapshot(agent: ManagedAgent, options?: {
+    title?: string | null;
+}): AgentSnapshotPayload;
+export declare function serializeAgentStreamEvent(event: AgentStreamEvent): AgentStreamEventPayload | null;
+//# sourceMappingURL=messages.d.ts.map

package/dist/server/server/messages.js

@@ -0,0 +1,29 @@
+import { toAgentPayload } from "./agent/agent-projections.js";
+import { AgentStreamEventPayloadSchema as AgentStreamEventPayloadRuntimeSchema } from "@camerontaylor/paseo-protocol/messages";
+export * from "@camerontaylor/paseo-protocol/messages";
+function validateStreamEventPayload(payload) {
+    const parsed = AgentStreamEventPayloadRuntimeSchema.safeParse(payload);
+    if (!parsed.success) {
+        return null;
+    }
+    return parsed.data;
+}
+export function serializeAgentSnapshot(agent, options) {
+    return toAgentPayload(agent, options);
+}
+export function serializeAgentStreamEvent(event) {
+    if (event.type === "attention_required") {
+        // Providers may emit attention_required without per-client notification context.
+        // The websocket server emits attention_required with shouldNotify computed per client.
+        // Normalize provider events so they satisfy the shared schema.
+        return validateStreamEventPayload({
+            type: "attention_required",
+            provider: event.provider,
+            reason: event.reason,
+            timestamp: event.timestamp,
+            shouldNotify: false,
+        });
+    }
+    return validateStreamEventPayload(event);
+}
+//# sourceMappingURL=messages.js.map

package/dist/server/server/migrations/backfill-workspace-id.migration.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from "pino";
+import type { AgentStorage } from "../agent/agent-storage.js";
+import type { WorkspaceRegistry } from "../workspace-registry.js";
+export declare function backfillWorkspaceIdForLegacyAgents(options: {
+    agentStorage: AgentStorage;
+    workspaceRegistry: WorkspaceRegistry;
+    logger: Logger;
+}): Promise<number>;
+//# sourceMappingURL=backfill-workspace-id.migration.d.ts.map

package/dist/server/server/migrations/backfill-workspace-id.migration.js

@@ -0,0 +1,64 @@
+// COMPAT(workspaceIdBackfill): one-time legacy backfill, delete after 2026-12-16
+// once floor >= the release that always stamps workspaceId at create time.
+//
+// This is the ONLY place in the codebase that maps a cwd to a workspaceId.
+// Every other code path treats a record's `workspaceId` field as authoritative
+// ownership. Legacy agent records persisted before workspaceId stamping have no
+// owner, so this migration stamps each one with the workspace that owned its
+// directory at the time it was written. It runs once at startup and writes the
+// id back to storage, after which all runtime code can assume the field exists.
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+// Picks the workspace that owned `cwd` for a legacy, unstamped agent record.
+// Prefers an exact-cwd workspace (oldest wins) and otherwise attributes to the
+// deepest enclosing workspace directory, never letting the home directory own
+// descendants. Live records only consider live workspaces; archived records can
+// resolve to archived workspaces so History/restore retains legacy ownership.
+// Used only by the one-time backfill below.
+function resolveLegacyWorkspaceOwner(cwd, workspaces, options) {
+    const normalizedCwd = resolve(cwd);
+    const userHome = resolve(homedir());
+    const candidateWorkspaces = Array.from(workspaces).filter((workspace) => options?.includeArchived === true || !workspace.archivedAt);
+    const exactMatches = candidateWorkspaces.filter((workspace) => resolve(workspace.cwd) === normalizedCwd);
+    if (exactMatches.length > 0) {
+        return oldestWorkspace(exactMatches).workspaceId;
+    }
+    const prefixMatches = candidateWorkspaces.filter((workspace) => {
+        const workspaceCwd = resolve(workspace.cwd);
+        if (workspaceCwd === userHome) {
+            return false;
+        }
+        return normalizedCwd === workspaceCwd || normalizedCwd.startsWith(`${workspaceCwd}${sep}`);
+    });
+    if (prefixMatches.length === 0) {
+        return null;
+    }
+    const deepestPrefixLength = Math.max(...prefixMatches.map((workspace) => resolve(workspace.cwd).length));
+    return oldestWorkspace(prefixMatches.filter((workspace) => resolve(workspace.cwd).length === deepestPrefixLength)).workspaceId;
+}
+function oldestWorkspace(workspaces) {
+    return workspaces.reduce((oldest, candidate) => candidate.createdAt < oldest.createdAt ? candidate : oldest);
+}
+export async function backfillWorkspaceIdForLegacyAgents(options) {
+    const workspaceRecords = await options.workspaceRegistry.list();
+    const records = await options.agentStorage.list();
+    let migrated = 0;
+    for (const record of records) {
+        if (record.workspaceId) {
+            continue;
+        }
+        const workspaceId = resolveLegacyWorkspaceOwner(record.cwd, workspaceRecords, {
+            includeArchived: record.archivedAt != null,
+        });
+        if (!workspaceId) {
+            continue;
+        }
+        await options.agentStorage.upsert({ ...record, workspaceId });
+        migrated += 1;
+    }
+    if (migrated > 0) {
+        options.logger.info({ migrated }, "Backfilled workspaceId for legacy agent records");
+    }
+    return migrated;
+}
+//# sourceMappingURL=backfill-workspace-id.migration.js.map

package/dist/server/server/orchestration-skills/index.d.ts

@@ -0,0 +1,18 @@
+import type { AgentSkillSelection } from "@camerontaylor/paseo-protocol/messages";
+import type { DaemonConfigStore } from "../daemon-config-store.js";
+import { type SkillsSaveResult, type SkillsSnapshot } from "./internal/controller.js";
+import { resolveSkillTargets } from "./internal/paths.js";
+export interface OrchestrationSkills {
+    getStatus(): Promise<SkillsSnapshot>;
+    reconcile(): Promise<SkillsSnapshot>;
+    uninstall(): Promise<SkillsSnapshot>;
+    saveSelection(selection: AgentSkillSelection, confirmedRemovals?: readonly string[]): Promise<SkillsSaveResult>;
+    importLegacySelectionIfUnset(selection: AgentSkillSelection): Promise<{
+        imported: boolean;
+        selection: AgentSkillSelection;
+    }>;
+    autoUpdate(): Promise<SkillsSnapshot>;
+}
+export declare function createOrchestrationSkills(configStore: DaemonConfigStore, resolveTargets?: typeof resolveSkillTargets): OrchestrationSkills;
+export type { SkillsSaveResult, SkillsSnapshot } from "./internal/controller.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/server/server/orchestration-skills/index.js

@@ -0,0 +1,18 @@
+import { createSkillsController, } from "./internal/controller.js";
+import { resolveSkillTargets } from "./internal/paths.js";
+import { createSkillSelectionStore } from "./internal/selection-store.js";
+export function createOrchestrationSkills(configStore, resolveTargets = resolveSkillTargets) {
+    const controller = createSkillsController({
+        resolveTargets,
+        selectionStore: createSkillSelectionStore(configStore),
+    });
+    return {
+        getStatus: () => controller.status(),
+        reconcile: () => controller.update(),
+        uninstall: () => controller.uninstall(),
+        saveSelection: (selection, confirmedRemovals = []) => controller.save({ ...selection, confirmedRemovals }),
+        importLegacySelectionIfUnset: (selection) => controller.importLegacySelectionIfUnset(selection),
+        autoUpdate: () => controller.autoUpdate(),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/server/server/orchestration-skills/internal/controller.d.ts

@@ -0,0 +1,39 @@
+import { type SkillSelection, type SkillsStatus, type SkillTargets } from "./operations.js";
+import { type SkillSelectionStore } from "./selection-store.js";
+/** Everything the settings UI needs to render skills in one round trip. */
+export interface SkillsSnapshot extends SkillsStatus {
+    selection: SkillSelection;
+}
+export interface SkillsSaveResult extends SkillsSnapshot {
+    /**
+     * Non-null when the save did nothing because these directories would be
+     * deleted and the request had not confirmed them. Retry with the names.
+     */
+    confirmationRequired: {
+        removals: string[];
+    } | null;
+}
+export interface SkillsController {
+    status(): Promise<SkillsSnapshot>;
+    install(): Promise<SkillsSnapshot>;
+    update(): Promise<SkillsSnapshot>;
+    uninstall(): Promise<SkillsSnapshot>;
+    autoUpdate(): Promise<SkillsSnapshot>;
+    save(request: unknown): Promise<SkillsSaveResult>;
+    importLegacySelectionIfUnset(selection: unknown): Promise<{
+        imported: boolean;
+        selection: SkillSelection;
+    }>;
+}
+/**
+ * The single writer for installed skills. Startup convergence and every settings
+ * command run through one queue, so no operation applies a plan computed from a
+ * selection another one has already replaced, and no read sees a half-applied
+ * directory. Ordering between concurrent callers is not promised — consistency
+ * after both finish is.
+ */
+export declare function createSkillsController({ resolveTargets, selectionStore, }: {
+    resolveTargets: () => SkillTargets;
+    selectionStore: SkillSelectionStore;
+}): SkillsController;
+//# sourceMappingURL=controller.d.ts.map

package/dist/server/server/orchestration-skills/internal/controller.js

@@ -0,0 +1,108 @@
+import { autoUpdateInstalledSkills, getSkillsStatus, installSkills, uninstallSkills, updateSkills, } from "./operations.js";
+import { coerceSkillNames, coerceSkillSelection, } from "./selection-store.js";
+import { beginSkillsTransaction, recoverInterruptedSkillTransactions } from "./transaction.js";
+const MAX_SAVE_ATTEMPTS = 3;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The single writer for installed skills. Startup convergence and every settings
+ * command run through one queue, so no operation applies a plan computed from a
+ * selection another one has already replaced, and no read sees a half-applied
+ * directory. Ordering between concurrent callers is not promised — consistency
+ * after both finish is.
+ */
+export function createSkillsController({ resolveTargets, selectionStore, }) {
+    let queue = Promise.resolve();
+    function serialize(run) {
+        const next = queue.then(run, run);
+        queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    async function converge(apply) {
+        const selection = await selectionStore.get();
+        await recoverInterruptedSkillTransactions(resolveTargets(), selection);
+        return { ...(await apply(resolveTargets(), selection)), selection };
+    }
+    async function saveSelection(request) {
+        const targets = resolveTargets();
+        const next = coerceSkillSelection(request);
+        const previous = await selectionStore.get();
+        await recoverInterruptedSkillTransactions(targets, previous);
+        const confirmed = new Set(coerceSkillNames(isRecord(request) ? request.confirmedRemovals : null));
+        // The plan comes from a scan taken here, inside the queue, and is the exact
+        // plan applied below. Deciding what will be deleted from an older snapshot
+        // leaves a window for a directory to appear and be deleted unannounced.
+        let plan = await getSkillsStatus(targets, next);
+        for (let attempt = 0; attempt < MAX_SAVE_ATTEMPTS; attempt += 1) {
+            const removals = plan.ops.filter((op) => op.kind === "delete").map((op) => op.name);
+            if (removals.some((name) => !confirmed.has(name))) {
+                return {
+                    ...(await getSkillsStatus(targets, previous)),
+                    selection: previous,
+                    confirmationRequired: { removals },
+                };
+            }
+            // Capture only paths this frozen plan can mutate. Capturing every managed
+            // path would make rollback delete a new external directory that appeared
+            // after the scan merely because it was absent from the snapshot.
+            const transaction = await beginSkillsTransaction(targets, previous, next, plan.ops);
+            let status;
+            try {
+                status = await installSkills(targets, next, {
+                    ...plan,
+                    // beginSkillsTransaction atomically staged these directories. Running
+                    // removeSkill afterward would delete a path another writer recreated.
+                    ops: plan.ops.filter((op) => op.kind !== "delete"),
+                });
+            }
+            catch (error) {
+                await transaction.rollback();
+                throw error;
+            }
+            // An empty custom selection converges to the intentional not-installed
+            // state; zero remaining operations is the invariant, not the label.
+            if (status.ops.length === 0) {
+                try {
+                    await selectionStore.set(next);
+                }
+                catch (error) {
+                    await transaction.rollback();
+                    throw error;
+                }
+                try {
+                    await transaction.commit();
+                }
+                catch {
+                    // Selection and disk convergence are already durable. The owned
+                    // manifest stays behind so the next serialized operation retries
+                    // cleanup; reporting this save as failed would misstate its outcome.
+                }
+                return { ...status, selection: next, confirmationRequired: null };
+            }
+            // The frozen plan became incomplete while it was being applied. Put only
+            // its mutations back, rescan, and either request confirmation for a new
+            // deletion or retry harmless additions/updates from the fresh plan.
+            await transaction.rollback();
+            plan = await getSkillsStatus(targets, next);
+        }
+        throw new Error("Skills changed repeatedly while the selection was being saved");
+    }
+    async function importLegacySelectionIfUnset(selection) {
+        if (await selectionStore.isSet()) {
+            return { imported: false, selection: await selectionStore.get() };
+        }
+        const imported = await selectionStore.set(selection);
+        return { imported: true, selection: imported };
+    }
+    return {
+        status: () => serialize(() => converge(getSkillsStatus)),
+        install: () => serialize(() => converge(updateSkills)),
+        update: () => serialize(() => converge(updateSkills)),
+        uninstall: () => serialize(() => converge(uninstallSkills)),
+        autoUpdate: () => serialize(() => converge(autoUpdateInstalledSkills)),
+        save: (selection) => serialize(() => saveSelection(selection)),
+        importLegacySelectionIfUnset: (selection) => serialize(() => importLegacySelectionIfUnset(selection)),
+    };
+}
+//# sourceMappingURL=controller.js.map

package/dist/server/server/orchestration-skills/internal/operations.d.ts

@@ -0,0 +1,43 @@
+import type { AgentSkillSelection } from "@camerontaylor/paseo-protocol/messages";
+export type SkillsState = "not-installed" | "up-to-date" | "drift";
+export type SkillOp = {
+    kind: "add";
+    name: string;
+} | {
+    kind: "update";
+    name: string;
+} | {
+    kind: "delete";
+    name: string;
+};
+/** What the user asked to have installed. `all` follows the bundle as it grows. */
+export type SkillSelection = AgentSkillSelection;
+export interface SkillsStatus {
+    state: SkillsState;
+    ops: SkillOp[];
+    /** Every skill the bundle currently ships, sorted. The selectable catalog. */
+    available: string[];
+    /**
+     * Managed skills with a directory in at least one agent home, sorted. An `add`
+     * op means "missing from at least one target", so it cannot answer whether
+     * there is anything on disk to delete — this can.
+     */
+    installed: string[];
+}
+export interface SkillTargets {
+    sourceDir: string;
+    agentsDir: string;
+    claudeDir: string;
+    codexDir: string;
+}
+export declare const LEGACY_SKILL_NAMES: readonly ["paseo-chat", "paseo-epic", "paseo-orchestrate", "paseo-orchestrator"];
+/** The names a convergence may create, replace, or delete. */
+export declare function listManagedSkillNames(sourceDir: string): Promise<string[]>;
+export declare function getSkillsStatus(targets: SkillTargets, selection: SkillSelection): Promise<SkillsStatus>;
+export declare function installSkills(targets: SkillTargets, selection: SkillSelection, 
+/** Apply exactly this plan instead of rescanning, so a confirmed plan is the applied plan. */
+plan?: SkillsStatus): Promise<SkillsStatus>;
+export declare function updateSkills(targets: SkillTargets, selection: SkillSelection): Promise<SkillsStatus>;
+export declare function autoUpdateInstalledSkills(targets: SkillTargets, selection: SkillSelection): Promise<SkillsStatus>;
+export declare function uninstallSkills(targets: SkillTargets, selection: SkillSelection): Promise<SkillsStatus>;
+//# sourceMappingURL=operations.d.ts.map