sneakoscope 7.0.2 → 7.0.3

package/dist/core/feature-fixture-executor.js

@@ -4,25 +4,10 @@ import { spawnSync } from 'node:child_process';
 import { resolveExpectedArtifactPath } from './feature-fixture-runner.js';
 import { findLatestMission } from './mission.js';
 const FIXTURE_COMMAND_TIMEOUT_MS = 60_000;
-/** Per-fixture override, set via the fixture()'s `extra.timeout_ms` for commands
- * that are legitimately slower than the 60s default (real agent/runtime orchestration,
- * multi-step pipelines) rather than actually hung. */
 function fixtureTimeoutMs(fixture) {
     const override = Number(fixture?.timeout_ms);
     return Number.isFinite(override) && override > 0 ? override : FIXTURE_COMMAND_TIMEOUT_MS;
 }
-/**
- * Actually spawns a feature fixture's declared `command` string (safely tokenized,
- * no shell interpolation) for `execute` / `execute_and_validate_artifacts` fixtures,
- * checks the real exit code, validates any expected_artifacts that were declared
- * (string path or { path, schema } object form), and derives a real pass/fail status
- * from what actually happened rather than trusting fixture.status.
- *
- * This is distinct from runFeatureFixture() in feature-fixture-runner.ts, which only
- * executes fixtures present in an explicit safe-args allowlist. This function executes
- * whatever the fixture itself declares as its command, so it must tokenize defensively
- * and never hand a raw string to a shell.
- */
 export async function runFeatureFixture(feature, { root = process.cwd() } = {}) {
     const id = feature?.id || feature?.featureId || 'unknown';
     const fixture = feature?.fixture || feature || {};
@@ -75,14 +60,6 @@ export async function runFeatureFixture(feature, { root = process.cwd() } = {})
     });
     const timedOut = spawnResult.error?.code === 'ETIMEDOUT';
     const exitOk = !timedOut && spawnResult.status === 0;
-    // Most fixture commands create a fresh, uniquely-IDed mission and write their
-    // expected artifacts (completion-proof.json, <route>-gate.json, ...) inside that
-    // mission's own directory, not at the project root. Without a mission id,
-    // resolveExpectedArtifactPath() falls back to root-relative resolution and every
-    // such artifact is reported "missing" even when the command succeeded. Prefer the
-    // mission id the command itself printed in its --json stdout (unambiguous, immune
-    // to races with unrelated concurrent sessions on a shared machine); only fall back
-    // to a filesystem mtime scan if the command's own output didn't carry one.
     const missionIdFromOutput = extractMissionId(spawnResult.stdout);
     const latestMissionId = missionIdFromOutput
         ?? (kind === 'execute_and_validate_artifacts' ? await findLatestMission(root).catch(() => null) : null);
@@ -99,16 +76,6 @@ export async function runFeatureFixture(feature, { root = process.cwd() } = {})
     blockers.push(...artifactFailures);
     const ok = blockers.length === 0;
     const actualStatus = ok ? 'pass' : 'blocked';
-    // "ok" (the ultimate pass/fail signal selftest --real counts) must mean "the
-    // registry's claimed status matches reality" - NOT "the underlying command exited
-    // 0" - those are different questions. Several fixtures intentionally run a
-    // command that always exits non-zero by design (an honest mock/blocked
-    // demonstration, per the execution_class:'mock_fixture' hardening elsewhere in
-    // this codebase); such a fixture correctly declaring claimed_status:'blocked' is
-    // a PASSING self-consistency check, not a failure, even though blockers still
-    // faithfully records the real command_exit_N/artifact issues for anyone auditing
-    // what actually happened. Only an actual mismatch between claim and reality is a
-    // real fixture-registry defect worth failing selftest --real over.
     const statusMatches = !claimedStatus || claimedStatus === actualStatus;
     if (!statusMatches) {
         blockers.push(`${id}:fixture_status_claim_mismatch:claimed=${claimedStatus}:actual=${actualStatus}`);
@@ -141,13 +108,6 @@ export async function runFeatureFixture(feature, { root = process.cwd() } = {})
         resolved_mission_id: latestMissionId
     };
 }
