@prodero/curator 0.1.0 → 0.2.1

package/dist/core/sync-transaction.js

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { z } from 'zod';
 import { parseKnowledge } from './memory.js';
 import { parseSkill } from './skills.js';
-import { readConfig, checkedDataPath, exists, parseCheckpointData, ensureRuntimeDirectories, ensureDataDirectory, sha256, writeFileAtomic } from './storage.js';
+import { readConfig, checkedDataPath, exists, parseCheckpointData, ensureRuntimeDirectories, ensureDataDirectory, ensureSelfIgnoredPrivateDirectory, sha256, writeFileAtomic } from './storage.js';
 const writeSchema = z.object({ path: z.string().regex(/^(memory|local\/memory|local\/skills|skills|(local\/)?archive\/\d{4}_(0[1-9]|1[0-2]))\/[a-zA-Z0-9_-]+\.md$|^checkpoints\/chk_[a-zA-Z0-9_-]+\.json$/), before: z.string().nullable(), after: z.string() }).strict();
 const moveSchema = z.object({ from: z.string().regex(/^(local\/)?memory\/[a-zA-Z0-9_-]+\.md$/), to: z.string().regex(/^(local\/)?archive\/\d{4}_(0[1-9]|1[0-2])\/[a-zA-Z0-9_-]+\.md$/), before: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
 const journalSchema = z.discriminatedUnion('version', [
@@ -45,67 +45,98 @@ export function ownsSyncLock(root) {
     const owner = writerContext.getStore();
     return Boolean(owner?.active && owner.root === path.resolve(root));
 }
+function sameLock(a, b) { return a.dev === b.dev && a.ino === b.ino; }
+// Recovery may inspect a PID only while every cooperating acquisition/release is
+// excluded. Otherwise a dead PID can describe the previous directory generation.
+// An interrupted transition guard remains fail-closed, as documented in RECOVERY.
+async function tryLockTransition(root, transition) {
+    const guard = await checkedDataPath(root, '.transactions/lock-recovery');
+    try {
+        await fs.mkdir(guard, { mode: PRIVATE_DIRECTORY_MODE });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return null;
+        throw error;
+    }
+    const identity = await fs.lstat(guard);
+    try {
+        return { value: await transition() };
+    }
+    finally {
+        const current = await fs.lstat(await checkedDataPath(root, '.transactions/lock-recovery'));
+        if (!sameLock(identity, current))
+            throw new Error('Sync lock recovery guard changed; preserve transaction state for inspection');
+        await fs.rm(guard, { recursive: true, force: true });
+    }
+}
+async function removeOwnedLock(root, identity, owner) {
+    const lock = await checkedDataPath(root, '.transactions/lock');
+    const current = await fs.lstat(lock);
+    if (!sameLock(identity, current) || (owner !== undefined && await fs.readFile(await checkedDataPath(root, '.transactions/lock/owner'), 'utf8') !== owner)) {
+        throw new Error('Sync storage writer lock ownership changed; preserve transaction state for inspection');
+    }
+    await fs.rm(lock, { recursive: true, force: true });
+}
+const writerBusy = () => new Error('Another Sync or storage writer is already running, or its lock has no live owner; inspect .prodero/.transactions/lock and .prodero/.transactions/lock-recovery before retrying');
 /** Per-worktree writer exclusion shared by migration, Sync and session mutations. */
 export async function withSyncLock(root, operation, options = {}) {
-    await runtimeDirectory(root);
+    if (options.maintainIntegration === false)
+        await ensureSelfIgnoredPrivateDirectory(root, '.transactions');
+    else
+        await runtimeDirectory(root);
     const lock = await checkedDataPath(root, '.transactions/lock');
     const deadline = Date.now() + (options.waitMs ?? 0);
+    let identity;
     while (true) {
-        try {
-            await fs.mkdir(lock, { mode: PRIVATE_DIRECTORY_MODE });
-            try {
-                await writeFileExclusive(await checkedDataPath(root, '.transactions/lock/owner'), String(process.pid));
-            }
-            catch (error) {
-                await fs.rm(lock, { recursive: true, force: true });
-                throw error;
-            }
-            break;
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
-            await checkedDataPath(root, '.transactions/lock/owner');
-            // Only one stale-owner reaper may inspect/remove a lock. Re-read under that guard
-            // so a second reaper cannot delete a newly acquired writer's lock.
-            const reaper = await checkedDataPath(root, '.transactions/lock-recovery');
-            let reaping = false, recovered = false;
+        const attempt = await tryLockTransition(root, async () => {
+            let created = false;
             try {
+                await fs.mkdir(lock, { mode: PRIVATE_DIRECTORY_MODE });
+                created = true;
+                const acquired = await fs.lstat(lock);
                 try {
-                    await fs.mkdir(reaper, { mode: PRIVATE_DIRECTORY_MODE });
-                    reaping = true;
+                    await writeFileExclusive(await checkedDataPath(root, '.transactions/lock/owner'), String(process.pid));
                 }
                 catch (error) {
-                    if (error.code !== 'EEXIST')
-                        throw error;
+                    await removeOwnedLock(root, acquired);
+                    throw error;
                 }
-                if (reaping) {
-                    const owner = await fs.readFile(await checkedDataPath(root, '.transactions/lock/owner'), 'utf8').catch(error => { if (error.code === 'ENOENT')
-                        return ''; throw error; });
-                    const pid = /^\d+$/.test(owner) ? Number(owner) : 0;
-                    if (pid > 0 && Number.isSafeInteger(pid)) {
-                        try {
-                            process.kill(pid, 0);
-                        }
-                        catch (probe) {
-                            if (probe.code !== 'ESRCH')
-                                throw probe;
-                            await fs.rm(lock, { recursive: true, force: true });
-                            recovered = true;
-                        }
+                return { identity: acquired, recovered: false };
+            }
+            catch (error) {
+                if (created || error.code !== 'EEXIST')
+                    throw error;
+                const stale = await fs.lstat(await checkedDataPath(root, '.transactions/lock')).catch(error => { if (error.code === 'ENOENT')
+                    return null; throw error; });
+                if (!stale)
+                    return { identity: null, recovered: true };
+                const owner = await fs.readFile(await checkedDataPath(root, '.transactions/lock/owner'), 'utf8').catch(error => { if (error.code === 'ENOENT')
+                    return ''; throw error; });
+                const pid = /^\d+$/.test(owner) ? Number(owner) : 0;
+                if (pid > 0 && Number.isSafeInteger(pid)) {
+                    try {
+                        process.kill(pid, 0);
+                    }
+                    catch (probe) {
+                        if (probe.code !== 'ESRCH')
+                            throw probe;
+                        await removeOwnedLock(root, stale, owner);
+                        return { identity: null, recovered: true };
                     }
                 }
+                return { identity: null, recovered: false };
             }
-            finally {
-                if (reaping)
-                    await fs.rm(reaper, { recursive: true, force: true });
-            }
-            if (recovered)
-                continue;
-            if (Date.now() >= deadline)
-                throw new Error('Another Sync or storage writer is already running, or its lock has no live owner; inspect .prodero/.transactions/lock before retrying');
-            await new Promise(resolve => setTimeout(resolve, 10));
+        });
+        if (attempt?.value.identity) {
+            identity = attempt.value.identity;
+            break;
         }
+        if (attempt?.value.recovered)
+            continue;
+        if (Date.now() >= deadline)
+            throw writerBusy();
+        await new Promise(resolve => setTimeout(resolve, 10));
     }
     try {
         if (!options.migrationRecovery && await exists(await checkedDataPath(root, '.transactions/migration.json')))
@@ -133,7 +164,12 @@ export async function withSyncLock(root, operation, options = {}) {
         }
     }
     finally {
-        await fs.rm(lock, { recursive: true, force: true });
+        const releaseDeadline = Date.now() + 5_000;
+        while (!await tryLockTransition(root, () => removeOwnedLock(root, identity, String(process.pid)))) {
+            if (Date.now() >= releaseDeadline)
+                throw writerBusy();
+            await new Promise(resolve => setTimeout(resolve, 10));
+        }
     }
 }
 async function validateWriteContent(root, writes) {

package/dist/core/update.js

@@ -7,6 +7,8 @@ import path from "node:path";
 import { z } from "zod";
 import { PRODERO_SCHEMA_VERSION, PRODERO_VERSION } from "./constants.js";
 import { writeFileAtomic } from "./storage.js";
+import { MANUAL_UPDATE_COMMAND, UPDATE_INSTRUCTIONS } from '../update-instructions.js';
+export { MANUAL_UPDATE_COMMAND } from '../update-instructions.js';
 const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const versionSchema = z.string().regex(semverPattern, "Expected a valid semantic version");
 export const releaseMetadataSchema = z.object({
@@ -17,7 +19,11 @@ export const releaseMetadataSchema = z.object({
     notes: z.string().max(4_000).optional(),
     artifact: z.object({ locator: z.string().trim().min(1), integrity: z.string().regex(/^sha256:[a-f0-9]{64}$/) }).strict(),
 }).strict();
-export const MANUAL_UPDATE_COMMAND = "npm install --global @prodero/curator@latest";
+/** MCP/App instructions are inert for every release source, including dev adapters. */
+export function updateInstructions(source = { id: 'npm' }, installedVersion = PRODERO_VERSION) {
+    return { ok: true, action: 'update-instructions', instructionOnly: true, status: 'manual-update',
+        installedVersion, availableVersion: null, source: source.id, restartRequired: false, command: MANUAL_UPDATE_COMMAND, message: UPDATE_INSTRUCTIONS };
+}
 export class ReleaseSourceUnavailableError extends Error {
 }
 function parseVersion(value) {
@@ -113,7 +119,7 @@ async function runLocalBuild(root, signal) {
         });
     });
 }
-/** One-click adapter for an MCP runtime launched from a development checkout. */
+/** Legacy internal development build adapter. Never invoked by MCP update instructions. */
 export class LocalCheckoutReleaseSource {
     root;
     id = "local-checkout";
@@ -275,7 +281,7 @@ export async function installLatest(source = configuredReleaseSource(), installe
     if (source instanceof NpmReleaseSource || source instanceof UnconfiguredReleaseSource) {
         const check = await checkForUpdate(source, installedVersion);
         return { ok: true, status: "manual-update", installedVersion, availableVersion: check.latest, source: source.id, restartRequired: false,
-            message: `${check.error ? `${check.error} ` : ""}Run: ${MANUAL_UPDATE_COMMAND}. Then restart your MCP host. This tool has not installed or changed anything. Project knowledge remains in the project .prodero directory.` };
+            message: `${check.error ? `${check.error} ` : ""}${UPDATE_INSTRUCTIONS}` };
     }
     let raw;
     try {

package/dist/curation-review-adapter.js

@@ -40,7 +40,7 @@ export async function executeCurationReview(root, input) {
         }
         const review = await loadCurationReview(root, input.reviewId);
         if (review.snapshot.plan.memorySyncSources)
-            throw new CurationReviewError('invalid_selection', 'Sync analysis is read-only; continue its owning Sync Memory operation.');
+            throw new CurationReviewError('invalid_selection', 'Sync analysis is read-only; continue its owning Curate Memory operation.');
         if (review.snapshot.planHash !== input.planHash)
             throw new CurationReviewError('stale_review', 'Knowledge changed since this review.');
         if (review.state.revision !== input.decisionRevision)

package/dist/diagnostic-boundary.js

@@ -1,3 +1,4 @@
+import { renderTextError } from './text-layout.js';
 import { publicDiagnostic } from "./core/diagnostics.js";
 // Preserve only known protocol states, with fixed public prose. Never forward
 // arbitrary plugin error payloads or client-supplied diagnostics.
@@ -29,19 +30,19 @@ export function installDiagnosticBoundary(server) {
                 const state = raw.structuredContent;
                 if (state?.action === 'curation-review-error' && typeof state.code === 'string' && Object.hasOwn(reviewMessages, state.code)) {
                     const message = reviewMessages[state.code];
-                    return { isError: true, content: [{ type: 'text', text: message }], structuredContent: { ok: false, action: 'curation-review-error', code: state.code, error: message, message, ...(state.code === 'dependency_blocked' ? { details: safeDependencyDetails(state.details) } : {}) } };
+                    return { isError: true, content: [{ type: 'text', text: renderTextError(message) }], structuredContent: { ok: false, action: 'curation-review-error', code: state.code, error: message, message, ...(state.code === 'dependency_blocked' ? { details: safeDependencyDetails(state.details) } : {}) } };
                 }
                 const message = raw.structuredContent?.error ?? raw.content?.find(item => item.type === "text")?.text;
                 const safe = publicDiagnostic(message);
                 // Drop arbitrary plugin error payloads too: they may contain rejected input.
-                return { isError: true, content: [{ type: "text", text: safe }], structuredContent: { ok: false, error: safe, message: safe, ...(safe.startsWith("POLICY_REVIEW_REQUIRED:") ? { policyTransition: { decision: "review_required", blocking: true, preserved: true } } : {}) } };
+                return { isError: true, content: [{ type: "text", text: renderTextError(safe) }], structuredContent: { ok: false, error: safe, message: safe, ...(safe.startsWith("POLICY_REVIEW_REQUIRED:") ? { policyTransition: { decision: "review_required", blocking: true, preserved: true } } : {}) } };
             }
             return result;
         }
         catch (error) {
             if (error && typeof error === 'object' && 'code' in error && typeof error.code === 'string' && Object.hasOwn(reviewMessages, error.code)) {
                 const message = reviewMessages[error.code];
-                return { isError: true, content: [{ type: 'text', text: message }], structuredContent: { ok: false, action: 'curation-review-error', code: error.code, error: message, message } };
+                return { isError: true, content: [{ type: 'text', text: renderTextError(message) }], structuredContent: { ok: false, action: 'curation-review-error', code: error.code, error: message, message } };
             }
             throw new Error(publicDiagnostic(error));
         }

package/dist/memory-presentation.js

@@ -1,10 +1,13 @@
+/** Pure product copy shared by Open, Curate Memory and text clients. Core owns decisions. */
+import { memorySyncOperation } from './memory-sync-operation.js';
 const count = (n, one, many = one + 's') => `${n} ${n === 1 ? one : many}`;
 const tokens = (n) => n >= 1000 ? `${(n / 1000).toFixed(2)}K` : String(n);
 export const MEMORY_COPY = {
     automatic: 'Prodero remembers automatically. Sessions save useful knowledge into Local Knowledge when they close.',
-    purpose: 'Sync Memory keeps that memory useful and shareable.',
+    purpose: 'Curate Memory keeps that memory useful and shareable.',
     noHistory: 'Not enough usage history yet to evaluate memory optimization.',
-    stale: 'Project memory changed since this Sync started. Re-analyze before continuing.',
+    stale: 'Project memory changed since this curation started. Re-analyze before continuing.',
+    incompleteProvenance: 'Some provenance fields are incomplete; this is not proof of lost history. Existing records are preserved. Verify actual sources before proposing repairs; diagnostics do not infer or backfill provenance.',
     shared: 'Versioned Knowledge is Git-shareable project state that your agent can change. Curator does not commit or push; review the repository diff before doing so.',
 };
 /** Display only: never infer a topic from a knowledge title. Full labels remain in text/details. */
@@ -41,7 +44,7 @@ export function memoryOpenPresentation(p) {
     const headline = !o?.available ? 'Memory overview unavailable' : areas.length ? `${count(areas.length, 'area')} can be improved` : hasHistory ? 'No improvements suggested by recent usage' : 'Memory is ready to learn';
     const notes = [MEMORY_COPY.automatic, MEMORY_COPY.purpose];
     if (!o?.available)
-        notes.push('Memory analysis is temporarily unavailable. Try Sync Memory again when current work has finished.');
+        notes.push('Memory analysis is temporarily unavailable. Try Curate Memory again when current work has finished.');
     else if (!hasHistory)
         notes.push(MEMORY_COPY.noHistory);
     else if (!areas.length)
@@ -53,31 +56,32 @@ export function memoryOpenPresentation(p) {
     if (areas.some((a) => a.reasons.some((r) => r.includes('did not fit'))))
         notes.push('Some relevant knowledge has not fit into recent task context.');
     if (o?.areasOmitted)
-        notes.push(`${count(o.areasOmitted, 'additional area')} can be inspected in a later Sync Memory run.`);
+        notes.push(`${count(o.areasOmitted, 'additional area')} can be inspected in a later Curate Memory run.`);
     const workflow = o?.workflow;
     if (workflow)
-        notes.push(workflow.state === 'stale' ? MEMORY_COPY.stale : 'Memory Sync is in progress. Continue when you are ready.');
+        notes.push(workflow.state === 'stale' ? MEMORY_COPY.stale : 'Curate Memory is in progress. Continue when you are ready.');
     const signal = areas.some((a) => a.reasons.some((r) => r.includes('did not fit'))) ? 'Relevant knowledge has not fit into recent task context.'
         : areas.length ? areas[0].reasons.find((r) => !r.includes('incompatible')) ?? 'Related knowledge is ready for review.'
             : !o?.available ? 'Memory analysis is temporarily unavailable.' : !hasHistory ? 'Not enough usage history yet to evaluate improvements.' : 'No improvements suggested by recent usage.';
     const total = areas.length + (o?.areasOmitted ?? 0);
     const dashboard = { headline: areas.length ? 'Memory can be improved' : headline, areasLabel: total ? `${count(total, 'area')} identified` : null, signal,
         sharing: typeof p.localKnowledgeCount === 'number' ? p.localKnowledgeCount ? `${count(p.localKnowledgeCount, 'Local memory', 'Local memories')} available for sharing review.` : 'No Local memories to share.' : null,
-        established: p.knowledgeCount > 0, workflowNotice: workflow ? workflow.state === 'stale' ? MEMORY_COPY.stale : 'Memory Sync is in progress.' : null };
-    return { headline, notes, areas, conflicts, workflow, dashboard, button: workflow ? (workflow.state === 'stale' ? 'Re-analyze memory' : 'Continue Memory Sync') : 'Sync Memory' };
+        established: p.knowledgeCount > 0, workflowNotice: workflow ? workflow.state === 'stale' ? MEMORY_COPY.stale : 'Curate Memory is in progress.' : null };
+    return { headline, notes, areas, conflicts, workflow, dashboard, button: workflow ? (workflow.state === 'stale' ? 'Re-analyze memory' : 'Continue curation') : 'Curate Memory' };
 }
 export function memorySyncPresentation(w) {
     const areas = (w.jobs ?? []).map(memoryArea), s = w.summary ?? {}, p = w.review?.preview;
-    const headlines = { awaiting_selection: 'Sync Memory', semantic_work: 'Improving memory…', awaiting_clarification: 'A question about your project', awaiting_review: w.review?.kind === 'promotion' ? 'Review knowledge for team sharing' : p?.requiresVersionedReview ? 'Review shared-memory changes' : 'Review memory changes', applying: 'Saving changes…', awaiting_promotion_selection: 'Review Local knowledge for sharing', completed: 'Memory synced', stale: 'Re-analyze memory' };
+    const operation = w.operation ?? memorySyncOperation(w);
+    const headlines = { awaiting_selection: 'Curate Memory', semantic_work: 'Improving memory…', awaiting_clarification: 'A question about your project', awaiting_review: w.review?.kind === 'promotion' ? 'Review knowledge for team sharing' : p?.requiresVersionedReview ? 'Review shared-memory changes' : 'Review memory changes', applying: 'Approved changes pending verification', awaiting_promotion_selection: 'Review Local knowledge for sharing', completed: 'Memory curated', stale: 'Re-analyze memory' };
     const notes = [], warnings = [], metrics = [], sections = [];
     const section = (title, body) => sections.push({ title, items: [{ title: '', body, notes: [] }] });
     if (w.state === 'awaiting_selection') {
         // Operation choices are the entry surface; planner data is diagnostic.
     }
-    if (w.state === 'semantic_work')
-        notes.push('Prodero is reviewing related knowledge and making safe Local improvements. You will only be asked about missing project facts.');
+    if (['semantic_work', 'awaiting_clarification'].includes(w.state) && operation.phase !== 'question')
+        notes.push(operation.phase === 'submitted' ? 'The result was submitted and is awaiting validation.' : operation.phase === 'awaiting_agent' ? 'Prepared evidence is waiting for host-agent analysis. No background worker is confirmed.' : 'Analysis is queued. Continue with the prepared evidence; you may be asked about missing project facts.');
     if (w.state === 'applying')
-        notes.push('Your approved changes are being saved safely. Continue to check their result.');
+        notes.push('The approved intention is saved. Check progress to verify the result or resume recovery; no active writer is assumed.');
     if (w.state === 'stale')
         notes.push(MEMORY_COPY.stale);
     if (w.state === 'awaiting_promotion_selection')
@@ -117,7 +121,7 @@ export function memorySyncPresentation(w) {
         if (p.requiresVersionedReview)
             notes.push(MEMORY_COPY.shared);
         if (p.remaining)
-            notes.push(`${count(p.remaining, 'additional broken link')} will remain for a later Sync.`);
+            notes.push(`${count(p.remaining, 'additional broken link')} will remain for a later curation run.`);
         sections.push({ title: 'Broken links to remove', items: p.changes.map((c) => ({ title: c.title, body: c.links.map((l) => `${l.type} → ${l.target}`).join('\n'), notes: [`${c.layer === 'versioned' ? 'Shared / Versioned' : 'Local'} · ${c.id}`] })) });
     }
     if (w.state !== 'stale' && w.review?.kind === 'promotion') {
@@ -148,11 +152,11 @@ export function memorySyncPresentation(w) {
         if (s.brokenLinksRemaining)
             notes.push(`${count(s.brokenLinksRemaining, 'broken link')} remain unchanged.`);
         if (s.promoted)
-            notes.push(`${count(s.promoted, 'Local memory', 'Local memories')} shared with the team.`);
+            notes.push(`${count(s.promoted, 'Local memory', 'Local memories')} prepared in Versioned files. Review the Git diff before sharing; Curator did not commit or push.`);
         if (s.areasProcessed)
             notes.push(`Estimated context for reviewed knowledge: ${tokens(s.estimatedTokens.before)} → ${tokens(s.estimatedTokens.after)} tokens.`);
         if (s.unresolved)
-            notes.push(`${count(s.unresolved, 'memory', 'memories')} still need clarification and remain current.`);
+            notes.push(`${count(s.unresolved, 'unresolved item')} still need clarification and remain current.`);
         if (s.areasSkipped)
             notes.push('Some knowledge was retained because a safe improvement could not be established.');
         if (s.areasFailed)
@@ -163,10 +167,16 @@ export function memorySyncPresentation(w) {
             notes.push(`${count(s.promotionConflicts, 'sharing item')} still need review and remain Local.`);
         notes.push('Previous knowledge remains available through history.');
     }
+    notes.push('Your place and saved answers are retained. Leave and return with Continue curation.');
+    if (['semantic_work', 'awaiting_clarification', 'awaiting_review'].includes(w.state))
+        notes.push('Skip or Answer later retains original knowledge and saved answers, then continues other selected work.');
+    if (w.state === 'stale' || w.state === 'completed')
+        notes.push('Re-analyze starts a fresh workflow from current project data. Changes already saved remain in place.');
     if (w.error && w.state !== 'stale')
         notes.push('This step could not finish. Continue to check saved progress before retrying.');
     if (w.state === 'awaiting_promotion_selection' && w.coverage?.promotionCandidatesOmitted)
-        notes.push(`${count(w.coverage.promotionCandidatesOmitted, 'additional Local memory', 'additional Local memories')} can be reviewed in a later Sync Memory run.`);
-    return { headline: headlines[w.state] ?? 'Sync Memory', graphicalHeadline: headlines[w.state] ?? 'Sync Memory', reviewAreaLabel: 'Memory changes', notes, warnings, metrics, sections, areas };
+        notes.push(`${count(w.coverage.promotionCandidatesOmitted, 'additional Local memory', 'additional Local memories')} can be reviewed in a later Curate Memory run.`);
+    const headline = w.state === 'completed' && operation.outcome === 'remaining' ? 'Completed with remaining work' : operation.phase === 'awaiting_agent' ? 'Awaiting agent analysis' : operation.phase === 'submitted' ? 'Submitted · validation pending' : w.state === 'semantic_work' ? 'Analysis queued' : headlines[w.state] ?? 'Curate Memory';
+    return { headline, graphicalHeadline: headline, operation, reviewAreaLabel: 'Memory changes', notes, warnings, metrics, sections, areas };
 }
 //# sourceMappingURL=memory-presentation.js.map

package/dist/memory-sync-operation.js

@@ -0,0 +1,88 @@
+/** Pure derived Sync state/actions. No I/O, writes, host detection or authority. */
+import { publicDiagnostic } from './core/diagnostics.js';
+import { hasSecret } from './core/secrets.js';
+/** Only returned Core diagnostics are screened for display. Raw transport
+ * exceptions are deliberately replaced with fixed client-owned wording. */
+export function syncClientFailure(workflowId, stage, response, confirmedState = false) {
+    const payload = response?.structuredContent;
+    const rejected = stage === 'action' && Boolean(payload), code = payload && typeof payload.code === 'string' && /^[a-zA-Z0-9_-]{1,100}$/.test(payload.code) && !hasSecret(payload.code) ? payload.code : stage === 'handoff' ? 'SYNC_HANDOFF_UNKNOWN' : rejected ? 'SYNC_ACTION_REJECTED' : 'SYNC_TRANSPORT_UNKNOWN';
+    const cause = payload ? publicDiagnostic(typeof payload.message === 'string' ? payload.message : typeof payload.error === 'string' ? payload.error : 'The server rejected this step.').slice(0, 1000) : stage === 'handoff' ? 'Agent continuation outcome is unknown. Saved workflow changes remain confirmed.' : 'The action outcome is unknown because the host did not return a usable result.';
+    return { workflowId, stage, certainty: rejected && confirmedState ? 'rejected' : 'unknown', confirmedState, diagnostic: { code, cause, recovery: stage === 'handoff' ? 'Check saved progress or continue the saved request in chat.' : confirmedState ? 'Saved state refreshed. Review it before retrying; the action was not replayed.' : 'Check saved progress before retrying. Do not repeat approval while its outcome is unknown.' } };
+}
+export function syncClientNotice(evidence) {
+    if (!evidence)
+        return '';
+    return [evidence.diagnostic ? `${evidence.diagnostic.code}: ${evidence.diagnostic.cause} ${evidence.diagnostic.recovery}` : evidence.stage === 'handoff' ? evidence.certainty === 'requested' ? 'Continuation requested from the host; agent execution is not confirmed.' : evidence.certainty === 'acknowledged' ? 'The host acknowledged the request. Waiting for saved analysis; agent execution is not confirmed.' : '' : '', evidence.pollPaused ? 'Automatic checks paused after 12 attempts. Waiting for saved progress; use Check progress or continue the saved request in chat.' : ''].filter(Boolean).join(' ');
+}
+const finished = new Set(['applied', 'skipped', 'failed', 'deferred']);
+export function memorySyncOperation(w, selection) {
+    const counts = { areasProcessed: 0, areasFailed: 0, areasSkipped: 0, questionsDeferred: 0, unresolved: 0, brokenLinksRemaining: 0, promotionConflicts: 0, ...w.summary };
+    const selected = (w.jobs ?? []).filter(j => j.selected), current = selected.find(j => ['pending', 'semantic_work', 'awaiting_review', 'awaiting_clarification'].includes(j.status)), reasoning = w.reasoning ?? w.clarification?.graphical;
+    const remaining = counts.areasFailed + counts.areasSkipped + counts.questionsDeferred + counts.unresolved + counts.brokenLinksRemaining + counts.promotionConflicts > 0;
+    let phase = { awaiting_selection: 'selection', semantic_work: 'queued', awaiting_clarification: 'question', awaiting_review: 'review', applying: 'recovery', awaiting_promotion_selection: 'sharing', completed: 'completed', stale: 'stale' }[w.state];
+    const pendingAnalysis = w.state === 'semantic_work' || w.state === 'awaiting_clarification' && !w.clarification?.graphical?.questions.some(q => q.needsInput);
+    if (pendingAnalysis && reasoning?.jobs.some(j => !j.suspended && ['prepared', 'awaiting_reasoning'].includes(j.status)))
+        phase = 'awaiting_agent';
+    if (pendingAnalysis && reasoning?.jobs.some(j => !j.suspended && j.status === 'submitted'))
+        phase = 'submitted';
+    const actions = [], args = { workflowId: w.id, revision: w.revision };
+    const add = (id, label, request, approval = false) => actions.push({ id, label, tool: 'prodero_memory_sync', arguments: { projectRoot: w.root, request }, ...(approval ? { approval: true } : {}) });
+    if (w.state === 'awaiting_selection' && (selection?.improve !== false || selection?.share !== false || Boolean(w.brokenLinks) && selection?.repairLinks !== false))
+        add('select', 'Start curation', { action: 'select', ...args, improve: selection?.improve ?? true, share: selection?.share ?? true, ...(w.brokenLinks ? { repairLinks: selection?.repairLinks ?? true } : {}) });
+    if (w.state === 'semantic_work' && current)
+        add('prepare', 'Continue improving memory', { action: 'prepare', ...args, candidateId: current.id });
+    if (w.state === 'semantic_work' && current)
+        add('skip', 'Continue with other knowledge', { action: 'skip', ...args, candidateId: current.id });
+    if (w.state === 'awaiting_review' && w.review) {
+        add('approve', w.review.kind === 'promotion' ? 'Share reviewed knowledge' : 'Approve reviewed changes', { action: 'approve', ...args, reviewId: w.review.reviewId, approved: true }, true);
+        add('skip', 'Skip this review', { action: 'skip', ...args, ...(w.review.kind === 'transformation' && current ? { candidateId: current.id } : {}) });
+    }
+    const availableIds = (w.promotionCandidates ?? []).map(c => c.id), ids = selection?.promotionIds ?? availableIds;
+    const validSelection = ids.length > 0 && new Set(ids).size === ids.length && ids.every(id => availableIds.includes(id));
+    if (w.state === 'awaiting_promotion_selection') {
+        if (validSelection)
+            add('promotions', ids.length === availableIds.length ? `Review all ${ids.length} for sharing` : `Review ${ids.length} selected for sharing`, { action: 'promotions', ...args, ids: [...ids] });
+        add('complete', 'Finish without sharing', { action: 'complete', ...args });
+    }
+    if (!['stale', 'applying'].includes(w.state) && !w.review && !w.promotionResult)
+        for (const job of selected.filter(j => j.status === 'failed'))
+            add(`retry:${job.id}`, 'Retry incomplete analysis', { action: 'retry', ...args, candidateId: job.id });
+    for (const q of w.deferredQuestions ?? []) {
+        const { candidateId, title, prompt, expired, affectedQuestions, ...binding } = q;
+        if (expired && w.review)
+            continue;
+        if (expired) {
+            const { action, questionId, questionVersion, ...exact } = binding;
+            add(`refresh:${candidateId}:${q.questionId}`, 'Refresh expired question review', { action: 'refresh_questions', ...args, candidateId, ...exact });
+        }
+        else {
+            const app = { tool: 'prodero_curation_review', arguments: { projectRoot: w.root, ...binding } };
+            actions.push({ id: `revisit:${q.questionId}`, label: affectedQuestions.length > 1 ? `Revisit ${affectedQuestions.length} related questions` : `Revisit ${title}`, tool: 'prodero_curation_question', arguments: { projectRoot: w.root, ...binding, workflowId: w.id, candidateId }, app });
+        }
+    }
+    const data = w.clarification, review = data?.review, g = data?.graphical, owner = selected.find(j => j.curationReviewId === review?.snapshot.reviewId);
+    if (review?.snapshot.revision && g && owner) {
+        const binding = { workflowId: w.id, candidateId: owner.id, reviewId: review.snapshot.reviewId, reviewRevisionId: review.snapshot.revision.id, planHash: review.snapshot.planHash, decisionRevision: review.state.revision, answerLogHash: g.answerLogHash };
+        for (const q of g.questions.filter(q => q.needsInput || q.state === 'answered_pending_analysis')) {
+            if (q.needsInput && !g.analysisPending)
+                for (const choice of q.question.choices)
+                    actions.push({ id: `answer:${q.question.id}:${choice.id}`, label: choice.label, tool: 'prodero_curation_question', arguments: { projectRoot: w.root, ...binding, action: 'answer', questionId: q.question.id, questionVersion: q.question.version, choiceId: choice.id, requestId: `chat_${globalThis.crypto.randomUUID()}`, ...(q.answer ? { replacesAnswerId: q.answer.id } : {}) } });
+            actions.push({ id: `later:${q.question.id}`, label: q.relatedQuestions && q.relatedQuestions.length > 1 ? `Defer ${q.relatedQuestions.length} related questions` : 'Answer later', tool: 'prodero_curation_question', arguments: { projectRoot: w.root, ...binding, action: 'question_later', questionId: q.question.id, questionVersion: q.question.version } });
+        }
+        if (g.canRetryAnalysis)
+            actions.push({ id: 'retry_analysis', label: 'Retry saved answer analysis', tool: 'prodero_curation_question', arguments: { projectRoot: w.root, ...binding, action: 'retry_analysis' } });
+        else if (g.needsPreparation)
+            actions.push({ id: 'analyze', label: 'Analyze saved answer', tool: 'prodero_curation_question', arguments: { projectRoot: w.root, ...binding, action: 'analyze' } });
+    }
+    if (reasoning?.continuationJobId)
+        actions.push({ id: 'reasoning', label: 'Continue bounded analysis', tool: 'prodero_curation_reasoning_prepare', arguments: { projectRoot: w.root, jobId: reasoning.continuationJobId } });
+    if (w.state === 'stale' || w.state === 'applying')
+        actions.length = 0;
+    if (w.state === 'stale' || w.state === 'completed')
+        add('restart', 'Re-analyze memory', { action: 'start', restart: true });
+    add('inspect', 'Check progress', { action: 'inspect', workflowId: w.id });
+    actions.push({ id: 'details', label: 'Show details', tool: 'prodero_memory_sync', arguments: { projectRoot: w.root, request: { action: 'inspect', workflowId: w.id }, details: true } });
+    const error = w.error ?? selected.find(j => j.status === 'failed' && j.error)?.error;
+    return { version: 1, phase, outcome: w.state === 'stale' ? 'stale' : w.state === 'completed' ? remaining ? 'remaining' : 'complete' : 'pending', counts: { ...counts, deferredAreas: counts.questionsDeferred, questionsDeferred: w.questionCounts?.deferred ?? null, areasTotal: selected.length, areasFinished: selected.filter(j => finished.has(j.status)).length, savedAnswers: w.questionCounts?.savedAnswerEvents ?? null, unsupersededAnswerEvents: w.questionCounts?.unsupersededAnswerEvents ?? null }, ...(current ? { currentItem: { id: current.id, label: current.label, status: current.status } } : {}), actions, ...(error ? { diagnostic: { code: 'SYNC_STEP_INCOMPLETE', cause: publicDiagnostic(error), recovery: 'Inspect saved progress before retrying.' } } : {}), ...(!['stale', 'applying'].includes(w.state) && reasoning?.continuationJobId ? { continuation: { jobId: reasoning.continuationJobId } } : {}), selection: { ids: validSelection ? [...ids] : [], availableIds } };
+}
+//# sourceMappingURL=memory-sync-operation.js.map

package/dist/presentation-server.js

@@ -1,12 +1,12 @@
 import { projectSettings } from "./core/settings.js";
 import { z } from "zod";
 import { registerAppTool, getUiCapability, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
-import { buildViewModel, renderText, PRESENTATION_REPLY } from "./presentation.js";
+import { buildViewModel, renderText, PRESENTATION_REPLY, LIFECYCLE_PRESENTATION_REPLY } from "./presentation.js";
 import { createPresentationCards } from './presentation-cards.js';
 import { conversationOperation } from './conversation-presentation.js';
 import { PRODERO_TOOLS } from './contracts.js';
-export const PRESENTED_TOOLS = ["prodero_initialize", "prodero_context", "prodero_curation", "prodero_migrate", "prodero_open", "prodero_status", "prodero_status_details", "prodero_prepare", "prodero_session_close", "prodero_knowledge", "prodero_knowledge_mutate", "prodero_instruction_review", "prodero_instruction_optimize", "prodero_session_review", "prodero_session_review_mutate", "prodero_promotion_preview", "prodero_promote", "prodero_sync", "prodero_memory_sync"];
-const modeSchema = z.enum(["auto", "ui", "text"]).optional().describe("Optional invocation override; defaults to canonical project presentation.mode. Auto uses advertised MCP Apps capability; UI prefers App; text supplies a compact conversational summary with details on request. Use prodero_text to guarantee no App attachment.");
+export const PRESENTED_TOOLS = ["prodero_initialize", "prodero_context", "prodero_curation", "prodero_curation_question", "prodero_migrate", "prodero_open", "prodero_status", "prodero_status_details", "prodero_prepare", "prodero_session_close", "prodero_knowledge", "prodero_knowledge_mutate", "prodero_instruction_review", "prodero_instruction_optimize", "prodero_session_review", "prodero_session_review_mutate", "prodero_promotion_preview", "prodero_promote", "prodero_sync", "prodero_memory_sync", "prodero_skill_preview", "prodero_skill_review"];
+const modeSchema = z.enum(["auto", "ui", "text"]).optional().describe("Optional invocation override; defaults to effective presentation.mode on this checkout (local preference, legacy project default, then built-in default). Auto uses advertised MCP Apps capability; UI prefers App; text supplies a compact conversational summary with details on request. Use prodero_text to guarantee no App attachment.");
 export function resolvePresentation(mode, capabilities) {
     return mode === "auto" ? (getUiCapability(capabilities)?.mimeTypes?.includes(RESOURCE_MIME_TYPE) ? "ui" : "text") : mode;
 }
@@ -27,20 +27,23 @@ export function presentationTools(server, resolveRoot) {
                 const resolved = resolvePresentation(settings.presentation.mode, server.server.getClientCapabilities());
                 const group = groupSchema.parse(presentationGroup);
                 const card = hasUi && resolved === 'ui' && group ? cards.issue(settings.root, `conversation:${group}`) : undefined;
-                return { ...result, structuredContent: { ...result.structuredContent, projectSettings: { root: settings.root, presentation: settings.presentation }, presentation: { requested: settings.presentation.mode, resolved, scope: "project", ...(card ? { card } : {}) } } };
+                return { ...result, structuredContent: { ...result.structuredContent, projectSettings: { root: settings.root, presentation: settings.presentation, presentationSources: settings.presentationSources, diagnostics: settings.diagnostics }, presentation: { requested: settings.presentation.mode, resolved, scope: "project", ...(card ? { card } : {}) } } };
             });
         const schema = z.object(config.inputSchema);
         const run = async (input, extra) => {
+            if (name === PRODERO_TOOLS.curationQuestion)
+                z.object({ ...config.inputSchema, presentation: modeSchema, presentationGroup: groupSchema, details: z.boolean().optional(), diagnostics: z.boolean().optional(), plain: z.boolean().optional() }).strict().parse(input);
             const root = await resolveRoot(input.projectRoot);
             const settings = await projectSettings(root);
             const details = z.boolean().optional().parse(input.details);
             const diagnostics = z.boolean().optional().parse(input.diagnostics);
+            const plain = z.boolean().optional().parse(input.plain);
             const requested = modeSchema.parse(input.presentation) ?? settings.presentation.mode;
             const presentationGroup = groupSchema.parse(input.presentationGroup);
             const resolved = resolvePresentation(requested, server.server.getClientCapabilities());
             // Parse using the original schema and strip presentation before invoking Core.
             const args = schema.parse({ ...input, projectRoot: root });
-            const result = await handler(args, extra);
+            const result = await handler(args, extra, { requested, resolved });
             if (result.isError || !result.structuredContent)
                 return result;
             const payload = result.structuredContent;
@@ -49,12 +52,24 @@ export function presentationTools(server, resolveRoot) {
             const group = presentationGroup ? `conversation:${presentationGroup}` : sessionId ? `session:${sessionId}` : undefined;
             const card = resolved === 'ui' && hasUi && group ? cards.issue(root, group) : undefined;
             const operational = conversationOperation(payload, viewModel, details || diagnostics, diagnostics);
-            const humanText = renderText(viewModel, diagnostics, details || diagnostics);
-            return { ...result, content: resolved === "text" ? [{ type: "text", text: humanText }, { type: "text", text: JSON.stringify({ proderoOperation: operational }), annotations: { audience: ["assistant"] } }] : [...result.content, { type: "text", text: PRESENTATION_REPLY + (viewModel.knowledgeTable ? `\n\n${humanText}\n\n${JSON.stringify({ knowledgeRows: operational.knowledgeRows, numberedActions: operational.numberedActions })}` : ""), annotations: { audience: ["assistant"] } }],
-                structuredContent: { ...payload, projectSettings: { root: settings.root, presentation: settings.presentation }, presentation: { requested, resolved, scope: input.presentation === undefined ? "project" : "invocation", actions: resolved === "text" ? operational.availableActions : viewModel.actions, ...(resolved === "text" ? { text: humanText, operational } : {}), ...(card ? { card } : {}) } } };
+            // Skill preview already supplies its complete exact Markdown and approval guidance.
+            // A generic compact projection must not discard that reviewed procedure.
+            const skillCompanion = ['skill-preview', 'skill-review'].includes(String(payload.action)) ? result.content.find(c => c.type === 'text') : undefined;
+            const humanText = skillCompanion?.type === 'text' ? skillCompanion.text : renderText(viewModel, diagnostics, details || diagnostics, plain);
+            // A capable connection can still have a surface where its App is invisible.
+            // Keep the existing compact lifecycle fallback; no extra Core call or card.
+            const lifecycle = ['prepare', 'session-close'].includes(String(payload.action));
+            const fallback = lifecycle ? ` ${LIFECYCLE_PRESENTATION_REPLY}\n\n${humanText}` : '';
+            // UI already carries these full Core snapshots in result; retain only the
+            // exact relay/action bindings alongside the fallback, avoiding duplication.
+            const { context: _context, session: _session, automaticSync: _sync, ...fallbackOperational } = operational;
+            return { ...result, content: resolved === "text" ? [{ type: "text", text: humanText }, { type: "text", text: JSON.stringify({ proderoOperation: operational }), annotations: { audience: ["assistant"] } }] : [...result.content, { type: "text", text: PRESENTATION_REPLY + fallback + (viewModel.knowledgeTable ? `\n\n${humanText}\n\n${JSON.stringify({ knowledgeRows: operational.knowledgeRows, numberedActions: operational.numberedActions })}` : ""), annotations: { audience: ["assistant"] } }],
+                structuredContent: { ...payload, projectSettings: { root: settings.root, presentation: settings.presentation, presentationSources: settings.presentationSources, diagnostics: settings.diagnostics }, presentation: { requested, resolved, scope: input.presentation === undefined ? "project" : "invocation", actions: resolved === "text" ? operational.availableActions : viewModel.actions, ...(resolved === "text" || lifecycle ? { text: humanText, operational: resolved === "text" ? operational : fallbackOperational } : {}), ...(card ? { card } : {}) } } };
         };
         handlers.set(name, (args, extra) => run({ ...args, presentation: "text" }, extra));
-        return registerAppTool(target, name, { ...config, _meta: config._meta ?? {}, inputSchema: { ...config.inputSchema, presentation: modeSchema, presentationGroup: groupSchema, details: z.boolean().optional().describe("Show full details and proposed wording instead of the compact summary."), diagnostics: z.boolean().optional().describe("Include technical diagnostics, allocation evidence and exact workflow data. Implies details.") } }, run);
+        if (name === PRODERO_TOOLS.curationQuestion)
+            return target.registerTool(name, { ...config, inputSchema: z.object({ ...config.inputSchema, presentation: modeSchema, presentationGroup: groupSchema, details: z.boolean().optional(), diagnostics: z.boolean().optional(), plain: z.boolean().optional() }).strict() }, run);
+        return registerAppTool(target, name, { ...config, _meta: config._meta ?? {}, inputSchema: { ...config.inputSchema, presentation: modeSchema, presentationGroup: groupSchema, details: z.boolean().optional().describe("Show full details and proposed wording instead of the compact summary."), plain: z.boolean().optional().describe("Use ASCII frame and meter glyphs when Unicode rendering is unsuitable."), diagnostics: z.boolean().optional().describe("Include technical diagnostics, allocation evidence and exact workflow data. Implies details.") } }, run);
     }
     function registerGateway() {
         // Register after the server installs its diagnostic boundary. Registering a
@@ -68,7 +83,7 @@ export function presentationTools(server, resolveRoot) {
         }, async ({ cardId, activate }) => ({ content: [], structuredContent: cards.inspect(cardId, activate) }));
         server.registerTool("prodero_text", {
             title: "Prodero Text Presentation",
-            description: PRESENTATION_REPLY + " Open Prodero as compact conversational text (details:true for full inspection), or present a covered lifecycle/knowledge tool without an MCP App attachment. Uses the original tool schema, Core operation and approval rules. Pass its normal arguments unchanged. Mutating operations require the same explicit human review. No preference is persisted. Relay presentation.text concisely, without expanding other result fields into a dashboard or listing every action. Operational data are for the agent; use exact continuations for follow-up replies. Show full proposed wording before approval.",
+            description: PRESENTATION_REPLY + " Open Prodero as compact conversational text (details:true for full inspection), or present a covered lifecycle/knowledge tool without an MCP App attachment. Uses the original tool schema, Core operation and approval rules. Pass its normal arguments unchanged. Mutating operations require the same explicit human review. No preference is persisted. Relay presentation.text exactly as supplied, preserving code fences, entry letters and the external Pulse menu. Healthy Prepare continues automatically; details use its returned context snapshot, never repeat retrieval. Operational data are for the agent; use exact continuations for follow-up replies. Show full proposed wording before approval.",
             inputSchema: { tool: z.enum(PRESENTED_TOOLS).default("prodero_open"), arguments: z.record(z.unknown()).default({}) },
             // Conservatively describe the entire gateway; never mark a mixed operation tool read-only.
             annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },