@voybio/ace-swarm 2.4.9 → 2.4.10

package/dist/store/repositories/goal-repository.js

@@ -17,6 +17,50 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { withStoreWriteCoordinatorSync } from "../write-coordinator.js";
+/** Wire representation understood by pre-marker 2.4.x engines, which compare
+ * numeric limits directly. In-memory callers continue to use zero for unlimited.
+ * This is a finite compatibility sentinel, not a mathematical infinity. */
+export const UNBOUNDED_GOAL_BUDGET_WIRE_VALUE = Number.MAX_SAFE_INTEGER;
+const LEGACY_GOAL_DEFAULTS = { max_wall_clock_ms: 14_400_000, max_ticks: 200, max_replans: 3 };
+function normalizeGoalRecord(goal) {
+    const source = goal.budgets ?? {};
+    const budgets = { ...source };
+    const legacyShape = [source.max_wall_clock_ms, source.max_ticks, source.max_replans]
+        .some(value => Number.isFinite(value) && value > 0 && value !== UNBOUNDED_GOAL_BUDGET_WIRE_VALUE);
+    const infer = (field) => {
+        const value = source[field];
+        return Number.isFinite(value) && value >= 0 && value !== UNBOUNDED_GOAL_BUDGET_WIRE_VALUE
+            && value !== LEGACY_GOAL_DEFAULTS[field] && (value > 0 || (field !== 'max_wall_clock_ms' && legacyShape));
+    };
+    // Old records did not retain whether a value equal to the default was explicit.
+    // Those ambiguous defaults follow the approved unlimited upgrade policy.
+    const duration = goal.executor === 'host'
+        ? source.host_deadline_explicit ?? source.deadline_explicit ?? infer('max_wall_clock_ms')
+        : source.deadline_explicit ?? infer('max_wall_clock_ms');
+    budgets.deadline_explicit = source.deadline_explicit ?? duration;
+    if (goal.executor === 'host' || source.host_deadline_explicit !== undefined) {
+        budgets.host_deadline_explicit = source.host_deadline_explicit ?? duration;
+    }
+    budgets.max_wall_clock_ms = duration ? source.max_wall_clock_ms : 0;
+    budgets.tick_budget_explicit = source.tick_budget_explicit ?? infer('max_ticks');
+    budgets.max_ticks = budgets.tick_budget_explicit ? source.max_ticks : 0;
+    budgets.replan_budget_explicit = source.replan_budget_explicit ?? infer('max_replans');
+    budgets.max_replans = budgets.replan_budget_explicit ? source.max_replans : 0;
+    budgets.max_step_retries = source.max_step_retries ?? 0;
+    return { ...goal, budgets };
+}
+function encodeGoalRecord(goal) {
+    const budgets = { ...goal.budgets };
+    const duration = goal.executor === 'host' ? budgets.host_deadline_explicit : budgets.deadline_explicit;
+    if (!duration)
+        budgets.max_wall_clock_ms = UNBOUNDED_GOAL_BUDGET_WIRE_VALUE;
+    if (!budgets.tick_budget_explicit)
+        budgets.max_ticks = UNBOUNDED_GOAL_BUDGET_WIRE_VALUE;
+    if (!budgets.replan_budget_explicit)
+        budgets.max_replans = UNBOUNDED_GOAL_BUDGET_WIRE_VALUE;
+    return { ...goal, budgets };
+}
 export function newGoalId() {
     return `goal-${randomUUID()}`;
 }
@@ -36,9 +80,13 @@ export class GoalRepository {
         }
     }
     goalPath(goalId) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(goalId))
+            throw new Error("Invalid goal id");
         return join(this.dir, `${goalId}.json`);
     }
     planPath(goalId) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(goalId))