-/**
- * Pulls a mission id out of a command's JSON stdout. Handles the common field
- * names/shapes used across sks commands (`mission_id`, `missionId`, a top-level
- * `id` that matches the `M-<timestamp>-<suffix>` pattern, or a nested `mission.id`),
- * and tolerates stdout that has trailing non-JSON log lines by scanning for the
- * last parseable JSON object.
- */
 function extractMissionId(stdout) {
     if (!stdout)
         return null;
@@ -160,15 +120,12 @@ function extractMissionId(stdout) {
             candidates.push(JSON.parse(trimmed));
         }
         catch {
-            // not a standalone JSON line; the payload may still be a multi-line pretty-printed
-            // object, handled by the whole-stdout attempt below.
         }
     }
     try {
         candidates.push(JSON.parse(stdout));
     }
     catch {
-        // pretty-printed JSON mixed with other stdout; ignore.
     }
     const missionIdPattern = /^M-\d{8}-\d{6}-[a-z0-9]+$/i;
     for (const parsed of candidates.reverse()) {
@@ -282,11 +239,6 @@ function resolveSksEntrypoint(root) {
     const found = candidates.find((candidate) => fs.existsSync(candidate));
     return found ?? candidates[0] ?? path.resolve('dist', 'bin', 'sks.js');
 }
-/**
- * Minimal, defensive command-line tokenizer: splits on whitespace while respecting
- * single and double quotes. Never passed to a shell — used purely to build a spawnSync
- * argv array, so shell metacharacters inside tokens are inert.
- */
 export function tokenizeCommand(command) {
     const tokens = [];
     let current = '';

package/dist/core/feature-fixtures.js

@@ -51,11 +51,6 @@ const FIXTURES = Object.freeze({
     'cli-versioning': fixture('execute', 'sks versioning status --json', [], 'pass'),
     'cli-aliases': fixture('execute', 'sks aliases', [], 'pass'),
     'cli-fix-path': fixture('execute', 'sks fix-path --json', [], 'pass'),
-    // selftest --real executes this fixture directly against this real repo (no
-    // hermetic isolation for execute/execute_and_validate_artifacts fixtures - see
-    // feature-fixture-executor.ts), so a real full scan (~79 modules) needs a
-    // realistic budget; the 8000 default is sized for smaller/typical repos, not
-    // this one, so pass an explicit larger budget rather than lowering the gate.
     'cli-wiki-code': fixture('execute_and_validate_artifacts', 'sks wiki refresh --code --token-budget 20000 --json', [{ path: '.sneakoscope/wiki/code-pack.json', schema: 'sks.code-pack.v1', optional: true }], 'pass'),
     'cli-agent-bridge': fixture('execute_and_validate_artifacts', 'sks agent-bridge setup --json', [{ path: '.sneakoscope/agent-bridge/manifest.json', schema: 'sks.agent-manifest.v1', optional: true }], 'pass'),
     'cli-mcp-server': fixture('execute', 'sks mcp-server --probe', [], 'pass'),

package/dist/core/fsx.js

@@ -61,6 +61,17 @@ export async function exists(p) {
         return false;
     }
 }
+export async function canonicalFilesystemPath(p) {
+    const resolved = path.resolve(p);
+    return fsp.realpath(resolved).catch(() => resolved);
+}
+export async function sameFilesystemPath(left, right) {
+    const [leftCanonical, rightCanonical] = await Promise.all([
+        canonicalFilesystemPath(left),
+        canonicalFilesystemPath(right)
+    ]);
+    return leftCanonical === rightCanonical;
+}
 export async function ensureDir(p) {
     await fsp.mkdir(p, { recursive: true });
 }
@@ -85,8 +96,6 @@ export async function writeTextAtomic(p, text, opts = {}) {
                 await fsp.chmod(p, opts.mode & 0o777);
                 return;
             }
-            // Replace symlink or non-regular targets atomically below. Never chmod
-            // through a link merely because its current contents happen to match.
         }
     }
     catch { }
@@ -125,14 +134,6 @@ export async function writeTextAtomic(p, text, opts = {}) {
         }
     }
 }
-// A non-atomic direct write is only justified when the atomic rename itself
-// is physically impossible (EXDEV: tmp and target span different devices,
-// e.g. an unusual bind-mount) — the rename already fsync'd the tmp file's
-// contents, so a direct write there just relocates already-durable bytes.
-// The other codes previously here (EACCES/EEXIST/ENOENT/ENOTEMPTY/EPERM)
-// have nothing to do with cross-device limits and used to quietly downgrade
-// every one of those failures to a non-atomic write, risking a partially
-// written file on crash (20차 P1-6) — they now propagate instead.
 function canFallbackToDirectWrite(err) {
     return errorCode(err) === 'EXDEV';
 }
