sfora-cli 0.15.0 → 0.16.0

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

@@ -0,0 +1,249 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { mkdir, lstat, open, readdir, realpath, rename, rm, rmdir } from 'node:fs/promises';
+import { basename, dirname, join, isAbsolute } from 'node:path';
+import { atomicCreate, atomicWrite, sha256, withLocalLock } from './files.js';
+import { inspectSkillTarget, readInstallation, readSkillBundle } from './skills.js';
+import { assertSkillBindingSnapshot, planSkillInstallation, planSkillTransfer, validatePublishedSkillSnapshot } from './skill-sync.js';
+import { operationDestination } from './skill-operations.js';
+const exists = async (path) => lstat(path).catch(e => { if (e.code === 'ENOENT')
+    return null; throw e; });
+const readRegular = async (path, limit) => {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > limit)
+            throw new Error('Invalid operation artifact.');
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const receiptHash = (receipt) => receipt ? sha256(JSON.stringify(receipt)) : null;
+async function directoryProof(path) {
+    const info = await lstat(path, { bigint: true });
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error('Destination is no longer a directory.');
+    return { dev: String(info.dev), ino: String(info.ino) };
+}
+/** 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 class SkillLocalExecutor {
+    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.claim(id, recover);
+        if (['succeeded', 'cancelled'].includes(op.status))
+            return op;
+        try {
+            const plan = op.plan;
+            if (plan.kind === 'skill-transfer-preview' && plan.direction !== 'pull')
+                throw new Error('Use the push executor for this plan.');
+            const destination = operationDestination(plan);
+            if (!isAbsolute(destination) || join(await realpath(dirname(destination)), basename(destination)) !== destination)
+                throw new Error('Destination parent changed since review.');
+            const lock = `${destination}.sfora-lock`;
+            if (recover && await exists(lock)) {
+                const info = await lstat(lock);
+                if (!info.isDirectory() || info.isSymbolicLink())
+                    throw new Error('Unrecognized local lock; preserved.');
+                const entries = await readdir(lock);
+                if (entries.length !== 1 || entries[0] !== 'operation.json')
+                    throw new Error('Local lock ownership is unknown; preserved for inspection.');
+                const owner = JSON.parse((await readRegular(join(lock, 'operation.json'), 1024)).toString());
+                if (owner.id !== op.id)
+                    throw new Error('Local lock belongs to another operation.');
+                await rm(join(lock, 'operation.json'));
+                await rmdir(lock);
+            }
+            return await withLocalLock(destination, async () => {
+                await atomicCreate(join(lock, 'operation.json'), JSON.stringify({ id: op.id }));
+                return await this.run(op, destination);
+            });
+        }
+        catch (error) {
+            await this.journal.finish(id, 'needs-attention', error.message);
+            throw error;
+        }
+    }
+    async run(op, destination) {
+        const plan = op.plan;
+        if (plan.kind === 'skill-transfer-preview' && plan.direction !== 'pull')
+            throw new Error('Not a local plan.');
+        const artifactDirectory = join(dirname(this.journal.path), 'operation-artifacts', op.id);
+        const artifact = join(artifactDirectory, 'snapshot.json');
+        const backup = plan.kind === 'skill-transfer-preview' ? join(dirname(destination), `.${basename(destination)}.sfora-${op.id}.previous`) : undefined;
+        let local = op.local;
+        if (local && (local.destination !== destination || local.backup !== backup))
+            throw new Error('Operation checkpoint does not match its destination.');
+        let remote;
+        if (local) {
+            remote = JSON.parse((await readRegular(artifact, 30 * 1024 * 1024)).toString());
+            validatePublishedSkillSnapshot(remote);
+        }
+        else {
+            const locator = plan.kind === 'skill-install-preview' ? plan.locator : plan.binding.locator;
+            remote = await this.cloud.snapshot(locator.project, locator.name);
+            validatePublishedSkillSnapshot(remote);
+        }
+        if (remote.revision.hash !== plan.expected.remote.hash || remote.revision.cloudVersion !== plan.expected.remote.cloudVersion)
+            throw new Error('Published revision differs from the reviewed plan.');
+        if (plan.kind === 'skill-transfer-preview')
+            assertSkillBindingSnapshot(plan.binding, remote);
+        else if (JSON.stringify({ ...remote.remote, accountId: remote.accountId }) !== JSON.stringify(plan.source))
+            throw new Error('Installation source identity changed.');
+        const before = await this.store.read();
+        if (plan.kind === 'skill-transfer-preview') {
+            const binding = before.bindings.find(b => b.id === plan.binding.id), location = before.locations.find(l => l.id === plan.location.id);
+            if (!binding || !location || location.path !== destination || location.skillId !== binding.localSkillId
+                || JSON.stringify({ ...binding, baseline: plan.binding.baseline }) !== JSON.stringify(plan.binding)
+                || (!op.confirmedRevision && JSON.stringify(binding.baseline) !== JSON.stringify(plan.binding.baseline)))
+                throw new Error('Binding or location changed since review.');
+        }
+        else {
+            const location = before.locations.find(l => l.path === destination);
+            if (location && before.bindings.some(b => b.localSkillId === location.skillId && b.accountId === remote.accountId && b.remote.deployment === remote.remote.deployment && b.remote.organizationId === remote.remote.organizationId && b.remote.projectId === remote.remote.projectId && b.remote.skillId !== remote.remote.skillId))
+                throw new Error('Destination history belongs to another cloud identity. Choose a new destination.');
+        }
+        const checkpoint = async (next) => { await this.journal.checkpoint(op.id, next); local = next; await this.cloud.checkpoint?.(next.phase); };
+        if (!local) {
+            const target = await inspectSkillTarget(destination);
+            const current = plan.kind === 'skill-install-preview' ? planSkillInstallation(remote, destination, target)
+                : planSkillTransfer({ direction: 'pull', binding: plan.binding, location: plan.location, remote, local: { state: 'available', bundle: await readSkillBundle(destination) }, ownership: target.ownership });
+            if (JSON.stringify(current) !== JSON.stringify(plan))
+                throw new Error('Local or cloud state changed since review.');
+            await mkdir(artifactDirectory, { recursive: true, mode: 0o700 });
+            if (await exists(artifact)) {
+                const previous = JSON.parse((await readRegular(artifact, 30 * 1024 * 1024)).toString());
+                if (JSON.stringify(previous) !== JSON.stringify(remote))
+                    throw new Error('Staged snapshot differs; preserve it and create a new plan.');
+            }
+            else
+                await atomicCreate(artifact, JSON.stringify(remote));
+            await checkpoint({ phase: 'prepared', destination, backup, receiptBefore: receiptHash(await readInstallation(destination)) });
+        }
+        if (local.phase === 'prepared') {
+            if (backup) {
+                if (await exists(backup)) {
+                    if (await exists(destination))
+                        throw new Error('Both backup and destination exist without an ownership checkpoint; preserved for inspection.');
+                }
+                else {
+                    const target = await inspectSkillTarget(destination);
+                    if (target.ownership !== 'managed' || target.hash !== plan.expected.localHash || receiptHash(target.receipt) !== local.receiptBefore)
+                        throw new Error('Managed target changed before replacement.');
+                    await rename(destination, backup);
+                    await this.cloud.checkpoint?.('after-backup-rename');
+                }
+                if ((await readSkillBundle(backup, basename(destination))).hash !== plan.expected.localHash)
+                    throw new Error('Backup contains external changes; preserved for inspection.');
+            }
+            else if (await exists(destination))
+                throw new Error('Installation destination became occupied.');
+            await checkpoint({ ...local, phase: 'backed-up' });
+        }
+        if (local.phase === 'backed-up') {
+            if (await exists(destination))
+                throw new Error('Destination exists without a recorded owner. Its contents were preserved; inspect before recovery.');
+            await mkdir(destination, { mode: 0o700 });
+            await checkpoint({ ...local, phase: 'owned', directory: await directoryProof(destination) });
+        }
+        const verifyOwner = async () => {
+            if (JSON.stringify(await directoryProof(destination)) !== JSON.stringify(local.directory))
+                throw new Error('Destination was replaced by another process.');
+            if (join(await realpath(dirname(destination)), basename(destination)) !== destination)
+                throw new Error('Destination parent changed.');
+        };
+        await verifyOwner();
+        if (local.phase === 'owned') {
+            for (const file of remote.bundle.files) {
+                await verifyOwner();
+                let parent = destination;
+                for (const part of file.path.split('/').slice(0, -1)) {
+                    parent = join(parent, part);
+                    await mkdir(parent).catch(e => { if (e.code !== 'EEXIST')
+                        throw e; });
+                    const info = await lstat(parent);
+                    if (!info.isDirectory() || info.isSymbolicLink() || await realpath(parent) !== parent)
+                        throw new Error('Skill subdirectory changed; refusing to follow a link.');
+                }
+                const path = join(destination, file.path);
+                try {
+                    await atomicCreate(path, Buffer.from(file.contentBase64, 'base64'), file.executable ? 0o755 : 0o644);
+                }
+                catch (error) {
+                    if (error.code !== 'EEXIST')
+                        throw error;
+                    const bytes = await readRegular(path, 5 * 1024 * 1024);
+                    const info = await lstat(path);
+                    if (sha256(bytes) !== file.sha256 || !!(info.mode & 0o111) !== file.executable)
+                        throw new Error(`External changes in ${file.path}; preserved instead of overwritten.`);
+                }
+                await this.cloud.checkpoint?.(`file:${file.path}`);
+            }
+            await verifyOwner();
+            if ((await readSkillBundle(destination)).hash !== remote.bundle.hash)
+                throw new Error('Installed files include external changes; no baseline was recorded.');
+            const record = { schemaVersion: 1, path: destination, name: basename(destination), hash: remote.bundle.hash, installedAt: op.createdAt, source: `${remote.remote.deployment}/${remote.locator.project}/${remote.locator.name}`, sourceVersion: remote.revision.cloudVersion, operationId: op.id };
+            const receipt = await readInstallation(destination);
+            const receiptPath = join(dirname(destination), `.${basename(destination)}.sfora-install.json`);
+            if (JSON.stringify(receipt) !== JSON.stringify(record)) {
+                if (receiptHash(receipt) !== local.receiptBefore)
+                    throw new Error('Installation ownership record changed.');
+                if (receipt)
+                    await atomicWrite(receiptPath, JSON.stringify(record));
+                else
+                    await atomicCreate(receiptPath, JSON.stringify(record));
+            }
+            await checkpoint({ ...local, phase: 'copied' });
+        }
+        await verifyOwner();
+        if ((await readSkillBundle(destination)).hash !== remote.bundle.hash)
+            throw new Error('Local files changed before confirmation; preserved.');
+        const finalReceipt = await readInstallation(destination);
+        if (finalReceipt?.operationId !== op.id || finalReceipt.hash !== remote.bundle.hash)
+            throw new Error('Installation ownership record changed before confirmation.');
+        await this.journal.confirm(op.id, remote.revision);
+        await this.store.transaction(c => {
+            if (plan.kind === 'skill-transfer-preview') {
+                const current = c.bindings.find(b => b.id === plan.binding.id);
+                if (!current || JSON.stringify({ ...current, baseline: plan.binding.baseline }) !== JSON.stringify(plan.binding))
+                    throw new Error('Binding changed during installation.');
+                if (JSON.stringify(current.baseline) === JSON.stringify(plan.binding.baseline))
+                    current.baseline = { ...remote.revision };
+            }
+            else {
+                let root = c.roots.find(r => r.path === destination);
+                if (!root) {
+                    root = { id: randomUUID(), path: destination, label: basename(destination), depth: 0, scope: 'custom' };
+                    c.roots.push(root);
+                }
+                let location = c.locations.find(l => l.path === destination);
+                if (!location) {
+                    const identity = { id: randomUUID(), createdAt: Date.now() };
+                    c.identities.push(identity);
+                    location = { id: randomUUID(), skillId: identity.id, path: destination, createdAt: Date.now(), aliases: [] };
+                    c.locations.push(location);
+                }
+                if (!location.aliases.some(a => a.sourceId === root.id))
+                    location.aliases.push({ sourceId: root.id, path: destination, label: root.label, kind: 'custom' });
+                const binding = c.bindings.find(b => b.localSkillId === location.skillId && b.accountId === remote.accountId && b.remote.deployment === remote.remote.deployment && b.remote.organizationId === remote.remote.organizationId && b.remote.projectId === remote.remote.projectId);
+                if (binding && binding.remote.skillId !== remote.remote.skillId)
+                    throw new Error('A different cloud identity claimed this destination.');
+                if (!binding)
+                    c.bindings.push({ id: randomUUID(), localSkillId: location.skillId, remote: { ...remote.remote }, accountId: remote.accountId, locator: { ...remote.locator }, baseline: { ...remote.revision } });
+                else if (!op.confirmedRevision)
+                    binding.baseline = { ...remote.revision };
+            }
+        });
+        // Retain the original directory and staged snapshot for explicit inspection.
+        return this.journal.finish(op.id, 'succeeded');
+    }
+}

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

@@ -0,0 +1,61 @@
+import { readSkillBundle } from './skills.js';
+import { type PublishedSkillSnapshot, type SkillTransferPlan, type SkillInstallPlan } from './skill-sync.js';
+import type { SkillStore } from './skill-store.js';
+import type { SkillRevision } from './skill-domain.js';
+export type SkillOperationPlan = SkillTransferPlan | SkillInstallPlan;
+export interface LocalOperationCheckpoint {
+    phase: "prepared" | "backed-up" | "owned" | "copied";
+    destination: string;
+    backup?: string;
+    directory?: {
+        dev: string;
+        ino: string;
+    };
+    receiptBefore: string | null;
+}
+export declare const operationDirection: (plan: SkillOperationPlan) => "push" | "pull" | "install";
+export declare const operationRemote: (plan: SkillOperationPlan) => import("./skill-domain.js").CloudSkillIdentity & {
+    projectId: string;
+};
+export declare const operationDestination: (plan: SkillOperationPlan) => string;
+export interface SkillTransferOperation {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    plan: SkillOperationPlan;
+    status: 'planned' | 'running' | 'needs-attention' | 'succeeded' | 'cancelled';
+    ownerPid?: number;
+    error?: string;
+    confirmedRevision?: SkillRevision;
+    local?: LocalOperationCheckpoint;
+}
+/** Separate versioned journal: intent commits before network I/O. A dead worker never retains a SQLite lock. */
+export declare class SkillOperationJournal {
+    readonly path: string;
+    constructor(path: string);
+    private access;
+    private decode;
+    list(): Promise<SkillTransferOperation[]>;
+    create(plan: SkillOperationPlan): Promise<SkillTransferOperation>;
+    confirm(id: string, revision: SkillRevision): Promise<void>;
+    checkpoint(id: string, local: LocalOperationCheckpoint): Promise<void>;
+    claim(id: string, recover?: boolean): Promise<SkillTransferOperation>;
+    cancel(id: string): Promise<SkillTransferOperation>;
+    finish(id: string, status: 'succeeded' | 'needs-attention', error?: string): Promise<SkillTransferOperation>;
+}
+export interface SkillPushPorts {
+    snapshot(project: string, name: string): Promise<PublishedSkillSnapshot>;
+    saveDraft(project: string, bundle: Awaited<ReturnType<typeof readSkillBundle>>, version: number, draftRevision: number, skillId: string): Promise<{
+        draftRevision: number;
+    }>;
+    publish(project: string, name: string, version: number, draftRevision: number, skillId: string): Promise<unknown>;
+    read?: typeof readSkillBundle;
+}
+/** Idempotent by exact observed content/revision, never by names or a blind retry. */
+export declare class SkillPushExecutor {
+    readonly store: SkillStore;
+    readonly journal: SkillOperationJournal;
+    readonly cloud: SkillPushPorts;
+    constructor(store: SkillStore, journal: SkillOperationJournal, cloud: SkillPushPorts);
+    apply(id: string, recover?: boolean): Promise<SkillTransferOperation>;
+}

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

