commandmate 0.11.3 → 0.12.0

package/dist/server/src/lib/skills/semver.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * SemVer 2.0 handling for the Skills distribution contract (Issue #1228)
+ *
+ * `src/lib/version-checker.ts` intentionally compares only `major.minor.patch`
+ * of CommandMate's own release tags and tolerates a `v` prefix. The Skill
+ * contract needs full SemVer 2.0 precedence (prerelease ordering, build
+ * metadata ignored) and rejects the `v` prefix, so it gets its own strict
+ * implementation instead of loosening the update-check semantics.
+ *
+ * The range grammar is deliberately a small, total subset of npm's: a
+ * space-separated AND list of comparators. `||`, `x`-ranges, `*` and hyphen
+ * ranges are rejected so a range always has one unambiguous reading.
+ *
+ * @module lib/skills/semver
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION_RANGE_MAX_COMPARATORS = exports.VERSION_RANGE_MAX_LENGTH = exports.SEMVER_MAX_LENGTH = exports.SEMVER_2_PATTERN = void 0;
+exports.parseSemVer = parseSemVer;
+exports.isValidSemVer = isValidSemVer;
+exports.compareParsedSemVer = compareParsedSemVer;
+exports.compareSemVer = compareSemVer;
+exports.parseSkillVersionRange = parseSkillVersionRange;
+exports.isValidSkillVersionRange = isValidSkillVersionRange;
+exports.satisfiesSkillVersionRange = satisfiesSkillVersionRange;
+/** Strict SemVer 2.0 grammar. No `v` prefix, no leading zeroes. */
+exports.SEMVER_2_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+/** Maximum accepted length of a version string. */
+exports.SEMVER_MAX_LENGTH = 64;
+/** Maximum accepted length of a range expression. */
+exports.VERSION_RANGE_MAX_LENGTH = 100;
+/** Maximum number of comparators in one range. */
+exports.VERSION_RANGE_MAX_COMPARATORS = 4;
+/** Parse a strict SemVer 2.0 string. Returns null when invalid. */
+function parseSemVer(version) {
+    if (typeof version !== 'string' || version.length > exports.SEMVER_MAX_LENGTH)
+        return null;
+    const match = exports.SEMVER_2_PATTERN.exec(version);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] ? match[4].split('.') : [],
+        build: match[5] ? match[5].split('.') : [],
+    };
+}
+/** True when the string is a strict SemVer 2.0 version. */
+function isValidSemVer(version) {
+    return parseSemVer(version) !== null;
+}
+function comparePrerelease(a, b) {
+    // A release outranks any prerelease of the same major.minor.patch.
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1;
+    if (b.length === 0)
+        return -1;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const left = a[i];
+        const right = b[i];
+        if (left === right)
+            continue;
+        const leftNumeric = /^\d+$/.test(left);
+        const rightNumeric = /^\d+$/.test(right);
+        if (leftNumeric && rightNumeric)
+            return Number(left) < Number(right) ? -1 : 1;
+        if (leftNumeric)
+            return -1;
+        if (rightNumeric)
+            return 1;
+        return left < right ? -1 : 1;
+    }
+    if (a.length === b.length)
+        return 0;
+    return a.length < b.length ? -1 : 1;
+}
+/** Compare two parsed versions by SemVer 2.0 precedence. Build metadata is ignored. */
+function compareParsedSemVer(a, b) {
+    if (a.major !== b.major)
+        return a.major < b.major ? -1 : 1;
+    if (a.minor !== b.minor)
+        return a.minor < b.minor ? -1 : 1;
+    if (a.patch !== b.patch)
+        return a.patch < b.patch ? -1 : 1;
+    return comparePrerelease(a.prerelease, b.prerelease);
+}
+/**
+ * Compare two SemVer 2.0 strings.
+ *
+ * @returns -1, 0 or 1; null when either input is not valid SemVer 2.0.
+ */
+function compareSemVer(a, b) {
+    const left = parseSemVer(a);
+    const right = parseSemVer(b);
+    if (!left || !right)
+        return null;
+    return compareParsedSemVer(left, right);
+}
+function samePrecedenceTuple(a, b) {
+    return a.major === b.major && a.minor === b.minor && a.patch === b.patch;
+}
+function caretUpperBound(v) {
+    if (v.major > 0)
+        return { major: v.major + 1, minor: 0, patch: 0, prerelease: [], build: [] };
+    if (v.minor > 0)
+        return { major: 0, minor: v.minor + 1, patch: 0, prerelease: [], build: [] };
+    return { major: 0, minor: 0, patch: v.patch + 1, prerelease: [], build: [] };
+}
+function tildeUpperBound(v) {
+    return { major: v.major, minor: v.minor + 1, patch: 0, prerelease: [], build: [] };
+}
+/**
+ * Parse a range into desugared comparators combined with AND.
+ *
+ * Accepted tokens: `x.y.z`, `=x.y.z`, `>x.y.z`, `>=x.y.z`, `<x.y.z`, `<=x.y.z`,
+ * `^x.y.z`, `~x.y.z`. Returns null for anything else.
+ */
+function parseSkillVersionRange(range) {
+    if (typeof range !== 'string')
+        return null;
+    const trimmed = range.trim();
+    if (trimmed.length === 0 || trimmed.length > exports.VERSION_RANGE_MAX_LENGTH)
+        return null;
+    if (trimmed.includes('||'))
+        return null;
+    const tokens = trimmed.split(/\s+/);
+    if (tokens.length > exports.VERSION_RANGE_MAX_COMPARATORS)
+        return null;
+    const comparators = [];
+    for (const token of tokens) {
+        const match = /^(>=|<=|>|<|=|\^|~)?(.+)$/.exec(token);
+        if (!match)
+            return null;
+        const operator = match[1] ?? '=';
+        const version = parseSemVer(match[2]);
+        if (!version)
+            return null;
+        if (operator === '^' || operator === '~') {
+            const upper = operator === '^' ? caretUpperBound(version) : tildeUpperBound(version);
+            comparators.push({ operator: '>=', version });
+            comparators.push({ operator: '<', version: upper });
+            continue;
+        }
+        comparators.push({ operator: operator, version });
+    }
+    if (comparators.length > exports.VERSION_RANGE_MAX_COMPARATORS * 2)
+        return null;
+    return comparators;
+}
+/** True when the range is expressible in the supported grammar. */
+function isValidSkillVersionRange(range) {
+    return parseSkillVersionRange(range) !== null;
+}
+function satisfiesComparator(version, comparator) {
+    const cmp = compareParsedSemVer(version, comparator.version);
+    switch (comparator.operator) {
+        case '=':
+            return cmp === 0;
+        case '>':
+            return cmp > 0;
+        case '>=':
+            return cmp >= 0;
+        case '<':
+            return cmp < 0;
+        case '<=':
+            return cmp <= 0;
+    }
+}
+/**
+ * Test a version against a range.
+ *
+ * A prerelease version only satisfies a range when some comparator names the
+ * same `major.minor.patch` *and* itself carries a prerelease. Without this rule
+ * `>=1.0.0` would silently accept `2.0.0-alpha.1`.
+ *
+ * @returns false for an invalid version or an unparsable range (fail closed).
+ */
+function satisfiesSkillVersionRange(version, range) {
+    const parsed = parseSemVer(version);
+    const comparators = parseSkillVersionRange(range);
+    if (!parsed || !comparators)
+        return false;
+    if (parsed.prerelease.length > 0) {
+        const allowed = comparators.some((c) => c.version.prerelease.length > 0 && samePrecedenceTuple(parsed, c.version));
+        if (!allowed)
+            return false;
+    }
+    return comparators.every((c) => satisfiesComparator(parsed, c));
+}