@@ -469,8 +470,6 @@ function installProcessGroupLifecycleHandlers() {
         return;
     processGroupLifecycleHandlersInstalled = true;
     process.on('exit', terminateRegisteredProcessGroups);
-    // Run before existing once listeners remove themselves so rawListeners still
-    // reflects whether Node's default signal termination was already suppressed.
     process.prependListener('SIGHUP', handleParentSighup);
     process.prependListener('SIGINT', handleParentSigint);
     process.prependListener('SIGTERM', handleParentSigterm);

package/dist/core/hooks-runtime/code-pack-freshness-preflight.js

@@ -1,9 +1,6 @@
 import path from 'node:path';
 import { exists, readJson } from '../fsx.js';
 import { inspectCodePackHeadFreshness } from '../triwiki/code-pack-head-freshness.js';
-/** Returns a bounded, non-blocking stale-code-pack note for user-prompt-submit.
- * It stays silent when no pack exists or freshness is inconclusive, never regenerates
- * the pack, and treats metadata-only follow-up commits as fresh. */
 export async function codePackFreshnessNote(root, opts = {}) {
     const budgetMs = Math.max(1, opts.budgetMs ?? 750);
     const gitTimeoutMs = Math.max(1, budgetMs - 50);
@@ -15,8 +12,6 @@ async function computeNote(root, gitTimeoutMs) {
         return null;
     const pack = await readJson(packPath, null).catch(() => null);
     const packSha = pack?.git_head_sha || null;
-    // A pack with no recorded sha (non-git build) can't be compared; stay silent
-    // rather than nag with a comparison we can't actually make.
     if (!packSha)
         return null;
     const freshness = await inspectCodePackHeadFreshness(root, packSha, {

package/dist/core/hooks-runtime/hook-context.js

@@ -0,0 +1,202 @@
+import path from 'node:path';
+import { readJson } from '../fsx.js';
+import { missionDir, validateExternallyReservedMissionId } from '../mission.js';
+import { routePrompt } from '../pipeline.js';
+import { allowlistedManagedRouteSkillNames, dollarCommand, INVALID_EXPLICIT_MANAGED_SKILL_NAME, managedSkillNamesForPrompt, routeRequiresSubagents, stripVisibleDecisionAnswerBlocks } from '../routes.js';
+import { inspectConfinedPath } from '../managed-path-safety.js';
+import { renderAuthoritativeSksSkillContext, resolveAuthoritativeSksSkillSources } from '../codex-native/sks-skill-paths.js';
+import { looksLikeActiveContinuationPrompt } from './naruto-decision-gate.js';
+import { extractUserPrompt, looksLikeCodexGitAction, looksLikeCodexUiSettingsEvent } from './payload-signals.js';
+const STANDALONE_PARENT_BASE_SKILLS = [
+    'sks-naruto',
+    'sks-pipeline-runner',
+    'sks-prompt-pipeline',
+    'sks-honest-mode'
+];
+export async function attachAuthoritativeSksSkillContext(root, state, payload, result) {
+    if (result?.decision === 'block' || result?.sksTaskProfile === 'passthrough')
+        return result;
+    if (looksLikeCodexGitAction(payload) || looksLikeCodexUiSettingsEvent(payload))
+        return result;
+    const prompt = stripVisibleDecisionAnswerBlocks(extractUserPrompt(payload));
+    if (!dollarCommand(prompt) && routeIsGitOnly(routePrompt(prompt)))
+        return result;
+    const skillNames = result?.attached_parent_mission_id
+        ? await standaloneParentManagedSkillNames(root, result.attached_parent_mission_id, state)
+        : selectedSksSkillNamesForTurn(state, prompt, result);
+    if (!skillNames.length)
+        return result;
+    const admission = await authoritativeSksSkillAdmission(root, skillNames);
+    if (admission.blocked)
+        return { ...result, ...admission.blocked };
+    const resolution = admission.resolution;
+    if (!resolution)
+        return result;
+    const skillContext = renderAuthoritativeSksSkillContext(resolution);
+    if (!skillContext)
+        return result;
+    return {
+        ...result,
+        additionalContext: [result?.additionalContext, skillContext].filter(Boolean).join('\n\n')
+    };
+}
+export async function standaloneParentManagedSkillNames(root, missionId, state = {}) {
+    const boundedMissionId = String(missionId || '').trim();
+    if (!boundedMissionId)
+        return [...STANDALONE_PARENT_BASE_SKILLS];
+    const validatedMissionId = validateExternallyReservedMissionId(boundedMissionId);
+    if (!validatedMissionId.ok) {
+        return [...STANDALONE_PARENT_BASE_SKILLS, INVALID_EXPLICIT_MANAGED_SKILL_NAME];
+    }
+    const canonicalMissionId = validatedMissionId.id;
+    const stateSkills = String(state?.mission_id || '') === canonicalMissionId
+        ? allowlistedManagedRouteSkillNames(state?.required_skills)
+        : [];
+    const routeContext = await readStandaloneParentRouteContext(root, canonicalMissionId);
+    const contextSkills = allowlistedManagedRouteSkillNames(routeContext?.required_skills);
+    return Array.from(new Set([
+        ...stateSkills,
+        ...contextSkills,
+        ...STANDALONE_PARENT_BASE_SKILLS
+    ]));
+}
+async function readStandaloneParentRouteContext(root, missionId) {
+    const file = path.join(missionDir(root, missionId), 'route-context.json');
+    try {
+        const inspection = await inspectConfinedPath(path.resolve(root), path.resolve(file));
+        if (!inspection.exists || inspection.leafSymlink || !inspection.stat?.isFile())
+            return null;
+        return await readJson(file, null).catch(() => null);
+    }
+    catch {
+        return null;
+    }
+}
+export async function authoritativeSksSkillAdmission(root, skillNames) {
+    const resolution = await resolveAuthoritativeSksSkillSources({ root, skillNames }).catch(() => null);
+    if (!resolution) {
+        return {
+            resolution: null,
+            blocked: {
+                decision: 'block',
+                reason: 'SKS managed skill resolution failed. Repair the global SKS installation, then retry.',
+                systemMessage: 'SKS: managed skill availability check blocked this turn.'
+            }
+        };
+    }
+    if (resolution.unresolved.length || resolution.blockers.length) {
+        const details = [
+            resolution.unresolved.length ? `unavailable=${resolution.unresolved.join(',')}` : '',
+            resolution.blockers.length ? `rejected=${resolution.blockers.join(',')}` : ''
+        ].filter(Boolean).join('; ');
+        return {
+            resolution,
+            blocked: {
+                decision: 'block',
+                reason: `SKS managed skill availability check failed (${details}). Repair the global SKS installation, then retry.`,
+                systemMessage: 'SKS: managed skill availability check blocked this turn.'
+            }
+        };
+    }
+    return { resolution, blocked: null };
+}
+function selectedSksSkillNamesForTurn(state, prompt, result) {
+    if (result?.attached_parent_mission_id)
+        return [...STANDALONE_PARENT_BASE_SKILLS];
+    const active = state?.mission_id && state?.route_closed !== true
+        && (looksLikeActiveContinuationPrompt(prompt) || isBlockingClarificationAwaiting(state));
+    if (active) {
+        const activeSkills = selectedSksSkillNamesForActiveState(state);
+        if (activeSkills.length)
+            return activeSkills;
+    }
+    const selectedRoute = routePrompt(prompt);
+    const selectedSkills = managedSkillNamesForPrompt(selectedRoute, prompt);
+    if (selectedSkills.length)
+        return selectedSkills;
+    return result?.sksTaskProfile === 'answer' ? ['answer', 'honest-mode'] : [];
+}
+export function selectedSksSkillNamesForActiveState(state) {
+    const persisted = Array.isArray(state?.required_skills) ? state.required_skills : [];
+    if (persisted.length)
+        return persisted.map(String);
+    const activeRoute = routePrompt(String(state?.route_command || state?.route || state?.mode || ''));
+    return activeRoute?.requiredSkills?.length ? activeRoute.requiredSkills.map(String) : [];
+}
+function activeSksSkillNames(state) {
+    if (!state?.mission_id || state?.route_closed === true)
+        return [];
+    return selectedSksSkillNamesForActiveState(state);
+}
+export async function activeAuthoritativeSksSkillRefresh(root, state) {
+    const skillNames = activeSksSkillNames(state);
+    if (!skillNames.length)
+        return { context: '', blocked: null };
+    const admission = await authoritativeSksSkillAdmission(root, skillNames);
+    if (admission.blocked)
+        return { context: '', blocked: admission.blocked };
+    return {
+        context: admission.resolution ? renderAuthoritativeSksSkillContext(admission.resolution) : '',
+        blocked: null
+    };
+}
+export async function hookActiveSkillContextRefresh(root, state, name) {
+    if (name !== 'session-start') {
+        if (!activeSksSkillNames(state).length)
+            return { continue: true };
+        return {
+            continue: true,
+            systemMessage: 'SKS will refresh active managed-skill paths from the current installation on compact resume and reverify them before the next tool call.'
+        };
+    }
+    const refresh = await activeAuthoritativeSksSkillRefresh(root, state);
+    if (refresh.blocked) {
+        return {
+            continue: true,
+            systemMessage: 'SKS managed skill refresh could not verify the current installation. Do not use a stale skill location; the next active tool call will be denied until the installation is repaired.'
+        };
+    }
+    if (!refresh.context)
+        return { continue: true };
+    return { continue: true, additionalContext: refresh.context, silent: true };
+}
+export function routeBypassesActiveContext(route = null) {
+    return ['DFix', 'Answer', 'Commit', 'CommitAndPush', 'Wiki', 'ComputerUse'].includes(String(route?.id || ''));
+}
+export function routeIsGitOnly(route = null) {
+    return ['Commit', 'CommitAndPush'].includes(String(route?.id || ''));
+}
+export function shouldPrepareFreshRouteOnActivePrompt(prompt, route = null, opts = {}) {
+    if (!route || opts.command || opts.bypassActiveRoute || opts.goalOverlay)
+        return false;
+    if (looksLikeActiveContinuationPrompt(prompt))
+        return false;
+    return routeRequiresSubagents(route, prompt);
+}
+function isClarificationAwaiting(state = {}) {
+    const phase = String(state.phase || '');
+    const stopGate = String(state.stop_gate || '');
+    const gateAwaiting = phase.includes('CLARIFICATION_AWAITING_ANSWERS') || stopGate === 'clarification-gate';
+    if (!gateAwaiting || !state?.mission_id)
+        return false;
+    if (state.ambiguity_gate_required !== true || state.ambiguity_gate_passed === true)
+        return false;
+    return Boolean(state.clarification_required || state.implementation_allowed === false);
+}
+export function isBlockingClarificationAwaiting(state = {}) {
+    return isClarificationAwaiting(state);
+}
+export function looksLikeClarificationCancel(prompt = '') {
+    return /^(cancel|reset|restart|new mission|새로|취소|중단|리셋|다시 시작)\b/i.test(String(prompt || '').trim());
+}
+export function activeGoalOverlayContext(state = {}, route = null) {
+    if (state.mode !== 'GOAL' || !state.mission_id)
+        return '';
+    if (!route || route.id === 'Goal' || route.id === 'DFix' || route.id === 'Answer')
+        return '';
+    return [
+        `Legacy SKS Goal state ${state.mission_id} is non-authoritative and must not be updated.`,
+        `Do not let it hijack this new ${route.command || '$SKS'} prompt. The newly prepared route mission and gate are authoritative for this turn.`,
+        'Codex native Goal is the only persisted Goal owner; use native controls only when the user explicitly returns to Goal.'
+    ].join('\n');
+}

package/dist/core/hooks-runtime/hook-io.js

@@ -1,10 +1,3 @@
-// Deliberately minimal dependency surface (just fsx.js + the lightweight
-// codex-compat output builders) — hooks-runtime.ts re-exports these, but
-// the daemon-accelerated hook dispatch (sksd-hook-dispatch.ts) imports
-// straight from here so a daemon-warm hook call never pays the cost of
-// loading hooks-runtime.ts's full ~20-module dependency graph (pipeline,
-// mission, db-safety, harness-guard, ...) just to read stdin and shape the
-// response (20차 P2-1).
 import { readStdin } from '../fsx.js';
 import { buildCompactContinue, buildPermissionRequestAllow, buildPermissionRequestDeny, buildPostToolUseBlock, buildPostToolUseContinue, buildPreToolUseContinue, buildPreToolUseDeny, buildSessionStartContinue, buildStopBlock, buildStopContinue, buildSubagentStartContinue, buildSubagentStopBlock, buildSubagentStopContinue, buildUserPromptSubmitBlock, buildUserPromptSubmitContinue } from '../codex-compat/codex-hook-output-builders.js';
 export async function loadHookPayload() {
@@ -19,10 +12,6 @@ export async function loadHookPayload() {
 export function normalizeHookResult(name, result = {}) {
     const eventName = codexHookEventName(name);
     const out = { ...result };
-    // Project and legacy user-level SKS hooks can briefly coexist during an
-    // upgrade. The runtime owner performs the work once; duplicate invocations
-    // must be silent so Codex does not inject the same route or Stop feedback
-    // twice into one turn.
     if (out.suppressedDuplicate === true)
         return { continue: true };
     const systemMessage = out.silent === true
@@ -43,7 +32,7 @@ export function normalizeHookResult(name, result = {}) {
         if (out.decision === 'block' || out.permissionDecision === 'deny' || out.decision === 'deny') {
             return buildPreToolUseDeny(reason, { systemMessage });
         }
-        return buildPreToolUseContinue({ systemMessage });
+        return buildPreToolUseContinue({ additionalContext: out.additionalContext, systemMessage });
     }
     if (eventName === 'PermissionRequest') {
         if (out.decision === 'deny' || out.permissionDecision === 'deny') {

package/dist/core/hooks-runtime/light-turn.js

@@ -24,8 +24,6 @@ export async function consumeLightTurnStopBypass(root, input) {
     const receipt = await readJson(file, null).catch(() => null);
     if (!receipt)
         return { accepted: false, receipt: null, reason: 'receipt_missing' };
-    // A light receipt is single-use. Remove it before evaluating stale route
-    // state so it can never become durable completion evidence or be replayed.
     await fsp.rm(file, { force: true }).catch(() => null);
     if (receipt.schema !== 'sks.light-turn.v1')
         return { accepted: false, receipt, reason: 'schema_mismatch' };

package/dist/core/hooks-runtime/naruto-decision-gate.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { appendJsonlBounded, nowIso, sha256 } from '../fsx.js';
+import { ensureConfinedDirectory } from '../managed-path-safety.js';
 import { codexHookEventName } from '../codex-compat/codex-hook-events.js';
 import { narutoDecisionForRoute, routeByDollarCommand, routeById, routePrompt, stripVisibleDecisionAnswerBlocks } from '../routes.js';
 import { classifyTaskProfile, isTaskProfile } from '../runtime/task-profile.js';
@@ -32,7 +33,9 @@ export async function evaluateHookNarutoDecisionGate(input) {
     };
     let recorded = true;
     try {
-        await appendJsonlBounded(hookNarutoDecisionLogPath(input.root), row, HOOK_NARUTO_DECISION_LOG_MAX_BYTES);
+        const logPath = hookNarutoDecisionLogPath(input.root);
+        await ensureConfinedDirectory(path.resolve(input.root), path.dirname(logPath));
+        await appendJsonlBounded(logPath, row, HOOK_NARUTO_DECISION_LOG_MAX_BYTES);
     }
     catch {
         recorded = false;

package/dist/core/hooks-runtime/naruto-terminal-finalization.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { nowIso, readJson, readText, sha256 } from '../fsx.js';
+import { withFileLock } from '../locks/file-lock.js';
+import { updateCurrentIfMissionAndRun } from '../mission.js';
+import { maybeFinalizeRoute } from '../proof/auto-finalize.js';
+import { validateRouteCompletionProof } from '../proof/route-proof-gate.js';
+import { officialSubagentPreparationInProgress, withOfficialSubagentLifecycleLock } from '../subagents/official-subagent-preparation.js';
+import { SUBAGENT_EVIDENCE_FILENAME, SUBAGENT_PARENT_SUMMARY_FILENAME } from '../subagents/subagent-evidence.js';
+import { closeWorkOrderLedgerForRouteResult } from '../work-order-ledger.js';
+export async function finalizeNarutoTerminalProof(root, state, sessionKey, dir, terminal) {
+    await withFileLock({
+        lockPath: path.join(dir, '.naruto-finalize.lock'),
+        timeoutMs: 5_000,
+        staleMs: 30_000
+    }, () => withOfficialSubagentLifecycleLock(dir, async () => {
+        if (await officialSubagentPreparationInProgress(dir))
+            return;
+        const [currentPlan, currentGate] = await Promise.all([
+            readJson(path.join(dir, 'subagent-plan.json'), null).catch(() => null),
+            readJson(path.join(dir, 'naruto-gate.json'), null).catch(() => null)
+        ]);
+        if (String(currentPlan?.workflow_run_id || '').trim() !== terminal.workflowRunId
+            || String(currentGate?.workflow_run_id || '').trim() !== terminal.workflowRunId
+            || currentGate?.passed !== true
+            || currentGate?.terminal !== true)
+            return;
+        let proofStatus = await currentNarutoProofStatus(root, terminal.missionId, terminal.workflowRunId, state);
+        if (!proofStatus.valid) {
+            const finalized = await maybeFinalizeRoute(root, {
+                missionId: terminal.missionId,
+                route: '$Naruto',
+                gateFile: 'naruto-gate.json',
+                gate: currentGate,
+                artifacts: [
+                    { path: 'subagent-plan.json', kind: 'agent', source: 'real', ignoreStale: true },
+                    { path: 'subagent-events.jsonl', kind: 'agent', source: 'real', ignoreStale: true },
+                    { path: SUBAGENT_PARENT_SUMMARY_FILENAME, kind: 'agent', source: 'real', ignoreStale: true },
+                    { path: SUBAGENT_EVIDENCE_FILENAME, kind: 'agent', source: 'real', ignoreStale: true },
+                    { path: 'naruto-summary.json', kind: 'agent', source: 'real', ignoreStale: true },
+                    { path: 'naruto-gate.json', kind: 'agent', source: 'real', ignoreStale: true }
+                ],
+                claims: [{ id: 'naruto-official-subagent-completion', status: 'supported', evidence: 'naruto-gate.json' }],
+                agents: true
+            });
+            if (finalized?.ok !== true) {
+                throw new Error(`naruto_terminal_proof_finalize_failed:${String(finalized?.validation?.issues?.join(',') || finalized?.status || 'unknown')}`);
+            }
+            proofStatus = await currentNarutoProofStatus(root, terminal.missionId, terminal.workflowRunId, state);
+        }
+        if (!proofStatus.valid)
+            throw new Error('naruto_terminal_proof_invalid_after_finalize');
+        await closeWorkOrderLedgerForRouteResult(dir, { ok: true });
+        await invalidateReflectionForNarutoProofOnce(root, state, sessionKey, terminal.workflowRunId, proofStatus.digest);
+    }));
+}
+async function currentNarutoProofStatus(root, missionId, workflowRunId, state) {
+    const validation = await validateRouteCompletionProof(root, {
+        missionId,
+        route: '$Naruto',
+        state: {
+            ...state,
+            mission_id: missionId,
+            subagents_required: true,
+            official_subagent_run_id: workflowRunId
+        }
+    }).catch(() => null);
+    const proofRunId = String(validation?.proof?.evidence?.route_gate?.workflow_run_id || '').trim();
+    const proofText = await readText(path.join(root, '.sneakoscope', 'missions', missionId, 'completion-proof.json'), '').catch(() => '');
+    return {
+        valid: validation?.ok === true && proofRunId === workflowRunId,
+        proof: validation?.proof || null,
+        digest: proofText ? `sha256:${sha256(proofText)}` : null
+    };
+}
+async function invalidateReflectionForNarutoProofOnce(root, state, sessionKey, workflowRunId, proofDigest) {
+    if (!workflowRunId || !proofDigest)
+        return;
+    const resolvedSessionKey = sessionKey || state?._session_key;
+    await updateCurrentIfMissionAndRun(root, state?.mission_id, workflowRunId, (current) => {
+        if (current?.reflection_invalidated_for_workflow_run_id === workflowRunId
+            && current?.reflection_invalidated_for_proof_digest === proofDigest)
+            return null;
+        return {
+            reflection_invalidation_required: true,
+            reflection_invalidated_at: nowIso(),
+            reflection_invalidation_reason: 'naruto_terminal_proof_committed',
+            reflection_invalidated_for_workflow_run_id: workflowRunId,
+            reflection_invalidated_for_proof_digest: proofDigest
+        };
+    }, { sessionKey: resolvedSessionKey });
+}