+            throw new Error("Invalid goal id");
         return join(this.dir, `${goalId}.plan.json`);
     }
     indexPath() {
@@ -68,31 +116,35 @@ export class GoalRepository {
         return stored;
     }
     upsertIndex(goal) {
-        const index = this.readIndex();
-        const entry = {
-            goal_id: goal.goal_id,
-            status: goal.status,
-            objective: goal.objective,
-            updated_at: goal.updated_at,
-        };
-        const next = index.goals.filter((row) => row.goal_id !== goal.goal_id);
-        next.push(entry);
-        next.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
-        this.writeAtomic(this.indexPath(), {
-            version: 1,
-            updated_at: nowIso(),
-            goals: next,
-        });
+        // Per-goal leases protect records, but independent workers share this index.
+        withStoreWriteCoordinatorSync(this.indexPath(), () => {
+            const index = this.readIndex();
+            const entry = {
+                goal_id: goal.goal_id,
+                status: goal.status,
+                objective: goal.objective,
+                updated_at: goal.updated_at,
+            };
+            const next = index.goals.filter((row) => row.goal_id !== goal.goal_id);
+            next.push(entry);
+            next.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+            this.writeAtomic(this.indexPath(), {
+                version: 1,
+                updated_at: nowIso(),
+                goals: next,
+            });
+        }, { operation_label: 'goal_index_upsert' });
     }
     /** Persist a goal record and refresh the index in one call. */
     saveGoal(goal) {
-        const record = { ...goal, updated_at: nowIso() };
-        this.writeAtomic(this.goalPath(record.goal_id), record);
+        const record = normalizeGoalRecord({ ...goal, updated_at: nowIso() });
+        this.writeAtomic(this.goalPath(record.goal_id), encodeGoalRecord(record));
         this.upsertIndex(record);
         return record;
     }
     getGoal(goalId) {
-        return this.readJson(this.goalPath(goalId));
+        const record = this.readJson(this.goalPath(goalId));
+        return record ? normalizeGoalRecord(record) : undefined;
     }
     savePlan(goalId, plan) {
         this.writeAtomic(this.planPath(goalId), plan);
@@ -101,7 +153,13 @@ export class GoalRepository {
         return this.readJson(this.planPath(goalId));
     }
     listGoals(filter) {
-        return this.readIndex().goals.filter((row) => filter?.status ? row.status === filter.status : true);
+        // Per-goal writers need not serialize on the shared listing cache. Read the
+        // existing authoritative records so concurrent goals cannot disappear there.
+        const records = existsSync(this.dir) ? readdirSync(this.dir).filter(name => name.endsWith('.json') && name !== 'index.json' && !name.endsWith('.plan.json')).flatMap(name => {
+            const goal = this.readJson(join(this.dir, name));
+            return goal?.goal_id ? [{ goal_id: goal.goal_id, status: goal.status, objective: goal.objective, updated_at: goal.updated_at }] : [];
+        }) : [];
+        return records.sort((a, b) => b.updated_at.localeCompare(a.updated_at)).filter((row) => filter?.status ? row.status === filter.status : true);
     }
     /** Delete a goal, its plan, and its index entry. Returns true if present. */
     deleteGoal(goalId) {
@@ -111,12 +169,14 @@ export class GoalRepository {
             if (existsSync(path))
                 rmSync(path);
         }
-        const index = this.readIndex();
-        this.writeAtomic(this.indexPath(), {
-            version: 1,
-            updated_at: nowIso(),
-            goals: index.goals.filter((row) => row.goal_id !== goalId),
-        });
+        withStoreWriteCoordinatorSync(this.indexPath(), () => {
+            const index = this.readIndex();
+            this.writeAtomic(this.indexPath(), {
+                version: 1,
+                updated_at: nowIso(),
+                goals: index.goals.filter((row) => row.goal_id !== goalId),
+            });
+        }, { operation_label: 'goal_index_delete' });
         return existed;
     }
     /**
@@ -124,34 +184,40 @@ export class GoalRepository {
      * startup so a hand-deleted or partially-written index never hides live goals.
      */
     rebuildIndex() {
-        this.ensureDir();
-        const goals = [];
-        for (const name of readdirSync(this.dir)) {
-            if (!name.endsWith(".json") || name.endsWith(".plan.json") || name === "index.json") {
-                continue;
-            }
-            const record = this.readJson(join(this.dir, name));
-            if (record?.goal_id) {
-                goals.push({
-                    goal_id: record.goal_id,
-                    status: record.status,
-                    objective: record.objective,
-                    updated_at: record.updated_at,
-                });
+        return withStoreWriteCoordinatorSync(this.indexPath(), () => {
+            this.ensureDir();
+            const goals = [];
+            for (const name of readdirSync(this.dir)) {
+                if (!name.endsWith(".json") || name.endsWith(".plan.json") || name === "index.json") {
+                    continue;
+                }
+                const record = this.readJson(join(this.dir, name));
+                if (record?.goal_id) {
+                    goals.push({
+                        goal_id: record.goal_id,
+                        status: record.status,
+                        objective: record.objective,
+                        updated_at: record.updated_at,
+                    });
+                }
             }
-        }
-        goals.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
-        const file = { version: 1, updated_at: nowIso(), goals };
-        this.writeAtomic(this.indexPath(), file);
-        return file;
+            goals.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+            const file = { version: 1, updated_at: nowIso(), goals };
+            this.writeAtomic(this.indexPath(), file);
+            return file;
+        }, { operation_label: 'goal_index_rebuild' });
     }
 }
 export function defaultGoalBudgets() {
     return {
-        max_wall_clock_ms: 4 * 60 * 60 * 1000, // 4h
-        max_ticks: 200,
-        max_replans: 3,
-        max_step_retries: 1,
+        max_wall_clock_ms: 0,
+        deadline_explicit: false,
+        host_deadline_explicit: false,
+        max_ticks: 0,
+        tick_budget_explicit: false,
+        max_replans: 0,
+        replan_budget_explicit: false,
+        max_step_retries: 0,
     };
 }
 //# sourceMappingURL=goal-repository.js.map

package/dist/store/repositories/playbook-repository.d.ts

@@ -6,6 +6,9 @@ export interface PlaybookScope {
     model?: string;
     tool?: string;
     reason_code?: string;
+    paths?: string[];
+    task_tags?: string[];
+    failure_signature?: string;
 }
 export interface PlaybookBullet {
     bullet_id: string;
@@ -18,9 +21,32 @@ export interface PlaybookBullet {
     status: PlaybookBulletStatus;
     evidence_refs: string[];
     provenance: {
-        source: "reflector" | "llm_reflector" | "operator" | "migration";
+        source: "reflector" | "llm_reflector" | "operator" | "migration" | "harvest";
         run_id?: string;
+        note?: string;
     };
+    served_count?: number;
+    used_count?: number;
+    used_goals?: string[];
+    scored_attempts?: string[];
+    served_outcomes?: {
+        done_first_attempt: number;
+        failed_same_signature: number;
+        other: number;
+    };
+    evidence_snapshots?: import("../../host-learning.js").Episode[];
+    label?: "checked" | "demonstrated";
+    validation_checks?: Array<{
+        command: string;
+        cwd: string;
+        ok: boolean;
+    }>;
+    acceptance_errors?: string[];
+    retired_reason?: string;
+    ever_active?: boolean;
+    activated_at?: string;
+    last_active_at?: string;
+    retired_at?: string;
     created_at: string;
     updated_at: string;
 }
@@ -31,6 +57,8 @@ export type PlaybookDeltaOp = {
     content: string;
     evidence_refs: string[];
     provenance: PlaybookBullet["provenance"];
+    status?: PlaybookBulletStatus;
+    evidence_snapshots?: PlaybookBullet["evidence_snapshots"];
 } | {
     type: "TAG";
     bullet_id: string;
@@ -65,9 +93,10 @@ export declare function isPlaybookSection(value: string): value is PlaybookSecti
 export declare function isPlaybookStatus(value: string): value is PlaybookBulletStatus;
 export declare class PlaybookRepository {
     private readonly workspaceRoot;
+    private readonly buffered?;
     private readonly dir;
     private migrated;
-    constructor(workspaceRoot: string);
+    constructor(workspaceRoot: string, buffered?: Map<string, string> | undefined);
     get root(): string;
     private useStore;
     private ensureDir;
@@ -88,13 +117,19 @@ export declare class PlaybookRepository {
     readIndex(): PlaybookIndexFile;
     private upsertIndex;
     saveBullet(bullet: PlaybookBullet): PlaybookBullet;
-    createBullet(input: Omit<PlaybookBullet, "bullet_id" | "helpful_count" | "harmful_count" | "observed_count" | "status" | "created_at" | "updated_at">): PlaybookBullet;
+    createBullet(input: Omit<PlaybookBullet, "bullet_id" | "helpful_count" | "harmful_count" | "observed_count" | "status" | "created_at" | "updated_at"> & {
+        status?: PlaybookBulletStatus;
+    }): PlaybookBullet;
     getBullet(bulletId: string): PlaybookBullet | undefined;
     listBullets(filter?: {
         section?: PlaybookSection;
         status?: PlaybookBulletStatus;
         scope?: PlaybookScope;
     }): PlaybookBullet[];
+    /** Pure listing for assignment/context selection; never migrates or repairs. */
+    listBulletsReadOnly(filter?: {
+        status?: PlaybookBulletStatus;
+    }): PlaybookBullet[];
     applyDeltaOps(ops: PlaybookDeltaOp[], config?: PlaybookConfig): PlaybookApplyResult;
     rebuildIndex(): PlaybookIndexFile;
 }
@@ -104,4 +139,7 @@ export declare function renderPlaybookMarkdown(repo: PlaybookRepository, filter?
     status?: PlaybookBulletStatus;
 }): string;
 export declare function materializePlaybookMarkdown(workspaceRoot: string): string;
+/** One existing-pack transaction; the synchronous repository edits an ephemeral
+ * buffer, never recursively taking the non-reentrant cross-process lease. */
+export declare function withPlaybookTransaction<T>(root: string, apply: (repo: PlaybookRepository) => T | Promise<T>): Promise<T>;
 //# sourceMappingURL=playbook-repository.d.ts.map

package/dist/store/repositories/playbook-repository.js

@@ -1,3 +1,4 @@
+import { learningLifecycle } from '../../learning-lifecycle.js';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -24,14 +25,16 @@ function truncateContent(content) {
 function scopeMatches(bulletScope, filter) {
     if (!filter)
         return true;
-    return Object.entries(filter).every(([key, value]) => value === undefined || bulletScope[key] === undefined || bulletScope[key] === value);
+    return Object.entries(filter).every(([key, value]) => value === undefined || bulletScope[key] === undefined || JSON.stringify(bulletScope[key]) === JSON.stringify(value));
 }
 export class PlaybookRepository {
     workspaceRoot;
+    buffered;
     dir;
     migrated = false;
-    constructor(workspaceRoot) {
+    constructor(workspaceRoot, buffered) {
         this.workspaceRoot = workspaceRoot;
+        this.buffered = buffered;
         this.dir = join(workspaceRoot, "agent-state", "playbook");
     }
     get root() {
@@ -67,6 +70,10 @@ export class PlaybookRepository {
         return operationalArtifactKey(relPath);
     }
     writeText(relPath, content) {
+        if (this.buffered) {
+            this.buffered.set(relPath, content);
+            return relPath;
+        }
         if (this.useStore()) {
             return writeOperationalArtifactSync(this.workspaceRoot, relPath, content);
         }
@@ -81,6 +88,8 @@ export class PlaybookRepository {
         return this.writeText(relPath, JSON.stringify(value, null, 2));
     }
     readText(relPath) {
+        if (this.buffered?.has(relPath))
+            return this.buffered.get(relPath);
         if (this.useStore()) {
             const storeText = readStoreBlobSync(this.workspaceRoot, this.artifactKey(relPath));
             if (typeof storeText === "string")
@@ -92,6 +101,8 @@ export class PlaybookRepository {
         return readFileSync(path, "utf8");
     }
     existsRel(relPath) {
+        if (this.buffered?.has(relPath))
+            return true;
         if (this.useStore() && typeof readStoreBlobSync(this.workspaceRoot, this.artifactKey(relPath)) === "string") {
             return true;
         }
@@ -109,7 +120,7 @@ export class PlaybookRepository {
         }
     }
     listBulletRelPaths() {
-        const rels = new Set();
+        const rels = new Set([...(this.buffered?.keys() ?? [])].filter(k => /^agent-state\/playbook\/[^/]+\.json$/.test(k) && !k.endsWith("/__index.json")));
         if (this.useStore()) {
             const prefix = this.artifactKey("agent-state/playbook/");
             for (const key of listStoreKeysSync(this.workspaceRoot, prefix)) {
@@ -164,7 +175,8 @@ export class PlaybookRepository {
     }
     saveBullet(bullet) {
         this.ensureDir();
-        const record = { ...bullet, content: truncateContent(bullet.content), updated_at: nowIso() };
+        const at = nowIso(), previous = this.readJson(this.bulletRelPath(bullet.bullet_id));
+        const record = { ...bullet, ...learningLifecycle(bullet, previous, at), content: truncateContent(bullet.content), updated_at: at };
         this.writeJson(this.bulletRelPath(record.bullet_id), record);
         this.upsertIndex(record);
         return record;
@@ -181,7 +193,11 @@ export class PlaybookRepository {
             observed_count: input.provenance.source === "llm_reflector" ? 0 : 1,
             // Evidence-free notes from every producer are retained but cannot be injected
             // until evidence is attached through a curated path.
-            status: input.evidence_refs.length === 0 ? "quarantined" : "active",
+            status: input.evidence_refs.length === 0 ? "quarantined" : input.status ?? "active",
+            evidence_snapshots: input.evidence_snapshots,
+            label: input.label,
+            validation_checks: input.validation_checks,
+            acceptance_errors: input.acceptance_errors,
             evidence_refs: input.evidence_refs.slice(0, 5),
             provenance: input.provenance,
             created_at: at,
@@ -200,6 +216,10 @@ export class PlaybookRepository {
             return bullet && scopeMatches(bullet.scope, filter?.scope) ? [bullet] : [];
         });
     }
+    /** Pure listing for assignment/context selection; never migrates or repairs. */
+    listBulletsReadOnly(filter) {
+        return this.listBulletRelPaths().flatMap(rel => { const b = this.readJson(rel); return b?.bullet_id && (!filter?.status || b.status === filter.status) ? [b] : []; });
+    }
     applyDeltaOps(ops, config = {}) {
         const result = { added: 0, tagged: 0, refused: [] };
         for (const op of ops) {
@@ -311,4 +331,40 @@ export function materializePlaybookMarkdown(workspaceRoot) {
     writeFileSync(path, renderPlaybookMarkdown(repo), "utf8");
     return path;
 }
+/** One existing-pack transaction; the synchronous repository edits an ephemeral
+ * buffer, never recursively taking the non-reentrant cross-process lease. */
+export async function withPlaybookTransaction(root, apply) {
+    const { withStoreWriteCoordinator } = await import("../write-coordinator.js");
+    const { getWorkspaceStorePath } = await import("../store-snapshot.js");
+    const { openStore } = await import("../ace-packed-store.js");
+    const lock = storeExistsSync(root) ? getWorkspaceStorePath(root) : join(root, "agent-state/playbook/__index.json");
+    return withStoreWriteCoordinator(lock, async () => {
+        if (!storeExistsSync(root))
+            return apply(new PlaybookRepository(root));
+        const store = await openStore(getWorkspaceStorePath(root));
+        try {
+            const buffer = new Map();
+            for await (const key of store.list())
+                if (key.startsWith("state/artifacts/agent-state/playbook/") || key === "state/artifacts/agent-state/lessons.md") {
+                    const value = await store.getBlob(key);
+                    if (value !== undefined)
+                        buffer.set(key.slice("state/artifacts/".length), value);
+                }
+            const prior = new Map(buffer);
+            const result = await apply(new PlaybookRepository(root, buffer));
+            for (const [rel, value] of buffer)
+                if (prior.get(rel) !== value)
+                    await store.setBlob(operationalArtifactKey(rel), value);
+            await store.commit();
+            return result;
+        }
+        catch (error) {
+            store.discardPending();
+            throw error;
+        }
+        finally {
+            await store.close({ commit: false });
+        }
+    }, { operation_label: "host_playbook" });
+}
 //# sourceMappingURL=playbook-repository.js.map

package/dist/store/repositories/todo-repository.d.ts

@@ -6,20 +6,26 @@ import { AcePackedStore } from "../ace-packed-store.js";
 export interface TodoNode {
     id: string;
     title: string;
-    status: "pending" | "in_progress" | "done" | "blocked" | "cancelled";
+    status: "pending" | "in_progress" | "done" | "blocked" | "gated" | "cancelled";
     priority?: "high" | "medium" | "low";
     assigned_to?: string;
     depends_on?: string[];
     created_at: number;
     updated_at: number;
     notes?: string;
+    section?: string;
+    source_line?: number;
+    step_ref?: {
+        goal_id: string;
+        step_id: string;
+    };
 }
 type TodoUpsertInput = Omit<TodoNode, "created_at" | "updated_at"> & Partial<Pick<TodoNode, "created_at">>;
 export declare class TodoRepository {
     private store;
     constructor(store: AcePackedStore);
     private key;
-    create(todo: Omit<TodoNode, "created_at" | "updated_at">): Promise<TodoNode>;
+    create(todo: TodoUpsertInput): Promise<TodoNode>;
     get(id: string): Promise<TodoNode | undefined>;
     update(id: string, patch: Partial<TodoNode>): Promise<TodoNode>;
     list(filter?: {

package/dist/store/repositories/todo-repository.js

@@ -14,7 +14,7 @@ export class TodoRepository {
     }
     async create(todo) {
         const now = Date.now();
-        const record = { ...todo, created_at: now, updated_at: now };
+        const record = { ...todo, created_at: todo.created_at ?? now, updated_at: now };
         await this.store.setJSON(this.key(todo.id), record);
         await this.store.appendEntry({
             kind: EntityKind.Todo,

package/dist/store/repositories/vericify-repository.d.ts

@@ -13,7 +13,10 @@ export interface VericifyPost {
     summary: string;
     ts: number;
     metadata?: Record<string, unknown>;
+    /** Exact imported record, including historical spelling and unknown fields. */
+    legacy_record?: Record<string, unknown>;
 }
+export declare function projectVericifyPost(post: VericifyPost): Record<string, unknown>;
 export declare class VericifyRepository {
     private store;
     private onMutation?;
@@ -27,6 +30,7 @@ export declare class VericifyRepository {
         agent_id?: string;
         kind?: VericifyPost["kind"];
     }): Promise<VericifyPost[]>;
+    importPost(original: Record<string, unknown>): Promise<VericifyPost>;
     private _addToIndex;
 }
 //# sourceMappingURL=vericify-repository.d.ts.map

package/dist/store/repositories/vericify-repository.js

@@ -5,6 +5,21 @@
  * Also triggers Vericify projection file writes on mutation.
  */
 import { ContentSource, EntityKind } from "../types.js";
+import { isDeepStrictEqual } from "node:util";
+export function projectVericifyPost(post) {
+    if (post.legacy_record)
+        return { ...post.legacy_record };
+    return {
+        process_post_id: post.id, run_id: post.run_id, agent_id: post.agent_id,
+        kind: post.kind, summary: post.summary, timestamp: new Date(post.ts).toISOString(),
+        branch_id: typeof post.metadata?.branch_id === "string" ? post.metadata.branch_id : undefined,
+        lane_id: typeof post.metadata?.lane_id === "string" ? post.metadata.lane_id : undefined,
+        blocker_category: typeof post.metadata?.blocker_category === "string" ? post.metadata.blocker_category : undefined,
+        checkpoint_ref: typeof post.metadata?.checkpoint_ref === "string" ? post.metadata.checkpoint_ref : undefined,
+        tool_refs: Array.isArray(post.metadata?.tool_refs) ? post.metadata.tool_refs.filter((v) => typeof v === "string") : [],
+        evidence_refs: Array.isArray(post.metadata?.evidence_refs) ? post.metadata.evidence_refs.filter((v) => typeof v === "string") : [],
+    };
+}
 const INDEX_KEY = "state/vericify/posts/index";
 export class VericifyRepository {
     store;
@@ -47,6 +62,37 @@ export class VericifyRepository {
         }
         return posts.sort((a, b) => a.ts - b.ts);
     }
+    async importPost(original) {
+        const id = original.process_post_id ?? original.id;
+        const ts = typeof original.ts === "number" ? original.ts : Date.parse(String(original.timestamp ?? ""));
+        if (typeof id !== "string" || !id || id === "index" || !Number.isFinite(ts) ||
+            typeof original.run_id !== "string" || typeof original.agent_id !== "string" ||
+            typeof original.kind !== "string" || typeof original.summary !== "string") {
+            throw new Error("Historical post lacks a valid identity, timestamp or required fields");
+        }
+        const existing = await this.store.getJSON(this.key(id));
+        if (existing) {
+            // JSON roundtrip removes undefined optional projection properties.
+            const prior = existing.legacy_record ?? JSON.parse(JSON.stringify(projectVericifyPost(existing)));
+            if (!isDeepStrictEqual(prior, original))
+                throw new Error(`Historical post identity conflict: ${id}`);
+            await this._addToIndex(id);
+            return existing;
+        }
+        const metadata = {
+            ...(original.metadata && typeof original.metadata === "object" && !Array.isArray(original.metadata) ? original.metadata : {}),
+            ...Object.fromEntries(["branch_id", "lane_id", "blocker_category", "checkpoint_ref", "tool_refs", "evidence_refs"].filter((k) => k in original).map((k) => [k, original[k]])),
+        };
+        const record = {
+            id, ts, run_id: original.run_id, agent_id: original.agent_id,
+            kind: original.kind, summary: original.summary,
+            metadata, legacy_record: original,
+        };
+        await this.store.setJSON(this.key(id), record);
+        await this.store.appendEntry({ kind: EntityKind.VericifyPost, content_source: ContentSource.User, key: this.key(id), payload: record });
+        await this._addToIndex(id);
+        return record;
+    }
     async _addToIndex(id) {
         const index = await this.store.getJSON(INDEX_KEY) ?? [];
         if (!index.includes(id)) {

package/dist/store/skills-install.d.ts

@@ -16,6 +16,7 @@ export interface InstallResult {
     skill: string;
     files: number;
     compacted: boolean;
+    skipped_files: string[];
 }
 export declare function installSkillPack(workspaceRoot: string, skillName: string): Promise<InstallResult>;
 export declare function installAllSkills(workspaceRoot: string): Promise<InstallResult[]>;

package/dist/store/skills-install.js

@@ -16,6 +16,7 @@ import { existsSync } from "fs";
 import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 import { openStore } from "./ace-packed-store.js";
+import { withStoreWriteCoordinator } from "./write-coordinator.js";
 import { bakeSkillPack, listAvailableSkills } from "./knowledge-bake.js";
 import { ensureCanonicalWorkspaceStore, resolveWorkspaceStorePath, } from "./workspace-store-paths.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -40,24 +41,27 @@ export async function installSkillPack(workspaceRoot, skillName) {
     if (!available.includes(skillName)) {
         throw new Error(`Skill pack '${skillName}' not found. Available: ${available.join(", ")}`);
     }
-    const store = await openStore(resolved.storePath);
-    let compacted = false;
-    try {
-        const existing = await store.listSkills();
-        if (existing.includes(skillName)) {
-            console.log(`[skills-install] '${skillName}' already installed — reinstalling`);
+    return withStoreWriteCoordinator(resolved.storePath, async () => {
+        const store = await openStore(resolved.storePath);
+        let compacted = false;
+        const skipped = [];
+        try {
+            const existing = await store.listSkills();
+            if (existing.includes(skillName)) {
+                console.log(`[skills-install] '${skillName}' already installed — reinstalling`);
+            }
+            const files = await bakeSkillPack(store, assetsRoot, skillName, { onSkip: (key) => skipped.push(key) });
+            await store.commit();
+            if (store.deadSpaceRatio > 0.5) {
+                await store.compact();
+                compacted = true;
+            }
+            return { skill: skillName, files, compacted, skipped_files: skipped };
         }
-        const files = await bakeSkillPack(store, assetsRoot, skillName);
-        await store.commit();
-        if (store.deadSpaceRatio > 0.5) {
-            await store.compact();
-            compacted = true;
+        finally {
+            await store.close({ commit: false });
         }
-        return { skill: skillName, files, compacted };
-    }
-    finally {
-        await store.close();
-    }
+    }, { operation_label: "installSkillPack" });
 }
 export async function installAllSkills(workspaceRoot) {
     const assetsRoot = getAssetsRoot();

package/dist/store/source-preservation.d.ts

@@ -0,0 +1,24 @@
+import type { AcePackedStore } from "./ace-packed-store.js";
+export interface SourceIdentity {
+    dev: number;
+    ino: number;
+    size: number;
+    mtimeMs: number;
+    ctimeMs: number;
+}
+export interface PreservedSource {
+    source_path: string;
+    sha256: string;
+    byte_length: number;
+    content_base64: string;
+    identity?: SourceIdentity;
+}
+export declare function sourceFromBytes(sourcePath: string, bytes: Buffer): PreservedSource;
+/** Capture exact bytes without following a replaced final symlink or accepting an unstable read. */
+export declare function captureWorkspaceSource(root: string, path: string): PreservedSource;
+export declare function sourceUnchanged(root: string, path: string, source: PreservedSource): boolean;
+export declare function preservedSourceKey(source: PreservedSource): string;
+export declare function stagePreservedSource(store: AcePackedStore, source: PreservedSource): Promise<string>;
+/** Uses the committed-file reader, never the writer's pending values. */
+export declare function verifyPreservedSource(storePath: string, source: PreservedSource): void;
+//# sourceMappingURL=source-preservation.d.ts.map