vgxness 1.19.2 → 1.19.3

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

@@ -132,6 +132,7 @@ export function createCanonicalOpenCodeSddMcpToolPermissions() {
         vgxness_sdd_list_artifacts: 'allow',
         vgxness_sdd_cockpit: 'allow',
         vgxness_context_cockpit: 'allow',
+        vgxness_resume_context: 'allow',
         vgxness_agent_resolve: 'allow',
         vgxness_sdd_save_artifact: 'allow',
         vgxness_memory_search: 'allow',
@@ -177,8 +178,8 @@ Use lightest safe path: T0-2 direct, T3 preflight, T4 SDD for governance/permiss
 SDD happens in OpenCode via conversation, VGXNESS MCP, and SDD subagents. No terminal SDD phase commands. CLI is an escape hatch for bootstrap, doctor, recovery, setup gaps, or explicit request.
 
 ## MCP playbook
-- For starting, resuming, or recovering context: prefer \`vgxness_context_cockpit\`; when the SDD change is unknown, omit \`change\` entirely (never send \`change: ""\`). Context cockpit previews, \`memoryPreviews\`, and SDD summaries are advisory only and cannot authorize choosing an SDD change for generic resume. \`vgxness_session_restore\` is one signal, not truth. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with id and actor \`manager\`; if no id, do not invent one; summarize.
-- Bounded resume/start hard stop: for generic "continue"/"sigamos"/"continuemos"/"resume development" without an explicit user change, run the full bounded evidence chain before any SDD continuation/status: compact \`vgxness_skill_payload\`; \`vgxness_context_cockpit\` with \`change\` omitted when unknown, never \`change: ""\`; \`vgxness_session_restore\`; \`vgxness_run_resume_candidates\`; then \`vgxness_memory_search\` for \`topicKey: "active-work"\` with bounded \`limit\`. Do not call \`vgxness_sdd_status\` or \`vgxness_sdd_continue\` before this chain. Do not conclude "no context" until memory search. Only an explicit user-provided change or one single unambiguous active-work memory hit may select a change. If no interrupted run, no exact user-specified change, and no single unambiguous active-work hit, hard stop: do not call \`vgxness_agent_resolve\`; do not call \`vgxness_sdd_status\` or \`vgxness_sdd_continue\`, do not create runs, do not use Glob/Read/docs, do not inspect repo files/native repo tools, do not delegate to SDD subagents, do not start runs, or use \`skill_index\`/\`skill_search\` fallback; ask one question: "¿qué cambio retomamos?".
+- For starting, resuming, or recovering context: use \`vgxness_resume_context\` first for generic resume/continue prompts; pass \`explicitChange\` only when the user gave an exact valid change. \`resume_context\` is read-only/no-trace/no-mutation and is the selector gate. \`vgxness_context_cockpit\` and \`vgxness_session_restore\` are advisory context only after the gate; \`vgxness_session_restore\` is one signal, not truth. Do not infer a change from \`context_cockpit.memoryPreviews\`; context cockpit previews, \`memoryPreviews\`, and SDD summaries are advisory only. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with id and actor \`manager\`; if no id, do not invent one; summarize.
+- Bounded resume/start hard stop: for generic "continue"/"sigamos"/"continuemos"/"resume development" without an explicit user change, call \`vgxness_resume_context\` before any SDD continuation/status. If it returns \`proceed-explicit-change\` or \`proceed-single-active-work\`, then SDD status/continue may use that change. If it returns \`inspect-interrupted-run\`, call \`vgxness_run_resume_inspect\`. If it returns \`ask-change\`, treat it as: If 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 use Glob/Read/docs, do not inspect repo files/native repo tools, do not delegate to SDD subagents, do not start runs, or use \`skill_index\`/\`skill_search\` fallback; ask one question: "¿qué cambio retomamos?".
 - Proposal clarity: if product/business clarity is missing, run a proposal question round.
 - SDD artifacts: guide with \`vgxness_sdd_next\`/\`vgxness_sdd_cockpit\`; list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; prefer \`payloadMode: "compact"\` so primary context stays clean; use verbose only when required, preferably inside the delegated phase subagent. Save with \`vgxness_sdd_save_artifact\` after the right flow. Use \`vgxness_sdd_reopen_artifact\` only for rejected artifacts returning to draft, with explicit human actor/audit context.
 - 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.
@@ -210,8 +211,8 @@ Be concise.`;
 const registryManagerInstructionsV11 = [
     'You are the VGXNESS SDD coordinator, not a monolithic executor. Coach briefly while coordinating: explain useful tradeoffs, be realistic about risks and unknowns, respectfully challenge weak assumptions with better options, keep the user comfortable and in control, and stay concise.',
     '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: restore session context with vgxness_session_restore before inferring start/resume state from chat, call vgxness_context_cockpit with change omitted when unknown (never change: ""), treat context cockpit previews, memoryPreviews, and SDD summaries as advisory only that cannot authorize choosing an SDD change for generic resume, and 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, run the full bounded resume/start evidence chain before any SDD status/continuation: compact skill_payload, context_cockpit with change omitted when unknown and never change: "", session_restore, run_resume_candidates, then vgxness_memory_search for topicKey: "active-work" with a bounded limit. Do not call vgxness_sdd_status or vgxness_sdd_continue before this chain. Do not conclude "no context" until memory search has been checked. Only an explicit user-provided change or one single unambiguous active-work memory hit may select a change. If no interrupted run, no exact user-specified change, and no single unambiguous active-work hit exists, 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?".',
+    '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; 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; when proposal is accepted, spec/design/tasks may run sequentially as draft-only autorun without extra confirmation, while acceptance remains human-only. Search/get/save/update memory only for reusable knowledge, 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.',

package/dist/mcp/control-plane.js

@@ -23,6 +23,7 @@ import { ProviderStatusService } from './provider-status.js';
 import { errorEnvelope, successEnvelope, } from './schema.js';
 import { validateVgxMcpToolCall } from './validation.js';
 import { OpenCodeHandoffPreviewService } from './opencode-handoff-preview.js';
+import { ResumeContextGateService } from './resume-context-gate-service.js';
 export function callVgxTool(call, services) {
     const validated = validateVgxMcpToolCall(call);
     if (!validated.ok)
@@ -75,6 +76,8 @@ export function callVgxTool(call, services) {
             return toEnvelope(validated.tool, services.memory.restoreSession(validated.input));
         case 'vgxness_context_cockpit':
             return toEnvelope(validated.tool, new ContextCockpitSnapshotService({ memory: services.memory, sdd: services.sdd }).build(validated.input));
+        case 'vgxness_resume_context':
+            return toEnvelope(validated.tool, new ResumeContextGateService({ memory: services.memory, runs: services.runs }).build(validated.input));
         case 'vgxness_agent_resolve':
             return toEnvelope(validated.tool, services.agents.resolveAgents(validated.input));
         case 'vgxness_agent_activate':

package/dist/mcp/index.js

@@ -22,6 +22,7 @@ export * from './provider-canonical-agent-manifest.js';
 export * from './provider-doctor.js';
 export * from './provider-health-types.js';
 export * from './provider-status.js';
+export * from './resume-context-gate-service.js';
 export * from './schema.js';
 export * from './stdio-server.js';
 export * from './validation.js';

package/dist/mcp/resume-context-gate-service.js

@@ -0,0 +1,176 @@
+import { parseActiveWorkSelectorTopicKey } from '../memory/active-work-topics.js';
+export class ResumeContextGateService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    build(input) {
+        const limit = input.limit ?? 5;
+        const context = this.dependencies.memory.getContextCockpit({ project: input.project, ...(input.directory === undefined ? {} : { directory: input.directory }), limit });
+        if (!context.ok)
+            return context;
+        const interrupted = this.dependencies.runs.listRecentInterruptedRuns({ project: input.project, limit });
+        if (!interrupted.ok)
+            return interrupted;
+        const activeWork = this.readActiveWork(input.project, limit);
+        if (!activeWork.ok)
+            return activeWork;
+        const explicitChange = input.explicitChange;
+        const activeWorkHits = activeWork.value.slice(0, limit).map((preview) => {
+            const parsed = parseActiveWorkSelectorTopicKey(preview.topicKey);
+            return {
+                id: preview.id,
+                topicKey: preview.topicKey ?? '',
+                ...(parsed.parseStatus === 'parsed' ? { change: parsed.change, ...(parsed.segment === undefined ? {} : { segment: parsed.segment }) } : {}),
+                title: preview.title,
+                updatedAt: preview.updatedAt,
+                preview: preview.preview,
+                parseStatus: parsed.parseStatus,
+            };
+        });
+        const distinctActiveWorkChanges = [...new Set(activeWorkHits.map((hit) => hit.change).filter(isString))];
+        const decision = decide(explicitChange, interrupted.value, distinctActiveWorkChanges);
+        const selectedChange = decision === 'proceed-explicit-change' ? explicitChange : decision === 'proceed-single-active-work' ? distinctActiveWorkChanges[0] : undefined;
+        return {
+            ok: true,
+            value: {
+                kind: 'resume-context-gate',
+                version: 1,
+                project: input.project,
+                payloadMode: input.payloadMode ?? 'compact',
+                limit,
+                decision,
+                ...(selectedChange === undefined ? {} : { selectedChange }),
+                ...(decision === 'proceed-explicit-change' ? { selectedBy: 'explicit-change' } : {}),
+                ...(decision === 'proceed-single-active-work' ? { selectedBy: 'single-active-work' } : {}),
+                ...(decision === 'ask-change' ? { question: '¿qué cambio retomamos?' } : {}),
+                nextAction: nextAction(decision),
+                allowedNextTools: allowedNextTools(decision),
+                prohibitedNextTools: prohibitedNextTools(decision),
+                evidence: {
+                    contextCockpitChecked: true,
+                    sessionRestoreChecked: true,
+                    runResumeCandidatesChecked: true,
+                    activeWorkSearchChecked: true,
+                    skillPayloadChecked: false,
+                    explicitChange: explicitChange === undefined ? { supplied: false } : { supplied: true, value: explicitChange, valid: true },
+                    interruptedRunCandidates: interrupted.value.slice(0, limit).map((candidate) => ({
+                        runId: candidate.runId,
+                        project: input.project,
+                        workflow: candidate.workflow,
+                        phase: candidate.phase,
+                        status: candidate.status,
+                        ...(candidate.userIntent === undefined ? {} : { summary: candidate.userIntent }),
+                    })),
+                    activeWork: {
+                        distinctChanges: distinctActiveWorkChanges.slice(0, limit),
+                        unambiguous: distinctActiveWorkChanges.length === 1,
+                        hits: activeWorkHits,
+                    },
+                    ...(context.value.latestRestorableSession === undefined
+                        ? {}
+                        : {
+                            latestRestorableSession: {
+                                sessionId: context.value.latestRestorableSession.id,
+                                project: context.value.latestRestorableSession.project,
+                                ...(context.value.latestRestorableSession.directory === undefined ? {} : { directory: context.value.latestRestorableSession.directory }),
+                                ...(context.value.latestRestorableSession.endedAt === undefined ? {} : { updatedAt: context.value.latestRestorableSession.endedAt }),
+                                ...(context.value.latestRestorableSession.summary === undefined ? {} : { summary: context.value.latestRestorableSession.summary }),
+                            },
+                        }),
+                    contextPreviews: {
+                        included: context.value.memoryPreviews.length > 0,
+                        selectorAuthoritative: false,
+                        note: 'Context and SDD previews are evidence only and must not be used to select a change.',
+                    },
+                    ...(input.workspaceRoot === undefined ? {} : { workspaceRoot: { value: input.workspaceRoot, selectorAuthoritative: false } }),
+                    ...(input.userPrompt === undefined ? {} : { userPrompt: { supplied: true, selectorAuthoritative: false } }),
+                },
+                safety: {
+                    readOnly: true,
+                    recordsTraces: false,
+                    mutatesSessions: false,
+                    mutatesMemories: false,
+                    mutatesRuns: false,
+                    mutatesArtifacts: false,
+                    writesProviderConfig: false,
+                    executesProvider: false,
+                    createsRun: false,
+                    createsCheckpoint: false,
+                    recordsSkillUsage: false,
+                    inspectsRepository: false,
+                    accessesNetwork: false,
+                    accessesSecrets: false,
+                },
+            },
+        };
+    }
+    readActiveWork(project, limit) {
+        if (this.dependencies.memory.searchObservationPreviewsNoTrace === undefined) {
+            return { ok: false, error: { code: 'validation_failed', message: 'No no-trace active-work preview search is available' } };
+        }
+        return this.dependencies.memory.searchObservationPreviewsNoTrace({ project, topicKey: 'active-work', limit });
+    }
+}
+function decide(explicitChange, interruptedRuns, distinctActiveWorkChanges) {
+    if (explicitChange !== undefined)
+        return 'proceed-explicit-change';
+    const interrupted = interruptedRuns[0];
+    if (interrupted !== undefined)
+        return 'inspect-interrupted-run';
+    if (distinctActiveWorkChanges.length === 1)
+        return 'proceed-single-active-work';
+    return 'ask-change';
+}
+function allowedNextTools(decision) {
+    if (decision === 'inspect-interrupted-run')
+        return ['vgxness_run_resume_inspect', 'vgxness_run_resume_gate'];
+    if (decision === 'ask-change')
+        return [];
+    return ['vgxness_sdd_status', 'vgxness_sdd_next', 'vgxness_sdd_cockpit', 'vgxness_sdd_continue', 'vgxness_sdd_get_artifact', 'vgxness_sdd_list_artifacts', 'vgxness_agent_resolve'];
+}
+function prohibitedNextTools(decision) {
+    const base = ['repository-inspection', 'provider-execution', 'provider-config-write', 'shell', 'git', 'install', 'network', 'secrets'];
+    if (decision === 'ask-change')
+        return [
+            ...base,
+            'vgxness_sdd_status',
+            'vgxness_sdd_next',
+            'vgxness_sdd_cockpit',
+            'vgxness_sdd_continue',
+            'vgxness_sdd_get_artifact',
+            'vgxness_sdd_list_artifacts',
+            'vgxness_agent_resolve',
+            'vgxness_run_start',
+            'delegation',
+        ];
+    if (decision === 'inspect-interrupted-run')
+        return [
+            ...base,
+            'vgxness_sdd_status',
+            'vgxness_sdd_next',
+            'vgxness_sdd_cockpit',
+            'vgxness_sdd_continue',
+            'vgxness_sdd_get_artifact',
+            'vgxness_sdd_list_artifacts',
+            'vgxness_agent_resolve',
+            'vgxness_run_start',
+            'delegation',
+        ];
+    return [...base, 'mutating-artifact-tools', 'vgxness_run_start'];
+}
+function nextAction(decision) {
+    switch (decision) {
+        case 'proceed-explicit-change':
+            return 'Proceed with SDD read/progression tools for the explicit selectedChange only.';
+        case 'proceed-single-active-work':
+            return 'Proceed with SDD read/progression tools for the single active-work selectedChange only.';
+        case 'inspect-interrupted-run':
+            return 'Inspect the interrupted run candidate before any SDD progression.';
+        case 'ask-change':
+            return 'Ask the user which change to resume and stop.';
+    }
+}
+function isString(value) {
+    return value !== undefined;
+}

package/dist/mcp/schema.js

@@ -25,6 +25,7 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_session_close',
     'vgxness_session_restore',
     'vgxness_context_cockpit',
+    'vgxness_resume_context',
     'vgxness_agent_resolve',
     'vgxness_agent_activate',
     'vgxness_manager_profile_get',
@@ -82,6 +83,7 @@ export const EXPOSED_VGX_MCP_TOOL_NAMES = [
     'session_close',
     'session_restore',
     'context_cockpit',
+    'resume_context',
     'agent_resolve',
     'agent_activate',
     'manager_profile_get',
@@ -483,6 +485,17 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         level: z.enum(contextCockpitLevels).optional(),
     })
         .passthrough(),
+    vgxness_resume_context: z
+        .object({
+        project: z.string().min(1),
+        directory: z.string().min(1).optional(),
+        workspaceRoot: z.string().min(1).optional(),
+        userPrompt: z.string().optional(),
+        explicitChange: z.preprocess((value) => (typeof value === 'string' && value.trim().length === 0 ? undefined : value), z.string().min(1).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/).optional()),
+        limit: z.number().int().min(1).max(25).optional(),
+        payloadMode: z.enum(payloadModes).optional(),
+    })
+        .passthrough(),
     vgxness_agent_resolve: z
         .object({
         project: z.string().min(1).optional(),

package/dist/mcp/stdio-server.js

@@ -67,6 +67,8 @@ function descriptionForTool(publicToolName) {
         return 'Read-only run resume gate advisory; plan-only and does not execute resume logic, invoke providers, write provider config, admit retries, abandon or mutate attempts, or reconstruct sandboxes, worktrees, sessions, or transcripts.';
     if (publicToolName === 'context_cockpit')
         return 'Read-only context cockpit for start/resume/recovery; change is optional and should be omitted when unknown; returns latest restorable session plus bounded memory previews without traces, provider config writes, repository writes, runs, artifacts, or session mutations.';
+    if (publicToolName === 'resume_context')
+        return 'Read-only no-trace/no-mutation resume gate required before generic resume prompts; decides explicit change, interrupted run inspect, single active-work, or ask-change without provider execution, repository inspection, traces, runs, artifacts, sessions, memory writes, or provider config writes.';
     if (publicToolName === 'skill_index')
         return 'Read-only skill registry index for a project and scope; returns SkillIndexOutput without provider config writes, native skill file writes, URL fetches, usage records, startup refresh, or plugin refresh.';
     if (publicToolName === 'skill_create_draft')

package/dist/mcp/validation.js

@@ -82,6 +82,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateSessionRestoreInput(input, tool.value));
         case 'vgxness_context_cockpit':
             return validationSuccess(tool.value, validateContextCockpitInput(input, tool.value));
+        case 'vgxness_resume_context':
+            return validationSuccess(tool.value, validateResumeContextInput(input, tool.value));
         case 'vgxness_agent_resolve':
             return validationSuccess(tool.value, validateAgentResolveInput(input, tool.value));
         case 'vgxness_agent_activate':
@@ -333,6 +335,45 @@ function validateContextCockpitInput(input, tool) {
         result.level = level.value;
     return { ok: true, value: result };
 }
+function validateResumeContextInput(input, tool) {
+    const record = inputRecord(input, tool, ['project', 'directory', 'workspaceRoot', 'userPrompt', 'explicitChange', 'limit', 'payloadMode']);
+    if (!record.ok)
+        return record;
+    const project = readNonEmptyString(record.value, 'project', tool);
+    if (!project.ok)
+        return project;
+    const result = { project: project.value };
+    const directory = readOptionalNonEmptyString(record.value, 'directory', tool);
+    if (!directory.ok)
+        return directory;
+    if (directory.value !== undefined)
+        result.directory = directory.value;
+    const workspaceRoot = readOptionalNonEmptyString(record.value, 'workspaceRoot', tool);
+    if (!workspaceRoot.ok)
+        return workspaceRoot;
+    if (workspaceRoot.value !== undefined)
+        result.workspaceRoot = workspaceRoot.value;
+    if (record.value.userPrompt !== undefined) {
+        if (typeof record.value.userPrompt !== 'string')
+            return validationFailure('userPrompt must be a string', tool);
+        result.userPrompt = record.value.userPrompt;
+    }
+    const explicitChange = readOptionalExplicitChange(record.value, tool);
+    if (!explicitChange.ok)
+        return explicitChange;
+    if (explicitChange.value !== undefined)
+        result.explicitChange = explicitChange.value;
+    if (record.value.limit !== undefined) {
+        if (typeof record.value.limit !== 'number' || !Number.isSafeInteger(record.value.limit) || record.value.limit < 1 || record.value.limit > 25)
+            return validationFailure('limit must be an integer between 1 and 25', tool);
+        result.limit = record.value.limit;
+    }
+    const payloadMode = readOptionalOneOf(record.value, 'payloadMode', payloadModes, tool);
+    if (!payloadMode.ok)
+        return payloadMode;
+    result.payloadMode = payloadMode.value ?? 'compact';
+    return { ok: true, value: result };
+}
 function readProjectAndChange(record, tool) {
     const project = readNonEmptyString(record, 'project', tool);
     if (!project.ok)
@@ -1719,6 +1760,18 @@ function readOptionalContextCockpitChange(record, tool) {
         return { ok: true, value: undefined };
     return readOptionalChange(record, tool);
 }
+function readOptionalExplicitChange(record, tool) {
+    if (record.explicitChange === undefined)
+        return { ok: true, value: undefined };
+    if (typeof record.explicitChange !== 'string')
+        return validationFailure('explicitChange must be a string', tool);
+    const trimmed = record.explicitChange.trim();
+    if (trimmed.length === 0)
+        return { ok: true, value: undefined };
+    if (!validChangePattern.test(trimmed))
+        return validationFailure(`Invalid explicit change id: ${trimmed}`, tool);
+    return { ok: true, value: trimmed };
+}
 function readPhase(record, tool) {
     const phase = readNonEmptyString(record, 'phase', tool);
     if (!phase.ok)

package/dist/memory/active-work-topics.js

@@ -33,6 +33,20 @@ export function parseActiveWorkTopicKey(topicKey) {
         return { change: parts[1], segment, slug: parts.slice(3).join('/') };
     return undefined;
 }
+export function parseActiveWorkChangeSelectorTopicKey(topicKey) {
+    const parsed = parseActiveWorkSelectorTopicKey(topicKey);
+    return parsed.parseStatus === 'parsed' ? { change: parsed.change } : undefined;
+}
+export function parseActiveWorkSelectorTopicKey(topicKey) {
+    const parts = topicKey?.split('/') ?? [];
+    if (parts[0] !== activeWorkTopicRoot)
+        return { parseStatus: 'ignored-non-active-work' };
+    const change = parts[1];
+    if (change === undefined || change.length === 0 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(change))
+        return { parseStatus: 'malformed' };
+    const segment = parts[2];
+    return segment === undefined || segment.length === 0 ? { parseStatus: 'parsed', change } : { parseStatus: 'parsed', change, segment };
+}
 function isActiveWorkSegment(value) {
     return isActiveWorkCurrentSegment(value) || isActiveWorkDetailSegment(value);
 }

package/package.json

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