oh-my-codex 0.20.3 → 0.21.0

package/dist/state/operations.js

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { assertValidHandoffCarriersIn, requirePersistedHandoffCarrier } from './handoff-carrier.js';
 import { withModeRuntimeContext } from './mode-state-context.js';
-import { getAllScopedStatePaths, getAuthoritativeActiveStateDirs, getBaseStateDir, getBaseStateDirWithSource, getReadScopedStateDirs, getReadScopedStatePaths, getStateDir, getStatePath, resolveRuntimeStateScope, resolveWritableStateScope, resolveWorkingDirectoryForState, validateSessionId, validateStateModeSegment, } from '../mcp/state-paths.js';
+import { createWritableCommitRevalidator, getStateFilename, getAllScopedStatePaths, getAuthoritativeActiveStateDirs, getBaseStateDir, getBaseStateDirWithSource, getReadScopedStateDirs, getReadScopedStatePaths, getStateDir, getStatePath, resolveRuntimeStateScope, resolveWritableStateScope, resolveWorkingDirectoryForState, validateSessionId, validateStateModeSegment, } from '../mcp/state-paths.js';
 import { evaluateRalphCompletionAuditEvidence } from '../ralph/completion-audit.js';
 import { ensureCanonicalRalphArtifacts } from '../ralph/persistence.js';
 import { RALPH_PHASES, validateAndNormalizeRalphState } from '../ralph/contract.js';
@@ -10,37 +11,9 @@ import { applyRunOutcomeContract } from '../runtime/run-outcome.js';
 import { normalizeTerminalWorkflowState } from './terminal-normalization.js';
 import { hasCleanAutopilotReviewAndQaEvidence, isAutopilotSuccessfulTerminalState, validateAutopilotCompletionTransition, } from '../autopilot/completion-gate.js';
 import { readUltragoalState } from '../hud/state.js';
-import { SKILL_ACTIVE_STATE_MODE, clearTerminalSkillActiveMarkers, getSkillActiveStatePathsForStateDir, isTerminalSkillActiveState, isTransitionCanonicalStateOwned, listActiveSkills, listTransitionActiveSkills, readSkillActiveState, readVisibleSkillActiveStateForStateDir, syncCanonicalSkillStateForMode, writeSkillActiveStateCopiesForStateDir, } from './skill-active.js';
-import { buildWorkflowTransitionError, evaluateWorkflowTransition, isTrackedWorkflowMode, } from './workflow-transition.js';
+import { SKILL_ACTIVE_STATE_MODE, clearTerminalSkillActiveMarkers, getSkillActiveStatePathsForStateDir, isTerminalSkillActiveState, isTransitionCanonicalStateOwned, listActiveSkills, listTransitionActiveSkills, readSkillActiveState, readVisibleSkillActiveStateForStateDir, syncCanonicalSkillStateForMode, writeSkillActiveStateCopiesForStateDir, writeSkillActiveStateWithPrimaryTransactionForStateDir, } from './skill-active.js';
+import { isTrackedWorkflowMode, } from './workflow-transition.js';
 import { reconcileWorkflowTransition } from './workflow-transition-reconcile.js';
-import { buildAutopilotDeepInterviewRalplanGateError, canAdvanceAutopilotDeepInterviewToRalplan, } from '../autopilot/deep-interview-gate.js';
-import { deriveAutopilotChildPhase, } from '../autopilot/fsm.js';
-import { buildAutopilotRalplanUltragoalGateError, canAdvanceAutopilotRalplanToUltragoal, } from '../autopilot/ralplan-gate.js';
-import { isUnsupportedNativeSubagentEvidenceForScope, } from '../leader/contract.js';
-import { buildRalplanConsensusGateFromSources, } from '../ralplan/consensus-gate.js';
-const AUTOPILOT_CHILD_PHASE_ORDER = [
-    'deep-interview',
-    'ralplan',
-    'ultragoal',
-    'rework',
-    'team',
-    'ralph',
-    'code-review',
-    'ultraqa',
-];
-function autopilotPhaseOrder(phase) {
-    return phase ? AUTOPILOT_CHILD_PHASE_ORDER.indexOf(phase) : -1;
-}
-function isForwardAutopilotPhase(currentPhase, nextPhase) {
-    const currentOrder = autopilotPhaseOrder(currentPhase);
-    const nextOrder = autopilotPhaseOrder(nextPhase);
-    return currentOrder >= 0 && nextOrder > currentOrder;
-}
-function isNextAutopilotPhase(currentPhase, nextPhase) {
-    const currentOrder = autopilotPhaseOrder(currentPhase);
-    const nextOrder = autopilotPhaseOrder(nextPhase);
-    return currentOrder >= 0 && nextOrder === currentOrder + 1;
-}
 export const SUPPORTED_STATE_READ_MODES = [
     'autopilot',
     'autoresearch',
@@ -72,6 +45,18 @@ async function withStateWriteLock(path, fn) {
         }
     }
 }
