openplanr 1.16.2 → 1.18.0

package/dist/services/operate/index.js

@@ -1,14 +1,17 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { resolveAIProviderReadiness } from '../ai-service.js';
+import { loadConfig } from '../config-service.js';
+import { computeNextDueAt } from './cadence.js';
 import { canonicalDigest, sha256Digest } from './canonical.js';
-import { applyOperatingInitialization, getOperatingProfile, listOperatingProfiles, normalizeCustomOperatingProfile, normalizeOperatingInitializationAnswers, prepareOperatingInitialization, validateOperatingConfiguration, } from './config.js';
+import { applyOperatingInitialization, getOperatingProfile, listOperatingProfiles, normalizeCustomOperatingProfile, normalizeOperatingInitializationAnswers, parseOperatingDispatchModeOverrideFlags, prepareOperatingInitialization, readOperatingLastRunAt, validateOperatingConfiguration, } from './config.js';
 import { runOperatingCycle } from './engine.js';
 import { OperatingEventStore } from './event-store.js';
 import { classifyEvidenceDiagnostic } from './evidence-classifications.js';
 import { listEvidenceDiagnostics, readEvidenceDiagnostic } from './evidence-diagnostics.js';
 import { parseStrictJson, readImportedEvidenceFile } from './evidence-import.js';
 import { createOperatingAction } from './interaction/action-service.js';
-import { persistableOperatingInitAnswers, resumeGuidedSession, submitGuidedAnswers, } from './interaction/answer-service.js';
+import { persistableOperatingInitAnswers, probeAvailableEvidenceSources, probeGitUserName, probePipelineInstalled, resumeGuidedSession, submitGuidedAnswers, } from './interaction/answer-service.js';
 import { assertOperatingConfirmation } from './interaction/confirmation-service.js';
 import { decodeOperatingInitializationReplay, encodeOperatingInitializationReplay, } from './interaction/initialization-replay.js';
 import { createOperatingInitQuestionnaire, evaluateOperatingInitQuestions, operatingInitAnswersFromOptions, } from './interaction/question-engine.js';