@@ -0,0 +1,268 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+import { mkdir, lstat, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { readSkillBundle } from './skills.js';
+import { assertSkillBindingSnapshot, planSkillTransfer } from './skill-sync.js';
+export const operationDirection = (plan) => plan.kind === 'skill-install-preview' ? 'install' : plan.direction;
+export const operationRemote = (plan) => plan.kind === 'skill-install-preview' ? plan.source : plan.binding.remote;
+export const operationDestination = (plan) => plan.kind === 'skill-install-preview' ? plan.destination : plan.location.path;
+/** Separate versioned journal: intent commits before network I/O. A dead worker never retains a SQLite lock. */
+export class SkillOperationJournal {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async access(change) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const handle = await open(this.path, 'ax', 0o600).catch(e => { if (e.code === 'EEXIST')
+            return null; throw e; });
+        await handle?.close();
+        const info = await lstat(this.path);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > 64 * 1024 * 1024)
+            throw new Error('Invalid skill operation journal file.');
+        const db = new DatabaseSync(this.path);
+        try {
+            db.exec('PRAGMA busy_timeout=5000; PRAGMA synchronous=FULL; BEGIN IMMEDIATE;');
+            const version = Number(db.prepare('PRAGMA user_version').get().user_version);
+            if (version === 0) {
+                if (db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().length)
+                    throw new Error('Unrecognized operation journal.');
+                db.exec('CREATE TABLE operations(id TEXT PRIMARY KEY,data TEXT NOT NULL); PRAGMA user_version=1;');
+            }
+            else if (version !== 1)
+                throw new Error('Unsupported operation journal version.');
+            const result = change(db);
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { }
+            throw error;
+        }
+        finally {
+            db.close();
+        }
+    }
+    decode(data) {
+        const op = JSON.parse(String(data));
+        if (!op || !/^[a-f0-9-]{36}$/.test(op.id) || !['planned', 'running', 'needs-attention', 'succeeded', 'cancelled'].includes(op.status)
+            || !['skill-transfer-preview', 'skill-install-preview'].includes(op.plan?.kind) || op.plan.schemaVersion !== 1 || !Number.isSafeInteger(op.createdAt)
+            || !Number.isSafeInteger(op.updatedAt) || (op.ownerPid !== undefined && (!Number.isSafeInteger(op.ownerPid) || op.ownerPid < 1))
+            || (op.status === 'running' && !op.ownerPid)
+            || (op.confirmedRevision && (op.confirmedRevision.contentPolicy !== 'bundle-v1' || op.confirmedRevision.hash !== (operationDirection(op.plan) === 'push' ? op.plan.expected.localHash : op.plan.expected.remote.hash) || op.confirmedRevision.cloudVersion !== op.plan.expected.remote.cloudVersion + (operationDirection(op.plan) === 'push' ? 1 : 0))))
+            throw new Error('Invalid operation record.');
+        return op;
+    }
+    async list() { return this.access(db => db.prepare('SELECT data FROM operations ORDER BY rowid DESC').all().map(row => this.decode(row.data))); }
+    async create(plan) {
+        if (!plan || plan.schemaVersion !== 1 || plan.outcome !== 'reviewable' || plan.blockers.length || JSON.stringify(plan).length > 2 * 1024 * 1024)
+            throw new Error('Only a reviewable plan can be queued.');
+        if (plan.kind === 'skill-install-preview') {
+            if (plan.expected.targetState !== 'missing' || plan.expected.localHash !== null || !plan.locator?.project || !plan.locator?.name)
+                throw new Error('Refresh the empty-destination installation plan.');
+        }
+        else if (plan.kind === 'skill-transfer-preview') {
+            const push = plan.direction === 'push';
+            if (!['push', 'pull'].includes(plan.direction) || plan.status !== (push ? 'local-changed' : 'remote-changed')
+                || plan.binding.baseline?.hash !== (push ? plan.expected.remote.hash : plan.expected.localHash)
+                || !/^[a-f0-9]{64}$/.test(plan.expected.localHash ?? '') || plan.expected.localHash === plan.expected.remote.hash
+                || (!push && plan.ownership !== 'managed'))
+                throw new Error('Only a reviewed, owned transfer can be queued.');
+        }
+        else
+            throw new Error('Unsupported operation plan.');
+        const now = Date.now();
+        const op = { id: randomUUID(), createdAt: now, updatedAt: now, status: 'planned', plan: structuredClone(plan) };
+        return this.access(db => {
+            if (Number(db.prepare('SELECT COUNT(*) AS count FROM operations').get().count) >= 10000)
+                throw new Error('Operation journal is full. Archive completed operations before queuing more.');
+            db.prepare('INSERT INTO operations VALUES (?,?)').run(op.id, JSON.stringify(op));
+            return op;
+        });
+    }
+    async confirm(id, revision) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status !== 'running' || op.ownerPid !== process.pid)
+                throw new Error('Operation lease changed.');
+            if (revision.hash !== (operationDirection(op.plan) === 'push' ? op.plan.expected.localHash : op.plan.expected.remote.hash) || revision.cloudVersion !== op.plan.expected.remote.cloudVersion + (operationDirection(op.plan) === 'push' ? 1 : 0))
+                throw new Error('Unexpected confirmed revision.');
+            op.confirmedRevision = { ...revision };
+            op.updatedAt = Date.now();
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+        });
+    }
+    async checkpoint(id, local) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status !== 'running' || op.ownerPid !== process.pid)
+                throw new Error('Operation lease changed.');
+            op.local = structuredClone(local);
+            op.updatedAt = Date.now();
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+        });
+    }
+    async claim(id, recover = false) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status === 'succeeded' || op.status === 'cancelled')
+                return op;
+            const target = (o) => { const r = operationRemote(o.plan); return JSON.stringify([r.deployment, r.organizationId, r.projectId, r.skillId]); };
+            for (const other of db.prepare('SELECT data FROM operations WHERE id!=?').all(id).map(row => this.decode(row.data))) {
+                if (other.status === 'running' && (target(other) === target(op) || operationDestination(other.plan) === operationDestination(op.plan)))
+                    throw new Error(`Cloud target is reserved by operation ${other.id}. Complete or recover that operation first.`);
+            }
+            if (op.status === 'running') {
+                if (!recover)
+                    throw new Error('Operation is already running. Use recover after its worker has exited.');
+                if (op.ownerPid) {
+                    let alive = true;
+                    try {
+                        process.kill(op.ownerPid, 0);
+                    }
+                    catch (e) {
+                        if (e.code === 'ESRCH')
+                            alive = false;
+                    }
+                    if (alive)
+                        throw new Error('The operation worker is still running; recovery refused.');
+                }
+            }
+            op.status = 'running';
+            op.ownerPid = process.pid;
+            op.updatedAt = Date.now();
+            delete op.error;
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+            return op;
+        });
+    }
+    async cancel(id) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status === 'cancelled')
+                return op;
+            if (op.status !== 'planned')
+                throw new Error('Only an unstarted operation can be cancelled. Recover uncertain work before abandoning it.');
+            op.status = 'cancelled';
+            op.updatedAt = Date.now();
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+            return op;
+        });
+    }
+    async finish(id, status, error) {
+        return this.access(db => {
+            const row = db.prepare('SELECT data FROM operations WHERE id=?').get(id);
+            if (!row)
+                throw new Error('Operation not found.');
+            const op = this.decode(row.data);
+            if (op.status !== 'running' || op.ownerPid !== process.pid)
+                throw new Error('Operation lease changed.');
+            op.status = status;
+            op.updatedAt = Date.now();
+            delete op.ownerPid;
+            if (error)
+                op.error = error.slice(0, 2000);
+            else
+                delete op.error;
+            db.prepare('UPDATE operations SET data=? WHERE id=?').run(JSON.stringify(op), id);
+            return op;
+        });
+    }
+}
+/** Idempotent by exact observed content/revision, never by names or a blind retry. */
+export class SkillPushExecutor {
+    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.claim(id, recover);
+        if (op.status === 'succeeded' || op.status === 'cancelled')
+            return op;
+        try {
+            const plan = op.plan;
+            if (plan.kind !== 'skill-transfer-preview' || plan.direction !== 'push')
+                throw new Error('Use the local executor for this operation.');
+            const catalog = await this.store.read();
+            const binding = catalog.bindings.find(b => b.id === plan.binding.id);
+            const location = catalog.locations.find(l => l.id === plan.location.id);
+            if (!binding || !location || location.skillId !== binding.localSkillId || location.path !== plan.location.path
+                || JSON.stringify({ ...binding, baseline: plan.binding.baseline }) !== JSON.stringify(plan.binding)
+                || (!op.confirmedRevision && JSON.stringify(binding.baseline) !== JSON.stringify(plan.binding.baseline)))
+                throw new Error('Binding or location changed since review. Create a new plan.');
+            const { project, name } = binding.locator;
+            let remote = await this.cloud.snapshot(project, name);
+            assertSkillBindingSnapshot(binding, remote);
+            if (op.confirmedRevision) {
+                await this.store.transaction(c => {
+                    const current = c.bindings.find(b => b.id === binding.id);
+                    if (!current || JSON.stringify(current) !== JSON.stringify(binding))
+                        throw new Error('Binding changed during recovery.');
+                    if (JSON.stringify(current.baseline) === JSON.stringify(plan.binding.baseline))
+                        current.baseline = { ...op.confirmedRevision };
+                });
+                return await this.journal.finish(id, 'succeeded');
+            }
+            if (!remote.supportsIdentityGuards)
+                throw new Error('This Sfora deployment does not support identity-checked transfers yet. Update the server before applying.');
+            const version = plan.expected.remote.cloudVersion;
+            const draft = plan.expected.draftRevision;
+            const hash = plan.expected.localHash;
+            const confirmed = () => remote.revision.cloudVersion === version + 1 && remote.revision.hash === hash;
+            if (!confirmed()) {
+                // A crash may have occurred after the draft committed but before its
+                // response arrived. Only the exact intended next draft can be resumed.
+                const saved = remote.revision.cloudVersion === version && remote.revision.hash === plan.expected.remote.hash
+                    && remote.draftRevision === draft + 1 && remote.hasDraft && remote.draftHash === hash;
+                if (!saved) {
+                    const local = await (this.cloud.read ?? readSkillBundle)(location.path);
+                    const current = planSkillTransfer({ direction: 'push', binding, location, local: { state: 'available', bundle: local }, remote, ownership: plan.ownership });
+                    if (JSON.stringify(current) !== JSON.stringify(plan))
+                        throw new Error('Skill changed since review. Create a new plan.');
+                    const result = await this.cloud.saveDraft(project, { ...local, name }, version, draft, binding.remote.skillId);
+                    if (result.draftRevision !== draft + 1)
+                        throw new Error('Unexpected draft response. Inspect the operation before recovery.');
+                }
+                await this.cloud.publish(project, name, version, draft + 1, binding.remote.skillId);
+                remote = await this.cloud.snapshot(project, name);
+                assertSkillBindingSnapshot(binding, remote);
+                if (!confirmed())
+                    throw new Error('Publication could not be confirmed at the expected revision. Inspect before recovery.');
+            }
+            // Baseline commit is deliberately after remote confirmation. If the
+            // journal completion is interrupted, recovery recognizes this baseline.
+            await this.journal.confirm(id, remote.revision);
+            await this.store.transaction(c => {
+                const current = c.bindings.find(b => b.id === binding.id);
+                if (!current || JSON.stringify(current) !== JSON.stringify(binding))
+                    throw new Error('Binding changed during publication. Confirmation requires review.');
+                current.baseline = { ...remote.revision };
+            });
+            return await this.journal.finish(id, 'succeeded');
+        }
+        catch (error) {
+            await this.journal.finish(id, 'needs-attention', error.message);
+            throw error;
+        }
+    }
+}

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