+/**
+ * The sole writer primitive for `.omx/state/` session-scoped workflow state.
+ * Every module that persists `{mode}-state.json` MUST route through this function
+ * so that the single-writer invariant is preserved.
+ */
+export async function writeStateFile(path, data) {
+    await writeAtomicFile(path, data);
+}
+/**
+ * Internal atomic write helper — not exported except through {@link writeStateFile}.
+ * Defined here so the single-writer surface has one implementation site.
+ */
 async function writeAtomicFile(path, data) {
     const tmpPath = `${path}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
     await writeFile(tmpPath, data, 'utf-8');
@@ -83,7 +68,7 @@ async function writeAtomicFile(path, data) {
         throw error;
     }
 }
-async function writeClearedSessionScopedModeState(path, mode, sessionId) {
+async function writeClearedSessionScopedModeState(path, mode, sessionId, beforeCommit) {
     const nowIso = new Date().toISOString();
     const clearedState = withModeRuntimeContext({}, {
         mode,
@@ -93,15 +78,17 @@ async function writeClearedSessionScopedModeState(path, mode, sessionId) {
         completed_at: nowIso,
         session_id: sessionId,
     });
-    await writeAtomicFile(path, JSON.stringify(clearedState, null, 2));
+    const payload = JSON.stringify(clearedState, null, 2);
+    await beforeCommit?.({ site: 'state-clear.primary', kind: 'write', path });
+    await writeAtomicFile(path, payload);
 }
-async function clearSessionNativeStopState(baseStateDir, sessionId) {
+async function clearSessionNativeStopState(baseStateDir, sessionId, beforeCommit) {
     const paths = [
-        join(baseStateDir, 'native-stop-state.json'),
-        join(baseStateDir, 'sessions', sessionId, 'native-stop-state.json'),
+        { path: join(baseStateDir, 'native-stop-state.json'), site: 'native-stop.root' },
+        { path: join(baseStateDir, 'sessions', sessionId, 'native-stop-state.json'), site: 'native-stop.session' },
     ];
     const changed = [];
-    for (const path of paths) {
+    for (const { path, site } of paths) {
         if (!existsSync(path))
             continue;
         let state;
@@ -118,7 +105,9 @@ async function clearSessionNativeStopState(baseStateDir, sessionId) {
             continue;
         delete sessions[sessionId];
         state.sessions = sessions;
-        await writeAtomicFile(path, JSON.stringify(state, null, 2));
+        const payload = JSON.stringify(state, null, 2);
+        await beforeCommit?.({ site, kind: 'write', path });
+        await writeAtomicFile(path, payload);
         changed.push(path);
     }
     return changed;
@@ -133,9 +122,14 @@ function validateStrictReadableMode(mode) {
     }
     return normalized;
 }
-async function initializeStateEnvironment(cwd, effectiveSessionId, rootSource) {
-    await mkdir(getStateDir(cwd), { recursive: true });
-    if (effectiveSessionId) {
+async function initializeStateEnvironment(cwd, effectiveSessionId, rootSource, exactStateDir) {
+    if (exactStateDir) {
+        await mkdir(exactStateDir, { recursive: true });
+    }
+    else {
+        await mkdir(getStateDir(cwd), { recursive: true });
+    }
+    if (effectiveSessionId && !exactStateDir) {
         await mkdir(getStateDir(cwd, effectiveSessionId), { recursive: true });
     }
     if (rootSource === 'team-env')
@@ -178,7 +172,12 @@ function normalizeCleanAutopilotCompletionEvidence(state) {
     const reviewVerdict = state.review_verdict;
     const qaVerdict = state.qa_verdict;
     const nestedState = { ...objectRecord(state.state) };
-    const handoffArtifacts = { ...objectRecord(nestedState.handoff_artifacts ?? state.handoff_artifacts) };
+    // Same invariant as the writers: objectRecord() would turn a corrupt carrier into {}, and this
+    // function then stamps clean review/QA verdicts onto it. Writing completion evidence over corruption
+    // would launder it into a valid-looking clean terminal state, so a corrupt carrier fails closed.
+    // Both locations, in the same precedence order the completion gate's stateField() uses.
+    const rawCarrier = nestedState.handoff_artifacts ?? state.handoff_artifacts;
+    const handoffArtifacts = { ...requirePersistedHandoffCarrier(rawCarrier, 'handoff_artifacts carrier') };
     handoffArtifacts.code_review = reviewVerdict;
     handoffArtifacts.ultraqa = qaVerdict;
     state.handoff_artifacts = handoffArtifacts;
@@ -189,91 +188,28 @@ function normalizeCleanAutopilotCompletionEvidence(state) {
     nestedState.return_to_ralplan_reason = null;
     state.state = nestedState;
 }
+function appendAutopilotCompletionAdvisory(state, completionAdvisory) {
+    const existing = Array.isArray(state.skipped_gates)
+        ? state.skipped_gates.filter((entry) => (Boolean(entry)
+            && typeof entry === 'object'
+            && !Array.isArray(entry)
+            && typeof entry.skippedGate === 'string'
+            && typeof entry.missingEvidence === 'string'
+            && typeof entry.message === 'string'))
+        : [];
+    const skippedGates = completionAdvisory && !existing.some((entry) => entry.skippedGate === completionAdvisory.skippedGate)
+        ? [...existing, completionAdvisory]
+        : existing;
+    if (skippedGates.length === 0)
+        return;
+    state.skipped_gates = skippedGates;
+    if (isAutopilotSuccessfulTerminalState(state))
+        state.completion_status = 'complete-with-skipped-gates';
+}
 function isCompleteRalplanTerminalState(state) {
     const currentPhase = stringValue(state.current_phase).trim().toLowerCase();
-    const gate = objectRecord(state.ralplan_consensus_gate);
     return state.active === false
-        && currentPhase === 'complete'
-        && gate.complete === true;
-}
-function isRalplanCompleteCloseoutAttempt(state) {
-    return state.active === false && hasCleanTerminalValue(state);
-}
-function stateContainsUnsupportedNativeSubagentEvidence(state, input = {}) {
-    const nestedState = objectRecord(state.state);
-    const handoffArtifacts = objectRecord(state.handoff_artifacts);
-    const nestedHandoffArtifacts = objectRecord(nestedState.handoff_artifacts);
-    const ralplanHandoff = objectRecord(handoffArtifacts.ralplan);
-    const nestedRalplanHandoff = objectRecord(nestedHandoffArtifacts.ralplan);
-    return isUnsupportedNativeSubagentEvidenceForScope(state.native_subagent_support, input)
-        || isUnsupportedNativeSubagentEvidenceForScope(nestedState.native_subagent_support, input)
-        || isUnsupportedNativeSubagentEvidenceForScope(handoffArtifacts.native_subagent_support, input)
-        || isUnsupportedNativeSubagentEvidenceForScope(nestedHandoffArtifacts.native_subagent_support, input)
-        || isUnsupportedNativeSubagentEvidenceForScope(ralplanHandoff.native_subagent_support, input)
-        || isUnsupportedNativeSubagentEvidenceForScope(nestedRalplanHandoff.native_subagent_support, input);
-}
-function hasNonCleanTerminalValue(state) {
-    const terminalValues = new Set(['blocked', 'cancelled', 'failed']);
-    return terminalValues.has(stringValue(state.current_phase).trim().toLowerCase())
-        || terminalValues.has(stringValue(state.status).trim().toLowerCase())
-        || terminalValues.has(stringValue(state.outcome).trim().toLowerCase())
-        || terminalValues.has(stringValue(state.terminal_outcome).trim().toLowerCase())
-        || terminalValues.has(stringValue(state.lifecycle_outcome).trim().toLowerCase())
-        || terminalValues.has(stringValue(state.run_outcome).trim().toLowerCase());
-}
-function hasCleanTerminalValue(state) {
-    const terminalValues = [
-        state.current_phase,
-        state.status,
-        state.outcome,
-        state.terminal_outcome,
-        state.lifecycle_outcome,
-        state.run_outcome,
-    ];
-    return terminalValues.some((value) => stringValue(value).trim().toLowerCase() === 'complete');
-}
-function hasCompleteRalplanConsensusGate(state) {
-    const nestedState = objectRecord(state.state);
-    return objectRecord(state.ralplan_consensus_gate).complete === true
-        || objectRecord(nestedState.ralplan_consensus_gate).complete === true;
-}
-function isApprovedUnsupportedNativeNonCleanRecoveryState(state, input = {}) {
-    if (state.active !== false)
-        return false;
-    if (hasCleanTerminalValue(state))
-        return false;
-    if (hasCompleteRalplanConsensusGate(state))
-        return false;
-    return stateContainsUnsupportedNativeSubagentEvidence(state, input) && hasNonCleanTerminalValue(state);
-}
-export function validateRalplanTerminalConsensus(cwd, state, sessionId, options = {}) {
-    if (!isRalplanCompleteCloseoutAttempt(state))
-        return null;
-    if (stateContainsUnsupportedNativeSubagentEvidence(state, { cwd, sessionId })) {
-        return 'Cannot complete ralplan cleanly while native subagent support is unavailable; terminalize the workflow as blocked/cancelled/failed or restart in a runtime with working native subagents.';
-    }
-    const stateSessionId = sessionId ?? optionalSessionId(state.session_id);
-    const gate = buildRalplanConsensusGateFromSources([
-        { source: 'state-write-ralplan-terminal', value: state, sessionId: stateSessionId },
-    ], {
-        cwd,
-        sessionId: stateSessionId,
-        requireNativeSubagents: options.requireNativeSubagents === true,
-    });
-    if (gate.complete === true) {
-        if (options.requireNativeSubagents === true) {
-            state.ralplan_consensus_gate = {
-                ...objectRecord(state.ralplan_consensus_gate),
-                ...gate,
-            };
-        }
-        return null;
-    }
-    const details = gate.blockedDetails?.length ? ` Details: ${gate.blockedDetails.join('; ')}.` : '';
-    const evidenceDescription = options.requireNativeSubagents === true
-        ? 'tracker-backed native architect and critic consensus evidence'
-        : 'architect and critic consensus evidence';
-    return `ralplan complete state requires ${evidenceDescription} (${gate.blockedReason ?? 'missing_consensus'}).${details}`;
+        && currentPhase === 'complete';
 }
 function buildRalplanTerminalState(state, sessionId, nowIso) {
     const completedAt = stringValue(state.completed_at).trim() || nowIso;
@@ -288,10 +224,6 @@ function buildRalplanTerminalState(state, sessionId, nowIso) {
         completed_at: completedAt,
         terminal_reason: terminalReason,
         session_id: sessionId,
-        ralplan_consensus_gate: {
-            ...objectRecord(state.ralplan_consensus_gate),
-            complete: true,
-        },
     });
 }
 function buildRalplanTerminalSkillState(base, terminalState, sessionId, nowIso) {
@@ -369,10 +301,12 @@ function collectCompletedRalplanSessionEntries(sessionState, rootState, sessionI
     }
     return [...entries.values()];
 }
-async function writeAtomicJson(path, value) {
+function serializeAtomicJson(value) {
     const serialized = JSON.stringify(value, null, 2);
     JSON.parse(serialized);
-    await mkdir(dirname(path), { recursive: true });
+    return serialized;
+}
+async function writeAtomicJson(path, serialized) {
     await writeAtomicFile(path, serialized);
 }
 async function readJsonRecordIfExists(path) {
@@ -392,44 +326,70 @@ function shouldWriteRootRalplanTerminalState(rootState, sessionId) {
     return optionalSessionId(rootState?.session_id) === sessionId;
 }
 export async function completeRalplanSession(options) {
+    if (options.beforeCommit && !options.capturedScope) {
+        throw new Error('completeRalplanSession requires capturedScope when beforeCommit is provided');
+    }
     if (!isCompleteRalplanTerminalState(options.state))
         return false;
-    const writableScope = await resolveWritableStateScope(options.cwd, options.explicitSessionId);
+    const writableScope = options.capturedScope
+        ?? await resolveWritableStateScope(options.cwd, options.explicitSessionId);
     const sessionId = writableScope.sessionId;
-    const validationError = validateRalplanTerminalConsensus(options.cwd, options.state, sessionId, {
-        requireNativeSubagents: options.requireNativeSubagents === true,
+    const beforeCommit = options.beforeCommit ?? createWritableCommitRevalidator({
+        operation: 'completeRalplanSession',
+        cwd: options.cwd,
+        explicitSessionId: options.explicitSessionId,
+        capturedScope: writableScope,
+        baseStateDir: options.baseStateDir,
     });
-    if (validationError)
-        throw new Error(validationError);
     const completedSessionId = sessionId ?? optionalSessionId(options.state.session_id);
     const rootScopeCompletion = !sessionId;
     const nowIso = new Date().toISOString();
     const rootState = buildRalplanTerminalState(options.state, sessionId, nowIso);
-    const rootStatePath = getStatePath('ralplan', options.cwd);
+    const rootStatePath = join(options.baseStateDir, getStateFilename('ralplan'));
     const existingRootState = await readJsonRecordIfExists(rootStatePath);
     const shouldWriteRootState = shouldWriteRootRalplanTerminalState(existingRootState, sessionId);
     if (shouldWriteRootState) {
-        await writeAtomicJson(rootStatePath, rootState);
+        const rootStatePayload = serializeAtomicJson(rootState);
+        await mkdir(dirname(rootStatePath), { recursive: true });
+        await beforeCommit({ site: 'ralplan.root-state', kind: 'write', path: rootStatePath });
+        await writeAtomicJson(rootStatePath, rootStatePayload);
     }
     if (sessionId) {
-        await writeAtomicJson(getStatePath('ralplan', options.cwd, sessionId), buildRalplanTerminalState(options.state, sessionId, nowIso));
+        const sessionStatePath = join(writableScope.stateDir, getStateFilename('ralplan'));
+        const sessionState = buildRalplanTerminalState(options.state, sessionId, nowIso);
+        const sessionStatePayload = serializeAtomicJson(sessionState);
+        await mkdir(dirname(sessionStatePath), { recursive: true });
+        await beforeCommit({ site: 'ralplan.session-state', kind: 'write', path: sessionStatePath });
+        await writeAtomicJson(sessionStatePath, sessionStatePayload);
     }
     const { rootPath, sessionPath } = getSkillActiveStatePathsForStateDir(options.baseStateDir, sessionId);
     const rootSkillState = await readSkillActiveState(rootPath);
     const rootEntries = filterCompletedRalplanRootEntries(listActiveSkills(rootSkillState ?? {}), completedSessionId, rootScopeCompletion);
     if (rootEntries.length > 0 || (shouldWriteRootState && rootSkillState !== null)) {
-        await writeAtomicJson(rootPath, buildRalplanSkillStateFromEntries(rootSkillState, rootState, rootEntries, undefined, nowIso));
+        const nextRootSkillState = buildRalplanSkillStateFromEntries(rootSkillState, rootState, rootEntries, undefined, nowIso);
+        const rootSkillStatePayload = serializeAtomicJson(nextRootSkillState);
+        await mkdir(dirname(rootPath), { recursive: true });
+        await beforeCommit({ site: 'ralplan.root-skill-write', kind: 'write', path: rootPath });
+        await writeAtomicJson(rootPath, rootSkillStatePayload);
     }
     else if (rootSkillState !== null && !isTerminalSkillActiveTombstone(rootSkillState)) {
-        await unlink(rootPath).catch(() => { });
+        await beforeCommit({ site: 'ralplan.root-skill-unlink', kind: 'unlink', path: rootPath });
+        await unlink(rootPath).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
     }
     if (sessionPath && sessionId) {
         const sessionSkillState = await readSkillActiveState(sessionPath);
         const sessionEntries = collectCompletedRalplanSessionEntries(sessionSkillState, rootSkillState, sessionId);
         if (sessionEntries.length > 0 || sessionSkillState !== null) {
-            await writeAtomicJson(sessionPath, sessionEntries.length > 0
+            const nextSessionSkillState = sessionEntries.length > 0
                 ? buildRalplanSkillStateFromEntries(sessionSkillState ?? rootSkillState, rootState, sessionEntries, sessionId, nowIso)
-                : buildRalplanTerminalSkillState(sessionSkillState, rootState, sessionId, nowIso));
+                : buildRalplanTerminalSkillState(sessionSkillState, rootState, sessionId, nowIso);
+            const sessionSkillStatePayload = serializeAtomicJson(nextSessionSkillState);
+            await mkdir(dirname(sessionPath), { recursive: true });
+            await beforeCommit({ site: 'ralplan.session-skill-write', kind: 'write', path: sessionPath });
+            await writeAtomicJson(sessionPath, sessionSkillStatePayload);
         }
     }
     return true;
@@ -445,7 +405,7 @@ export async function listStateStatuses(cwd, explicitSessionId, mode, options =
             continue;
         const files = await readdir(stateDir);
         for (const file of files) {
-            if (!file.endsWith('-state.json'))
+            if (!file.endsWith('-state.json') || file === 'run-state.json')
                 continue;
             const currentMode = file.replace('-state.json', '');
             if (!mode && currentMode === SKILL_ACTIVE_STATE_MODE)
@@ -572,12 +532,25 @@ export async function executeStateOperation(name, rawArgs = {}) {
                 const effectiveSessionId = stateScope.sessionId;
                 const mode = validateStateModeSegment(rawArgs.mode);
                 const { baseStateDir, rootSource } = getBaseStateDirWithSource(cwd);
-                await initializeStateEnvironment(cwd, effectiveSessionId, rootSource);
-                const path = getStatePath(mode, cwd, effectiveSessionId);
+                const beforeCommit = createWritableCommitRevalidator({
+                    operation: 'state_write',
+                    cwd,
+                    explicitSessionId,
+                    capturedScope: stateScope,
+                    baseStateDir,
+                });
+                // Write to the exact resolved scope directory; never recompute the
+                // target root/path after authorization.
+                const path = join(stateScope.stateDir, getStateFilename(mode));
                 const { mode: _mode, workingDirectory: _workingDirectory, session_id: _sessionId, state: customState, ...fields } = rawArgs;
+                const customStateRecord = customState && typeof customState === 'object' && !Array.isArray(customState)
+                    ? customState
+                    : {};
                 let validationError = null;
                 let transitionMessage;
+                let completionAdvisory = null;
                 let ensureRalphArtifacts = false;
+                let skillActivePrimaryCommitted = false;
                 await withStateWriteLock(path, async () => {
                     let existing = {};
                     if (existsSync(path)) {
@@ -604,6 +577,11 @@ export async function executeStateOperation(name, rawArgs = {}) {
                     if (!hasExplicitStateField(fields, customState, 'terminal_outcome')) {
                         delete mergedRaw.terminal_outcome;
                     }
+                    let activeCanonicalModes;
+                    if (isTrackedWorkflowMode(mode) && mergedRaw.active === true) {
+                        activeCanonicalModes = await readCanonicalActiveWorkflowModes(baseStateDir, effectiveSessionId);
+                    }
+                    await initializeStateEnvironment(cwd, effectiveSessionId, rootSource, stateScope.stateDir);
                     if (mode === 'ralph' &&
                         effectiveSessionId &&
                         typeof mergedRaw.owner_omx_session_id !== 'string') {
@@ -645,96 +623,52 @@ export async function executeStateOperation(name, rawArgs = {}) {
                         Object.assign(mergedRaw, terminalNormalization.state);
                     }
                     if (mode === 'autopilot') {
-                        normalizeCleanAutopilotCompletionEvidence(mergedRaw);
-                    }
-                    const unsupportedNativeNonCleanRecovery = isApprovedUnsupportedNativeNonCleanRecoveryState(mergedRaw, { cwd, sessionId: effectiveSessionId });
-                    if (mode === 'ralplan' && !unsupportedNativeNonCleanRecovery) {
-                        validationError = validateRalplanTerminalConsensus(cwd, mergedRaw, effectiveSessionId, {
-                            requireNativeSubagents: true,
-                        });
-                        if (validationError)
+                        const nestedSessionId = typeof customStateRecord.session_id === 'string' ? customStateRecord.session_id.trim() : '';
+                        if (nestedSessionId && effectiveSessionId && nestedSessionId !== effectiveSessionId) {
+                            validationError = 'autopilot.session_id must match the selected writable session scope';
                             return;
-                    }
-                    const currentAutopilotChildPhase = mode === 'autopilot'
-                        ? deriveAutopilotChildPhase({ mode: 'autopilot', ...existing })
-                        : null;
-                    let nextAutopilotChildPhase = mode === 'autopilot'
-                        ? deriveAutopilotChildPhase({ mode: 'autopilot', ...mergedRaw })
-                        : null;
-                    if (mode === 'autopilot'
-                        && currentAutopilotChildPhase === 'deep-interview'
-                        && isAutopilotSuccessfulTerminalState(mergedRaw)) {
-                        validationError = 'Cannot complete Autopilot before ralplan gate: deep-interview may only advance to ralplan.';
-                        return;
-                    }
-                    if (mode === 'autopilot'
-                        && currentAutopilotChildPhase === 'ralplan'
-                        && isAutopilotSuccessfulTerminalState(mergedRaw)) {
-                        validationError = 'Cannot complete Autopilot before ultragoal gate: ralplan may only advance to ultragoal.';
-                        return;
-                    }
-                    if (mode === 'autopilot'
-                        && currentAutopilotChildPhase === 'ralplan'
-                        && unsupportedNativeNonCleanRecovery) {
-                        nextAutopilotChildPhase = currentAutopilotChildPhase;
-                    }
-                    if (mode === 'autopilot') {
-                        const completionTransitionError = validateAutopilotCompletionTransition(existing, mergedRaw);
-                        if (completionTransitionError) {
-                            validationError = completionTransitionError;
+                        }
+                        const nestedWorkingDirectory = typeof customStateRecord.workingDirectory === 'string'
+                            ? customStateRecord.workingDirectory.trim()
+                            : '';
+                        if (nestedWorkingDirectory && nestedWorkingDirectory !== cwd) {
+                            validationError = 'autopilot.workingDirectory must match the selected writable workspace';
                             return;
                         }
-                    }
-                    if (mode === 'autopilot'
-                        && currentAutopilotChildPhase === 'deep-interview'
-                        && isForwardAutopilotPhase(currentAutopilotChildPhase, nextAutopilotChildPhase)
-                        && !isNextAutopilotPhase(currentAutopilotChildPhase, nextAutopilotChildPhase)) {
-                        validationError = 'Cannot skip Autopilot ralplan gate: deep-interview may only advance to ralplan.';
-                        return;
-                    }
-                    if (mode === 'autopilot'
-                        && currentAutopilotChildPhase === 'deep-interview'
-                        && isNextAutopilotPhase(currentAutopilotChildPhase, nextAutopilotChildPhase)) {
-                        const gate = await canAdvanceAutopilotDeepInterviewToRalplan({
-                            cwd,
-                            sessionId: effectiveSessionId,
-                            baseStateDir,
-                            currentState: existing,
-                            nextState: mergedRaw,
-                        });
-                        if (!gate.allowed) {
-                            validationError = buildAutopilotDeepInterviewRalplanGateError(gate);
+                        const submittedSessionId = typeof mergedRaw.session_id === 'string' ? mergedRaw.session_id.trim() : '';
+                        if (submittedSessionId && effectiveSessionId && submittedSessionId !== effectiveSessionId) {
+                            validationError = 'autopilot.session_id must match the selected writable session scope';
                             return;
                         }
-                    }
-                    if (mode === 'autopilot'
-                        && currentAutopilotChildPhase === 'ralplan'
-                        && isForwardAutopilotPhase(currentAutopilotChildPhase, nextAutopilotChildPhase)
-                        && !isNextAutopilotPhase(currentAutopilotChildPhase, nextAutopilotChildPhase)) {
-                        validationError = 'Cannot skip Autopilot ultragoal gate: ralplan may only advance to ultragoal.';
-                        return;
-                    }
-                    if (mode === 'autopilot'
-                        && currentAutopilotChildPhase === 'ralplan'
-                        && isNextAutopilotPhase(currentAutopilotChildPhase, nextAutopilotChildPhase)) {
-                        const gate = canAdvanceAutopilotRalplanToUltragoal({
-                            cwd,
-                            sessionId: effectiveSessionId,
-                            currentState: existing,
-                            nextState: mergedRaw,
-                        });
-                        if (!gate.allowed) {
-                            validationError = buildAutopilotRalplanUltragoalGateError(gate);
+                        const submittedWorkingDirectory = typeof mergedRaw.workingDirectory === 'string'
+                            ? mergedRaw.workingDirectory.trim()
+                            : '';
+                        if (submittedWorkingDirectory && submittedWorkingDirectory !== cwd) {
+                            validationError = 'autopilot.workingDirectory must match the selected writable workspace';
                             return;
                         }
+                        if (effectiveSessionId)
+                            mergedRaw.session_id = effectiveSessionId;
+                        if (typeof mergedRaw.workingDirectory !== 'string' || mergedRaw.workingDirectory.trim() === '') {
+                            mergedRaw.workingDirectory = cwd;
+                        }
+                        // state_write is an independent public writer with its own merge, so it needs the same
+                        // invariant as modes/base.ts: reject a supplied malformed carrier BEFORE normalizing it.
+                        // Otherwise an existing non-empty carrier simply overwrote the malformed value and the gate
+                        // saw an ordinary object, which is how a forged array advanced a phase with an advisory.
+                        assertValidHandoffCarriersIn(mergedRaw, 'state_write');
+                        const existingHandoffs = requirePersistedHandoffCarrier(existing.handoff_artifacts, 'stored handoff_artifacts carrier');
+                        const nextHandoffs = requirePersistedHandoffCarrier(mergedRaw.handoff_artifacts, 'state_write handoff_artifacts carrier');
+                        if (Object.keys(existingHandoffs).length > 0 || Object.keys(nextHandoffs).length > 0) {
+                            mergedRaw.handoff_artifacts = { ...existingHandoffs, ...nextHandoffs };
+                        }
+                        normalizeCleanAutopilotCompletionEvidence(mergedRaw);
+                    }
+                    if (mode === 'autopilot') {
+                        completionAdvisory = validateAutopilotCompletionTransition(existing, mergedRaw);
+                        appendAutopilotCompletionAdvisory(mergedRaw, completionAdvisory);
                     }
                     if (isTrackedWorkflowMode(mode) && mergedRaw.active === true) {
-                        const activeCanonicalModes = await readCanonicalActiveWorkflowModes(baseStateDir, effectiveSessionId);
-                        const canonicalDecision = evaluateWorkflowTransition(activeCanonicalModes, mode);
-                        if (!canonicalDecision.allowed && canonicalDecision.denialReason === 'rollback') {
-                            validationError = buildWorkflowTransitionError(activeCanonicalModes, mode, 'write');
-                            return;
-                        }
                         const transitionCurrentModes = mode === 'ralplan'
                             ? (activeCanonicalModes.length > 0
                                 ? activeCanonicalModes
@@ -746,6 +680,7 @@ export async function executeStateOperation(name, rawArgs = {}) {
                                 sessionId: effectiveSessionId,
                                 source: 'state-operations',
                                 baseStateDir,
+                                beforeCommit,
                                 ...(transitionCurrentModes ? { currentModes: transitionCurrentModes } : {}),
                             });
                             transitionMessage ??= transition.transitionMessage;
@@ -756,7 +691,18 @@ export async function executeStateOperation(name, rawArgs = {}) {
                         }
                     }
                     const merged = withModeRuntimeContext(existing, mergedRaw);
-                    await writeAtomicFile(path, JSON.stringify(merged, null, 2));
+                    const payload = JSON.stringify(merged, null, 2);
+                    if (mode === SKILL_ACTIVE_STATE_MODE && effectiveSessionId) {
+                        await writeSkillActiveStateWithPrimaryTransactionForStateDir(baseStateDir, merged, effectiveSessionId, path, async () => {
+                            await beforeCommit({ site: 'mode.primary', kind: 'write', path });
+                            await writeAtomicFile(path, payload);
+                        }, { beforeCommit });
+                        skillActivePrimaryCommitted = true;
+                    }
+                    else {
+                        await beforeCommit({ site: 'mode.primary', kind: 'write', path });
+                        await writeAtomicFile(path, payload);
+                    }
                 });
                 if (validationError) {
                     return {
@@ -765,9 +711,11 @@ export async function executeStateOperation(name, rawArgs = {}) {
                     };
                 }
                 if (mode === SKILL_ACTIVE_STATE_MODE) {
-                    const state = await readSkillActiveState(path);
-                    if (state) {
-                        await writeSkillActiveStateCopiesForStateDir(baseStateDir, state, effectiveSessionId);
+                    if (!skillActivePrimaryCommitted) {
+                        const state = await readSkillActiveState(path);
+                        if (state) {
+                            await writeSkillActiveStateCopiesForStateDir(baseStateDir, state, effectiveSessionId, undefined, { beforeCommit });
+                        }
                     }
                 }
                 else {
@@ -776,13 +724,13 @@ export async function executeStateOperation(name, rawArgs = {}) {
                     }
                     const data = JSON.parse(await readFile(path, 'utf-8'));
                     const ralplanCompletionHandled = mode === 'ralplan'
-                        && !isApprovedUnsupportedNativeNonCleanRecoveryState(data, { cwd, sessionId: effectiveSessionId })
                         && await completeRalplanSession({
                             cwd,
                             baseStateDir,
                             state: data,
                             explicitSessionId,
-                            requireNativeSubagents: true,
+                            beforeCommit,
+                            capturedScope: stateScope,
                         });
                     if (!ralplanCompletionHandled) {
                         await syncCanonicalSkillStateForMode({
@@ -793,6 +741,7 @@ export async function executeStateOperation(name, rawArgs = {}) {
                             currentPhase: typeof data.current_phase === 'string' ? data.current_phase : undefined,
                             sessionId: effectiveSessionId,
                             source: 'state-operations',
+                            beforeCommit,
                         });
                     }
                 }
@@ -802,6 +751,7 @@ export async function executeStateOperation(name, rawArgs = {}) {
                         mode,
                         path,
                         ...(transitionMessage ? { transition: transitionMessage } : {}),
+                        ...(completionAdvisory ? { advisory: completionAdvisory } : {}),
                     },
                 };
             }
@@ -845,17 +795,25 @@ export async function executeStateOperation(name, rawArgs = {}) {
                 const stateScope = await resolveWritableStateScope(cwd, explicitSessionId);
                 const effectiveSessionId = stateScope.sessionId;
                 await initializeStateEnvironment(cwd, effectiveSessionId, rootSource);
-                const path = getStatePath(mode, cwd, effectiveSessionId);
+                const beforeCommit = createWritableCommitRevalidator({
+                    operation: 'state_clear',
+                    cwd,
+                    explicitSessionId,
+                    capturedScope: stateScope,
+                    baseStateDir,
+                });
+                const path = join(stateScope.stateDir, getStateFilename(mode));
                 if (mode !== SKILL_ACTIVE_STATE_MODE
                     && effectiveSessionId
                     && existsSync(getStatePath(mode, cwd))) {
-                    await writeClearedSessionScopedModeState(path, mode, effectiveSessionId);
+                    await writeClearedSessionScopedModeState(path, mode, effectiveSessionId, beforeCommit);
                 }
                 else if (existsSync(path)) {
+                    await beforeCommit({ site: 'state-clear.primary', kind: 'unlink', path });
                     await unlink(path);
                 }
                 const nativeStopCleared = effectiveSessionId
-                    ? await clearSessionNativeStopState(baseStateDir, effectiveSessionId)
+                    ? await clearSessionNativeStopState(baseStateDir, effectiveSessionId, beforeCommit)
                     : [];
                 if (mode !== SKILL_ACTIVE_STATE_MODE) {
                     await syncCanonicalSkillStateForMode({
@@ -865,6 +823,7 @@ export async function executeStateOperation(name, rawArgs = {}) {
                         active: false,
                         sessionId: effectiveSessionId,
                         source: 'state-operations',
+                        beforeCommit,
                     });
                 }
                 return { payload: { cleared: true, mode, path, ...(nativeStopCleared.length > 0 ? { native_stop_cleared: nativeStopCleared } : {}) } };