package/dist/server/src/lib/skills/snapshot-store.js

@@ -0,0 +1,334 @@
+"use strict";
+/**
+ * Read-only snapshot store for verified Skill artifacts (Issue #1229)
+ *
+ * A snapshot is verified artifact bytes parked in the service-owned data root
+ * so a later step (#1230 extraction, #1231 install) can read them without
+ * re-downloading. Snapshots are addressed by an opaque ID: absolute paths never
+ * leave this module, because they identify the machine and the data root.
+ *
+ * Lifetime is reference-counted with a TTL backstop. A snapshot with live
+ * references is never swept, no matter how much quota pressure there is —
+ * failing the new download is correct, corrupting an in-progress install is
+ * not. Process restart drops every reference, so initialization treats whatever
+ * is on disk as orphaned and removes it.
+ *
+ * @module lib/skills/snapshot-store
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initSkillSnapshotStore = initSkillSnapshotStore;
+exports.isSkillSnapshotStoreInitialized = isSkillSnapshotStoreInitialized;
+exports.createSkillSnapshot = createSkillSnapshot;
+exports.acquireSkillSnapshot = acquireSkillSnapshot;
+exports.releaseSkillSnapshot = releaseSkillSnapshot;
+exports.getSkillSnapshot = getSkillSnapshot;
+exports.readSkillSnapshotBytes = readSkillSnapshotBytes;
+exports.resolveSkillSnapshotPath = resolveSkillSnapshotPath;
+exports.sweepSkillSnapshots = sweepSkillSnapshots;
+exports.getSkillSnapshotUsage = getSkillSnapshotUsage;
+exports.resetSkillSnapshotStoreForTesting = resetSkillSnapshotStoreForTesting;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const install_context_1 = require("../../cli/utils/install-context");
+const skill_security_config_1 = require("../../config/skill-security-config");
+const system_directories_1 = require("../../config/system-directories");
+const skills_1 = require("../../lib/skills");
+const integrity_1 = require("../../lib/skills/integrity");
+const state = globalThis.__skillSnapshotStore ??
+    (globalThis.__skillSnapshotStore = { rootDir: null, records: new Map(), totalBytes: 0 });
+const SNAPSHOT_FILE_SUFFIX = '.artifact';
+// =============================================================================
+// Initialization
+// =============================================================================
+function resolveDefaultRoot() {
+    return path_1.default.join((0, install_context_1.getConfigDir)(), 'data', skill_security_config_1.SKILL_SNAPSHOT_DIRNAME);
+}
+/**
+ * Prepare the snapshot root and drop anything left behind by a previous process.
+ *
+ * Repeated calls with the same root are no-ops so a warm store is not wiped by
+ * a second consumer initializing lazily.
+ *
+ * @param options.rootDir Override for tests and for callers that own their data root
+ * @returns The resolved snapshot root
+ * @throws SkillFetchError with `STORE_IO`
+ */
+function initSkillSnapshotStore(options = {}) {
+    const rootDir = path_1.default.resolve(options.rootDir ?? resolveDefaultRoot());
+    if ((0, system_directories_1.isSystemDirectory)(rootDir)) {
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.STORE_IO, { reason: 'system-directory' });
+    }
+    if (state.rootDir === rootDir)
+        return rootDir;
+    try {
+        (0, fs_1.mkdirSync)(rootDir, { recursive: true, mode: skill_security_config_1.SKILL_SNAPSHOT_DIR_MODE });
+        (0, fs_1.chmodSync)(rootDir, skill_security_config_1.SKILL_SNAPSHOT_DIR_MODE);
+    }
+    catch {
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.STORE_IO, { reason: 'mkdir' });
+    }
+    state.rootDir = rootDir;
+    state.records.clear();
+    state.totalBytes = 0;
+    purgeOrphanFiles();
+    return rootDir;
+}
+function requireRoot() {
+    if (!state.rootDir)
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.STORE_UNINITIALIZED);
+    return state.rootDir;
+}
+/**
+ * Whether a data root has been resolved.
+ *
+ * For callers that may run before the first artifact download — the background
+ * sweeper starts with the process, the store only on first use — and must skip
+ * rather than treat an untouched store as an error.
+ */
+function isSkillSnapshotStoreInitialized() {
+    return state.rootDir !== null;
+}
+/** Remove every snapshot file the in-memory index does not account for. */
+function purgeOrphanFiles() {
+    const rootDir = requireRoot();
+    const tracked = new Set([...state.records.values()].map((record) => record.filename));
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(rootDir);
+    }
+    catch {
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.STORE_IO, { reason: 'readdir' });
+    }
+    for (const entry of entries) {
+        if (tracked.has(entry))
+            continue;
+        (0, fs_1.rmSync)(path_1.default.join(rootDir, entry), { force: true, recursive: true });
+    }
+}
+// =============================================================================
+// Internals
+// =============================================================================
+function filePathOf(record) {
+    return path_1.default.join(requireRoot(), record.filename);
+}
+function removeRecord(record) {
+    (0, fs_1.rmSync)(filePathOf(record), { force: true });
+    state.records.delete(record.snapshotId);
+    state.totalBytes -= record.size;
+}
+function requireRecord(snapshotId) {
+    requireRoot();
+    if (!skill_security_config_1.SKILL_SNAPSHOT_ID_PATTERN.test(snapshotId)) {
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.SNAPSHOT_NOT_FOUND);
+    }
+    const record = state.records.get(snapshotId);
+    if (!record)
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.SNAPSHOT_NOT_FOUND);
+    if (record.refCount === 0 && Date.now() >= record.expiresAt) {
+        removeRecord(record);
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.SNAPSHOT_EXPIRED);
+    }
+    return record;
+}
+function toHandle(record) {
+    return {
+        snapshotId: record.snapshotId,
+        skillId: record.skillId,
+        version: record.version,
+        commit: record.commit,
+        sha256: record.sha256,
+        size: record.size,
+        expiresAt: record.expiresAt,
+    };
+}
+function touch(record, now) {
+    record.lastAccessedAt = now;
+    record.expiresAt = now + skill_security_config_1.SKILL_SNAPSHOT_TTL_MS;
+}
+/**
+ * Free space for an incoming snapshot by evicting unreferenced ones.
+ *
+ * Expired entries go first, then least-recently-used. Referenced snapshots are
+ * never candidates, so a full store rejects the newcomer instead.
+ */
+function makeRoomFor(size, now) {
+    const fits = () => state.totalBytes + size <= skill_security_config_1.SKILL_SNAPSHOT_TOTAL_QUOTA_BYTES &&
+        state.records.size < skill_security_config_1.SKILL_SNAPSHOT_MAX_COUNT;
+    if (fits())
+        return;
+    const candidates = [...state.records.values()]
+        .filter((record) => record.refCount === 0)
+        .sort((a, b) => {
+        const aExpired = now >= a.expiresAt ? 0 : 1;
+        const bExpired = now >= b.expiresAt ? 0 : 1;
+        if (aExpired !== bExpired)
+            return aExpired - bExpired;
+        return a.lastAccessedAt - b.lastAccessedAt;
+    });
+    for (const candidate of candidates) {
+        if (fits())
+            return;
+        removeRecord(candidate);
+    }
+    if (!fits()) {
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.QUOTA_EXCEEDED, {
+            requested: size,
+            limit: skill_security_config_1.SKILL_SNAPSHOT_TOTAL_QUOTA_BYTES,
+        });
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Store verified artifact bytes as a read-only snapshot with one reference held.
+ *
+ * The digest is recomputed here rather than trusted from the downloader: this
+ * is the last point before bytes become readable by another module, and bytes
+ * that do not match the Catalog must never become visible as a snapshot.
+ *
+ * Bytes already snapshotted under the same digest are shared: the existing
+ * snapshot gains a reference and no second copy is written.
+ *
+ * @throws SkillFetchError — `CHECKSUM_MISMATCH`, `QUOTA_EXCEEDED`, `STORE_IO`
+ */
+function createSkillSnapshot(input) {
+    const rootDir = requireRoot();
+    const now = Date.now();
+    const size = input.bytes.byteLength;
+    if (size <= 0 || size > skills_1.SKILL_ARTIFACT_MAX_SIZE) {
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.SIZE_LIMIT_EXCEEDED, {
+            limit: skills_1.SKILL_ARTIFACT_MAX_SIZE,
+        });
+    }
+    if (!(0, integrity_1.digestMatches)(input.sha256, (0, integrity_1.computeSha256Hex)(input.bytes))) {
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.CHECKSUM_MISMATCH);
+    }
+    for (const record of state.records.values()) {
+        if (record.sha256 === input.sha256 && (0, fs_1.existsSync)(filePathOf(record))) {
+            record.refCount += 1;
+            touch(record, now);
+            return toHandle(record);
+        }
+    }
+    makeRoomFor(size, now);
+    const snapshotId = (0, crypto_1.randomBytes)(skill_security_config_1.SKILL_SNAPSHOT_ID_BYTES).toString('hex');
+    const filename = `${snapshotId}${SNAPSHOT_FILE_SUFFIX}`;
+    const finalPath = path_1.default.join(rootDir, filename);
+    const stagingPath = `${finalPath}.tmp`;
+    try {
+        (0, fs_1.writeFileSync)(stagingPath, input.bytes, { mode: 0o600 });
+        (0, fs_1.chmodSync)(stagingPath, skill_security_config_1.SKILL_SNAPSHOT_FILE_MODE);
+        (0, fs_1.renameSync)(stagingPath, finalPath);
+    }
+    catch {
+        (0, fs_1.rmSync)(stagingPath, { force: true });
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.STORE_IO, { reason: 'write' });
+    }
+    const record = {
+        snapshotId,
+        skillId: input.skillId,
+        version: input.version,
+        commit: input.commit,
+        sha256: input.sha256,
+        size,
+        expiresAt: now + skill_security_config_1.SKILL_SNAPSHOT_TTL_MS,
+        refCount: 1,
+        lastAccessedAt: now,
+        filename,
+    };
+    state.records.set(snapshotId, record);
+    state.totalBytes += size;
+    return toHandle(record);
+}
+/** Take an additional reference, extending the TTL. */
+function acquireSkillSnapshot(snapshotId) {
+    const record = requireRecord(snapshotId);
+    record.refCount += 1;
+    touch(record, Date.now());
+    return toHandle(record);
+}
+/**
+ * Drop one reference.
+ *
+ * The bytes stay until the TTL elapses or quota pressure evicts them, so a
+ * retry right after a failed install does not have to re-download. Releasing an
+ * unknown ID is a no-op: cleanup paths must be safe to run twice.
+ */
+function releaseSkillSnapshot(snapshotId) {
+    const record = state.records.get(snapshotId);
+    if (!record)
+        return;
+    if (record.refCount > 0)
+        record.refCount -= 1;
+    if (record.refCount === 0)
+        record.lastAccessedAt = Date.now();
+}
+/** Read a snapshot's metadata without taking a reference. */
+function getSkillSnapshot(snapshotId) {
+    return toHandle(requireRecord(snapshotId));
+}
+/** Read the snapshot bytes. */
+function readSkillSnapshotBytes(snapshotId) {
+    const record = requireRecord(snapshotId);
+    try {
+        const bytes = (0, fs_1.readFileSync)(filePathOf(record));
+        record.lastAccessedAt = Date.now();
+        return bytes;
+    }
+    catch {
+        throw new integrity_1.SkillFetchError(integrity_1.SkillFetchErrorCode.STORE_IO, { reason: 'read' });
+    }
+}
+/**
+ * Absolute path of a snapshot file.
+ *
+ * For modules that must hand a path to a streaming reader (#1230 extraction).
+ * The result identifies the machine's data root and must never reach an API
+ * response, a log line or an error message.
+ *
+ * @internal
+ */
+function resolveSkillSnapshotPath(snapshotId) {
+    return filePathOf(requireRecord(snapshotId));
+}
+/**
+ * Remove expired, unreferenced snapshots and any untracked file in the root.
+ *
+ * @returns Number of snapshots removed
+ */
+function sweepSkillSnapshots(options = {}) {
+    requireRoot();
+    const now = options.now ?? Date.now();
+    let removed = 0;
+    for (const record of [...state.records.values()]) {
+        if (record.refCount === 0 && now >= record.expiresAt) {
+            removeRecord(record);
+            removed += 1;
+        }
+    }
+    purgeOrphanFiles();
+    return removed;
+}
+/** Current disk usage in bytes, for quota assertions and diagnostics. */
+function getSkillSnapshotUsage() {
+    return { totalBytes: state.totalBytes, count: state.records.size };
+}
+/**
+ * Drop every snapshot and forget the root.
+ * @internal
+ */
+function resetSkillSnapshotStoreForTesting() {
+    if (state.rootDir && (0, fs_1.existsSync)(state.rootDir)) {
+        for (const record of [...state.records.values()]) {
+            (0, fs_1.rmSync)(path_1.default.join(state.rootDir, record.filename), { force: true });
+        }
+    }
+    state.rootDir = null;
+    state.records.clear();
+    state.totalBytes = 0;
+}

