@prodero/curator 0.2.1 → 0.3.0

package/dist/core/curation-review.js

@@ -25,7 +25,7 @@ export class CurationReviewError extends Error {
     }
 }
 const fail = (code, message) => { throw new CurationReviewError(code, message); };
-const decisionSchema = z.record(z.enum(['current', 'suggested', 'deferred']));
+const decisionSchema = z.record(z.string(), z.enum(['current', 'suggested', 'deferred']));
 const legacySchema = z.object({ revision: z.number().int().nonnegative(), snapshotHash: z.string(), decisions: decisionSchema }).strict();
 const eventSchema = z.object({
     revision: z.number().int().positive(), at: z.string().datetime(),
@@ -34,7 +34,7 @@ const eventSchema = z.object({
 }).strict();
 const journalSchema = z.object({
     version: z.literal(2), projectIdentity: z.string(), snapshotHash: z.string(),
-    base: z.object({ revision: z.number().int().nonnegative(), decisions: decisionSchema, paused: z.boolean(), origin: z.enum(['new', 'legacy_v1', 'inherited']), inheritedFrom: z.array(z.string()), pauseUpdatedAt: z.string().datetime().optional(), analysis: z.enum(['complete', 'pending', 'failed']).optional(), clarifications: z.record(z.object({ id: z.string(), basisHash: z.string(), sourceIds: z.array(z.string()), state: clarificationStateSchema }).strict()).optional() }).strict(),
+    base: z.object({ revision: z.number().int().nonnegative(), decisions: decisionSchema, paused: z.boolean(), origin: z.enum(['new', 'legacy_v1', 'inherited']), inheritedFrom: z.array(z.string()), pauseUpdatedAt: z.string().datetime().optional(), analysis: z.enum(['complete', 'pending', 'failed']).optional(), clarifications: z.record(z.string(), z.object({ id: z.string(), basisHash: z.string(), sourceIds: z.array(z.string()), state: clarificationStateSchema }).strict()).optional() }).strict(),
     events: z.array(eventSchema).max(REVIEW_RETENTION.maxEvents),
 }).strict();
 export function reviewUnits(plan) {
@@ -176,6 +176,20 @@ async function names(root) {
         return []; throw e; });
     return files.filter(n => /^review_[a-zA-Z0-9_]+\.json$/.test(n)).sort();
 }
+/** Explicit management diagnostics only. Never repairs, deletes or trusts old choices. */
+export async function curationHistoryDiagnostics(root) {
+    const diagnostics = [];
+    for (const name of await names(root))
+        try {
+            await loadStored(root, name.slice(0, -5));
+        }
+        catch (error) {
+            if (!(error instanceof CurationReviewError))
+                throw error;
+            diagnostics.push({ reviewId: name.slice(0, -5), code: error.code, message: error.message });
+        }
+    return diagnostics;
+}
 async function loadStored(root, reviewId) {
     const snapshot = await readJson(await reviewPath(root, reviewId));
     if (snapshot.version !== 1 && snapshot.version !== 2 && snapshot.version !== 3)
@@ -236,11 +250,23 @@ export async function loadCurationReview(root, reviewId, options = {}) {
 const expired = (snapshot) => Date.now() - Date.parse(snapshot.createdAt) > REVIEW_RETENTION.maxAgeMs;
 // Pin all decision-bearing history, even after expiry. Refuse at capacity instead
 // of silently removing unresolved decisions. Empty abandoned previews may expire.
-async function pruneForCreation(root, now) {
+async function pruneForCreation(root, now, preserveUnavailable = false) {
     const referenced = await (await import('./curation-semantic-jobs.js')).semanticReferencedReviews(root);
     const records = [];
     for (const name of await names(root)) {
-        const id = name.slice(0, -5), { review, journal } = await loadStored(root, id);
+        const id = name.slice(0, -5);
+        let stored;
+        try {
+            stored = await loadStored(root, id);
+        }
+        catch (error) {
+            if (!preserveUnavailable || !(error instanceof CurationReviewError))
+                throw error;
+            const stat = await fs.stat(await reviewPath(root, id));
+            records.push({ id, pinned: true, time: stat.mtimeMs });
+            continue;
+        }
+        const { review, journal } = stored;
         const stat = await fs.stat(await reviewPath(root, id));
         const pinned = referenced.has(review.snapshot.reviewId) || !!review.snapshot.revision?.parentRevisionId || journal.events.length > 0 || Object.keys(journal.base.decisions).length > 0 || journal.base.paused;
         records.push({ id: review.snapshot.reviewId, pinned, time: stat.mtimeMs });
@@ -293,7 +319,7 @@ async function legacyPause(root, plan, journal) {
         return journal.base.paused;
     return !!checkpoint || !!journal?.base.paused;
 }
-export async function createCurationReview(root, successor, memorySyncSources) {
+export async function createCurationReview(root, successor, memorySyncSources, options = {}) {
     const create = async () => {
         if (await fs.stat(await checkedDataPath(root, '.transactions/pending.json')).then(() => true, () => false))
             fail('recovery_required', 'Finish the pending transaction before starting a new review.');
@@ -309,8 +335,9 @@ export async function createCurationReview(root, successor, memorySyncSources) {
                 carriedSemantic = { kind: 'semantic-v2', validator: 'semantic-1', basePlan: baselinePlan, analyses, plan };
             }
         }
+        const fresh = options.fresh === true || successor?.parent.snapshot.revision?.historyPolicy === 'fresh-current';
         const units = reviewUnits(plan);
-        const inherited = successor ? { decisions: {}, from: [successor.parent.snapshot.reviewId] } : await inheritedDecisions(root, plan, units);
+        const inherited = successor ? { decisions: {}, from: [successor.parent.snapshot.reviewId] } : fresh ? { decisions: {}, from: [] } : await inheritedDecisions(root, plan, units);
         const invalidatedDecisions = [];
         if (successor)
             for (const [id, decision] of Object.entries(successor.parent.state.decisions)) {
@@ -322,18 +349,18 @@ export async function createCurationReview(root, successor, memorySyncSources) {
                 else
                     invalidatedDecisions.push(id);
             }
-        const previous = await latestCurationReview(root, plan.planId);
+        const previous = fresh ? undefined : await latestCurationReview(root, plan.planId);
         const body = { version: carriedSemantic ? 3 : 2, reviewId: successor ? `review_${hash(successor.operationId).slice(0, 40)}` : sortableId('obs').replace(/^obs_/, 'review_'), project: plan.project, projectIdentity: await fs.realpath(root), planHash: plan.planId, createdAt: new Date(now).toISOString(), plan, units };
         let snapshot = JSON.parse(JSON.stringify({ ...body, snapshotHash: hash(body) }));
         const journal = { version: 2, projectIdentity: snapshot.projectIdentity, snapshotHash: snapshot.snapshotHash,
-            base: { revision: 0, decisions: inherited.decisions, paused: successor?.parent.state.paused ?? previous?.state.paused ?? await legacyPause(root, plan), origin: inherited.from.length ? 'inherited' : 'new', inheritedFrom: inherited.from }, events: [] };
+            base: { revision: 0, decisions: inherited.decisions, paused: successor?.parent.state.paused ?? previous?.state.paused ?? (fresh ? false : await legacyPause(root, plan)), origin: inherited.from.length ? 'inherited' : 'new', inheritedFrom: inherited.from }, events: [] };
         journal.base.pauseUpdatedAt = new Date(now).toISOString();
         journal.base.analysis = 'complete';
         journal.base.clarifications = Object.fromEntries(Object.entries(stateFrom(snapshot, journal).items).filter(([, i]) => i.issue).map(([id, i]) => [id, i.issue]));
         const initial = stateFrom(snapshot, journal), catalog = await loadMemoryCatalog(root, { persistCache: false });
         const revisionSources = catalog.summaries.filter(s => !memorySyncSources || memorySyncSources.includes(s.id));
         await Promise.all(revisionSources.map(s => catalog.load(s.id)));
-        const revision = sealRevision({ version: carriedSemantic ? 2 : 1, lineageId: successor?.parent.snapshot.revision?.lineageId ?? successor?.parent.snapshot.reviewId ?? snapshot.reviewId,
+        const revision = sealRevision({ ...(fresh ? { historyPolicy: 'fresh-current' } : {}), version: carriedSemantic ? 2 : 1, lineageId: successor?.parent.snapshot.revision?.lineageId ?? successor?.parent.snapshot.reviewId ?? snapshot.reviewId,
             parentRevisionId: successor?.parent.snapshot.revision?.id ?? null, parentReviewId: successor?.parent.snapshot.reviewId ?? null, reviewId: snapshot.reviewId, projectIdentity: snapshot.projectIdentity,
             baseline: plan.fingerprint, sources: revisionSources.map(s => ({ id: s.id, revision: catalog.originalHashes.get(s.id) })).sort((a, b) => a.id.localeCompare(b.id)),
             evidence: [...new Map(plan.proposals.flatMap(p => (p.investigation?.evidence ?? []).map(e => [e.path, { path: e.path, revision: e.revision }]))).values()].sort((a, b) => a.path.localeCompare(b.path)),
@@ -347,7 +374,7 @@ export async function createCurationReview(root, successor, memorySyncSources) {
         if (Buffer.byteLength(JSON.stringify(snapshot)) > REVIEW_RETENTION.maxBytes)
             fail('review_too_large', 'Review is too large. Reduce the review scope first.');
         await ensureDataDirectory(root, directory);
-        await pruneForCreation(root, now);
+        await pruneForCreation(root, now, fresh);
         // Publish the immutable snapshot last. A crash can leave only an unpublished seed.
         await writeFileAtomic(await reviewPath(root, snapshot.reviewId, true), JSON.stringify(journal));
         await writeFileAtomic(await reviewPath(root, snapshot.reviewId), JSON.stringify(snapshot));
@@ -419,18 +446,18 @@ export async function latestCurationReview(root, planHash) {
     return reviews.filter(r => !parents.has(r.snapshot.revision?.id) && (r.snapshot.planHash === planHash || (r.snapshot.revision ? deterministicBaseline(r.snapshot.revision).planId : r.snapshot.planHash) === planHash)).sort((a, b) => b.snapshot.createdAt.localeCompare(a.snapshot.createdAt))[0];
 }
 /** Authoritative saved-state projection, including old pauses and completed receipts. */
-export async function curationReviewView(root, plan, supplied) {
-    const candidate = supplied ?? await latestCurationReview(root, plan.planId);
+export async function curationReviewView(root, plan, supplied, options = {}) {
+    const candidate = supplied ?? (options.fresh ? undefined : await latestCurationReview(root, plan.planId));
     const stored = candidate ? await loadStored(root, candidate.snapshot.reviewId) : undefined;
     const review = stored?.review;
     plan = review?.snapshot.plan ?? plan;
     const units = review?.snapshot.units ?? reviewUnits(plan);
-    const inherited = review ? undefined : await inheritedDecisions(root, plan, units);
+    const inherited = review ? undefined : options.fresh ? { decisions: {}, from: [] } : await inheritedDecisions(root, plan, units);
     const journal = stored?.journal;
     const state = review ? structuredClone(review.state) : stateFrom({ snapshotHash: '', plan, units }, {
         base: { revision: 0, decisions: inherited.decisions, paused: false, origin: 'inherited', inheritedFrom: inherited.from }, events: [],
     });
-    state.paused = await legacyPause(root, plan, journal);
+    state.paused = options.fresh && !review ? false : await legacyPause(root, plan, journal);
     if (review)
         await applyReceiptState(root, { snapshot: review.snapshot, state });
     const semantic = review ? await (await import('./curation-semantic-jobs.js')).semanticReviewStatus(root, review) : undefined;
@@ -494,7 +521,15 @@ export async function resumeCurationReview(root, reviewId) {
         seen.add(review.snapshot.reviewId);
         let child;
         for (const name of await names(root)) {
-            const stored = await loadStored(root, name.slice(0, -5));
+            let stored;
+            try {
+                stored = await loadStored(root, name.slice(0, -5));
+            }
+            catch (error) {
+                if (review.snapshot.revision?.historyPolicy !== 'fresh-current' || !(error instanceof CurationReviewError))
+                    throw error;
+                continue;
+            }
             if (stored.review.snapshot.revision?.parentRevisionId === review.snapshot.revision?.id && review.snapshot.revision) {
                 if (child)
                     fail('invalid_review', 'Forked review lineage.');
@@ -521,11 +556,20 @@ export function validateRevisionReceipt(receipt) {
     if (![2, 3].includes(snapshot.version) || state.snapshotHash !== snapshotHash || snapshot.projectIdentity !== receipt.projectIdentity || hash(receipt.applied) !== hash(receipt.selectedIds) || receipt.operationId !== curationOperationId(receipt.reviewId, receipt.selectedIds, receipt.reviewRevisionId, receipt.selectionHash) || hash(body) !== snapshotHash || snapshot.planHash !== receipt.planHash || snapshot.reviewId !== receipt.reviewId || snapshot.revision.id !== receipt.reviewRevisionId || hash(snapshot.revision.typedPlan.plan) !== hash(snapshot.plan) || hash(state.decisions) !== hash(receipt.decisions) || state.revision !== receipt.decisionRevision || receipt.selectionHash !== curationSelectionHash(snapshot.revision.id, state.revision, receipt.selectedIds) || receipt.executionHash !== hash([snapshotHash, state, receipt.selectedIds]))
         fail('invalid_review', 'Execution binding changed.');
 }
-export async function reserveSuccessorCapacity(root) { await pruneForCreation(root, Date.now()); }
+export async function reserveSuccessorCapacity(root, preserveUnavailable = false) { await pruneForCreation(root, Date.now(), preserveUnavailable); }
 /** Read-only lineage check; semantic tools must never invoke transaction recovery. */
 export async function assertCurationHead(root, review) {
     for (const name of await names(root)) {
-        const { review: other } = await loadStored(root, name.slice(0, -5));
+        let stored;
+        try {
+            stored = await loadStored(root, name.slice(0, -5));
+        }
+        catch (error) {
+            if (review.snapshot.revision?.historyPolicy !== 'fresh-current' || !(error instanceof CurationReviewError))
+                throw error;
+            continue;
+        }
+        const { review: other } = stored;
         if (other.snapshot.revision?.lineageId !== review.snapshot.revision?.lineageId && other.snapshot.createdAt > review.snapshot.createdAt && other.snapshot.revision && review.snapshot.revision && deterministicBaseline(other.snapshot.revision).planId === deterministicBaseline(review.snapshot.revision).planId)
             fail('stale_review', 'A newer review supersedes this input.');
         if (other.snapshot.revision?.parentRevisionId === review.snapshot.revision?.id && review.snapshot.revision)

package/dist/core/curation-revision.js

@@ -59,6 +59,8 @@ export function selectionProblems(manifest, selectedIds) {
 export function sealRevision(body) { return { ...body, id: `revision_${revisionHash(body)}` }; }
 export function validateRevision(revision) {
     assertSafeCurationData(revision);
+    if (revision.historyPolicy !== undefined && revision.historyPolicy !== 'fresh-current')
+        throw new Error('Unsupported curation history policy');
     if (![1, 2].includes(revision.version) || revision.typedPlan.plan.version !== 1 || revision.dependencies.version !== 1 || revision.dependencies.engine !== 'structural-1')
         throw new Error('Unsupported curation revision validator');
     const { id, ...body } = revision;

package/dist/core/curation-semantic-jobs.js

@@ -3,7 +3,7 @@
 import { assertSafeCurationData } from './curation-evidence.js';
 import fs from 'node:fs/promises';
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { jsonSchema } from './json-schema.js';
 import { checkedDataPath, ensureDataDirectory, writeFileAtomic } from './storage.js';
 import { withSyncLock, ownsSyncLock } from './sync-transaction.js';
 import { loadMemoryCatalog } from './memory-index.js';
@@ -160,7 +160,7 @@ async function makeBundle(root, review, componentId, limits) {
     bundle.id = `bundle_${hash(bundle)}`;
     return bundle;
 }
-function response(job) { const { bundle, ...input } = job.input; const history = job.events.map(({ proposal, ...event }) => event); return { jobId: job.input.jobId, status: last(job).status, job: { ...job, input, events: history }, task: { instructions: SEMANTIC_INSTRUCTIONS, proposalSchema: zodToJsonSchema(semanticProposalSchema, { $refStrategy: 'none' }), data: bundle }, acceptance: 'staged_candidate_only', validation: last(job).reason, resultReviewId: last(job).resultReviewId }; }
+function response(job) { const { bundle, ...input } = job.input; const history = job.events.map(({ proposal, ...event }) => event); return { jobId: job.input.jobId, status: last(job).status, job: { ...job, input, events: history }, task: { instructions: SEMANTIC_INSTRUCTIONS, proposalSchema: jsonSchema(semanticProposalSchema), data: bundle }, acceptance: 'staged_candidate_only', validation: last(job).reason, resultReviewId: last(job).resultReviewId }; }
 const passCount = (history, lineageId) => history.filter(j => j.input.lineageId === lineageId && j.input.reason !== 'validation_correction').length;
 const passLimit = (history, lineageId, limits) => Math.min(limits.maxPasses, ...history.filter(j => j.input.lineageId === lineageId).map(j => j.input.bundle.limits.maxPasses));
 function boundedRecoveryLimits(previous, requested) {

package/dist/core/json-schema.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+/** Preserve the existing draft-7 input contract, including optional defaults. */
+export function jsonSchema(schema) {
+    return z.toJSONSchema(schema, { target: 'draft-7', io: 'input', reused: 'inline' });
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/core/memory-index.js

@@ -99,7 +99,7 @@ const summarySchema = z.object({
         ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid v3 applicability cache entry' });
     }
 });
-const memoryCacheSchema = z.object({ version: z.literal(10), entries: z.record(summarySchema) });
+const memoryCacheSchema = z.object({ version: z.literal(10), entries: z.record(z.string(), summarySchema) });
 async function readCache(root, persistCache) {
     if (persistCache)
         await ensureDerivedStateRoot(root);

package/dist/core/memory-pressure.js

@@ -5,7 +5,7 @@ import { checkedDataPath, ensureDataDirectory, writeFileAtomic, sha256, parseChe
 import { withSyncLock } from './sync-transaction.js';
 export const MEMORY_PRESSURE_LIMITS = { sessions: 32, syncs: 32, records: 128, relationships: 128, bytes: 1048576 };
 export const MEMORY_PRESSURE_PATH = 'local/memory-pressure.json';
-const reasons = ['selected', 'marginal-value', 'context-budget', 'required-budget', 'item-limit', 'rank-window', 'inactive', 'superseded', 'scope-mismatch', 'no-match'];
+const reasons = ['selected', 'task-dispute', 'marginal-value', 'context-budget', 'required-budget', 'item-limit', 'rank-window', 'inactive', 'superseded', 'scope-mismatch', 'no-match'];
 const count = z.number().finite().nonnegative();
 const id = z.string().max(256);
 const recordSchema = z.object({
@@ -20,10 +20,19 @@ const selectionSchema = recordSchema.extend({ bucket: z.enum(['required', 'conte
 const totalsSchema = z.object({ records: count, tokens: count }).strict();
 const retrievalSchema = z.object({
     queryHash: z.string().regex(/^[a-f0-9]{64}$/), purpose: z.string().max(16),
+    taskContextHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     budgets: z.object({ contextBudgetTokens: count, requiredContextBudgetTokens: count, maxRequiredItems: count, maxContextItems: count }).strict(),
-    totals: z.record(z.enum(reasons), totalsSchema), requiredTruncated: z.boolean(), requiredOmitted: count,
+    totals: z.partialRecord(z.enum(reasons), totalsSchema), requiredTruncated: z.boolean(), requiredOmitted: count,
     records: z.array(selectionSchema).max(MEMORY_PRESSURE_LIMITS.records), detailsDropped: count,
 }).strict();
+/** Bind optional retrieval telemetry to the actual latest native task scope. */
+export function retrievalTaskContextHash(taskContext) {
+    const value = (taskContext && typeof taskContext === 'object' ? taskContext : {});
+    const dimensions = (key) => Array.isArray(value[key]) ? [...new Set(value[key])].sort() : [];
+    // Signal provenance is diagnostic; replaying the same normalized scope can
+    // legitimately change 'task-text' to 'argument' without changing authority.
+    return sha256(JSON.stringify({ taskText: value.taskText ?? '', paths: dimensions('paths'), subsystems: dimensions('subsystems'), taskKinds: dimensions('taskKinds'), documentationOnly: value.documentationOnly ?? false }));
+}
 /** Called at existing selection/filter branches; never evaluates relevance itself. */
 export class RetrievalEvidenceCollector {
     samples = {};
@@ -40,8 +49,10 @@ export class RetrievalEvidenceCollector {
             sample.push({ ...pressureRecord(item), bucket, reason, score, rankScore, signals: signals.slice(0, 12).map(({ kind, score }) => ({ kind, score })) });
     }
     finish(query, purpose, budgets) {
-        // Retain selected and budget-pressure details before lower-ranked/filter samples.
-        const records = ['selected', 'required-budget', 'context-budget', 'item-limit', 'marginal-value', 'rank-window', 'scope-mismatch', 'inactive', 'superseded', 'no-match'].flatMap(r => this.samples[r] ?? []).slice(0, MEMORY_PRESSURE_LIMITS.records);
+        // Task-bound dispute diagnostics are read-only evidence, never selected
+        // context or a license to activate disputed knowledge. Keep their small
+        // bounded set before ordinary samples so real conflicts reach the agent.
+        const records = ['task-dispute', 'selected', 'required-budget', 'context-budget', 'item-limit', 'marginal-value', 'rank-window', 'scope-mismatch', 'inactive', 'superseded', 'no-match'].flatMap(r => this.samples[r] ?? []).slice(0, MEMORY_PRESSURE_LIMITS.records);
         return { queryHash: sha256(query.trim()), purpose, budgets, totals: this.totals, requiredTruncated: this.requiredOmitted > 0, requiredOmitted: this.requiredOmitted, records, detailsDropped: Object.values(this.totals).reduce((n, t) => n + (t?.records ?? 0), 0) - records.length };
     }
 }
@@ -50,7 +61,7 @@ const relationshipSchema = z.object({ source: id, target: recordSchema, classifi
 const syncSchema = z.object({ checkpoint: id, sessionIds: z.array(id).max(128), sessionIdsDropped: count,
     changes: z.array(recordSchema.extend({ actions: z.array(z.enum(['created', 'updated', 'merged', 'superseded'])).max(4) }).strict()).max(MEMORY_PRESSURE_LIMITS.records),
     totals: z.object({ created: count, updated: count, merged: count, superseded: count }).strict(), changesDropped: count,
-    reconciliation: z.array(relationshipSchema).max(MEMORY_PRESSURE_LIMITS.relationships), classifications: z.record(z.enum(categories), count), relationshipsDropped: count,
+    reconciliation: z.array(relationshipSchema).max(MEMORY_PRESSURE_LIMITS.relationships), classifications: z.partialRecord(z.enum(categories), count), relationshipsDropped: count,
 }).strict();
 export class SyncEvidenceCollector {
     relationships = [];

package/dist/core/memory-sync.js

@@ -25,7 +25,7 @@ export const MEMORY_SYNC_LIMITS = { workflows: 1, candidates: 20, promotions: 50
 const digest = (v) => sha256(JSON.stringify(v));
 const id = z.string().regex(/^area_[a-f0-9]{20}$/);
 const fingerprintSchema = z.object({ knowledge: z.string(), telemetry: z.string(), checkpoints: z.string() }).strict();
-const jobSchema = z.object({ id, label: z.string(), signals: z.array(z.string()), recordCount: z.number(), counts: z.record(z.number()).optional(), categories: z.record(z.number()).optional(), sourceIds: z.array(z.string()).max(24), layers: z.object({ local: z.number(), versioned: z.number() }), selected: z.boolean(), status: z.enum(['unselected', 'pending', 'semantic_work', 'awaiting_review', 'awaiting_clarification', 'deferred', 'applied', 'skipped', 'failed']), curationReviewId: z.string().optional(), curationStateHash: z.string().optional(), error: z.string().optional(), unresolved: z.number().optional(), result: z.unknown().optional() }).strict();
+const jobSchema = z.object({ id, label: z.string(), signals: z.array(z.string()), recordCount: z.number(), counts: z.record(z.string(), z.number()).optional(), categories: z.record(z.string(), z.number()).optional(), sourceIds: z.array(z.string()).max(24), layers: z.object({ local: z.number(), versioned: z.number() }), selected: z.boolean(), status: z.enum(['unselected', 'pending', 'semantic_work', 'awaiting_review', 'awaiting_clarification', 'deferred', 'applied', 'skipped', 'failed']), curationReviewId: z.string().optional(), curationStateHash: z.string().optional(), error: z.string().optional(), unresolved: z.number().optional(), result: z.unknown().optional() }).strict();
 const stateSchema = z.object({ version: z.literal(1), id: z.string().uuid(), root: z.string(), revision: z.number().int(), createdAt: z.string(), state: z.enum(['awaiting_selection', 'semantic_work', 'awaiting_clarification', 'awaiting_review', 'applying', 'awaiting_promotion_selection', 'completed', 'stale']), improveEnabled: z.boolean().optional(), repairLinksEnabled: z.boolean().optional(), brokenLinks: z.number().int().nonnegative().optional(), repairLinksDone: z.boolean().optional(), repairLinksResult: z.object({ fixed: z.number(), remaining: z.number() }).optional(),
     usage: z.object({ sessions: z.number(), available: z.boolean() }).optional(), baseline: fingerprintSchema, jobs: z.array(jobSchema).max(20), promotionEnabled: z.boolean(), promotionDone: z.boolean(), promotionCandidates: z.array(z.object({ id: z.string(), title: z.string(), score: z.number(), signals: z.array(z.string()), recommended: z.boolean() })).max(50), promotionTotal: z.number(), promotionResult: z.unknown().optional(), recovery: z.object({ sessions: z.number(), created: z.number() }), error: z.string().optional(),
     active: z.object({ kind: z.enum(['transformation', 'promotion', 'link-repair']), reviewId: z.string(), candidateId: id.optional(), preview: z.unknown(), approved: z.boolean(), unaffectedKnowledge: z.string().optional(), touchedIds: z.array(z.string()).max(150).optional() }).strict().optional(),
@@ -135,7 +135,7 @@ function view(w, clarification, deferred = []) {
             estimatedTokens: { scope: 'transformed_areas', before: applied.reduce((n, r) => n + r.estimatedTokens.before, 0), after: applied.reduce((n, r) => n + r.estimatedTokens.after, 0) },
             versionedCreated: applied.reduce((n, r) => n + r.created.filter(c => c.layer === 'versioned').length, 0), promoted: promotion?.published ?? 0, promotionCreated: promotion?.created.length ?? 0, promotionUpdated: promotion?.updated.length ?? 0, promotionCovered: promotion?.covered.length ?? 0, localArchived: applied.reduce((n, r) => n + r.archives.filter(a => a.layer === 'local').length, 0), versionedArchived: applied.reduce((n, r) => n + r.archives.filter(a => a.layer === 'versioned').length, 0), acknowledgedCandidateIds: w.jobs.filter(j => j.status === 'applied').map(j => j.id), promotionConflicts: promotion?.conflicts.length ?? 0, historicalProvenancePreserved: true },
         coverage: { promotionCandidatesOmitted: Math.max(0, w.promotionTotal - w.promotionCandidates.length) },
-        next: w.state === 'semantic_work' ? { action: 'semantic_work_required', candidateId: currentJob(w)?.id, instructions: w.improveEnabled ? 'Use prodero_memory_sync prepare for the next candidate. For its curation job, use the existing prodero_curation_reasoning_prepare/propose protocol, then inspect this Sync workflow. Continue sequentially until a question, review or completion. Never Apply or approve; Core handles eligible Local changes. No session lifecycle or extra scans.' : 'Use prodero_memory_sync action=prepare, then reason only over that one bundle and submit action=propose with the returned workflow ID/revision. Continue sequentially while semantic_work_required. Never approve review automatically. Do not use session prepare/record/close for this workflow.' } : ['awaiting_clarification', 'awaiting_promotion_selection', 'awaiting_review'].includes(w.state) ? { action: w.state === 'awaiting_review' ? 'human_review_required' : w.state, tool: 'prodero_sync', arguments: { projectRoot: w.root, workflowId: w.id }, instructions: 'When an unattached continuation returns this state, present the pending human step before ending the turn: read project presentation settings and invoke prodero_sync with these exact arguments once (use prodero_text for text mode). This reopens the same saved workflow without restarting analysis. After presenting it, stop and wait; do not repeatedly reopen an unchanged step. Never select records, answer questions, approve or publish for the human.' } : { action: w.state },
+        next: w.state === 'semantic_work' ? { action: 'semantic_work_required', candidateId: currentJob(w)?.id, instructions: w.improveEnabled ? 'Use prodero_memory_sync prepare for the next candidate. For its curation job, use the existing prodero_curation_reasoning_prepare/propose protocol, then inspect this Sync workflow. Continue sequentially until a question, review or completion. Never Apply or approve; Core handles eligible Local changes. No session lifecycle or extra scans.' : 'Use prodero_memory_sync action=prepare, then reason only over that one bundle and submit action=propose with the returned workflow ID/revision. Continue sequentially while semantic_work_required. Never approve review automatically. Do not use session prepare/record/close for this workflow.' } : ['awaiting_clarification', 'awaiting_promotion_selection', 'awaiting_review'].includes(w.state) ? { action: w.state === 'awaiting_review' ? 'human_review_required' : w.state, tool: 'prodero_sync', arguments: { projectRoot: w.root, workflowId: w.id }, instructions: 'Legacy technical continuation only. Preserve this exact saved workflow and its unresolved originals; do not restore the removed moderation UI or ask routine housekeeping questions. A technical caller may inspect these bindings on explicit request. Required exact human approval still applies to protected/shared/link-removal/publication operations; never infer it, fabricate answers or approve for the user. Ordinary work uses the bounded current-session reconciliation protocol.' } : { action: w.state },
     };
 }
 async function workflowView(root, w, clarification, deferred) {
@@ -516,20 +516,27 @@ export async function runMemorySync(root, raw) {
 }
 /** Open-only diagnostic projection. Never resumes, recovers, migrates or persists a workflow. */
 export async function getMemorySyncOverview(root) {
-    const workflow = await load(root);
-    const pending = workflow && workflow.state !== 'completed' ? workflow : null;
-    const stale = pending && (pending.state === 'stale' || pending.state !== 'applying' && digest(await fingerprint(root)) !== digest(pending.baseline));
-    const workflowStatus = pending ? { id: pending.id, state: stale ? 'stale' : pending.state } : null;
+    let workflowStatus = null;
     try {
+        const workflow = await load(root);
+        const pending = workflow && workflow.state !== 'completed' ? workflow : null;
+        const stale = pending && (pending.state === 'stale' || pending.state !== 'applying' && digest(await fingerprint(root)) !== digest(pending.baseline));
+        workflowStatus = pending ? { id: pending.id, state: stale ? 'stale' : pending.state, ...(pending.error ? { error: publicDiagnostic(pending.error) } : {}) } : null;
         const plan = await getMemoryIntelligencePlan(root);
         return { available: plan.coverage.telemetry !== 'unavailable', sessions: plan.coverage.sessions,
             areas: plan.candidates.map(c => ({ id: c.id, label: c.label, recordCount: c.recordCount, signals: c.signals, counts: c.counts, layers: c.layers, categories: c.categories })),
-            areasOmitted: plan.truncated.candidates, workflow: workflowStatus };
+            areasOmitted: plan.truncated.candidates, workflow: workflowStatus,
+            ...(workflow?.error ? { diagnostic: { code: 'PRODERO_MEMORY_MAINTENANCE_INCOMPLETE', cause: publicDiagnostic(workflow.error), recovery: 'Original knowledge and saved progress are retained. Inspect the saved operation before retrying.' } } : {}) };
     }
-    catch {
-        return { available: false, sessions: 0, areas: [], areasOmitted: 0, workflow: workflowStatus };
+    catch (error) {
+        return memoryOverviewFailure(error, workflowStatus);
     }
 }
+/** Preserve a sanitized failure separately from missing optional usage history. */
+export function memoryOverviewFailure(error, workflow = null) {
+    return { available: false, sessions: 0, areas: [], areasOmitted: 0, workflow,
+        diagnostic: { code: 'PRODERO_MEMORY_OVERVIEW_UNAVAILABLE', cause: publicDiagnostic(error), recovery: 'Saved knowledge is preserved. Inspect the storage diagnostic before retrying; no maintenance was applied by this read.' } };
+}
 /** Resolve continuation ownership from persisted review lineage, not a particular App instance. */
 export async function syncWorkflowForCuration(root, lineageId) {
     const w = await load(root);

package/dist/core/memory-transformation-proposal.js

@@ -1,7 +1,7 @@
 import { applicabilitySchema } from "./applicability.js";
 /** Semantic proposals only: no writer, lifecycle mutation, recovery or provider. */
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { jsonSchema } from './json-schema.js';
 import { buildMemoryTransformationBundle } from './memory-transformation-bundle.js';
 import { assertPathScope } from './path-scope.js';
 import { sha256 } from './storage.js';
@@ -38,7 +38,7 @@ For each source explain coverage, explicitly list only information omitted as re
 export async function prepareMemoryTransformation(root, candidateId) {
     const bundle = await buildMemoryTransformationBundle(root, candidateId);
     return { bundle, instructions: MEMORY_TRANSFORMATION_INSTRUCTIONS,
-        proposalSchema: zodToJsonSchema(memoryTransformationProposalSchema, { $refStrategy: 'none' }),
+        proposalSchema: jsonSchema(memoryTransformationProposalSchema),
         binding: { version: 1, bundleId: bundle.bundleId, candidateId, sourceRevisions: bundle.revisions },
         canPropose: bundle.readyForSemanticWork, persistence: 'return_only' };
 }

package/dist/core/project.js

@@ -5,6 +5,7 @@ import { recordRetrievalEvidence, recordSyncEvidenceLocked } from "./memory-pres
 import { publicDiagnostic } from "./diagnostics.js";
 import { explicitProjectRoot } from "./project-root.js";
 import { reviewSessionKnowledge } from "./session-review.js";
+import { prepareSessionReconciliation } from './session-reconciliation.js';
 import { assertNoSecrets } from "./secrets.js";
 import { intelligenceTelemetry } from "./intelligence.js";
 import { planAssistedSync, observationEvidence, observationKey } from "./knowledge-engine.js";
@@ -432,9 +433,15 @@ export async function prepareProject(start = process.cwd(), options = {}) {
         onRequiredOmitted: options.onRequiredOmitted,
     });
     context.agentUsage = options.agentUsage ?? null;
-    if (automaticSync.intelligence?.audit.status === "attention" && !context.attention.some((item) => item.kind === "conflict")) {
-        context.attention.push({ kind: "memory-health", severity: "important", title: "Knowledge review needed", detail: "The affected-area audit left uncertainty or reached its review budget. Original evidence is preserved." });
-    }
+    // Audit uncertainty/budget is deferred maintenance, not a task blocker or an
+    // instruction to ask the user to moderate memory. Context still owns actual
+    // task-relevant disputes and Required-policy readiness.
+    const maintenance = {
+        automatic: { sessions: automaticSync.sessions, created: automaticSync.created, consolidated: automaticSync.consolidated, duplicates: automaticSync.duplicates, checkpoint: automaticSync.checkpoint },
+        audit: automaticSync.intelligence?.audit,
+        unresolvedRetained: automaticSync.intelligence?.audit.status === 'attention',
+        userInputRequired: false,
+    };
     let session = options.sessionId ? await readSession(root, options.sessionId) : undefined;
     if (session?.status === "closed")
         session = undefined;
@@ -444,9 +451,16 @@ export async function prepareProject(start = process.cwd(), options = {}) {
         session = await updateSessionTaskContext(root, session.id, context.taskContext);
     associatePreparedContext(context, session.id);
     const memoryTelemetry = retrievalEvidence ? await recordRetrievalEvidence(root, session.id, retrievalEvidence) : "unavailable";
+    const reconciliation = context.policyReadiness?.blocking || memoryTelemetry !== 'recorded'
+        ? { state: 'deferred', reason: context.policyReadiness?.blocking ? 'current-task-policy-not-ready' : 'current-retrieval-evidence-unavailable', humanDecisionRequired: false }
+        : await prepareSessionReconciliation(root, { sessionId: session.id }).catch(error => {
+            const diagnostic = publicDiagnostic(error);
+            context.attention.push({ kind: 'memory-health', severity: 'important', title: 'Memory maintenance could not finish', detail: diagnostic });
+            return { state: 'deferred', reason: 'maintenance-storage-failure', diagnostic, humanDecisionRequired: false };
+        });
     const status = await getProjectStatus(root);
     const uiState = { blocking: context.policyReadiness?.blocking ?? false, view: context.attention.length ? "attention" : "context-ready", attention: context.attention };
-    return { memoryTelemetry, project: status, session: { id: session.id, path: `.prodero/sessions/${session.path}`, status: session.status }, automaticSync, context, proderoMetrics: context.metrics, agentUsage: context.agentUsage, uiState };
+    return { memoryTelemetry, project: status, session: { id: session.id, path: `.prodero/sessions/${session.path}`, status: session.status }, automaticSync, maintenance: { ...maintenance, reconciliation }, context, proderoMetrics: context.metrics, agentUsage: context.agentUsage, uiState };
 }
 export async function recordProjectSession(start, sessionId, entries) {
     const root = await findProjectRoot(start);

package/dist/core/session-index.js

@@ -10,8 +10,8 @@ function sameStamp(left, right) { return Boolean(left && left.size === right.siz
 const stampSchema = z.object({ size: z.number().nonnegative(), mtimeMs: z.number().finite(), ctimeMs: z.number().finite() });
 const cacheSchema = z.object({
     version: z.literal(3),
-    checkpoints: z.record(stampSchema.extend({ id: z.string(), createdAt: z.string(), processedKeys: z.array(z.string()), observationHashes: z.array(z.string()).optional() })),
-    sessions: z.record(stampSchema.extend({ id: z.string(), parentSessionId: z.string().regex(/^sess_[a-zA-Z0-9_]+$/).optional(), sha256: z.string().regex(/^[a-f0-9]{64}$/), status: z.enum(["active", "open", "closed"]), hasObservations: z.boolean() })),
+    checkpoints: z.record(z.string(), stampSchema.extend({ id: z.string(), createdAt: z.string(), processedKeys: z.array(z.string()), observationHashes: z.array(z.string()).optional() })),
+    sessions: z.record(z.string(), stampSchema.extend({ id: z.string(), parentSessionId: z.string().regex(/^sess_[a-zA-Z0-9_]+$/).optional(), sha256: z.string().regex(/^[a-f0-9]{64}$/), status: z.enum(["active", "open", "closed"]), hasObservations: z.boolean() })),
 });
 async function readCache(root, persistCache) {
     if (persistCache)