openmausbot 0.1.93 → 0.1.94

package/dist-server/server/proxy-paths.js

@@ -40,6 +40,7 @@ export const SPAWNED_PROXIES = {
     dweb: resolveProxy("drivers/dweb-proxy"),
     connectors: resolveProxy("connector-proxy"),
     mcpGate: resolveProxy("mcp-gate"),
+    mcpRemote: resolveProxy("mcp-remote-proxy"),
     phone: resolveProxy("drivers/phone-proxy"),
     hook: resolveProxy("hooks/omb-hook"),
     // Loaded by the external `pi` process via `-e`, not by this server — but

package/dist-server/server/redact.js

@@ -18,6 +18,8 @@ const SECRET_KEY_PARTS = ["token", "secret", "password", "passwd", "apikey", "ap
  * every real one is spelled (API_KEY, consumer-key, xai_key). */
 function isSecretName(name) {
     const lower = name.toLowerCase();
+    if (lower === "omb_gate_upstream" || lower === "omb_remote_mcp_server")
+        return true;
     if (SECRET_KEY_PARTS.some((part) => lower.includes(part)))
         return true;
     return /(^|[_.-])keys?$/.test(lower);

package/dist-server/server/request-auth.js

@@ -1,6 +1,6 @@
 import { timingSafeEqual } from "node:crypto";
 import { isIP } from "node:net";
-import { denyReason as companionDenial } from "../companion/src/routes.js";
+import { denyReason as companionDenial, isCompanionNotice } from "../companion/src/routes.js";
 const LOOPBACK_SCOPES = ["admin", "client"];
 const SERVICE_SCOPES = ["client"];
 /** What a `service`-trust loopback caller may reach, and nothing else:
@@ -442,7 +442,8 @@ export function resolveRequestAuth(req, options) {
             if (!secureTokenMatch(companionToken, options.companionMutationToken ?? "") ||
                 req.headers["x-openmausbot-companion"] !== "1" ||
                 !/^[\w-]{1,128}$/.test(headerValue(req.headers["x-openmausbot-companion-device"]) ?? "") ||
-                companionDenial({ path, method, authenticated: true }))
+                // a phone's allowlisted route, or the companion's own notice (an unpaired phone)
+                (companionDenial({ path, method, authenticated: true }) && !isCompanionNotice(method, path)))
                 return deny(403, "forbidden: invalid companion request");
             return { auth: { kind: "loopback", scopes: LOOPBACK_SCOPES }, status: 401, error: "" };
         }

package/dist-server/server/routes/live.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { LiveSessionError, MAX_SDP_BYTES } from "../live-call.js";
+import { LiveCallBusyError } from "../live-call-controller.js";
+import { PASS } from "./table.js";
+const id = z.string().regex(/^[\w-]{1,120}$/);
+const sessionBody = z.object({
+    botId: id,
+    threadId: id.optional(),
+    // Not trimmed: the SDP offer goes to OpenAI byte for byte.
+    sdp: z.string().min(1).refine((sdp) => Buffer.byteLength(sdp) <= MAX_SDP_BYTES),
+    client: z.enum(["desktop", "ios", "android"]),
+}).strict();
+const endBody = z.object({ callId: z.string().min(1).max(120) }).strict();
+// Strict, so `key` (or anything else) is refused rather than ignored: the key
+// is only ever set on the computer that runs the harness.
+const settingsBody = z.object({
+    voice: z.string().trim().max(40).regex(/^[a-z]*$/).optional(),
+    readTypedReplies: z.boolean().optional(),
+    idleMinutes: z.number().int().min(1).max(60).optional(),
+}).strict();
+const DEVICE_ID = /^[\w-]{1,128}$/;
+/** The paired phone the companion vouched for, or undefined. The companion
+ * sends its own id for the phone that authenticated (never one the phone
+ * chose); in the desktop app the harness has already checked the companion's
+ * private token before this runs (server/request-auth.ts). */
+function companionDevice(req) {
+    if (req.headers["x-openmausbot-companion"] !== "1")
+        return undefined;
+    const device = req.headers["x-openmausbot-companion-device"];
+    return typeof device === "string" && DEVICE_ID.test(device) ? device : undefined;
+}
+/** The parsed JSON body, or undefined when it is not JSON (the schema then refuses it). */
+async function bodyOf(req, readBody) {
+    try {
+        return await readBody(req);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createLiveRoutes(deps) {
+    return async ({ req, res, path, method, auth, json, readBody }) => {
+        if (!path.startsWith("/api/live/"))
+            return PASS;
+        if (method === "POST" && path === "/api/live/session") {
+            const parsed = sessionBody.safeParse(await bodyOf(req, readBody));
+            if (!parsed.success)
+                return json(res, 400, { error: "The call request was not valid." });
+            const target = deps.resolveTarget(parsed.data.botId, parsed.data.threadId);
+            if (!target)
+                return json(res, 404, { error: "That bot or chat does not exist." });
+            try {
+                // A phone's call is bound to the phone, so unpairing it ends the call.
+                const device = companionDevice(req);
+                const { call, sdp } = await deps.calls.start({ auth, ...(device ? { device } : {}), ...target, client: parsed.data.client, sdp: parsed.data.sdp });
+                return json(res, 201, { call, transport: { type: "webrtc", sdp } });
+            }
+            catch (error) {
+                if (error instanceof LiveCallBusyError)
+                    return json(res, 409, { error: error.message, activeCall: error.call });
+                if (error instanceof LiveSessionError) {
+                    // The one 409 a session refuses with is a missing key.
+                    return json(res, error.status, error.status === 409 ? { error: error.message, needsKey: true } : { error: error.message });
+                }
+                throw error;
+            }
+        }
+        if (method === "POST" && path === "/api/live/call/end") {
+            const parsed = endBody.safeParse(await bodyOf(req, readBody));
+            if (!parsed.success)
+                return json(res, 400, { error: "The request was not valid." });
+            const call = await deps.calls.end(parsed.data.callId);
+            return call ? json(res, 200, { call }) : json(res, 404, { error: "That call is not running." });
+        }
+        if (method === "GET" && path === "/api/live/call")
+            return json(res, 200, { call: deps.calls.current() });
+        // The companion unpaired a phone: end the call that phone holds, if any.
+        if (method === "POST" && path === "/api/live/device-revoked") {
+            if (req.headers["x-openmausbot-companion"] !== "1")
+                return json(res, 403, { error: "Only the phone companion can report an unpaired phone." });
+            const device = companionDevice(req);
+            if (!device)
+                return json(res, 400, { error: "The unpaired phone was not named." });
+            return json(res, 200, { call: deps.calls.deviceRevoked(device) });
+        }
+        if (method === "PATCH" && path === "/api/live/settings") {
+            const parsed = settingsBody.safeParse(await bodyOf(req, readBody));
+            if (!parsed.success) {
+                return json(res, 400, { error: "Those Live settings are not valid. The OpenAI key can only be changed on the computer that runs OpenMausBot." });
+            }
+            // as PUT /api/config: an empty patch is not saved (or broadcast)
+            if (!Object.keys(parsed.data).length)
+                return json(res, 400, { error: "nothing to save" });
+            return json(res, 200, { live: await deps.saveSettings(parsed.data) });
+        }
+        return PASS;
+    };
+}

package/dist-server/server/skill-library.js

@@ -4,6 +4,13 @@
 // declared trigger terms and mounted capabilities.
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join } from "node:path";
+import { createHash } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { mkdirSync } from "node:fs";
+import { z } from "zod";
+import { writeFileAtomic } from "./atomic.js";
+import { DATA_DIR } from "./config.js";
+import { isSkillName, parseSkillMd, SKILL_FILE_MAX_BYTES } from "../shared/skill-md.js";
 const SAFE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function strings(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "string" && item.trim())
@@ -114,3 +121,203 @@ export function renderSkillInstructions(selected, { includeRoot = false } = {})
         return "";
     return selected.map(({ manifest, instructions, directory }) => `\n\n<openmaus-skill id=${JSON.stringify(manifest.id)} version=${JSON.stringify(manifest.version)}${includeRoot ? ` root=${JSON.stringify(directory)}` : ""}>\n${instructions}\n</openmaus-skill>`).join("");
 }
+const skillLibraryEntrySchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    source: z.string(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    importedAt: z.string(),
+    reviewState: z.enum(["approved", "disabled"]),
+    license: z.string().optional(),
+    compatibility: z.string().optional(),
+    tags: z.array(z.string().regex(/^[a-z0-9][a-z0-9-]{0,23}$/)).max(8).optional(),
+    warnings: z.array(z.string()),
+    skippedFiles: z.array(z.string()),
+    package: z.object({
+        installId: z.string().regex(/^[a-f0-9]{32}$/),
+        key: z.string().min(1).max(64),
+        release: z.string().min(1).max(40),
+        r: z.string().regex(/^[a-f0-9]{64}$/),
+        w: z.string().regex(/^[a-f0-9]{64}$/),
+        via: z.literal("preset").optional(),
+    }).optional(),
+});
+const skillLibraryIndexSchema = z.record(z.string(), skillLibraryEntrySchema);
+/** Every library write emits here so later skills-lane consumers can drop
+ * caches without polling. The payload names what changed. */
+export const skillLibraryEvents = new EventEmitter();
+export function skillsLibraryRoot(dataDir = DATA_DIR) {
+    return join(dataDir, "skills-library");
+}
+function libraryIndexPath(root) {
+    return join(root, "index.json");
+}
+export function librarySkillDirectory(root, name) {
+    return join(root, "skills", name);
+}
+/** The path agents are told to read for an assigned library skill. */
+export function librarySkillFilePath(name, root = skillsLibraryRoot()) {
+    return join(root, "skills", name, "SKILL.md");
+}
+/** Where a migrated per-bot copy is preserved. Archives are write-once:
+ * migration never deletes the original bytes, it moves them here. */
+export function libraryArchiveDirectory(root, botId, name) {
+    return join(root, "archive", botId, name);
+}
+/** A missing index is a legitimate empty library; an index that exists but
+ * cannot be read or validated is not, and writers must refuse rather than
+ * replace it and strand every stored skill. */
+function readSkillLibraryIndexState(root) {
+    try {
+        const parsed = JSON.parse(readFileSync(libraryIndexPath(root), "utf8"));
+        const result = skillLibraryIndexSchema.safeParse(parsed);
+        return result.success
+            ? { index: result.data }
+            : { error: "the skills library index is invalid" };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { index: {} };
+        return { error: "the skills library index could not be read" };
+    }
+}
+export function readSkillLibraryIndex(root = skillsLibraryRoot()) {
+    const result = readSkillLibraryIndexState(root);
+    return "error" in result ? {} : result.index;
+}
+function writeSkillLibraryIndex(root, index) {
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    writeFileAtomic(libraryIndexPath(root), `${JSON.stringify(index, null, 2)}\n`, { mode: 0o600 });
+}
+function sha256Hex(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function libraryContentMatches(root, entry) {
+    try {
+        const file = join(librarySkillDirectory(root, entry.name), "SKILL.md");
+        if (!existsSync(file))
+            return false;
+        return sha256Hex(readFileSync(file, "utf8")) === entry.sha256;
+    }
+    catch {
+        return false;
+    }
+}
+function librarySkillListing(root, entry) {
+    const intact = libraryContentMatches(root, entry);
+    return {
+        name: entry.name,
+        description: entry.description,
+        enabled: entry.reviewState === "approved" && intact,
+        editable: false,
+        source: entry.source,
+        sha256: entry.sha256,
+        importedAt: entry.importedAt,
+        ...(entry.license ? { license: entry.license } : {}),
+        ...(entry.compatibility ? { compatibility: entry.compatibility } : {}),
+        tags: entry.tags ?? [],
+        warnings: intact
+            ? entry.warnings
+            : [...entry.warnings, "stored SKILL.md changed after review — enablement is blocked"],
+        skippedFiles: entry.skippedFiles,
+    };
+}
+export function listLibrarySkills(root = skillsLibraryRoot()) {
+    return Object.values(readSkillLibraryIndex(root))
+        .map((entry) => librarySkillListing(root, entry))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Put a skill in the library. Installing the same name with the same
+ * SKILL.md bytes is idempotent (the existing entry wins); the same name
+ * with different bytes is refused, mirroring the per-bot import rule.
+ * Every failure returns `{ error }` — callers fall back. */
+export function installLibrarySkill(input) {
+    const root = input.root ?? skillsLibraryRoot();
+    if (!isSkillName(input.name))
+        return { error: "invalid skill name" };
+    if (Buffer.byteLength(input.instructions, "utf8") > SKILL_FILE_MAX_BYTES) {
+        return { error: `SKILL.md is larger than ${SKILL_FILE_MAX_BYTES / 1024}KB` };
+    }
+    const parsed = parseSkillMd(input.instructions);
+    if ("error" in parsed)
+        return parsed;
+    if (parsed.name !== input.name)
+        return { error: `the skill is named "${parsed.name}", not "${input.name}"` };
+    const sha256 = sha256Hex(input.instructions);
+    const indexRead = readSkillLibraryIndexState(root);
+    if ("error" in indexRead)
+        return indexRead;
+    const index = indexRead.index;
+    const existing = index[input.name];
+    if (existing) {
+        if (existing.sha256 === sha256)
+            return librarySkillListing(root, existing);
+        return { error: `a skill named "${input.name}" is already in the library — choose a different name` };
+    }
+    // Callers such as the library migration do not pass tags; frontmatter
+    // tags parsed from the instructions are the source of record then.
+    const tags = input.tags?.length ? input.tags : parsed.tags;
+    const entry = {
+        name: input.name,
+        description: input.description?.trim() || parsed.description,
+        source: input.source,
+        sha256,
+        importedAt: new Date().toISOString(),
+        reviewState: input.reviewState ?? "disabled",
+        ...(input.license ? { license: input.license } : {}),
+        ...(input.compatibility ? { compatibility: input.compatibility } : {}),
+        ...(tags?.length ? { tags } : {}),
+        warnings: input.warnings ?? [],
+        skippedFiles: [],
+        ...(input.package ? { package: { ...input.package } } : {}),
+    };
+    // Bytes first, index second: the index is the commit point, so a crash
+    // between the two leaves unreferenced bytes, never a dangling entry.
+    mkdirSync(librarySkillDirectory(root, input.name), { recursive: true, mode: 0o700 });
+    writeFileAtomic(join(librarySkillDirectory(root, input.name), "SKILL.md"), input.instructions, { mode: 0o600 });
+    index[input.name] = entry;
+    writeSkillLibraryIndex(root, index);
+    skillLibraryEvents.emit("invalidate", { kind: "install", name: input.name });
+    return librarySkillListing(root, entry);
+}
+export function readLibrarySkillFile(name, root = skillsLibraryRoot()) {
+    if (!isSkillName(name))
+        return null;
+    const entry = readSkillLibraryIndex(root)[name];
+    if (!entry)
+        return null;
+    try {
+        const text = readFileSync(join(librarySkillDirectory(root, name), "SKILL.md"), "utf8");
+        return sha256Hex(text) === entry.sha256 ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function setLibrarySkillReviewState(name, reviewState, root = skillsLibraryRoot()) {
+    if (!isSkillName(name))
+        return { error: "invalid skill name" };
+    const index = readSkillLibraryIndex(root);
+    const entry = index[name];
+    if (!entry)
+        return { error: `no library skill named "${name}"` };
+    if (reviewState === "approved" && !libraryContentMatches(root, entry)) {
+        return { error: "stored SKILL.md changed after review — the library entry cannot be approved" };
+    }
+    entry.reviewState = reviewState;
+    writeSkillLibraryIndex(root, index);
+    skillLibraryEvents.emit("invalidate", { kind: "review-state", name });
+    return librarySkillListing(root, entry);
+}
+/** The lane's one resolution rule, stated once: a skill name means the
+ * bot-private copy when one exists, else the library entry, else the
+ * bundled skill. Later slices route every lookup through this order. */
+export function resolveSkillSourceOrder(name, sources) {
+    if (sources.private !== undefined)
+        return { source: "private", name, value: sources.private };
+    if (sources.library !== undefined)
+        return { source: "library", name, value: sources.library };
+    if (sources.bundled !== undefined)
+        return { source: "bundled", name, value: sources.bundled };
+    return null;
+}

package/dist-server/server/skills-library-migration.js

@@ -0,0 +1,235 @@
+// Skills library migration (features.skillsLibrary, skills lane S1).
+//
+// Per-bot skill copies move into the shared library, deduplicated by the
+// reviewed SKILL.md sha256. Originals are archived under the library root —
+// write-once, never deleted — and the per-bot manifest entry is dropped
+// only after the archive exists and the assignment is durably recorded. The
+// sweep is idempotent through state, not markers: a migrated skill has no
+// manifest entry left to re-read, and an existing archive short-circuits
+// the move.
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { installLibrarySkill, libraryArchiveDirectory, readSkillLibraryIndex, skillsLibraryRoot, } from "./skill-library.js";
+import { listMigratableSkills, removeManifestEntry } from "./skills.js";
+function sha256Hex(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** Move a per-bot skill directory into its archive slot. Same-volume moves
+ * rename; a cross-device fallback copies recursively and verifies the
+ * SKILL.md hash before the copy counts as the archive. */
+function archiveSkillDirectory(source, archive, expectSha256) {
+    mkdirSync(dirname(archive), { recursive: true, mode: 0o700 });
+    // Every source directory gets its own slot: the same sha256 can be
+    // reinstalled after its manifest entry was cleared, so a collision takes
+    // a hash-qualified name, then numeric suffixes, never a silent drop.
+    let destination = archive;
+    if (existsSync(destination)) {
+        const stem = `${archive}.${expectSha256}`;
+        destination = stem;
+        let suffix = 1;
+        while (existsSync(destination))
+            destination = `${stem}.${suffix++}`;
+    }
+    try {
+        renameSync(source, destination);
+    }
+    catch (error) {
+        if (error.code !== "EXDEV")
+            throw error;
+        cpSync(source, destination, { recursive: true, force: false, errorOnExist: true });
+    }
+    const archived = readFileSync(join(destination, "SKILL.md"), "utf8");
+    if (sha256Hex(archived) !== expectSha256) {
+        throw new Error("the archived copy does not match the reviewed sha256");
+    }
+}
+/** Migrate one bot's per-bot skill copies into the library. Org-stamped
+ * skills carry their stamp onto the library entry, so an organization
+ * install becomes a library source instead of a parallel system. A bot is
+ * assigned only when its own copy was enabled; the first copy's enabled
+ * flag still decides the entry's reviewState. */
+export function migrateBotSkillsToLibrary(botId, root = skillsLibraryRoot()) {
+    const outcomes = [];
+    const assigned = [];
+    for (const copy of listMigratableSkills(botId)) {
+        if (!copy.intact || !copy.directory) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: "stored SKILL.md is missing or changed after review" });
+            continue;
+        }
+        // The shared library currently stores SKILL.md only. Moving a package
+        // with scripts/references/assets would make its relative paths vanish
+        // from the bot's usable directory, so keep that working private copy.
+        try {
+            if (readdirSync(copy.directory).some((name) => name !== "SKILL.md")) {
+                outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: "skill has auxiliary files — keeping its complete private directory" });
+                continue;
+            }
+        }
+        catch {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: "could not inspect the private skill directory" });
+            continue;
+        }
+        let instructions;
+        try {
+            instructions = readFileSync(join(copy.directory, "SKILL.md"), "utf8");
+        }
+        catch (error) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: `could not read the stored SKILL.md: ${error instanceof Error ? error.message : String(error)}` });
+            continue;
+        }
+        if (sha256Hex(instructions) !== copy.sha256) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: "stored SKILL.md changed after review" });
+            continue;
+        }
+        const existing = readSkillLibraryIndex(root)[copy.name];
+        if (existing && existing.sha256 !== copy.sha256) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: `the library already has a different "${copy.name}" — rename one of them` });
+            continue;
+        }
+        // The library entry's review state is shared by every assigned bot, so
+        // deduplicating a copy whose own on/off differs from it would silently
+        // flip that bot's switch. Keep the per-bot copy in place for a human to
+        // reconcile instead of archiving and assigning it.
+        if (existing && (existing.reviewState === "approved") !== copy.enabled) {
+            outcomes.push({
+                botId,
+                name: copy.name,
+                outcome: "skipped",
+                detail: `the library "${copy.name}" is ${existing.reviewState === "approved" ? "enabled" : "disabled"} while this bot had it ${copy.enabled ? "enabled" : "disabled"} — align them before migrating`,
+            });
+            continue;
+        }
+        if (!existing) {
+            const installed = installLibrarySkill({
+                name: copy.name,
+                description: copy.description,
+                instructions,
+                source: copy.source,
+                license: copy.license,
+                compatibility: copy.compatibility,
+                reviewState: copy.enabled ? "approved" : "disabled",
+                package: copy.package,
+                root,
+            });
+            if ("error" in installed) {
+                outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: installed.error });
+                continue;
+            }
+            outcomes.push({ botId, name: copy.name, outcome: "migrated" });
+        }
+        else {
+            outcomes.push({ botId, name: copy.name, outcome: "deduplicated", detail: "identical sha256 already in the library" });
+        }
+        // The manifest entry is the only re-readable record of this skill, so
+        // the assignment must be durable before it goes away. Record it in the
+        // pending-assignments file the boot sweep and the standalone script both
+        // replay: if this write — or the later patch to the bot record — fails,
+        // the next boot restores the assignment instead of stranding an
+        // archived skill with no manifest and no assignment.
+        try {
+            const pendingAssignments = readPendingAssignments(root);
+            if (copy.enabled)
+                writePendingAssignments({
+                    ...pendingAssignments,
+                    [botId]: [...new Set([...(pendingAssignments[botId] ?? []), ...assigned, copy.name])].sort(),
+                }, root);
+        }
+        catch (error) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: `could not record the assignment durably: ${error instanceof Error ? error.message : String(error)}` });
+            continue;
+        }
+        try {
+            archiveSkillDirectory(copy.directory, libraryArchiveDirectory(root, botId, copy.name), copy.sha256);
+        }
+        catch (error) {
+            // The library entry is idempotent, so leaving the per-bot copy in
+            // place only means the next sweep retries this skill. The assignment
+            // recorded above replays idempotently, so the extra pending entry a
+            // failed archive leaves behind is harmless.
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: `archiving failed: ${error instanceof Error ? error.message : String(error)}` });
+            continue;
+        }
+        const removed = removeManifestEntry(botId, copy.name, copy.sha256);
+        if ("error" in removed) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: removed.error });
+            continue;
+        }
+        // Assignment follows this bot's own copy.enabled: a disabled copy
+        // migrates its bytes but assigns nothing, so nobody gains a skill
+        // they never turned on.
+        if (copy.enabled)
+            assigned.push(copy.name);
+    }
+    return { ranAt: new Date().toISOString(), outcomes, assignments: assigned.length ? { [botId]: assigned } : {} };
+}
+export function pendingAssignmentsPath(root = skillsLibraryRoot()) {
+    return join(root, "pending-assignments.json");
+}
+/** Assignments waiting to reach bot records: recorded by the standalone
+ * script for a stopped server, and by the migration itself before a
+ * manifest entry is dropped. The next flag-on boot applies them through
+ * the Store, the single writer of bots.json. */
+export function readPendingAssignments(root = skillsLibraryRoot()) {
+    try {
+        const parsed = JSON.parse(readFileSync(pendingAssignmentsPath(root), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const result = {};
+        for (const [botId, names] of Object.entries(parsed)) {
+            if (Array.isArray(names) && names.every((name) => typeof name === "string"))
+                result[botId] = [...names];
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+export function writePendingAssignments(assignments, root = skillsLibraryRoot()) {
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    writeFileAtomic(pendingAssignmentsPath(root), `${JSON.stringify(assignments, null, 2)}\n`, { mode: 0o600 });
+}
+/** The boot sweep: migrate every bot's copies, then apply assignments.
+ * With a `patch` callback (the live server) assignments land on the bot
+ * records directly and any script-recorded pending file is cleared; without
+ * one this only reports. Runs under features.skillsLibrary only. */
+export function runSkillsLibraryBootSweep(options) {
+    const root = options.root ?? skillsLibraryRoot();
+    const outcomes = [];
+    const assignments = {};
+    const pending = options.patch ? readPendingAssignments(root) : {};
+    for (const bot of options.bots) {
+        const report = migrateBotSkillsToLibrary(bot.id, root);
+        outcomes.push(...report.outcomes);
+        const current = bot.assignedSkills ?? [];
+        const merged = [...new Set([...(pending[bot.id] ?? []), ...(report.assignments[bot.id] ?? []), ...current])].sort();
+        const changed = merged.length !== current.length || merged.some((name, index) => name !== current[index]);
+        if (!changed)
+            continue;
+        if (options.patch)
+            options.patch(bot.id, merged);
+        assignments[bot.id] = merged;
+    }
+    // Clear the pending file once every patch applied: entries recorded by
+    // the script before this boot and recovery records written by this run's
+    // migrations are both spent.
+    if (options.patch && (Object.keys(pending).length || Object.keys(readPendingAssignments(root)).length)) {
+        writePendingAssignments({}, root);
+    }
+    return { ranAt: new Date().toISOString(), outcomes, assignments };
+}
+/** Bot ids that have per-bot skill manifests on disk. Used by the
+ * standalone script, which cannot reach the Store. */
+export function botIdsWithSkillState(dataDir) {
+    try {
+        return readdirSync(join(dataDir, "skill-state"), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}