@@ -16,7 +19,8 @@ import { cancelGuidedSession, createGuidedSession, createGuidedSessionId, curren
 import { assertCommittedOperatingView } from './journal.js';
 import { applyOperatingMigration, inspectOperatingMigration, rollbackOperatingMigration, } from './legacy-import-service.js';
 import { answerOperatingGap, applyOrRollbackRoute, decideOperatingDecision, governOperatingFinding, readOperatingCollection, readOperatingReview, transitionOperatingCycle, verifyOperatingGap, } from './lifecycle.js';
-import { createOperatingAdapterStartHandoff, exportOperatingDiagnostics, operateAdapterLifecycle, operatingCacheAction, operatingIntegrityAction, repairOperatingSecurity, } from './maintenance.js';
+import { createOperatingAdapterStartHandoff, exportOperatingDiagnostics, operateAdapterLifecycle, operatingCacheAction, operatingIntegrityAction, purgeBoardMachineLocalCaches, repairOperatingSecurity, } from './maintenance.js';
+import { migrateOperatingStorageLayoutOnOpen } from './migration.js';
 import { renderOperatingBrief } from './projection.js';
 import { loadOperatingProtocol, resolveOperatingPipelineRoot } from './protocol.js';
 import { executeGitHubReadOnly, executeGitReadOnly } from './read-only-providers.js';
@@ -48,17 +52,43 @@ function stringList(value) {
             .filter(Boolean);
     return [];
 }
+/**
+ * Probe the coding-runtime identity of the host process from the environment
+ * markers set by the agent that launched the CLI. Mirrors the compatible-runtime
+ * detection in terminal-renderer.ts's `detectOperatingQuestionContext`, but keys
+ * off the launcher's env markers so a non-interactive/JSON invocation can stamp a
+ * truthful adapter block and resolve `auto` instead of stamping `unknown`/`none`
+ * or silently disabling native dispatch.
+ */
+function detectOperatingHostRuntime() {
+    const env = process.env;
+    const marker = (value) => (value ?? '').length > 0;
+    if (marker(env.CLAUDECODE) || marker(env.CLAUDE_CODE_ENTRYPOINT))
+        return 'claude';
+    if (marker(env.CURSOR_TRACE_ID) || marker(env.CURSOR_AGENT))
+        return 'cursor';
+    if (marker(env.CODEX_SANDBOX) || marker(env.CODEX_HOME))
+        return 'codex';
+    return undefined;
+}
 async function resolvedOperatingRuntime(projectRoot, requested) {
     if (requested !== 'auto')
         return requested;
-    return readFile(path.join(resolveOperatingPaths(projectRoot).localRoot, 'preferences.json'), 'utf8')
+    const persisted = await readFile(path.join(resolveOperatingPaths(projectRoot).localRoot, 'preferences.json'), 'utf8')
         .then((raw) => {
         const runtime = JSON.parse(raw).runtime;
         return typeof runtime === 'string' && runtime ? runtime : 'auto';
     })
         .catch(() => 'auto');
+    if (persisted !== 'auto')
+        return persisted;
+    // A persisted (or absent) `auto` preference must never silently disable native
+    // dispatch inside a capable host: resolve it to the detected runtime identity
+    // so `usesNativeOperatingAdvisors` evaluates the real host, not the `auto`
+    // placeholder that always returns false.
+    return detectOperatingHostRuntime() ?? 'auto';
 }
-async function usesNativeOperatingAdvisors(projectRoot, requestedRuntime) {
+export async function usesNativeOperatingAdvisors(projectRoot, requestedRuntime) {
     const runtime = await resolvedOperatingRuntime(projectRoot, requestedRuntime);
     const adapterId = runtime === 'claude' ? 'claude-code' : runtime;
     if (adapterId === 'auto')
@@ -72,7 +102,10 @@ async function usesNativeOperatingAdvisors(projectRoot, requestedRuntime) {
     const adapter = registry.adapters?.find((entry) => entry.id === adapterId);
     if (adapter?.capabilities?.operatingBoard !== true)
         return false;
-    if (['native-isolated', 'native-bounded'].includes(adapter.capabilities.operatingAdvisorDispatch ?? '')) {
+    if (
+    // `native-read-only` is the US-001/T-001 adapters-registry capability name that
+    // supersedes the earlier isolation labels; recognize it alongside them.
+    ['native-isolated', 'native-bounded', 'native-read-only'].includes(adapter.capabilities.operatingAdvisorDispatch ?? '')) {
         return true;
     }
     // Compatibility with Protocol v1.2 registries published before the
@@ -121,6 +154,47 @@ function success(action, value = {}) {
         nextActions,
     };
 }
+/**
+ * A healthy continuation (FR7/E-007): a guided-stage advance
+ * (`E_OPERATE_INPUT_REQUIRED`) or first-use provider consent
+ * (`E_OPERATE_AUTHORITY_REQUIRED`) is not a failure. It is returned as an
+ * `ok: true` handoff carrying a machine-readable `flow: 'handoff'` discriminator
+ * (and the originating `code`), mirroring `run`'s adapter-handoff shape so a
+ * harness reads the pause without treating it as a red exit. No `exitCode` is
+ * set: the CLI leaves the process exit code at 0 for `ok: true` results.
+ */
+function handoffContinuation(action, code, value = {}) {
+    return { ...success(action, value), code, flow: 'handoff' };
+}
+/**
+ * First-use / renewal provider consent is disclosed by
+ * `ensureOperatingProviderConsent` (advisors.ts) as an
+ * `E_OPERATE_AUTHORITY_REQUIRED` carrying the full policy disclosure
+ * (`endpoint`, `permittedDataClasses`, `policyDigest`). That specific
+ * disclosure is a continuation, not a refusal — unlike every other
+ * `E_OPERATE_AUTHORITY_REQUIRED` (a mutation attempted without `--yes`), which
+ * stays an `ok: false` exit-4 failure so the authority model is unchanged.
+ */
+function isProviderConsentHandoff(error) {
+    if (!(error instanceof OperateError) || error.code !== 'E_OPERATE_AUTHORITY_REQUIRED') {
+        return false;
+    }
+    const details = error.details;
+    return (typeof details === 'object' &&
+        details !== null &&
+        'policyDigest' in details &&
+        'endpoint' in details &&
+        'permittedDataClasses' in details);
+}
+function providerConsentContinuation(action, error) {
+    const retry = `planr operate ${action} --yes`;
+    return handoffContinuation(action, 'E_OPERATE_AUTHORITY_REQUIRED', {
+        message: error.message,
+        data: error.details,
+        nextActions: [retry],
+        next: [retry],
+    });
+}
 /**
  * Stable process exit classes for automation.
  *
@@ -133,6 +207,15 @@ function success(action, value = {}) {
  *
  * Keep this exhaustive so adding a public Operate error cannot silently fall
  * through to the internal-error class.
+ *
+ * FR7/E-007 continuation note: `E_OPERATE_INPUT_REQUIRED` and
+ * `E_OPERATE_AUTHORITY_REQUIRED` keep this class-4 mapping for the cases that
+ * are genuine refusals — a mutation attempted without `--yes` still fails with
+ * `ok: false` and exit 4. But a *healthy continuation* — a guided-stage advance
+ * or first-use provider consent — is not a failure: it is returned as an
+ * `ok: true` handoff (`flow: 'handoff'`) with no failure exit code, mirroring
+ * `run`'s adapter handoff, so a harness never paints the happy path red. The
+ * numeric class below is therefore only consulted for the failure branch.
  */
 const OPERATE_EXIT_CODES = {
     E_OPERATE_INTERNAL: 1,
@@ -178,13 +261,23 @@ const OPERATE_EXIT_CODES = {
     E_OPERATE_EVIDENCE_REJECTED: 6,
     E_OPERATE_PROVIDER_READ_ONLY: 6,
     E_OPERATE_SECRET_DETECTED: 6,
+    E_OPERATE_MISSION_PACKET_BUDGET: 6,
+    E_OPERATE_MISSION_UNAVAILABLE: 3,
     E_OPERATE_SESSION_INVALID: 2,
 };
 function operateExitCode(code) {
     return OPERATE_EXIT_CODES[code];
 }
-function failure(action, error) {
+export function failure(action, error) {
     const code = error instanceof OperateError ? error.code : 'E_OPERATE_INTERNAL';
+    // E_OPERATE_INTERNAL must never be zero-information: record the redacted error
+    // class/name (no message or stack, which can carry paths or secrets) so the
+    // diagnostics export and automation callers can classify the internal failure.
+    const internalErrorClass = code === 'E_OPERATE_INTERNAL'
+        ? error instanceof Error && typeof error.name === 'string' && error.name.length > 0
+            ? error.name
+            : 'Error'
+        : undefined;
     const confirmationAction = error instanceof OperateError &&
         error.details?.action &&
         typeof error.details.action === 'object' &&
@@ -244,11 +337,29 @@ function failure(action, error) {
         counts: {},
         warnings: [],
         nextActions,
-        data: error instanceof OperateError ? error.details : undefined,
+        data: error instanceof OperateError
+            ? error.details
+            : internalErrorClass
+                ? { errorClass: internalErrorClass }
+                : undefined,
         next: nextActions,
         exitCode: operateExitCode(code),
     };
 }
+/**
+ * Reduce recovery `nextActions` to the set of public `planr operate` commands
+ * that back the structured actions. The digest-bound authority flags
+ * (`--yes`, `--confirm <digest>`, `--preview-digest <digest>`) are stripped from
+ * the *command* string — a raw sha256 digest must never enter a structured
+ * command (it would trip the sensitive-data guard in `assertSafeCommand`).
+ *
+ * FR8/E-008: stripping them here no longer strands a runner. For a
+ * digest-confirmable command the exact, ready-to-run argv (including the real
+ * `--confirm <digest> --yes` token) is re-surfaced on the structured action as
+ * `confirmArgv` in `attachStructuredActions`, so the runner never has to
+ * re-synthesize a confirmation token it was handed. A command whose only
+ * authority is `--yes` is never given a confirmationDigest at all.
+ */
 function publicActionCommands(nextActions) {
     return [
         ...new Set(nextActions
@@ -261,6 +372,17 @@ function publicActionCommands(nextActions) {
             .filter((value) => /^planr\s+/.test(value))),
     ];
 }
+/**
+ * The digest-bound confirmation flag a public command's CLI actually accepts, or
+ * `null` when its only authority is `--yes`. A confirmationDigest is meaningful
+ * only for a command that can consume it via `--confirm`; a `--yes`-only command
+ * (e.g. `operate run`) must never be handed one (FR8/E-008).
+ */
+function commandConfirmFlag(command) {
+    return /\boperate\s+init\b/.test(command) || /\bevidence\s+classify\b/.test(command)
+        ? '--confirm'
+        : null;
+}
 function hasFlag(command, flag) {
     return new RegExp(`(?:^|\\s)${flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\s|$)`).test(command);
 }
@@ -296,8 +418,9 @@ async function actionEffect(request, command) {
     return 'project-write';
 }
 async function attachStructuredActions(request, result) {
-    if (result.actions?.length || result.action === 'input_required')
+    if (result.actions?.length || result.action === 'input_required' || result.flow === 'handoff') {
         return result;
+    }
     const commands = publicActionCommands(result.nextActions);
     if (commands.length === 0)
         return result;
@@ -323,6 +446,7 @@ async function attachStructuredActions(request, result) {
     const actions = [];
     for (const [index, command] of commands.entries()) {
         const effect = await actionEffect(request, command);
+        const confirmFlag = commandConfirmFlag(command);
         const id = `operate.next.${canonicalDigest({ command }).slice('sha256:'.length, 'sha256:'.length + 20)}`.toLowerCase();
         const created = await createOperatingAction({
             id,
@@ -352,8 +476,29 @@ async function attachStructuredActions(request, result) {
                     },
                 }),
         });
-        actions.push(created.action);
+        let action = created.action;
+        // FR8/E-008: `operate run` authorizes with `--yes` alone — its CLI accepts no
+        // `--confirm` flag — so it must never carry a confirmationDigest a runner
+        // could never pass. It still appears as a structured action (mirroring the
+        // handoff `run` continuation) but with its digest binding cleared.
+        if (/\boperate\s+run\b/.test(command)) {
+            action = {
+                ...action,
+                requiresConfirmation: false,
+                confirmationScope: null,
+                confirmationDigest: null,
+            };
+        }
+        // A digest-confirmable action (`--confirm <digest>`) carries its exact,
+        // ready-to-run argv so a runner never has to re-synthesize the confirmation
+        // token it was already handed.
+        const confirmArgv = confirmFlag && action.confirmationDigest
+            ? [...command.split(/\s+/), confirmFlag, action.confirmationDigest, '--yes']
+            : undefined;
+        actions.push(confirmArgv ? { ...action, confirmArgv } : action);
     }
+    if (actions.length === 0)
+        return result;
     return { ...result, actions };
 }
 async function inspect(request) {
@@ -559,22 +704,14 @@ async function initialize(request) {
                 });
         supplied = normalizeOperatingInitializationAnswers(resumedSession.answers);
         if (resumedSession.status === 'input-required') {
-            return {
-                schemaVersion: '1.0.0',
-                protocolVersion: '1.2.0',
-                ok: false,
-                action: 'input_required',
-                code: 'E_OPERATE_INPUT_REQUIRED',
+            // FR7/E-007: a guided-stage advance is a healthy continuation, not a
+            // failure. Report it as an `ok: true` handoff (`flow: 'handoff'`) carrying
+            // the next questionnaire, mirroring `run`'s adapter handoff.
+            return handoffContinuation('input_required', 'E_OPERATE_INPUT_REQUIRED', {
                 message: 'Operating Board initialization needs explicit human input.',
                 state: resumedSession.session.state,
-                paths: {},
-                counts: {},
-                warnings: [],
-                nextActions: [],
-                next: [],
                 questionnaire: resumedSession.questionnaire,
-                exitCode: operateExitCode('E_OPERATE_INPUT_REQUIRED'),
-            };
+            });
         }
     }
     let customProfile;
@@ -586,13 +723,36 @@ async function initialize(request) {
         supplied.profileFile) {
         throw new OperateError('E_OPERATE_CONFIG_INVALID', '--profile-file is valid only with --profile custom.');
     }
+    // Probe the real host runtime instead of stamping `unknown`/`none`: an explicit
+    // --runtime flag wins, otherwise the launcher's env markers name the host so the
+    // questionnaire's adapter block is truthful (and the runtime question can be a
+    // detect-don't-ask suggestion rather than a required prompt).
+    const detectedHostRuntime = detectOperatingHostRuntime();
+    const requestedRuntimeOption = option(request, 'runtime', 'auto');
+    // Probe the same signals the terminal path does so the JSON/native init path is
+    // equally truthful: the decision-owner suggestion reaches this path (gitUserName),
+    // the "locally available" source claim is real (availableSources), and the
+    // planning-engine detects pipeline-po when a compatible pipeline is installed.
+    const [gitUserName, availableSources] = await Promise.all([
+        probeGitUserName(request.projectRoot),
+        probeAvailableEvidenceSources(request.projectRoot),
+    ]);
     const context = {
         projectRoot: request.projectRoot,
         ...bindings,
+        ...(detectedHostRuntime ? { detectedRuntime: detectedHostRuntime } : {}),
+        ...(gitUserName ? { gitUserName } : {}),
         timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-        availableSources: ['repository', 'planr', 'git', 'file-import'],
-        runtime: option(request, 'runtime', 'unknown'),
-        interaction: request.interactive ? 'terminal' : 'none',
+        availableSources,
+        pipelineInstalled: probePipelineInstalled(),
+        runtime: requestedRuntimeOption && requestedRuntimeOption !== 'auto'
+            ? requestedRuntimeOption
+            : (detectedHostRuntime ?? (request.interactive ? 'terminal' : 'unknown')),
+        interaction: detectedHostRuntime
+            ? 'native'
+            : request.interactive
+                ? 'terminal'
+                : 'none',
     };
     const questionState = await evaluateOperatingInitQuestions({
         answers: supplied,
@@ -613,28 +773,24 @@ async function initialize(request) {
             persistedAnswers: persistableOperatingInitAnswers(questionState.answers, context),
             localRoot,
         });
-        return {
-            schemaVersion: '1.0.0',
-            protocolVersion: '1.2.0',
-            ok: false,
-            action: 'input_required',
-            code: 'E_OPERATE_INPUT_REQUIRED',
-            message: 'Operating Board initialization needs explicit human input.',
-            state: null,
-            paths: {},
-            counts: {},
-            warnings: [],
-            nextActions: [],
-            next: [],
+        // FR7/E-007: the first guided-stage prompt is a healthy continuation — an
+        // `ok: true` handoff (`flow: 'handoff'`) carrying the questionnaire, not an
+        // exit-4 failure.
+        return handoffContinuation('input_required', 'E_OPERATE_INPUT_REQUIRED', {
             questionnaire,
-            exitCode: operateExitCode('E_OPERATE_INPUT_REQUIRED'),
-        };
+        });
     }
     const profile = supplied.profile;
     const decisionOwner = supplied.decisionOwner ?? option(request, 'decisionOwner', '').trim();
     const planningEngine = supplied.planningEngine ??
         option(request, 'planningEngine', 'openplanr');
     const rawCharter = supplied.charter ?? option(request, 'charter', {});
+    // FR4 / E-004 fold-in: forward the CLI-validated per-project dispatch-mode
+    // overrides into initialization so they are part of the committed machine-local
+    // preferences (and thus the preview digest), rather than a separate post-apply
+    // patch. Omitted entirely when no override flag was supplied, keeping the
+    // no-override preview digest byte-identical.
+    const dispatchModeOverrides = parseOperatingDispatchModeOverrideFlags(stringList(request.options.dispatchModeOverride));
     const preview = await prepareOperatingInitialization({
         projectRoot: request.projectRoot,
         profile,
@@ -642,6 +798,7 @@ async function initialize(request) {
         planningEngine,
         runtime: supplied.runtime ?? option(request, 'runtime', 'auto'),
         cadence: supplied.cadence ?? option(request, 'cadence', 'manual'),
+        ...(Object.keys(dispatchModeOverrides).length > 0 ? { dispatchModeOverrides } : {}),
         timezone: supplied.timezone ??
             option(request, 'timezone', Intl.DateTimeFormat().resolvedOptions().timeZone),
         sensitivityCeiling: supplied.sensitivityCeiling ?? option(request, 'sensitivityCeiling', 'internal'),
@@ -744,6 +901,11 @@ async function initialize(request) {
         preview,
         confirmationDigest: preview.previewDigest,
     });
+    // FR4: a committed init apply is a fresh (re-genesised) board. Purge the
+    // machine-local advisor sessions and incremental evidence baselines a prior
+    // generation left at this path so the new board never inherits a stale
+    // session or a baseline bound to a superseded workspace/board identity.
+    await purgeBoardMachineLocalCaches({ projectRoot: request.projectRoot, localRoot });
     if (resumedSession) {
         const appliedAt = new Date().toISOString();
         await updateGuidedSession({
@@ -935,16 +1097,24 @@ async function testOperatingSource(request, provider) {
     return { provider, healthy: true, observation, writeBoundary: 'none' };
 }
 async function status(request) {
-    await validateOperatingConfiguration(request.projectRoot);
-    await assertCommittedOperatingView(request.projectRoot);
-    const store = new OperatingEventStore(request.projectRoot);
+    const config = await validateOperatingConfiguration(request.projectRoot);
+    const localRoot = option(request, 'localRoot', undefined);
+    await assertCommittedOperatingView(request.projectRoot, localRoot ? { localRoot } : {});
+    const store = new OperatingEventStore(request.projectRoot, localRoot ? { localRoot } : {});
     const state = await store.state();
     const activeCycle = [...state.cycles]
         .filter((cycle) => !['closed', 'cancelled'].includes(cycle.state))
         .sort((left, right) => left.id.localeCompare(right.id))
         .at(-1);
+    // FR8 / E-008: surface `nextDueAt` via the pipeline's pure calculator with an
+    // INJECTED clock. This CLI boundary supplies `now` (an explicit option or the
+    // wall clock); the calculator itself reads no `Date.now()`. `manual` → null;
+    // `weekly` / `monthly` → the computed due date from the persisted `lastRunAt`.
+    const now = option(request, 'now', undefined) ?? new Date().toISOString();
+    const lastRunAt = await readOperatingLastRunAt(request.projectRoot, localRoot ? { localRoot } : {});
+    const nextDueAt = await computeNextDueAt(config.cadence, lastRunAt, now);
     return success(request.action, {
-        data: state,
+        data: { ...state, cadence: { mode: config.cadence, lastRunAt, nextDueAt } },
         message: activeCycle?.state === 'blocked'
             ? `Operating Board is blocked on ${state.summary.openGaps} evidence or advisor readiness gap(s).`
             : state.summary.quiet
@@ -961,6 +1131,27 @@ async function run(request) {
         !option(request, 'dryRun', false) &&
         !option(request, 'reviewOnly', false) &&
         nativeAdvisors;
+    // Preflight the structured-provider key on a non-offline, non-native preview so
+    // `run --preview` names a missing key before any cycle starts, rather than
+    // surfacing it only when a real cycle reaches the provider path. Native and
+    // offline runs never need the structured key, so they skip the check.
+    const previewProviderWarnings = [];
+    if (option(request, 'preview', false) &&
+        !option(request, 'offline', false) &&
+        !option(request, 'reviewOnly', false) &&
+        !nativeAdvisors) {
+        const openPlanrConfig = await loadConfig(request.projectRoot).catch(() => null);
+        const readiness = openPlanrConfig
+            ? await resolveAIProviderReadiness(openPlanrConfig)
+            : {
+                configured: false,
+                keyResolvable: false,
+                remedy: 'No AI provider is configured. Run `planr config set-provider <name>` then `planr config set-key <provider>`, or run offline with --offline.',
+            };
+        if (!readiness.keyResolvable && readiness.remedy) {
+            previewProviderWarnings.push(readiness.remedy);
+        }
+    }
     const result = await runOperatingCycle({
         projectRoot: request.projectRoot,
         cycleId: option(request, 'cycleId', undefined),
@@ -1022,7 +1213,13 @@ async function run(request) {
         },
         counts,
         handoff,
-        warnings: [...new Set([...(result.cycle.warnings ?? []), ...stringList(projected?.warnings)])],
+        warnings: [
+            ...new Set([
+                ...(result.cycle.warnings ?? []),
+                ...stringList(projected?.warnings),
+                ...previewProviderWarnings,
+            ]),
+        ],
         nextActions,
         data: result,
         next: nextActions,
@@ -1030,10 +1227,16 @@ async function run(request) {
 }
 async function reviewOrBrief(request) {
     const cycleId = argument(request, 'cycleId');
+    // FR3/E-003: the human review gate renders report Markdown (brief + per-role
+    // lens reports + exact next actions), never a raw `JSON.stringify` of the
+    // state. `--json` keeps returning the exact raw state object, byte-unchanged.
+    const human = request.action === 'review' && !option(request, 'json', false);
     const data = await readOperatingReview({
         projectRoot: request.projectRoot,
         cycleId,
         brief: request.action === 'brief',
+        human,
+        localRoot: option(request, 'localRoot', undefined),
     });
     return success(request.action, {
         data,
@@ -1388,6 +1591,47 @@ const HANDLERS = {
     'adapter.finalize': maintenance,
     'adapter.cancel': maintenance,
 };
+/**
+ * Actions that only read committed state. A SPEC-002-layout project stays
+ * readable through these without being migrated; only a mutating action opening
+ * such a project triggers the automatic, journal-safe v1.3 migration (FR5/E-005).
+ */
+const OPERATE_READ_ONLY_ACTIONS = new Set([
+    'inspect',
+    'demo',
+    'config.show',
+    'config.validate',
+    'config.edit',
+    'profiles.list',
+    'profiles.show',
+    'profiles.validate',
+    'sources.list',
+    'sources.show',
+    'sources.test',
+    'status',
+    'review',
+    'brief',
+    'report',
+    'cycles.list',
+    'cycles.show',
+    'findings.list',
+    'findings.show',
+    'routes.list',
+    'routes.show',
+    'decisions.list',
+    'decisions.show',
+    'gaps.list',
+    'gaps.show',
+    'evidence.list',
+    'evidence.show',
+    'evidence.diagnose',
+    'migrate.inspect',
+    'migrations.list',
+    'migrations.show',
+    'cache.status',
+    'integrity.status',
+    'adapter.resume',
+]);
 /**
  * Stable runtime-neutral Operating Board facade. Public CLI adapters only parse
  * arguments and render this structured result; all state and security semantics
@@ -1399,9 +1643,28 @@ export async function executeOperateAction(request) {
         if (!handler) {
             throw new OperateError('E_OPERATE_ACTION_UNKNOWN', `Unknown Operating Board action: ${request.action}.`);
         }
+        // Any mutating action that opens a SPEC-002-layout project migrates it to the
+        // v1.3 storage layout, through the write-ahead journal, before proceeding.
+        if (!OPERATE_READ_ONLY_ACTIONS.has(request.action)) {
+            await migrateOperatingStorageLayoutOnOpen(request.projectRoot, {
+                localRoot: option(request, 'localRoot', undefined),
+            });
+        }
         return await attachStructuredActions(request, await handler(request));
     }
     catch (error) {
+        // FR7/E-007: first-use provider consent is a healthy continuation, not a
+        // failure — return the `ok: true` handoff shape instead of an exit-4 error.
+        // Every other authority/error stays a genuine failure.
+        if (isProviderConsentHandoff(error)) {
+            const continuation = providerConsentContinuation(request.action, error);
+            try {
+                return await attachStructuredActions(request, continuation);
+            }
+            catch {
+                return continuation;
+            }
+        }
         try {
             return await attachStructuredActions(request, failure(request.action, error));
         }