vgxness 1.19.7 → 1.20.0

package/README.md

@@ -8,7 +8,7 @@ This package is proprietary software. The npm package ships inspectable JavaScri
 
 OpenCode is the primary supported provider. Claude setup support is secondary. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
 
-VGXNESS is currently versioned from `package.json` (`1.17.2`). The latest full project health audit is the historical [v1.14.x snapshot](./docs/project-health-audit-v1.14.x.md), which documents the implemented CLI/MCP/SDD control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps at that point in time. [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
+VGXNESS is currently versioned from `package.json` (`1.20.0`). The latest full project health audit is the historical [v1.14.x snapshot](./docs/project-health-audit-v1.14.x.md), which documents the implemented CLI/MCP/SDD control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps at that point in time. [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
 
 ## Requirements
 

package/dist/agents/canonical-agent-manifest.js

@@ -148,7 +148,7 @@ export function createCanonicalOpenCodeSddSubagentPrompt(name) {
     const phase = name.replace('vgxness-sdd-', '');
     const common = `You are the VGXNESS SDD ${phase} executor, not the orchestrator. Do this phase's work yourself. Do NOT delegate, do NOT call task/delegate, and do NOT launch sub-agents. Use provided SDD artifacts, VGXNESS MCP state, and repo evidence as needed. Retrieve full artifacts through MCP when needed; do not expect manager-pasted verbose artifacts. Do not depend on local skill files; this inline contract is sufficient. Preserve unrelated user work, keep output concise, and report evidence.`;
     const contract = subagentData[name].phaseContract;
-    return `${common}\n\nPhase contract: ${contract}\n\nBegin your output with a compact result envelope containing required fields: status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended. Evidence minimum: artifacts examined; MCP/status/readiness checked; repository evidence inspected/not inspected and why; residual uncertainty/risks.\n\nSDD governance v1: SDD artifact acceptance is human-only. Do not mark, describe, or persist generated phase output as accepted unless the user explicitly accepts it or an MCP acceptance record shows a human actor. Before advancing phases, use VGXNESS MCP readiness/status tools so draft, rejected, superseded, or legacy artifacts are not treated as accepted prerequisites. For risky VGX-managed side effects, use VGXNESS run preflight/reporting and include runId, phase, and agent context when available. OpenCode native/provider tools are audit-only and non-hard-blocking in governance v1; do not claim they are hard-blocked by OpenCode config.\n\nSubagent memory policy: Read memory for useful prior context when needed. Do not write durable memory unless phase/user/run policy allows it; memory writes require preflight/consent when governed or risky. Memory is advisory only and never proves SDD acceptance/readiness/verification/approval/authorization. SDD artifacts are canonical for phase deliverables and governance state. Do not save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive data. Report memory candidates separately when writes are not authorized.\n\nProvider-native daily progression: daily SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not instruct the user to run terminal SDD phase commands for normal daily flow. Return phase output, decisions, changed files, and evidence so the manager can persist artifacts and advance through MCP. Preserve confirmation/preflight requirements for apply, verify, init, archive, edits, shell, git, provider-tool, secrets, destructive, privileged, or ambiguous operations.`;
+    return `${common}\n\nPhase contract: ${contract}\n\nBegin your output with a compact result envelope containing required fields: status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended. Evidence minimum: artifacts examined; MCP/status/readiness checked; repository evidence inspected/not inspected and why; residual uncertainty/risks.\n\nSDD governance v1: SDD artifact acceptance is human-only. Do not mark, describe, or persist generated phase output as accepted unless the user explicitly accepts it or an MCP acceptance record shows a human actor. Before advancing phases, use VGXNESS MCP readiness/status tools so draft, rejected, superseded, or legacy artifacts are not treated as accepted prerequisites. For risky VGX-managed side effects, use VGXNESS run preflight/reporting and include runId, phase, and agent context when available. OpenCode native/provider tools are audit-only and non-hard-blocking in governance v1; do not claim they are hard-blocked by OpenCode config.\n\nSubagent memory policy: Read memory when useful. Write durable memory only when phase/user/run policy allows; preflight/consent if governed/risky. memoryCapture: review-only; no auto-persist. Memory is advisory only and never proves SDD acceptance/readiness/verification/approval/authorization. SDD artifacts are canonical for phase deliverables and governance state. Do not save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive data. Report memory candidates separately when writes are not authorized.\n\nProvider-native daily progression: daily SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not instruct the user to run terminal SDD phase commands for normal daily flow. Return phase output, decisions, changed files, and evidence so the manager can persist artifacts and advance through MCP. Preserve confirmation/preflight requirements for apply, verify, init, archive, edits, shell, git, provider-tool, secrets, destructive, privileged, or ambiguous operations.`;
 }
 /**
  * Provider runtime prompt for generated provider managers.
@@ -186,7 +186,7 @@ SDD happens in OpenCode via conversation, VGXNESS MCP, and SDD subagents. No ter
 - Delegated phase outputs: inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended); this is prompt guidance only, not runtime parsing/rejection.
 - Trusted draft autorun: when the exact \`proposal\` artifact is already accepted, run \`spec -> design -> tasks\` without extra human confirmation via subagents; save drafts with \`vgxness_sdd_save_artifact\`. This is draft-only planning, not acceptance or completion. Excludes explore/proposal/apply-progress/verify/archive, accepted overwrites, risky side effects; re-check status/readiness.
 - Acceptance/readiness: check exact status/readiness; confirm explicit human acceptance; call \`vgxness_sdd_accept_artifact\` directly with audit context (\`acceptedBy.type: "human"\`, non-empty \`acceptedBy.id\`, runId, agentId); re-check before reporting. Do not preflight solely for exact acceptance. Ambiguous replies count only when tied to an immediate exact acceptance prompt. Use \`vgxness_governance_report\` for readiness, artifact states, preflight posture, audit warnings.
-- Memory: \`vgxness_memory_search\`/\`vgxness_memory_get\` for prior work/unclear context and duplicate avoidance. Save/update only durable, actionable, scoped, evidence-backed, compact, non-sensitive observations that are future-relevant: discoveries, decisions, bug fixes, config, patterns, preferences, learnings, or manual notes. \`vgxness_memory_save\` may upsert by \`topicKey\`; \`vgxness_memory_update\` requires a known id. Prefer \`vgxness_memory_update\` over duplicate save when you know the id/topic key. Do not save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance/readiness/verification/approval/authorization. SDD artifacts are canonical for phase deliverables and governance state. \`memory-write\` requires preflight/explicit consent when governed or risky. Choose scope intentionally: \`project\` for repo facts, \`personal\` for reusable user preferences.
+- Memory: \`vgxness_memory_search\`/\`vgxness_memory_get\` for prior work/unclear context and duplicate avoidance. Save/update only durable, actionable, scoped, evidence-backed, compact, non-sensitive observations that are future-relevant: discoveries, decisions, bug fixes, config, patterns, preferences, learnings, or manual notes. \`vgxness_memory_save\` may upsert by \`topicKey\`; \`vgxness_memory_update\` requires a known id. Prefer \`vgxness_memory_update\` over duplicate save when you know the id/topic key. Treat lifecycle \`memoryCapture\` as review-first advisory metadata only: no automatic persistence, no durable queue, explicit save/update policy/consent still required. Do not save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance/readiness/verification/approval/authorization. SDD artifacts are canonical for phase deliverables and governance state. OpenCode previews/handoff are read-only and capture-free. \`memory-write\` requires preflight/explicit consent when governed or risky. Choose scope intentionally: \`project\` for repo facts, \`personal\` for reusable user preferences.
 - Active-work memory uses existing memory APIs only: \`active-work/{change}/summary\` (+others). No secrets or hidden reasoning. Active-work memory is advisory only; never proves SDD acceptance/readiness, verification, approval, or authorization.
 - Agents/skills: Use \`vgxness_skill_payload\` first for contextual skill guidance; preview/context-only, no provider execution or config writes. Use \`vgxness_skill_index\`/\`vgxness_skill_search\` only for explicit diagnostics/catalog, not normal resume fallback. Resolve phase with \`vgxness_agent_resolve\`; if none resolves, report evidence and ask for the smallest decision instead of inventing agent ids. \`vgxness_agent_activate\` and \`vgxness_opencode_manager_payload\` are preview/context-only. \`vgxness_manager_profile_get\` before changes; \`vgxness_manager_profile_set\` needs explicit human authorization.
 - Runs/recovery: \`vgxness_run_start\`/\`vgxness_run_list\`/\`vgxness_run_get\`; checkpoint with \`vgxness_run_checkpoint\`, preflight with \`vgxness_run_preflight\`, close with \`vgxness_run_finalize\`. Unknown runId: \`vgxness_run_resume_candidates\`. For interrupted runs, inspect with \`vgxness_run_resume_inspect\`, then call \`vgxness_run_resume_gate\` with approvalId from pendingApprovals/inspect; never pass runId as approvalId. Follow safe \`recommendedActions[]\`.
@@ -215,7 +215,7 @@ const registryManagerInstructionsV11 = [
     'Default to delegation for SDD phase-shaped work, repository exploration beyond one narrow lookup, implementation, verification, incident recovery, or multi-step analysis. Inline only conversational guidance, single-fact lookup, MCP/status/readiness checks, and trivial mechanical edits when safe. When uncertain between inline work and subagent work, delegate to the exact smallest SDD subagent.',
     'Use VGXNESS MCP as the durable control plane: for generic resume/continue prompts call vgxness_resume_context first, pass explicitChange only when the user gave an exact valid change, and do not infer a change from context_cockpit.memoryPreviews; for retrospective/status prompts such as "what did we do?" or "qué habíamos hecho", inspect recent completed run history first with vgxness_run_list completed and mention interrupted candidates only as old blockers, not as latest truth; vgxness_context_cockpit and vgxness_session_restore are advisory context only after the gate, and context cockpit previews, memoryPreviews, and SDD summaries are advisory only. Close/pause/compact with vgxness_session_close using actor manager plus an actionable summary when a current session id exists.',
     'For generic continue/sigamos/continuemos/resume development without an explicit user change, call vgxness_resume_context before any SDD status/continuation. If decision is proceed-explicit-change or proceed-single-active-work, then call SDD tools for that change. If inspect-interrupted-run, call vgxness_run_resume_inspect. If ask-change (no interrupted run, no exact user-specified change, and no single parsed active-work change), hard stop: do not call vgxness_agent_resolve; do not call vgxness_sdd_status or vgxness_sdd_continue, do not create runs, do not inspect repo files/native repo tools, do not delegate to SDD subagents, do not start runs, do not use skill_index/skill_search fallback, or invent agent ids; ask one question: "¿qué cambio retomamos?".',
-    'Check SDD status/next/ready/cockpit, read prerequisites with sdd_get_artifact or sdd_list_artifacts, use public sdd_continue/internal vgxness_sdd_continue first for advisory read-only continuation plans, use sdd_reopen_artifact only for rejected artifacts returning to draft with explicit human actor/audit context, save phase output with sdd_save_artifact only by governance; inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended) as prompt guidance only, not runtime parsing/rejection; when proposal is accepted, spec/design/tasks may run sequentially as draft-only autorun without extra confirmation, while acceptance remains human-only. Memory capture policy: save/update only durable, future-relevant, actionable, scoped, evidence-backed, compact, non-sensitive observations; prefer update by known id/topicKey over duplicate saves; never save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance, readiness, verification, approval, or authorization. SDD artifacts are canonical for phase deliverables/governance state. Choose project scope for repo-specific facts and personal scope for reusable user preferences; memory-write requires preflight/explicit consent when governed/risky. Resolve exact SDD subagents before substantial phase work, use runs/checkpoints/preflight/finalize for significant implementation or verification, use run_resume_candidates for unknown runId, inspect interrupted runs by runId with run_resume_inspect, then call run_resume_gate with approvalId from pendingApprovals/inspect; never pass runId as approvalId; use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health.',
+    'Check SDD status/next/ready/cockpit, read prerequisites with sdd_get_artifact or sdd_list_artifacts, use public sdd_continue/internal vgxness_sdd_continue first for advisory read-only continuation plans, use sdd_reopen_artifact only for rejected artifacts returning to draft with explicit human actor/audit context, save phase output with sdd_save_artifact only by governance; inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended) as prompt guidance only, not runtime parsing/rejection; when proposal is accepted, spec/design/tasks may run sequentially as draft-only autorun without extra confirmation, while acceptance remains human-only. Memory capture policy: save/update only durable, future-relevant, actionable, scoped, evidence-backed, compact, non-sensitive observations; lifecycle memoryCapture candidates are review-first advisory metadata only, not persisted automatically, not a durable candidate queue, and still require explicit save/update policy and consent; prefer update by known id/topicKey over duplicate saves; never save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance, readiness, verification, approval, or authorization. SDD artifacts are canonical for phase deliverables/governance state. OpenCode previews/handoff are read-only and capture-free. Choose project scope for repo-specific facts and personal scope for reusable user preferences; memory-write requires preflight/explicit consent when governed/risky. Resolve exact SDD subagents before substantial phase work, use runs/checkpoints/preflight/finalize for significant implementation or verification, use run_resume_candidates for unknown runId, inspect interrupted runs by runId with run_resume_inspect, then call run_resume_gate with approvalId from pendingApprovals/inspect; never pass runId as approvalId; use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health.',
     'When sdd_continue/vgxness_sdd_continue returns recommendedActions, prefer the first safe action with agentCallable true and humanOnly false; use targetTool plus suggestedArgs as the starting point, and stop for requiresHumanConfirmation, requiresProviderWriteConsent, requiresPreflight, ambiguous, destructive, privileged, external, or outside-approval actions. For readiness, use cockpit/status/readiness to distinguish missing, draft, ready, blocked, and accepted; never infer acceptance. For provider evidence, report providerEvidence.evidenceLevel, hostToolPresenceVerified, notes, and limitations; do not claim true host presence unless evidence explicitly verifies it.',
     'Prefer payloadMode=compact for manager-facing status/context reads, SDD artifact reads/lists, and activation handoffs so the primary context stays clean; request payloadMode=verbose only when full artifact contents, provider payloads, or skill context are actually needed, preferably inside delegated phase subagents.',
     'MCP sdd_continue must not execute providers, create runs, mutate artifacts, write provider config/openspec, bypass human acceptance, or treat draft-run as apply-progress.',

package/dist/mcp/control-plane.js

@@ -3,6 +3,7 @@ import { AgentRegistryService } from '../agents/agent-registry-service.js';
 import { ManagerProfileOverlayService } from '../agents/manager-profile-overlay-service.js';
 import { ManagerProfileOverlayRepository } from '../agents/repositories/manager-profile-overlays.js';
 import { GovernanceReportBuilder } from '../governance/index.js';
+import { AgentMemoryCaptureService } from '../memory/agent-memory-capture-service.js';
 import { MemoryService } from '../memory/memory-service.js';
 import { openMemoryDatabase } from '../memory/sqlite/database.js';
 import { prepareMemoryDatabasePath, resolveMemoryDatabasePath } from '../memory/storage-paths.js';
@@ -38,7 +39,7 @@ export function callVgxTool(call, services) {
         case 'vgxness_sdd_save_artifact':
             return auditedEnvelope(validated.tool, services.sdd.saveArtifact(validated.input), services, sddSaveAuditPayload(validated.input));
         case 'vgxness_sdd_accept_artifact':
-            return auditedEnvelope(validated.tool, services.sdd.acceptArtifact(validated.input), services, sddAcceptanceAuditPayload(validated.input));
+            return acceptSddArtifactEnvelope(validated.input, services);
         case 'vgxness_sdd_reopen_artifact':
             return auditedEnvelope(validated.tool, services.sdd.reopenArtifact(validated.input), services, sddReopenAuditPayload(validated.input));
         case 'vgxness_sdd_get_artifact':
@@ -71,7 +72,7 @@ export function callVgxTool(call, services) {
         case 'vgxness_session_append_activity':
             return toEnvelope(validated.tool, services.memory.appendActivity(validated.input, memoryContext(validated.input.sessionId)));
         case 'vgxness_session_close':
-            return toEnvelope(validated.tool, services.memory.closeSession(validated.input, memoryContext(validated.input.sessionId)));
+            return closeSessionEnvelope(validated.input, services);
         case 'vgxness_session_restore':
             return toEnvelope(validated.tool, services.memory.restoreSession(validated.input));
         case 'vgxness_context_cockpit':
@@ -161,7 +162,7 @@ export function callVgxTool(call, services) {
         case 'vgxness_run_checkpoint':
             return toEnvelope(validated.tool, services.runs.appendCheckpoint(validated.input));
         case 'vgxness_run_finalize':
-            return toEnvelope(validated.tool, services.runs.updateFinalStatus(validated.input));
+            return finalizeRunEnvelope(validated.input, services);
         case 'vgxness_run_resume_candidates':
             return runResumeCandidatesEnvelope(validated.input, services);
         case 'vgxness_run_resume_inspect':
@@ -419,14 +420,132 @@ function setManagerProfileEnvelope(input, services) {
     return toEnvelope('vgxness_manager_profile_set', services.managerProfiles.resolveEffectiveManager({ project: input.project, scope: input.scope, managerName: input.managerName }));
 }
 function saveMemoryObservationEnvelope(input, services) {
+    const policy = new AgentMemoryCaptureService().validateExplicitMemorySave(input);
+    if (!policy.ok)
+        return errorEnvelope(policy.error.code, policy.error.message, 'vgxness_memory_save');
+    if (!policy.value.allowed)
+        return memoryCapturePolicyErrorEnvelope('vgxness_memory_save', policy.value);
     return toEnvelope('vgxness_memory_save', services.memory.saveObservation({ ...input, scope: input.scope ?? 'project' }, memoryContext()));
 }
 function getMemoryObservationEnvelope(input, services) {
     return toEnvelope('vgxness_memory_get', services.memory.getObservation(input.id, memoryContext()));
 }
 function updateMemoryObservationEnvelope(input, services) {
+    const policy = new AgentMemoryCaptureService().validateExplicitMemoryUpdate(input);
+    if (!policy.ok)
+        return errorEnvelope(policy.error.code, policy.error.message, 'vgxness_memory_update');
+    if (!policy.value.allowed)
+        return memoryCapturePolicyErrorEnvelope('vgxness_memory_update', policy.value);
     return toEnvelope('vgxness_memory_update', services.memory.updateObservation(input, memoryContext()));
 }
+function acceptSddArtifactEnvelope(input, services) {
+    const accepted = auditedEnvelope('vgxness_sdd_accept_artifact', services.sdd.acceptArtifact(input), services, sddAcceptanceAuditPayload(input));
+    if (!accepted.ok)
+        return accepted;
+    const memoryCapture = sddReferenceMemoryCapture(input, accepted.value);
+    if (memoryCapture !== undefined)
+        accepted.memoryCapture = memoryCapture;
+    return accepted;
+}
+function sddReferenceMemoryCapture(input, artifact) {
+    try {
+        const captureInput = {
+            source: input.phase === 'archive' ? 'sdd_archive' : 'sdd_acceptance',
+            project: artifact.project,
+            change: input.change,
+            phase: input.phase,
+            artifactId: artifact.id,
+            topicKey: artifact.topicKey,
+            artifactState: 'accepted',
+        };
+        if (input.acceptedBy?.type !== undefined && input.acceptedBy.id !== undefined) {
+            captureInput.acceptedBy = {
+                type: input.acceptedBy.type,
+                id: input.acceptedBy.id,
+                ...(input.acceptedBy.displayName === undefined ? {} : { displayName: input.acceptedBy.displayName }),
+            };
+        }
+        if (input.acceptedAt !== undefined)
+            captureInput.acceptedAt = input.acceptedAt;
+        if (input.runId !== undefined)
+            captureInput.runId = input.runId;
+        if (input.agentId !== undefined)
+            captureInput.agentId = input.agentId;
+        const result = new AgentMemoryCaptureService().captureFromSddReferenceEvent(captureInput);
+        return result.ok ? result.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function closeSessionEnvelope(input, services) {
+    const closed = services.memory.closeSession(input, memoryContext(input.sessionId));
+    if (!closed.ok)
+        return errorEnvelope(closed.error.code, closed.error.message, 'vgxness_session_close');
+    const memoryCapture = sessionCloseMemoryCapture(input, closed.value);
+    const envelope = { ok: true, tool: 'vgxness_session_close', value: closed.value };
+    if (memoryCapture !== undefined)
+        envelope.memoryCapture = memoryCapture;
+    return envelope;
+}
+function sessionCloseMemoryCapture(input, session) {
+    const result = new AgentMemoryCaptureService().captureFromSessionClose({
+        project: session.project,
+        sessionId: session.id,
+        ...(session.directory === undefined ? {} : { directory: session.directory }),
+        summary: input.summary,
+    });
+    return result.ok ? result.value : undefined;
+}
+function finalizeRunEnvelope(input, services) {
+    const finalized = services.runs.updateFinalStatus(input);
+    if (!finalized.ok)
+        return errorEnvelope(finalized.error.code, finalized.error.message, 'vgxness_run_finalize');
+    const memoryCapture = runFinalizeMemoryCapture(input, finalized.value);
+    const envelope = { ok: true, tool: 'vgxness_run_finalize', value: finalized.value };
+    if (memoryCapture !== undefined)
+        envelope.memoryCapture = memoryCapture;
+    return envelope;
+}
+function runFinalizeMemoryCapture(input, run) {
+    try {
+        const boundedEvidence = [{ kind: 'run-finalization', ref: run.id, note: 'Derived from bounded run finalization response fields only.' }];
+        if (run.latestCheckpointId !== undefined) {
+            boundedEvidence.push({ kind: 'run-checkpoint', ref: run.latestCheckpointId, note: 'Checkpoint id reference only; checkpoint state omitted.' });
+        }
+        const captureInput = {
+            project: run.project,
+            runId: run.id,
+            workflow: run.workflow,
+            phase: run.phase,
+            status: run.status,
+            outcome: run.outcome ?? input.outcome,
+            boundedEvidence,
+        };
+        const outcomeReason = run.outcomeReason ?? input.outcomeReason;
+        if (outcomeReason !== undefined)
+            captureInput.outcomeReason = outcomeReason;
+        const result = new AgentMemoryCaptureService().captureFromRunFinalize(captureInput);
+        return result.ok ? result.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function memoryCapturePolicyErrorEnvelope(tool, decision) {
+    return errorEnvelope('validation_failed', `Memory capture policy rejected explicit durable memory write. Reason codes: ${decision.reasonCodes.join(', ')}`, tool, {
+        policy: {
+            service: 'AgentMemoryCaptureService',
+            version: decision.version,
+            allowed: decision.allowed,
+            severity: decision.severity,
+            persisted: decision.persisted,
+            reasonCodes: decision.reasonCodes,
+            warnings: decision.warnings,
+            redactions: decision.redactions,
+        },
+    });
+}
 function memoryContext(sessionId) {
     const context = { actor: 'mcp-control-plane' };
     if (sessionId !== undefined)

package/dist/mcp/schema.js

@@ -974,8 +974,11 @@ export const VGX_MCP_TOOL_OUTPUT_SCHEMAS = {
 export function successEnvelope(tool, value) {
     return { ok: true, tool, value };
 }
-export function errorEnvelope(code, message, tool) {
-    const result = { ok: false, error: { code, message } };
+export function errorEnvelope(code, message, tool, details) {
+    const error = { code, message };
+    if (details !== undefined)
+        error.details = details;
+    const result = { ok: false, error };
     if (tool !== undefined)
         result.tool = tool;
     return result;

package/dist/memory/agent-memory-capture-service.js

@@ -0,0 +1,497 @@
+import { createHash } from 'node:crypto';
+const MEMORY_TYPES = [
+    'architecture',
+    'decision',
+    'bugfix',
+    'pattern',
+    'config',
+    'discovery',
+    'learning',
+    'preference',
+    'manual',
+];
+const DEFAULT_LIMITS = {
+    maxCandidates: 3,
+    maxCandidateTitleChars: 120,
+    maxCandidateContentChars: 1500,
+    maxExplicitContentChars: 4000,
+    maxSourceContentChars: 12000,
+    maxEvidenceRefs: 10,
+    maxReasonCodes: 8,
+};
+export class AgentMemoryCaptureService {
+    now;
+    limits;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.limits = {
+            ...DEFAULT_LIMITS,
+            ...definedLimits(options),
+        };
+    }
+    validateExplicitMemorySave(input) {
+        const reasonCodes = [];
+        const warnings = [warning('memory_is_advisory_only')];
+        const project = clean(input.project);
+        const title = clean(input.title);
+        const content = clean(input.content);
+        const scope = input.scope ?? 'project';
+        const memoryType = normalizeMemoryType(input.type);
+        if (project === undefined)
+            reasonCodes.push('missing_required_field');
+        if (title === undefined)
+            reasonCodes.push('missing_required_field');
+        if (content === undefined)
+            reasonCodes.push('missing_required_field');
+        if (memoryType === undefined)
+            reasonCodes.push('invalid_memory_type');
+        reasonCodes.push(...this.policyReasonsForText(content ?? '', this.limits.maxExplicitContentChars));
+        reasonCodes.push(...scopeReasonCodes(scope));
+        if (input.topicKey !== undefined && clean(input.topicKey) === undefined)
+            reasonCodes.push('ambiguous_topic_key');
+        const rejectCodes = rejectCodesFrom(reasonCodes);
+        if (rejectCodes.length > 0)
+            return okDecision(false, rejectCodes, warnings);
+        const normalizedPayload = { scope };
+        assignIfDefined(normalizedPayload, 'project', project);
+        assignIfDefined(normalizedPayload, 'type', memoryType);
+        assignIfDefined(normalizedPayload, 'title', trimTo(title, this.limits.maxCandidateTitleChars));
+        assignIfDefined(normalizedPayload, 'content', content);
+        const topicKey = clean(input.topicKey);
+        if (topicKey !== undefined)
+            normalizedPayload.topicKey = topicKey;
+        return okDecision(true, uniqueReasonCodes(['durable_future_relevant', 'compact_summary', ...reasonCodes, 'memory_is_advisory_only']), warnings, normalizedPayload);
+    }
+    validateExplicitMemoryUpdate(input) {
+        const reasonCodes = [];
+        const warnings = [warning('memory_is_advisory_only')];
+        const id = clean(input.id);
+        if (id === undefined)
+            reasonCodes.push('missing_required_field');
+        const memoryType = input.type === undefined ? undefined : normalizeMemoryType(input.type);
+        if (input.type !== undefined && memoryType === undefined)
+            reasonCodes.push('invalid_memory_type');
+        if (input.content !== undefined)
+            reasonCodes.push(...this.policyReasonsForText(input.content, this.limits.maxExplicitContentChars));
+        if (input.topicKey !== undefined && clean(input.topicKey) === undefined)
+            reasonCodes.push('ambiguous_topic_key');
+        if (input.scope !== undefined)
+            reasonCodes.push(...scopeReasonCodes(input.scope));
+        const hasField = input.project !== undefined || input.scope !== undefined || input.type !== undefined || input.title !== undefined || input.content !== undefined || input.topicKey !== undefined;
+        if (!hasField)
+            reasonCodes.push('missing_required_field');
+        const rejectCodes = rejectCodesFrom(reasonCodes);
+        if (rejectCodes.length > 0)
+            return okDecision(false, rejectCodes, warnings);
+        const normalizedPayload = {};
+        assignIfDefined(normalizedPayload, 'project', clean(input.project));
+        assignIfDefined(normalizedPayload, 'scope', input.scope);
+        assignIfDefined(normalizedPayload, 'type', memoryType);
+        assignIfDefined(normalizedPayload, 'title', trimTo(clean(input.title), this.limits.maxCandidateTitleChars));
+        assignIfDefined(normalizedPayload, 'content', clean(input.content));
+        assignIfDefined(normalizedPayload, 'topicKey', clean(input.topicKey));
+        return okDecision(true, uniqueReasonCodes(['durable_future_relevant', ...reasonCodes, 'memory_is_advisory_only']), warnings, normalizedPayload);
+    }
+    captureFromSessionClose(input) {
+        const sourceRef = makeSourceRef({ kind: 'session', project: input.project }, { id: input.sessionId, sessionId: input.sessionId });
+        const base = this.baseResult('session_close');
+        const summary = clean(input.summary);
+        if (summary === undefined) {
+            return { ok: true, value: withRejection(base, sourceRef, ['source_content_empty'], 'Session close summary was empty.') };
+        }
+        const sourceProblems = this.policyReasonsForText(summary, this.limits.maxSourceContentChars);
+        if (rejectCodesFrom(sourceProblems).length > 0) {
+            return { ok: true, value: withRejection(base, sourceRef, rejectCodesFrom(sourceProblems), 'Session close summary contained prohibited or unbounded content.') };
+        }
+        const sections = parseMarkdownSections(summary);
+        const candidates = [];
+        const preferenceSection = findSection(sections, 'Instructions');
+        if (preferenceSection !== undefined) {
+            candidates.push(this.candidate({
+                source: 'session_close',
+                sourceRef,
+                project: input.project,
+                type: 'preference',
+                title: 'Captured session instruction preference',
+                content: memoryContent('What', firstBulletOrLine(preferenceSection.body), 'Why', 'Session close summary recorded an instruction that may affect future work.', 'Where', input.directory ?? input.project),
+                topicKey: 'preference/session-instructions',
+                evidenceRefs: [{ kind: 'session-summary', ref: input.sessionId ?? input.project, note: 'Derived from close summary only.' }],
+                rationale: 'Session summary includes reusable instructions.',
+            }));
+        }
+        const discoverySection = findSection(sections, 'Discoveries');
+        if (discoverySection !== undefined) {
+            candidates.push(this.candidate({
+                source: 'session_close',
+                sourceRef,
+                project: input.project,
+                type: 'discovery',
+                title: 'Captured session discovery',
+                content: memoryContent('What', firstBulletOrLine(discoverySection.body), 'Why', 'Session close summary marked this as a durable discovery.', 'Where', input.directory ?? input.project),
+                topicKey: 'discovery/session-close',
+                evidenceRefs: [{ kind: 'session-summary', ref: input.sessionId ?? input.project, note: 'Derived from close summary only.' }],
+                rationale: 'Session summary includes a discovery section.',
+            }));
+        }
+        const accomplishedSection = findSection(sections, 'Accomplished');
+        if (accomplishedSection !== undefined) {
+            candidates.push(this.candidate({
+                source: 'session_close',
+                sourceRef,
+                project: input.project,
+                type: inferTypeFromText(accomplishedSection.body),
+                title: 'Captured completed session outcome',
+                content: memoryContent('What', firstBulletOrLine(accomplishedSection.body), 'Why', 'Session close summary marked this work as accomplished.', 'Where', input.directory ?? input.project),
+                topicKey: 'manual/session-outcome',
+                evidenceRefs: [{ kind: 'session-summary', ref: input.sessionId ?? input.project, note: 'Derived from close summary only.' }],
+                rationale: 'Session summary includes completed durable work.',
+            }));
+        }
+        base.candidates = candidates.slice(0, this.limits.maxCandidates);
+        if (base.candidates.length === 0)
+            base.rejections.push(rejection(sourceRef, ['no_candidate_worthy_content'], 'No durable candidate-worthy summary section was found.'));
+        return { ok: true, value: base };
+    }
+    captureFromRunFinalize(input) {
+        const sourceRef = makeSourceRef({ kind: 'run', id: input.runId, project: input.project, runId: input.runId });
+        const base = this.baseResult('run_finalize');
+        const reason = clean(input.outcomeReason);
+        if (reason === undefined) {
+            return { ok: true, value: withRejection(base, sourceRef, ['source_content_empty'], 'Run outcome reason was empty.') };
+        }
+        if (input.outcome === 'cancelled') {
+            return { ok: true, value: withRejection(base, sourceRef, ['cancelled_run_without_durable_learning'], 'Cancelled run did not produce a durable candidate by default.') };
+        }
+        const sourceProblems = this.policyReasonsForText(reason, this.limits.maxSourceContentChars);
+        if (rejectCodesFrom(sourceProblems).length > 0) {
+            return { ok: true, value: withRejection(base, sourceRef, rejectCodesFrom(sourceProblems), 'Run finalization evidence contained prohibited content.') };
+        }
+        const evidenceRefs = boundedEvidence(input.boundedEvidence, this.limits.maxEvidenceRefs);
+        const content = memoryContent('What', `Run ${input.runId} finalized with status=${input.status} outcome=${input.outcome}.`, 'Why', reason, 'Where', [input.workflow, input.phase].filter((value) => value !== undefined && value.length > 0).join('/') || input.project);
+        base.candidates = [
+            this.candidate({
+                source: 'run_finalize',
+                sourceRef,
+                project: input.project,
+                type: input.outcome === 'success' ? 'discovery' : 'manual',
+                title: `Captured run ${input.outcome} outcome`,
+                content,
+                topicKey: `run/${input.runId}/finalize`,
+                evidenceRefs: evidenceRefs.length > 0 ? evidenceRefs : [{ kind: 'run-finalization', ref: input.runId }],
+                rationale: 'Run finalization has bounded outcome evidence only.',
+            }),
+        ];
+        return { ok: true, value: base };
+    }
+    captureFromSddReferenceEvent(input) {
+        const sourceRef = makeSourceRef({ kind: 'sdd-artifact', project: input.project, change: input.change, phase: input.phase, topicKey: input.topicKey }, { id: input.artifactId, runId: input.runId });
+        const base = this.baseResult(input.source);
+        base.warnings.push(warning('sdd_acceptance_requires_human_record'), warning('canonical_state_required_for_governance'));
+        const actor = input.acceptedBy?.type === 'human' ? `human:${input.acceptedBy.id}` : 'not-provided';
+        const content = memoryContent('What', `${input.source === 'sdd_archive' ? 'SDD archive reference' : 'SDD acceptance reference'} for change=${input.change} phase=${input.phase} topicKey=${input.topicKey}.`, 'Why', 'Reference-only lifecycle candidate; canonical SDD artifact state remains the source of truth.', 'Where', `project=${input.project}; artifactId=${input.artifactId ?? 'unknown'}; state=${input.artifactState ?? 'unknown'}; acceptedBy=${actor}`);
+        base.candidates = [
+            this.candidate({
+                source: input.source,
+                sourceRef,
+                project: input.project,
+                type: input.source === 'sdd_archive' ? 'learning' : 'decision',
+                title: input.source === 'sdd_archive' ? 'Captured SDD archive reference' : 'Captured SDD acceptance reference',
+                content,
+                topicKey: `sdd-reference/${input.change}/${input.phase}`,
+                evidenceRefs: [
+                    { kind: 'sdd-topic-key', ref: input.topicKey, note: 'Reference only; artifact body omitted.' },
+                    { kind: 'sdd-event', ref: input.acceptedAt ?? this.now(), note: input.source },
+                ],
+                rationale: 'SDD lifecycle memory candidates must reference canonical artifacts only.',
+            }),
+        ];
+        return { ok: true, value: base };
+    }
+    baseResult(source) {
+        return {
+            version: 1,
+            source,
+            mode: 'ephemeral-review-first',
+            persisted: false,
+            generatedAt: this.now(),
+            policy: {
+                service: 'AgentMemoryCaptureService',
+                version: 1,
+                maxCandidates: this.limits.maxCandidates,
+                maxCandidateContentChars: this.limits.maxCandidateContentChars,
+                maxEvidenceRefs: this.limits.maxEvidenceRefs,
+            },
+            safety: {
+                advisoryOnly: true,
+                provesGovernance: false,
+                automaticPersistence: false,
+                persistedCandidateQueue: false,
+            },
+            candidates: [],
+            rejections: [],
+            warnings: [warning('lifecycle_candidate_not_persisted'), warning('candidate_requires_review'), warning('memory_is_advisory_only')],
+            nextActions: defaultNextActions(),
+        };
+    }
+    candidate(input) {
+        const content = trimTo(input.content, this.limits.maxCandidateContentChars) ?? '';
+        const title = trimTo(input.title, this.limits.maxCandidateTitleChars) ?? input.title;
+        const suggestedPayload = {
+            project: input.project,
+            scope: 'project',
+            type: input.type,
+            title,
+            content,
+            topicKey: input.topicKey,
+        };
+        return {
+            id: stableId(['memory-candidate', input.source, input.project, input.topicKey, content].join('|')),
+            status: 'proposed',
+            sourceItemRef: input.sourceRef,
+            suggestedOperation: 'save',
+            suggestedPayload,
+            rationale: input.rationale,
+            reasonCodes: uniqueReasonCodes(['review_first_candidate', 'safe_reference_only', 'compact_summary', 'evidence_backed']).slice(0, this.limits.maxReasonCodes),
+            evidenceRefs: boundedEvidence(input.evidenceRefs, this.limits.maxEvidenceRefs),
+            reviewRequired: true,
+        };
+    }
+    policyReasonsForText(text, maxChars) {
+        const lower = text.toLowerCase();
+        const reasons = [];
+        if (text.length > maxChars)
+            reasons.push('unbounded_content');
+        if (/full transcript|conversation transcript|^user:|\nuser:|\nassistant:/i.test(text))
+            reasons.push('contains_transcript');
+        if (/stdout:|stderr:|stack trace|raw log|traceback|exception:/i.test(text))
+            reasons.push('contains_raw_logs');
+        if (/chain-of-thought|hidden reasoning|private reasoning|internal reasoning|deliberation/i.test(text))
+            reasons.push('contains_hidden_reasoning');
+        if (/api[_-]?key|secret|password|token\s*=|bearer\s+[a-z0-9._-]+|private key|sk_(?:test|live)_/i.test(text))
+            reasons.push('contains_secret_or_credential');
+        if (/ssn|social security|credit card|passport number|medical record/i.test(text))
+            reasons.push('contains_sensitive_user_data');
+        if (/^#\s*sdd\s+(explore|proposal|spec|design|tasks|archive)|#\s*sdd .*draft|##\s+1\.\s+overview/i.test(text))
+            reasons.push('contains_full_sdd_artifact');
+        if (lower.includes('approval is granted') || lower.includes('authorized by memory'))
+            reasons.push('unsafe_authorization_claim');
+        if (lower.includes('verification is proven by memory'))
+            reasons.push('unsafe_verification_claim');
+        if (lower.includes('sdd acceptance is proven by memory'))
+            reasons.push('unsafe_sdd_acceptance_claim');
+        return uniqueReasonCodes(reasons);
+    }
+}
+function definedLimits(options) {
+    const limits = {};
+    assignIfDefined(limits, 'maxCandidates', options.maxCandidates);
+    assignIfDefined(limits, 'maxCandidateTitleChars', options.maxCandidateTitleChars);
+    assignIfDefined(limits, 'maxCandidateContentChars', options.maxCandidateContentChars);
+    assignIfDefined(limits, 'maxExplicitContentChars', options.maxExplicitContentChars);
+    assignIfDefined(limits, 'maxSourceContentChars', options.maxSourceContentChars);
+    assignIfDefined(limits, 'maxEvidenceRefs', options.maxEvidenceRefs);
+    return limits;
+}
+function okDecision(allowed, reasonCodes, warnings, normalizedPayload) {
+    const decision = {
+        version: 1,
+        allowed,
+        severity: allowed ? (warnings.length > 0 ? 'warn' : 'allow') : 'reject',
+        persisted: false,
+        reasonCodes: uniqueReasonCodes(reasonCodes),
+        warnings,
+        redactions: [],
+    };
+    if (normalizedPayload !== undefined)
+        decision.normalizedPayload = normalizedPayload;
+    return { ok: true, value: decision };
+}
+function rejectCodesFrom(reasonCodes) {
+    const rejectPrefixes = new Set([
+        'contains_secret_or_credential',
+        'contains_sensitive_user_data',
+        'contains_hidden_reasoning',
+        'contains_raw_logs',
+        'contains_transcript',
+        'contains_full_sdd_artifact',
+        'unbounded_content',
+        'ambiguous_scope',
+        'invalid_memory_type',
+        'unsafe_authorization_claim',
+        'unsafe_approval_claim',
+        'unsafe_verification_claim',
+        'unsafe_sdd_acceptance_claim',
+        'missing_required_field',
+        'policy_input_invalid',
+    ]);
+    return uniqueReasonCodes(reasonCodes.filter((code) => rejectPrefixes.has(code)));
+}
+function normalizeMemoryType(type) {
+    if (type === undefined)
+        return undefined;
+    return MEMORY_TYPES.includes(type) ? type : undefined;
+}
+function scopeReasonCodes(scope) {
+    if (scope === 'project')
+        return ['scope_project_appropriate'];
+    if (scope === 'personal')
+        return ['scope_personal_appropriate'];
+    return ['ambiguous_scope'];
+}
+function clean(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function trimTo(value, maxChars) {
+    if (value === undefined)
+        return undefined;
+    if (value.length <= maxChars)
+        return value;
+    return `${value.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+function uniqueReasonCodes(codes) {
+    return Array.from(new Set(codes));
+}
+function warning(reasonCode) {
+    const messages = {
+        durable_future_relevant: 'Content appears durable and future-relevant.',
+        actionable_project_fact: 'Content appears actionable for future project work.',
+        actionable_user_preference: 'Content appears to describe a reusable preference.',
+        compact_summary: 'Content is represented as a compact summary.',
+        evidence_backed: 'Candidate includes bounded evidence references.',
+        scope_project_appropriate: 'Project scope is appropriate.',
+        scope_personal_appropriate: 'Personal scope is appropriate.',
+        topic_key_stable: 'Topic key appears stable.',
+        safe_reference_only: 'Candidate uses safe references only.',
+        review_first_candidate: 'Candidate requires review before any explicit memory write.',
+        memory_is_advisory_only: 'Memory is advisory and never proves governance, acceptance, authorization, or verification.',
+        canonical_state_required_for_governance: 'Canonical SDD/run/session state must be inspected for governance facts.',
+        verification_requires_run_or_test_evidence: 'Verification requires run or test evidence, not memory alone.',
+        sdd_acceptance_requires_human_record: 'SDD acceptance is canonical only when backed by a human acceptance record.',
+        low_evidence_candidate: 'Candidate has low evidence.',
+        ambiguous_topic_key: 'Topic key is missing or ambiguous.',
+        candidate_requires_review: 'Lifecycle candidates are suggestions that require review.',
+        lifecycle_candidate_not_persisted: 'Lifecycle capture did not persist memory.',
+        content_truncated_to_policy_limit: 'Content was truncated to policy limits.',
+        contains_secret_or_credential: 'Content appears to contain a secret or credential.',
+        contains_sensitive_user_data: 'Content appears to contain sensitive user data.',
+        contains_hidden_reasoning: 'Content appears to contain hidden reasoning.',
+        contains_raw_logs: 'Content appears to contain raw logs.',
+        contains_transcript: 'Content appears to contain a transcript.',
+        contains_full_sdd_artifact: 'Content appears to contain a full SDD artifact.',
+        unbounded_content: 'Content exceeds policy size limits.',
+        not_future_relevant: 'Content does not appear future-relevant.',
+        not_actionable: 'Content does not appear actionable.',
+        ambiguous_scope: 'Scope is ambiguous.',
+        invalid_memory_type: 'Memory type is invalid.',
+        unsafe_authorization_claim: 'Content makes an unsafe authorization claim.',
+        unsafe_approval_claim: 'Content makes an unsafe approval claim.',
+        unsafe_verification_claim: 'Content makes an unsafe verification claim.',
+        unsafe_sdd_acceptance_claim: 'Content makes an unsafe SDD acceptance claim.',
+        missing_required_field: 'A required field is missing.',
+        policy_input_invalid: 'Policy input is invalid.',
+        no_candidate_worthy_content: 'No candidate-worthy content was found.',
+        cancelled_run_without_durable_learning: 'Cancelled run did not include durable learning.',
+        source_content_empty: 'Source content was empty.',
+        source_content_too_ambiguous: 'Source content was too ambiguous.',
+        redaction_removed_required_context: 'Redaction removed required context.',
+        unsupported_lifecycle_source: 'Lifecycle source is unsupported.',
+    };
+    return { reasonCode, message: messages[reasonCode] };
+}
+function defaultNextActions() {
+    return [
+        { kind: 'review_candidate', description: 'Review candidates before taking any durable memory action.' },
+        { kind: 'explicit_memory_save', description: 'Persist only selected safe candidates through an explicit memory save.', tool: 'vgxness_memory_save' },
+        { kind: 'discard_candidate', description: 'Discard candidates that are noisy, unsafe, or not durable.' },
+        { kind: 'inspect_canonical_source', description: 'Inspect canonical run, session, or SDD state for governance facts.' },
+    ];
+}
+function makeSourceRef(input, optional = {}) {
+    const ref = { kind: input.kind };
+    assignIfDefined(ref, 'id', input.id);
+    assignIfDefined(ref, 'id', optional.id);
+    assignIfDefined(ref, 'project', input.project);
+    assignIfDefined(ref, 'change', input.change);
+    assignIfDefined(ref, 'phase', input.phase);
+    assignIfDefined(ref, 'topicKey', input.topicKey);
+    assignIfDefined(ref, 'runId', input.runId);
+    assignIfDefined(ref, 'runId', optional.runId);
+    assignIfDefined(ref, 'sessionId', input.sessionId);
+    assignIfDefined(ref, 'sessionId', optional.sessionId);
+    return ref;
+}
+function withRejection(result, ref, reasonCodes, message) {
+    result.rejections.push(rejection(ref, reasonCodes, message));
+    return result;
+}
+function rejection(ref, reasonCodes, message) {
+    return { sourceItemRef: ref, reasonCodes: uniqueReasonCodes(reasonCodes), message };
+}
+function boundedEvidence(refs, maxRefs) {
+    if (refs === undefined)
+        return [];
+    return refs.slice(0, maxRefs).map((ref) => {
+        const copy = { kind: ref.kind, ref: ref.ref };
+        assignIfDefined(copy, 'note', ref.note);
+        return copy;
+    });
+}
+function parseMarkdownSections(summary) {
+    const sections = [];
+    let currentHeading = 'Summary';
+    let currentLines = [];
+    for (const line of summary.split(/\r?\n/)) {
+        const heading = /^#{1,3}\s+(.+)$/.exec(line.trim());
+        if (heading?.[1] !== undefined) {
+            pushSection(sections, currentHeading, currentLines);
+            currentHeading = heading[1].trim();
+            currentLines = [];
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    pushSection(sections, currentHeading, currentLines);
+    return sections;
+}
+function pushSection(sections, heading, lines) {
+    const body = lines.join('\n').trim();
+    if (body.length > 0)
+        sections.push({ heading, body });
+}
+function findSection(sections, heading) {
+    const target = heading.toLowerCase();
+    return sections.find((section) => section.heading.toLowerCase() === target);
+}
+function firstBulletOrLine(text) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.replace(/^[-*]\s+/, '').trim())
+        .filter((line) => line.length > 0);
+    return lines[0] ?? text.trim();
+}
+function memoryContent(labelA, valueA, labelB, valueB, labelC, valueC) {
+    return `${labelA}: ${valueA}\n${labelB}: ${valueB}\n${labelC}: ${valueC}`;
+}
+function inferTypeFromText(text) {
+    const lower = text.toLowerCase();
+    if (lower.includes('fix'))
+        return 'bugfix';
+    if (lower.includes('decision') || lower.includes('chose'))
+        return 'decision';
+    if (lower.includes('config'))
+        return 'config';
+    if (lower.includes('pattern'))
+        return 'pattern';
+    return 'manual';
+}
+function stableId(value) {
+    return `memcap_${createHash('sha256').update(value).digest('hex').slice(0, 16)}`;
+}
+function assignIfDefined(target, key, value) {
+    if (value !== undefined)
+        target[key] = value;
+}

package/dist/memory/memory-capture-schema.js

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

package/docs/mcp.md

@@ -49,13 +49,15 @@ Use memory for durable, future-relevant facts that are reusable beyond the curre
 
 Memory is advisory only: it never proves SDD acceptance, readiness, verification, approval, or authorization. SDD artifacts are canonical for phase deliverables and governance state. Active-work memory remains advisory and should point to current context without replacing artifacts or runs. `memory-write` is a durable governed action; use preflight or explicit consent whenever policy marks it governed/risky.
 
+Lifecycle responses may include `memoryCapture` metadata for review-first memory candidates, such as session close summaries, run finalization outcomes, and SDD acceptance/archive references. These candidates are advisory only and are never persisted automatically: there is no durable candidate queue, and callers must make a separate explicit `vgxness_memory_save` or `vgxness_memory_update` decision under the same durable memory policy. `memoryCapture` must not include full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, sensitive data, or other protected content, and it is not proof of SDD acceptance, readiness, verification, approval, or authorization.
+
 ## Sessions (5)
 
 | Tool | Purpose | Required inputs | Notes |
 |---|---|---|---|
 | `vgxness_session_start` | Begin a session record. | `project`; optional `id`, `directory` | If `id` is omitted, the runtime generates one. |
 | `vgxness_session_append_activity` | Append a structured event to a session. | `sessionId`, `actor`, `kind` (`prompt`/`tool_call`/`artifact`/`summary`/`error`), `payloadJson` | `payloadJson` is a stringified JSON value, validated before append. |
-| `vgxness_session_close` | Close a session with a summary. | `sessionId`, `actor`, `summary` (non-empty, trimmed) | |
+| `vgxness_session_close` | Close a session with a summary. | `sessionId`, `actor`, `summary` (non-empty, trimmed) | May return advisory `memoryCapture` candidates derived from the close summary only; candidates are not persisted automatically. |
 | `vgxness_session_restore` | Read the latest restorable session for a project/directory. | `project`; optional `directory` | One signal — not authoritative. Prefer `vgxness_context_cockpit`. |
 | `vgxness_context_cockpit` | Read-only cockpit: recent sessions, bounded memory previews, last restorable session. | `project`; optional `directory`, `limit` | Does not trace, mutate state, run preflight, or write provider config. |
 
@@ -79,7 +81,7 @@ Payload tools that accept `agentId` resolve it as a canonical registry id first.
 | Tool | Purpose | Required inputs | Notes |
 |---|---|---|---|
 | `vgxness_opencode_manager_payload` | Build the OpenCode manager payload envelope. | `OpenCodeManagerPayloadInput` shape (project, scope, agent, workflow/phase, workspaceRoot, maxSourceBytes, payloadMode) | `installable: false`, `readOnly: true`. |
-| `vgxness_opencode_handoff_preview` | Compose a full handoff preview: provider artifacts + skill diagnostics + SDD status + provider status + safety flags. | `project`; optional `scope`, `agentId`, `agentName`, `workspaceRoot`, `maxSourceBytes`, `change`, `phase` | Read-only preview. Does not execute OpenCode, install hooks, or write provider config. |
+| `vgxness_opencode_handoff_preview` | Compose a full handoff preview: provider artifacts + skill diagnostics + SDD status + provider status + safety flags. | `project`; optional `scope`, `agentId`, `agentName`, `workspaceRoot`, `maxSourceBytes`, `change`, `phase` | Read-only preview. Does not execute OpenCode, install hooks, write provider config, or capture memory candidates. |
 
 ## Runs (9)
 
@@ -89,7 +91,7 @@ Payload tools that accept `agentId` resolve it as a canonical registry id first.
 | `vgxness_run_get` | Read a run with `events`, `checkpoints`, `approvals`, `operationAttempts`. | `id` | |
 | `vgxness_run_start` | Create a run record. | `CreateRunInput` shape | |
 | `vgxness_run_checkpoint` | Append a resumable JSON state. | `AppendRunCheckpointInput` shape | |
-| `vgxness_run_finalize` | Finalize a run with `outcome` and `outcomeReason`. | `FinalizeRunInput` shape | `outcome` must match a terminal `status`. Re-finalization is rejected. |
+| `vgxness_run_finalize` | Finalize a run with `outcome` and `outcomeReason`. | `FinalizeRunInput` shape | `outcome` must match a terminal `status`. Re-finalization is rejected. May return advisory `memoryCapture` candidates from bounded finalization fields; candidates are not persisted automatically. |
 | `vgxness_run_preflight` | Run policy evaluation and return the decision, workspace strategy recommendation, and planned execution isolation strategy. | `PreflightRunOperationInput` shape | May create a pending approval when the decision is `ask`. Does not invoke an executor, write provider config, create branches, create worktrees, create PRs, or prove isolation exists. |
 | `vgxness_run_resume_candidates` | List recent interrupted runs for a project when the run id is unknown. | `project`; optional `limit` (1-100, default 5) | Returns failed, blocked, and needs-human candidates with `inspectInput` for `run_resume_inspect`. Does not retry, resume, mutate runs, create sandboxes/worktrees, invoke providers, or write artifacts/config. |
 | `vgxness_run_resume_inspect` | Plan-only resume advisory. | `runId` | Returns `RunResumeOrchestrationPlan` with blockers and `nextAction` (`resolve-approval`/`inspect-run`/`retry-check`/`manual-recovery`/`no-action`). |
@@ -168,6 +170,7 @@ MCP tools do not:
 - Write project-local provider config (`.opencode/`, `.mcp.json`, `.claude/`, project-root `CLAUDE.md`). VGX-managed OpenCode and Claude writes are user-global only and must stay behind explicit install/apply confirmation outside read-only status/preview tools.
 - Execute providers (`opencode`, `claude`, etc.).
 - Install global memory.
+- Persist `memoryCapture` lifecycle candidates automatically or use them as proof of SDD acceptance, readiness, verification, approval, or authorization.
 - Create `openspec/`.
 - Bypass permission policy.
 - Mutate other tools' state outside the VGXNESS SQLite store.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.19.7",
+  "version": "1.20.0",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {