sfora-cli 0.15.0 → 0.16.0

package/README.md

@@ -405,7 +405,7 @@ Reads outside `projects/<slug>/(posts|drafts)`, `inbox/mentions.md`, and
 The desktop app and npm CLI use the same Node-only `sfora-cli/local-core`
 operations. `sfora desktop path/to/file.md` opens a local file in the installed
 Sfora macOS app. `sfora open` continues to open Sfora web URLs. npm installation
-still requires Node 20+; the desktop distribution bundles its own CLI runtime.
+still requires Node 22.13+; the desktop distribution bundles its own CLI runtime.
 Both read the existing `~/.sfora/config.json` profiles. Config writes are atomic
 and process-locked; no account is required for local files or local skill scans.
 
@@ -466,3 +466,64 @@ changes appear here only after publication; use `skills push` or the project
 workbench to change a bundle. Cloud installations record both the immutable
 bundle hash and numeric `sourceVersion`; resolving “latest” pins that version
 before downloading so concurrent publications cannot mix provenance and bytes.
+
+
+### Persistent local skill inventory
+
+Requires Node 22.13 or later. Desktop and CLI share a private SQLite catalogue at `~/.sfora/skills/catalog.sqlite`. Skill names and content hashes are not identity; separate local copies remain separate until explicitly linked.
+
+```sh
+sfora skills roots add ~/.my-skills "My skills"
+sfora skills roots add-project ~/Developer/my-project "My project"
+sfora skills roots --json
+sfora skills inventory --json
+sfora skills roots remove <root-id>
+```
+
+Registered roots and local identities survive restart. Removing a root only removes tracking. Missing or inaccessible skills retain last-known metadata and an unavailable state. `skills scan --json` retains its array result; `skills inventory --json` includes scan warnings. SQLite handles concurrent clients and transaction rollback. Do not edit or delete the catalogue to rebuild observations. Explicit cloud bindings and read-only transfer previews share this catalogue. Transfer execution and recovery remain separate mission increments.
+
+
+### Explicit cloud bindings and transfer previews
+
+```sh
+sfora skills bind <location-id> <cloud-name> --project my-project
+sfora skills bindings --json
+sfora skills status <binding-id> --json
+sfora skills plan <binding-id> push --json
+sfora skills plan <binding-id> pull --json
+sfora skills relocate <location-id> /new/skill-folder
+```
+
+Take the location ID from `skills inventory`. Linking verifies the authenticated member, deployment, organization, project and cloud skill ID. Names are lookup hints. A same-name replacement cannot silently take over a binding. Relocation preserves identity after an explicitly chosen folder move; register the destination discovery root first.
+
+Explicit adoption of equal, verified published and local content establishes a baseline. Differing content starts with an unknown baseline, or preserves an existing confirmed baseline. Status compares fresh local bytes and a pinned published cloud revision against that baseline. It distinguishes synchronized, local changed, remote changed, conflict, missing and unavailable content. An unavailable cloud request exits with an error and never reports synchronization.
+
+Plans contain exact IDs, local and remote hashes, published version, draft revision and per-file byte/mode metadata. They perform no writes. Unknown baselines, conflicts, existing cloud drafts and unverified local ownership block automatic replacement. CLI previews verify ownership against both the installation receipt and the current filesystem object. A replaced link, file or locally edited copy is never treated as an unchanged managed directory. Reviewed pushes can be executed through the journal below. Recovery for local pull/install mutations and migration of the older transfer commands remain tracked by #470 and #472.
+
+The first write upgrades catalogue schema 1 to 2 transactionally after making a private SQLite-consistent `.v1-<id>.sqlite` backup beside the catalogue. Read-only inspection can read schema 1 without upgrading it. Older clients fail closed after an upgrade; update the desktop app and CLI together. Keep the backup until the updated clients have been verified.
+
+
+### Guarded pushes and recovery
+
+```sh
+sfora skills plan <binding-id> push --json > push-plan.json
+sfora skills queue push-plan.json
+sfora skills apply <operation-id>
+sfora skills operations --json
+sfora skills recover <operation-id>
+sfora skills cancel <unstarted-operation-id>
+sfora skills plan-install <cloud-name> --project my-project --skills-target /existing/parent
+```
+
+`apply push-plan.json` queues and starts a push in one command. A reviewed plan is rechecked against current local content, the explicit binding, published version and draft revision. The server must advertise identity-checked writes; the client refuses to apply against an older server. Existing cloud drafts and changed review tokens stop the operation.
+
+The private `~/.sfora/skills/operations.sqlite` journal commits intent before requests and reserves the qualified cloud target across upload/publication. A live worker cannot be recovered by another process. Recover an interrupted worker's operation before starting another operation on its target. Lost responses produce a durable `needs-attention` outcome. Recovery checks whether the exact intended next draft or publication landed before retrying, and a separate confirmation receipt covers interruption during the local baseline commit. Completed operations are not republished. Cancelling is supported only before work starts; it does not pretend to undo remote effects.
+
+`plan-install` produces a read-only preview for a new, empty destination and blocks occupied destinations. Pull and installation previews can be queued and applied through the same journal. Local updates preserve the previous directory in an operation-specific backup; recovery verifies ownership and staged content before continuing, and preserves external edits. Backups and staged snapshots remain available for inspection. An interruption between creating a destination and recording its owner requires inspection rather than guessing ownership. The older `push`, `pull` and `install` commands retain their existing behavior; use `plan`/`apply` for binding-aware update safety. Use `skills apply-batch ids.json` or `skills recover-batch ids.json` with a JSON array of operation IDs. Outcomes are retained per item and completed work is not replayed. Ctrl-C stops after the current item and cancels unstarted items. In the macOS app, Skills → Transfers reviews the same device-wide queue before running or recovering selected plans.
+
+The desktop keeps a cached local skill inventory and watches registered/agent folders. Known file changes re-read only affected skills; new paths and periodic reconciliation repair missed events. Refresh requests a full reconciliation. Removed or inaccessible folders keep their stable identity and last known metadata. Watchers are hints, not authority for transfer planning, which always rechecks current files.
+
+
+In the macOS app, **On this Mac → Push to Sfora / Update local copy** opens a project chooser and a **Review changes** dialog. Published cloud skills offer **Install on this Mac**, followed by the native destination picker and the same review. No CLI plan file is needed. Opening a review creates no binding or queued operation; confirmation rechecks current content and records the durable transfer. Matching unlinked copies can be explicitly linked. Different unlinked copies remain blocked rather than receiving an invented baseline.
+
+A first publication continues into the existing project draft editor. After successful publication, the original local copy is linked only if its files still match the published version. A failed link does not turn a successful publication into a failed result. Transfers remains the history/recovery view, including work queued from the CLI.

package/dist/local-core/files.d.ts

@@ -17,7 +17,7 @@ export interface LocalMarkdownSnapshot {
 export declare function readLocalMarkdown(path: string): Promise<LocalMarkdownSnapshot>;
 export declare function saveLocalMarkdown(path: string, content: string, expectedRevision: string): Promise<LocalMarkdownSnapshot>;
 /** Save As creates a new path only. Replacing an existing file requires its current revision. */
-export declare function atomicCreate(path: string, content: string | Uint8Array): Promise<string>;
+export declare function atomicCreate(path: string, content: string | Uint8Array, mode?: number): Promise<string>;
 export declare function saveNewLocalMarkdown(path: string, content: string): Promise<LocalMarkdownSnapshot>;
 /** Watch the parent so atomic replacement by another editor remains observable. */
 export declare function watchLocalMarkdown(path: string, onChange: () => void): FSWatcher;

package/dist/local-core/files.js

@@ -82,11 +82,11 @@ export async function saveLocalMarkdown(path, content, expectedRevision) {
     });
 }
 /** Save As creates a new path only. Replacing an existing file requires its current revision. */
-export async function atomicCreate(path, content) {
+export async function atomicCreate(path, content, mode = 0o600) {
     const destination = join(await realpath(dirname(resolve(path))), basename(path));
     const temporary = `${destination}.${randomUUID()}.tmp`;
     try {
-        await atomicWrite(temporary, content);
+        await atomicWrite(temporary, content, mode);
         // Hard link publishes atomically and fails EEXIST instead of overwriting a raced save.
         await link(temporary, destination);
     }

package/dist/local-core/index.d.ts

@@ -2,3 +2,15 @@
  * Renderers must obtain native dialog grants; never expose these as arbitrary IPC paths. */
 export * from "./files.js";
 export * from "./skills.js";
+export * from "./skill-domain.js";
+export * from "./skill-discovery.js";
+export * from "./skill-store.js";
+export * from "./skill-service.js";
+export * from "./skill-sync.js";
+export * from "./skill-operations.js";
+export { SKILL_AGENT_ADAPTERS, projectSkillSources } from "./skill-adapters.js";
+export type { SkillAgentAdapter } from "./skill-adapters.js";
+export * from "./skill-local-executor.js";
+export * from "./skill-executor.js";
+export { SkillIndex } from './skill-index.js';
+export { SkillReviewService, type SkillReview } from './skill-review.js';

package/dist/local-core/index.js

@@ -2,3 +2,14 @@
  * Renderers must obtain native dialog grants; never expose these as arbitrary IPC paths. */
 export * from "./files.js";
 export * from "./skills.js";
+export * from "./skill-domain.js";
+export * from "./skill-discovery.js";
+export * from "./skill-store.js";
+export * from "./skill-service.js";
+export * from "./skill-sync.js";
+export * from "./skill-operations.js";
+export { SKILL_AGENT_ADAPTERS, projectSkillSources } from "./skill-adapters.js";
+export * from "./skill-local-executor.js";
+export * from "./skill-executor.js";
+export { SkillIndex } from './skill-index.js';
+export { SkillReviewService } from './skill-review.js';

package/dist/local-core/skill-adapters.d.ts

@@ -0,0 +1,21 @@
+import type { SkillSource } from './skill-discovery.js';
+export interface SkillAgentAdapter {
+    id: string;
+    label: string;
+    globalPath: string;
+    projectPath: string;
+    depth: number;
+    /** A folder observation alone never establishes that an agent enables a skill. */
+    activation: 'unknown';
+    deploymentModes: readonly ['copy'];
+    caches: readonly {
+        id: string;
+        path: string;
+        label: string;
+        depth: number;
+    }[];
+}
+export declare const SKILL_AGENT_ADAPTERS: readonly SkillAgentAdapter[];
+export declare function defaultSkillSources(home?: string): SkillSource[];
+/** Caller explicitly selects/registers the project; never infer access from cwd in desktop. */
+export declare function projectSkillSources(project: string): SkillSource[];

package/dist/local-core/skill-adapters.js

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+export const SKILL_AGENT_ADAPTERS = [
+    { id: 'agents', label: 'Agents', globalPath: '.agents/skills', projectPath: '.agents/skills', depth: 1, activation: 'unknown', deploymentModes: ['copy'], caches: [] },
+    { id: 'codex', label: 'Codex', globalPath: '.codex/skills', projectPath: '.codex/skills', depth: 2, activation: 'unknown', deploymentModes: ['copy'], caches: [{ id: 'codex-plugin-cache', path: '.codex/plugins/cache', label: 'Codex plugin cache', depth: 6 }] },
+    { id: 'claude', label: 'Claude', globalPath: '.claude/skills', projectPath: '.claude/skills', depth: 1, activation: 'unknown', deploymentModes: ['copy'], caches: [{ id: 'claude-plugin-cache', path: '.claude/plugins/cache', label: 'Claude plugin cache', depth: 6 }] },
+    { id: 'cursor', label: 'Cursor', globalPath: '.cursor/skills', projectPath: '.cursor/skills', depth: 1, activation: 'unknown', deploymentModes: ['copy'], caches: [] },
+];
+export function defaultSkillSources(home = homedir()) {
+    return SKILL_AGENT_ADAPTERS.flatMap(adapter => [
+        { id: adapter.id, path: join(home, adapter.globalPath), label: adapter.label, depth: adapter.depth, kind: 'agent' },
+        ...adapter.caches.map(cache => ({ id: cache.id, path: join(home, cache.path), label: cache.label, depth: cache.depth, kind: 'cache' })),
+    ]);
+}
+/** Caller explicitly selects/registers the project; never infer access from cwd in desktop. */
+export function projectSkillSources(project) {
+    const root = resolve(project);
+    return SKILL_AGENT_ADAPTERS.map(adapter => ({ id: `project:${root}:${adapter.id}`, path: join(root, adapter.projectPath), label: `${adapter.label} · project`, depth: adapter.depth, kind: 'agent' }));
+}

package/dist/local-core/skill-discovery.d.ts

@@ -0,0 +1,22 @@
+export { defaultSkillSources } from './skill-adapters.js';
+export interface SkillSource {
+    path: string;
+    label: string;
+    depth: number;
+    id?: string;
+    kind?: "agent" | "cache" | "custom";
+}
+export interface LocalSkill {
+    path: string;
+    name: string;
+    sources: string[];
+    aliases: import("./skill-domain.js").SkillAlias[];
+    hash?: string;
+    fileCount?: number;
+    error?: string;
+}
+/** Bounded discovery; canonical aliases share a row. Bundles retain strict link/size checks. */
+export declare function discoverSkills(sources?: SkillSource[]): Promise<{
+    skills: LocalSkill[];
+    warnings: string[];
+}>;

package/dist/local-core/skill-discovery.js

@@ -0,0 +1,79 @@
+import { readdir, realpath, lstat } from 'node:fs/promises';
+import { defaultSkillSources } from './skill-adapters.js';
+export { defaultSkillSources } from './skill-adapters.js';
+import { join, basename } from 'node:path';
+import { readSkillBundle } from './skills.js';
+class ScanLimitError extends Error {
+}
+/** Bounded discovery; canonical aliases share a row. Bundles retain strict link/size checks. */
+export async function discoverSkills(sources = defaultSkillSources()) {
+    const found = new Map();
+    const warnings = [];
+    let visited = 0;
+    for (const source of sources) {
+        const seen = new Set();
+        async function walk(path, depth) {
+            if (++visited > 5000 || found.size >= 1000)
+                throw new ScanLimitError('Scan limit reached. Choose a narrower folder to find more skills.');
+            const canonical = await realpath(path);
+            if (seen.has(canonical)) {
+                const existing = found.get(canonical);
+                if (existing && !existing.aliases.some(a => a.sourceId === (source.id ?? source.path) && a.path === path))
+                    existing.aliases.push({ sourceId: source.id ?? source.path, path, label: source.label, kind: source.kind ?? "custom" });
+                return;
+            }
+            seen.add(canonical);
+            const entries = await readdir(canonical, { withFileTypes: true });
+            if (entries.some(entry => entry.name === 'SKILL.md')) {
+                const existing = found.get(canonical);
+                if (existing) {
+                    if (!existing.sources.includes(source.label))
+                        existing.sources.push(source.label);
+                    existing.aliases.push({ sourceId: source.id ?? source.path, path, label: source.label, kind: source.kind ?? "custom" });
+                    return;
+                }
+                const skill = { path: canonical, name: basename(canonical), sources: [source.label], aliases: [{ sourceId: source.id ?? source.path, path, label: source.label, kind: source.kind ?? "custom" }] };
+                found.set(canonical, skill);
+                try {
+                    const bundle = await readSkillBundle(canonical);
+                    skill.hash = bundle.hash;
+                    skill.fileCount = bundle.files.length;
+                }
+                catch (error) {
+                    skill.error = error instanceof Error ? error.message : String(error);
+                }
+                return;
+            }
+            if (depth === 0)
+                return;
+            for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (['node_modules', '.git'].includes(entry.name))
+                    continue;
+                if (!entry.isDirectory() && !entry.isSymbolicLink())
+                    continue;
+                const child = join(path, entry.name);
+                try {
+                    if ((await lstat(await realpath(child))).isDirectory())
+                        await walk(child, depth - 1);
+                }
+                catch (error) {
+                    if (error instanceof ScanLimitError)
+                        throw error;
+                    warnings.push(`${source.label}: ${child}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        try {
+            await walk(source.path, source.depth);
+        }
+        catch (error) {
+            if (error instanceof ScanLimitError) {
+                warnings.push(error.message);
+                break;
+            }
+            if (error.code !== 'ENOENT')
+                warnings.push(`${source.label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return { skills: [...found.values()].sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path)), warnings };
+}

package/dist/local-core/skill-domain.d.ts

@@ -0,0 +1,74 @@
+/** Stable domain records. Names/hashes are labels/content, never identity or permission. */
+export interface SkillIdentity {
+    id: string;
+    createdAt: number;
+}
+export interface SkillAlias {
+    sourceId: string;
+    path: string;
+    label: string;
+    kind: 'agent' | 'cache' | 'custom';
+}
+export interface SkillLocation {
+    id: string;
+    skillId: string;
+    path: string;
+    aliases: SkillAlias[];
+    createdAt: number;
+}
+export interface SkillObservation {
+    locationId: string;
+    name: string;
+    observedAt: number;
+    hash?: string;
+    fileCount?: number;
+    error?: string;
+    availability: 'available' | 'unavailable';
+}
+export interface SkillRevision {
+    hash: string;
+    contentPolicy: 'bundle-v1';
+    cloudVersion?: number;
+}
+export interface CloudSkillIdentity {
+    deployment: string;
+    organizationId: string;
+    skillId: string;
+}
+export interface SkillCloudBinding {
+    id: string;
+    localSkillId: string;
+    remote: CloudSkillIdentity & {
+        projectId: string;
+    };
+    /** Authenticated member ID, never an API key or its fingerprint. */
+    accountId: string;
+    /** Lookup hints only; every lookup must revalidate the qualified IDs. */
+    locator: {
+        project: string;
+        name: string;
+    };
+    baseline?: SkillRevision;
+}
+export interface SkillProjectAssignment {
+    projectId: string;
+    remote: CloudSkillIdentity;
+    pinnedVersion: number;
+    overrideSkillId?: string;
+}
+export interface SkillAgentTarget {
+    skillId: string;
+    agentId: string;
+    path: string;
+    scope: 'global' | 'project';
+    mode: 'copy' | 'link';
+    ownership: 'managed' | 'unmanaged' | 'unknown';
+}
+export interface SkillOperation {
+    id: string;
+    kind: 'push' | 'pull' | 'install';
+    skillId: string;
+    expectedLocalHash?: string;
+    expectedRemote?: SkillRevision;
+    status: 'planned' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+}

package/dist/local-core/skill-domain.js

@@ -0,0 +1 @@
+export {};

package/dist/local-core/skill-executor.d.ts

@@ -0,0 +1,23 @@
+import { SkillOperationJournal, type SkillPushPorts } from './skill-operations.js';
+import type { SkillStore } from './skill-store.js';
+export declare class SkillOperationExecutor {
+    readonly store: SkillStore;
+    readonly journal: SkillOperationJournal;
+    readonly cloud: SkillPushPorts;
+    constructor(store: SkillStore, journal: SkillOperationJournal, cloud: SkillPushPorts);
+    apply(id: string, recover?: boolean): Promise<import("./skill-operations.js").SkillTransferOperation>;
+    /** Each item owns its durable outcome. Successful work is never replayed. */
+    batch(ids: string[], options?: {
+        recover?: boolean;
+        signal?: AbortSignal;
+        onResult?: (result: {
+            id: string;
+            status: string;
+            error?: string;
+        }) => void;
+    }): Promise<{
+        id: string;
+        status: string;
+        error?: string;
+    }[]>;
+}

package/dist/local-core/skill-executor.js

@@ -0,0 +1,51 @@
+import { SkillPushExecutor, operationDirection } from './skill-operations.js';
+import { SkillLocalExecutor } from './skill-local-executor.js';
+export class SkillOperationExecutor {
+    store;
+    journal;
+    cloud;
+    constructor(store, journal, cloud) {
+        this.store = store;
+        this.journal = journal;
+        this.cloud = cloud;
+    }
+    async apply(id, recover = false) {
+        const op = (await this.journal.list()).find(o => o.id === id);
+        if (!op)
+            throw new Error('Operation not found.');
+        return operationDirection(op.plan) === 'push'
+            ? new SkillPushExecutor(this.store, this.journal, this.cloud).apply(id, recover)
+            : new SkillLocalExecutor(this.store, this.journal, this.cloud).apply(id, recover);
+    }
+    /** Each item owns its durable outcome. Successful work is never replayed. */
+    async batch(ids, options = {}) {
+        if (!Array.isArray(ids) || !ids.length || ids.length > 1000 || new Set(ids).size !== ids.length || ids.some(id => typeof id !== 'string'))
+            throw new Error('Select 1–1000 distinct operation IDs.');
+        const operations = await this.journal.list();
+        if (ids.some(id => !operations.some(op => op.id === id)))
+            throw new Error('A selected operation no longer exists. Refresh before running.');
+        const results = [];
+        for (const id of ids) {
+            let result;
+            if (options.signal?.aborted) {
+                const op = (await this.journal.list()).find(o => o.id === id);
+                if (op.status === 'planned')
+                    result = { id, status: (await this.journal.cancel(id)).status };
+                else
+                    result = { id, status: op.status, error: ['succeeded', 'cancelled'].includes(op.status) ? undefined : 'Batch stopped before this item; its previous outcome is retained.' };
+            }
+            else {
+                try {
+                    result = { id, status: (await this.apply(id, options.recover)).status };
+                }
+                catch (error) {
+                    const current = (await this.journal.list()).find(o => o.id === id);
+                    result = { id, status: current.status, error: error.message };
+                }
+            }
+            results.push(result);
+            options.onResult?.(result);
+        }
+        return results;
+    }
+}

package/dist/local-core/skill-index.d.ts

@@ -0,0 +1,54 @@
+import { SkillService } from './skill-service.js';
+/** Events are hints; periodic reconciliation repairs missed events and root changes. */
+export declare class SkillIndex {
+    readonly service: SkillService;
+    readonly changed: () => void;
+    readonly reconciliationMs: number;
+    private watchers;
+    private timer?;
+    private interval?;
+    private pending;
+    private full;
+    private running;
+    private active?;
+    private closed;
+    private started?;
+    private warnings;
+    constructor(service: SkillService, changed?: () => void, reconciliationMs?: number);
+    start(): Promise<void>;
+    inventory(): Promise<{
+        warnings: string[];
+        skills: {
+            skillId: string;
+            locationId: string;
+            path: string;
+            name: string;
+            sources: string[];
+            aliases: import("./skill-domain.js").SkillAlias[];
+            hash: string | undefined;
+            fileCount: number | undefined;
+            error: string | undefined;
+            availability: "available" | "unavailable";
+        }[];
+    }>;
+    invalidate(path?: string): void;
+    private configure;
+    refresh(): Promise<{
+        warnings: string[];
+        skills: {
+            skillId: string;
+            locationId: string;
+            path: string;
+            name: string;
+            sources: string[];
+            aliases: import("./skill-domain.js").SkillAlias[];
+            hash: string | undefined;
+            fileCount: number | undefined;
+            error: string | undefined;
+            availability: "available" | "unavailable";
+        }[];
+    }>;
+    private flush;
+    private perform;
+    close(): void;
+}

package/dist/local-core/skill-index.js

@@ -0,0 +1,115 @@
+import { watch } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathWithin } from './skill-service.js';
+/** Events are hints; periodic reconciliation repairs missed events and root changes. */
+export class SkillIndex {
+    service;
+    changed;
+    reconciliationMs;
+    watchers = [];
+    timer;
+    interval;
+    pending = new Set();
+    full = false;
+    running = false;
+    active;
+    closed = false;
+    started;
+    warnings = [];
+    constructor(service, changed = () => { }, reconciliationMs = 60_000) {
+        this.service = service;
+        this.changed = changed;
+        this.reconciliationMs = reconciliationMs;
+    }
+    start() {
+        return this.started ??= (async () => {
+            this.full = true;
+            await this.flush();
+            if (!this.closed) {
+                this.interval = setInterval(() => this.invalidate(), this.reconciliationMs);
+                this.interval.unref();
+            }
+        })();
+    }
+    async inventory() { await this.start(); return { ...await this.service.cachedInventory(), warnings: this.warnings }; }
+    invalidate(path) {
+        if (this.closed)
+            return;
+        const storePath = 'path' in this.service.store ? String(this.service.store.path) : undefined;
+        if (path && storePath && (path === storePath || path.startsWith(`${storePath}-`)))
+            return;
+        if (path && this.pending.size < 1000)
+            this.pending.add(path);
+        else
+            this.full = true;
+        if (!this.timer)
+            this.timer = setTimeout(() => { this.timer = undefined; void this.flush(); }, 150);
+    }
+    async configure() {
+        for (const watcher of this.watchers)
+            watcher.close();
+        this.watchers = [];
+        const sources = await this.service.discoverySources();
+        for (const source of sources.slice(0, 128)) {
+            try {
+                const watcher = watch(source.path, { recursive: true, persistent: false }, (_event, name) => this.invalidate(name ? resolve(source.path, String(name)) : undefined));
+                watcher.on('error', () => this.invalidate());
+                this.watchers.push(watcher);
+            }
+            catch { /* Missing roots are retried by reconciliation, never deleted from the catalog. */ }
+        }
+    }
+    async refresh() {
+        await this.start();
+        if (this.active)
+            await this.active;
+        this.full = true;
+        await this.flush();
+        return { ...await this.service.cachedInventory(), warnings: this.warnings };
+    }
+    flush() {
+        if (this.active)
+            return this.active;
+        this.active = this.perform().finally(() => { this.active = undefined; });
+        return this.active;
+    }
+    async perform() {
+        if (this.running || this.closed)
+            return;
+        this.running = true;
+        const full = this.full;
+        this.full = false;
+        const paths = [...this.pending];
+        this.pending.clear();
+        let failed = false;
+        try {
+            const catalog = await this.service.store.read();
+            const ids = catalog.locations.filter(l => paths.some(p => pathWithin(l.path, p))).map(l => l.id);
+            const unknown = paths.some(p => !catalog.locations.some(l => pathWithin(l.path, p)));
+            if (full || unknown) {
+                const result = await this.service.inventory();
+                this.warnings = result.warnings;
+                await this.configure();
+            }
+            else if (ids.length)
+                await this.service.refreshLocations(ids);
+            if (!this.closed)
+                this.changed();
+        }
+        catch (error) {
+            failed = true;
+            this.warnings = [error.message];
+            this.full = true;
+            if (!this.closed)
+                this.changed();
+        }
+        finally {
+            this.running = false;
+        }
+        // Do not drop events received during inspection, including external edits during our own writes.
+        if ((this.pending.size || (this.full && !failed)) && !this.closed && !this.timer)
+            this.timer = setTimeout(() => { this.timer = undefined; void this.flush(); }, 150);
+    }
+    close() { this.closed = true; clearTimeout(this.timer); clearInterval(this.interval); for (const watcher of this.watchers)
+        watcher.close(); this.watchers = []; }
+}

package/dist/local-core/skill-local-executor.d.ts

@@ -0,0 +1,18 @@
+import { type PublishedSkillSnapshot } from './skill-sync.js';
+import { SkillOperationJournal, type SkillTransferOperation } from './skill-operations.js';
+import type { SkillStore } from './skill-store.js';
+export interface SkillLocalPorts {
+    snapshot(project: string, name: string): Promise<PublishedSkillSnapshot>;
+    /** Fault/telemetry seam, after durable steps; production never infers success from it. */
+    checkpoint?: (phase: string) => Promise<void>;
+}
+/** Recoverable local installation. Old bytes remain in an operation-specific backup.
+ * Destination creation and every file publication are exclusive: no foreign file is overwritten. */
+export declare class SkillLocalExecutor {
+    readonly store: SkillStore;
+    readonly journal: SkillOperationJournal;
+    readonly cloud: SkillLocalPorts;
+    constructor(store: SkillStore, journal: SkillOperationJournal, cloud: SkillLocalPorts);
+    apply(id: string, recover?: boolean): Promise<SkillTransferOperation>;
+    private run;
+}