package/dist/server/src/lib/skills/startup-reconcile.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Startup wiring for Skill operation crash recovery (Issue #1428)
+ *
+ * #1234 built {@link reconcileSkillOperations} and left the concrete ports it
+ * needs — *is the payload on disk?* and *rebuild the index row* — to the layers
+ * that own the filesystem and the DB (#1235/#1236). This module is the assembly
+ * point those pieces were missing: it constructs the production ports and runs
+ * reconciliation, and it is the single function the server startup path calls so
+ * that a restart converges every interrupted install/uninstall on one answer.
+ *
+ * It is deliberately the *only* place the startup ports are assembled. The
+ * Phase 1 gap that shipped a never-invoked reconciler happened because the tests
+ * imported the library directly and never crossed the startup seam; this
+ * function is what both `server.ts` and its test now go through, so a future
+ * regression that unwires it fails a test rather than passing silently.
+ *
+ * Running here also garbage-collects the journal: terminal entries past their
+ * retention window are pruned, so the journal directory tracks the operations of
+ * one window rather than growing without bound.
+ *
+ * @module lib/skills/startup-reconcile
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSkillReconcilerPorts = buildSkillReconcilerPorts;
+exports.runSkillStartupReconciliation = runSkillStartupReconciliation;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const db_1 = require("../../lib/db");
+const logger_1 = require("../../lib/logger");
+const integrity_1 = require("../../lib/skills/integrity");
+const install_plan_1 = require("../../lib/skills/install-plan");
+const install_apply_1 = require("../../lib/skills/install-apply");
+const uninstall_apply_1 = require("../../lib/skills/uninstall-apply");
+const installed_state_1 = require("../../lib/skills/installed-state");
+const operation_audit_1 = require("../../lib/skills/operation-audit");
+const operation_journal_1 = require("../../lib/skills/operation-journal");
+const operation_reconciler_1 = require("../../lib/skills/operation-reconciler");
+const reconcileLogger = (0, logger_1.createLogger)('lib/skills/startup-reconcile');
+/**
+ * Whether an operation's kind removes payload (uninstall) rather than adding it.
+ * `update` re-installs, so it shares the install-side probe and index write.
+ */
+function isRemovalOperation(entry) {
+    return entry.operation === 'uninstall';
+}
+/**
+ * Build the reconciler ports against the real filesystem and database.
+ *
+ * The reconciler asks one filesystem question and performs one index write per
+ * entry; both dispatch on the operation kind because "did it land?" and "rebuild
+ * the row" mean opposite things for an install and an uninstall.
+ */
+function buildSkillReconcilerPorts(db, options = {}) {
+    const resolveWorktreePath = options.resolveWorktreePath ??
+        ((worktreeId) => {
+            const worktree = (0, db_1.getWorktreeById)(db, worktreeId);
+            return worktree ? worktree.path : null;
+        });
+    return {
+        hasCommittedPayload: (entry) => {
+            const worktreePath = resolveWorktreePath(entry.target.worktreeId);
+            if (worktreePath === null) {
+                // The worktree is gone: an install could not have left payload behind,
+                // and an uninstall's payload is by definition no longer present.
+                return isRemovalOperation(entry);
+            }
+            return isRemovalOperation(entry)
+                ? (0, uninstall_apply_1.hasRemovedSkillPayload)(worktreePath, entry.target.skillId, entry.receiptDigest)
+                : (0, install_apply_1.hasCommittedSkillPayload)(worktreePath, entry.target.skillId, entry.receiptDigest);
+        },
+        reindex: (entry) => {
+            if (isRemovalOperation(entry)) {
+                // The row is dropped by (worktree, skill); no path or receipt is needed,
+                // and the delete is idempotent so a replay after a partial pass is safe.
+                (0, installed_state_1.deleteSkillInstallation)(db, entry.target.worktreeId, entry.target.skillId);
+                return;
+            }
+            const worktreePath = resolveWorktreePath(entry.target.worktreeId);
+            if (worktreePath === null) {
+                throw new Error('worktree path is unavailable for reindex');
+            }
+            // Converge any secondary root a partial multi-root install did not reach,
+            // copying the byte-identical payload forward from the committed primary
+            // (#1460). Best-effort: a root blocked by a user file must not stall the
+            // index write, which is what actually makes the install visible.
+            try {
+                (0, install_apply_1.completeSecondarySkillInstallRoots)(worktreePath, (0, fs_1.realpathSync)(worktreePath), entry.target.skillId);
+            }
+            catch (error) {
+                reconcileLogger.warn('skill-secondary-root-convergence-failed', {
+                    operationId: entry.operationId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            // The index row is rebuilt from the receipt that actually landed rather
+            // than from the journal, which never carried the full receipt. The receipt
+            // on disk is the same artifact the user can see, so the row cannot drift
+            // from it.
+            const installRootAbs = (0, install_apply_1.resolveSkillInstallTarget)(worktreePath, entry.target.skillId);
+            const bytes = (0, fs_1.readFileSync)((0, path_1.join)(installRootAbs, install_plan_1.SKILL_RECEIPT_FILENAME));
+            const receipt = (0, install_plan_1.parseInstalledReceipt)(bytes);
+            if (receipt === null) {
+                throw new Error('receipt on disk is unreadable during reindex');
+            }
+            (0, installed_state_1.upsertSkillInstallation)(db, {
+                worktreeId: entry.target.worktreeId,
+                receipt,
+                receiptSha256: (0, integrity_1.computeSha256Hex)(bytes),
+                operationId: entry.operationId,
+                installedAt: entry.fsCommittedAt ?? options.now ?? Date.now(),
+            });
+        },
+        recordAudit: (input) => {
+            (0, operation_audit_1.recordSkillOperationAudit)(db, input);
+        },
+    };
+}
+/**
+ * Converge interrupted Skill operations and collect expired journal entries.
+ *
+ * Called once at server startup, after migrations (the audit table is
+ * migration-owned) and before the server begins accepting requests. Returns the
+ * reconciliation report augmented with what retention pruned.
+ */
+function runSkillStartupReconciliation(db, options = {}) {
+    const ports = buildSkillReconcilerPorts(db, options);
+    const report = (0, operation_reconciler_1.reconcileSkillOperations)(ports, options);
+    // Pruning runs after convergence: an entry that just converged to SUCCEEDED
+    // has a fresh `updatedAt` and is well inside its window, so this pass only
+    // collects entries that were already terminal in an earlier one.
+    const prunedKeys = (0, operation_journal_1.pruneExpiredSkillOperationJournal)({
+        root: options.root,
+        now: options.now,
+        retentionMs: options.retentionMs,
+    });
+    return { ...report, prunedKeys, pruned: prunedKeys.length };
+}