@@ -0,0 +1,46 @@
+import { SkillOperationJournal, type SkillPushPorts } from './skill-operations.js';
+import type { SkillStore } from './skill-store.js';
+export interface SkillReview {
+    id: string;
+    action: 'push' | 'pull' | 'install' | 'link';
+    outcome: 'reviewable' | 'blocked' | 'no-op' | 'draft-needed';
+    name: string;
+    project: string;
+    scope: string;
+    path: string;
+    version?: number;
+    files: Array<{
+        path: string;
+        kind: 'added' | 'removed' | 'modified';
+    }>;
+    blockers: string[];
+}
+/** Read-only previews become durable operations only when the person confirms.
+ * Ephemeral review IDs are capability tokens owned by the desktop main process. */
+export declare class SkillReviewService {
+    readonly store: SkillStore;
+    readonly journal: SkillOperationJournal;
+    readonly connect: (connection: string) => Promise<SkillPushPorts>;
+    readonly now: () => number;
+    private reviews;
+    constructor(store: SkillStore, journal: SkillOperationJournal, connect: (connection: string) => Promise<SkillPushPorts>, now?: () => number);
+    private remember;
+    private view;
+    transfer(input: {
+        locationId: string;
+        projectId: string;
+        connection: string;
+        direction: 'push' | 'pull';
+    }): Promise<SkillReview>;
+    install(input: {
+        projectId: string;
+        name: string;
+        connection: string;
+        destination: string;
+    }): Promise<SkillReview>;
+    confirm(id: string): Promise<{
+        status: string;
+        operationId?: string;
+    }>;
+    private apply;
+}