@neurcode-ai/cli 0.19.0 → 0.19.3

package/dist/commands/session.js

@@ -43,6 +43,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveUnderstandingDiffFiles = resolveUnderstandingDiffFiles;
 exports.buildLocalGovernanceStatus = buildLocalGovernanceStatus;
 exports.localGovernanceStatusCommand = localGovernanceStatusCommand;
 exports.resetStaleGovernanceSessionCommand = resetStaleGovernanceSessionCommand;
@@ -61,6 +62,7 @@ exports.verifyAIChangeRecordForCli = verifyAIChangeRecordForCli;
 exports.structuralUnderstandingCommand = structuralUnderstandingCommand;
 exports.listSessionsCommand = listSessionsCommand;
 exports.endSessionCommand = endSessionCommand;
+exports.endSessionCommandWithDependencies = endSessionCommandWithDependencies;
 exports.sessionStatusCommand = sessionStatusCommand;
 exports.listLocalSessionsCommand = listLocalSessionsCommand;
 exports.currentLocalSessionCommand = currentLocalSessionCommand;
@@ -84,6 +86,8 @@ const runtime_outbox_1 = require("../utils/runtime-outbox");
 const repo_brain_impact_1 = require("../utils/repo-brain-impact");
 const structural_understanding_1 = require("../utils/structural-understanding");
 const agent_guard_supervisor_1 = require("../utils/agent-guard-supervisor");
+const hook_heartbeat_1 = require("../utils/hook-heartbeat");
+const profile_drift_recovery_1 = require("../utils/profile-drift-recovery");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -173,7 +177,79 @@ function approvalContextFrom(event) {
             : event?.filePath,
     };
 }
-function resolveUnderstandingDiff(repoRoot, options) {
+const UNTRACKED_UNDERSTANDING_EXCLUDED_DIRS = new Set([
+    '.git',
+    '.neurcode',
+    '.neurcode-admission',
+    '.neurcode-ai-record',
+    '.cache',
+    '.next',
+    'build',
+    'cache',
+    'coverage',
+    'dist',
+    'evidence',
+    'generated',
+    'node_modules',
+    'out',
+    'vendor',
+]);
+const UNTRACKED_UNDERSTANDING_SOURCE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i;
+const UNTRACKED_UNDERSTANDING_GENERATED_FILE = /(?:\.d\.ts|\.map|\.min\.js|\.bundle\.js|\.generated\.[cm]?[jt]sx?)$/i;
+function normalizeUnderstandingPath(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '').trim();
+}
+function eligibleUntrackedUnderstandingPath(repoRoot, value) {
+    const normalized = normalizeUnderstandingPath(value);
+    if (!normalized || normalized.startsWith('/') || normalized === '..' || normalized.startsWith('../'))
+        return null;
+    const segments = normalized.split('/');
+    if (segments.includes('..') || segments.some((segment) => UNTRACKED_UNDERSTANDING_EXCLUDED_DIRS.has(segment.toLowerCase()))) {
+        return null;
+    }
+    if (UNTRACKED_UNDERSTANDING_GENERATED_FILE.test(normalized))
+        return null;
+    const absolutePath = (0, node_path_1.join)(repoRoot, normalized);
+    try {
+        const stat = (0, node_fs_1.lstatSync)(absolutePath);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return normalized;
+}
+function untrackedDiffFile(repoRoot, path) {
+    let lines = [];
+    if (UNTRACKED_UNDERSTANDING_SOURCE.test(path)) {
+        const text = (0, node_fs_1.readFileSync)((0, node_path_1.join)(repoRoot, path), 'utf8').replace(/\r\n/g, '\n');
+        lines = text ? text.split('\n') : [];
+        if (lines.at(-1) === '')
+            lines.pop();
+    }
+    return {
+        path,
+        changeType: 'add',
+        addedLines: lines.length,
+        removedLines: 0,
+        hunks: lines.length > 0
+            ? [{
+                    oldStart: 0,
+                    oldLines: 0,
+                    newStart: 1,
+                    newLines: lines.length,
+                    lines: lines.map((content, index) => ({
+                        type: 'added',
+                        content,
+                        lineNumber: index + 1,
+                    })),
+                }]
+            : [],
+        provenance: 'git-untracked',
+    };
+}
+function resolveUnderstandingDiffFiles(repoRoot, options = {}) {
     const args = ['diff'];
     if (options.staged) {
         args.push('--cached');
@@ -184,11 +260,27 @@ function resolveUnderstandingDiff(repoRoot, options) {
     else {
         args.push('HEAD');
     }
-    return (0, node_child_process_1.execFileSync)('git', args, {
+    const diffText = (0, node_child_process_1.execFileSync)('git', args, {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const selected = (0, diff_parser_1.parseDiff)(diffText);
+    if (options.staged)
+        return selected;
+    const untrackedOutput = (0, node_child_process_1.execFileSync)('git', ['ls-files', '--others', '--exclude-standard', '-z'], {
         cwd: repoRoot,
         encoding: 'utf8',
         maxBuffer: 64 * 1024 * 1024,
     });
+    const byPath = new Map(selected.map((file) => [normalizeUnderstandingPath(file.path), file]));
+    for (const rawPath of untrackedOutput.split('\0')) {
+        const path = eligibleUntrackedUnderstandingPath(repoRoot, rawPath);
+        if (!path || byPath.has(path))
+            continue;
+        byPath.set(path, untrackedDiffFile(repoRoot, path));
+    }
+    return [...byPath.values()].sort((a, b) => normalizeUnderstandingPath(a.path).localeCompare(normalizeUnderstandingPath(b.path)));
 }
 function loadLocalGovernanceSession(repoRoot, sessionId) {
     return sessionId ? (0, governance_runtime_1.loadSession)(repoRoot, sessionId) : (0, governance_runtime_1.loadActiveSession)(repoRoot);
@@ -251,6 +343,108 @@ function pendingApprovalBlock(session, now = new Date()) {
     }
     return null;
 }
+function activePointerInspection(repoRoot) {
+    const path = (0, node_path_1.join)(repoRoot, '.neurcode', 'active-session.json');
+    if (!(0, node_fs_1.existsSync)(path))
+        return { state: 'missing', sessionId: null, session: null };
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        if (parsed.sessionId === null)
+            return { state: 'cleared', sessionId: null, session: null };
+        if (typeof parsed.sessionId !== 'string' || !parsed.sessionId.trim()) {
+            return { state: 'malformed', sessionId: null, session: null };
+        }
+        const session = (0, governance_runtime_1.loadSession)(repoRoot, parsed.sessionId);
+        if (!session || session.status !== 'active') {
+            return { state: 'stale', sessionId: parsed.sessionId, session };
+        }
+        return { state: 'valid', sessionId: parsed.sessionId, session };
+    }
+    catch {
+        return { state: 'malformed', sessionId: null, session: null };
+    }
+}
+function validGovernanceSessionRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return (typeof record.sessionId === 'string' &&
+        typeof record.profileHash === 'string' &&
+        (record.status === 'active' || record.status === 'finished') &&
+        Array.isArray(record.events) &&
+        Boolean(record.contract && typeof record.contract === 'object'));
+}
+function scanSessionRecords(repoRoot) {
+    const directory = (0, governance_runtime_1.sessionsDir)(repoRoot);
+    if (!(0, node_fs_1.existsSync)(directory))
+        return { active: [], malformed: [] };
+    const active = [];
+    const malformed = [];
+    for (const entry of (0, node_fs_1.readdirSync)(directory, { withFileTypes: true })
+        .filter((item) => item.isFile() && item.name.endsWith('.json') && !item.name.endsWith('.change-record.json'))
+        .sort((a, b) => a.name.localeCompare(b.name))) {
+        const relativePath = `.neurcode/sessions/${entry.name}`;
+        try {
+            const parsed = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(directory, entry.name), 'utf8'));
+            if (!validGovernanceSessionRecord(parsed)) {
+                malformed.push({ file: relativePath, reasonCode: 'invalid_session_record' });
+                continue;
+            }
+            if (entry.name !== `${parsed.sessionId}.json`) {
+                malformed.push({ file: relativePath, reasonCode: 'session_id_filename_mismatch' });
+                continue;
+            }
+            if (parsed.status === 'active')
+                active.push(parsed);
+        }
+        catch {
+            malformed.push({ file: relativePath, reasonCode: 'malformed_json' });
+        }
+    }
+    return {
+        active: active.sort((a, b) => a.sessionId.localeCompare(b.sessionId)),
+        malformed,
+    };
+}
+function recoveryReasonCode(pointer, sessionId) {
+    if (pointer.state === 'valid') {
+        return pointer.sessionId === sessionId
+            ? 'stale_referenced_active_session'
+            : 'orphan_unreferenced_active_record';
+    }
+    if (pointer.state === 'missing')
+        return 'orphan_missing_active_pointer';
+    if (pointer.state === 'cleared')
+        return 'orphan_cleared_active_pointer';
+    if (pointer.state === 'malformed')
+        return 'orphan_malformed_active_pointer';
+    return 'orphan_stale_active_pointer';
+}
+function activeSessionLiveness(repoRoot, sessionId, now) {
+    const reasons = [];
+    const supervisor = (0, agent_guard_supervisor_1.inspectAgentGuardSupervisor)(repoRoot, sessionId);
+    if (supervisor.state?.sessionId === sessionId &&
+        supervisor.alive &&
+        ['running', 'starting', 'stopping'].includes(supervisor.effectiveStatus)) {
+        reasons.push('live_supervisor_process');
+    }
+    const heartbeat = (0, hook_heartbeat_1.readHookHeartbeat)(repoRoot);
+    const heartbeatAt = Date.parse(heartbeat?.lastEvent.ts ?? '');
+    if (heartbeat?.lastEvent.sessionId === sessionId &&
+        Number.isFinite(heartbeatAt) &&
+        now.getTime() - heartbeatAt >= 0 &&
+        now.getTime() - heartbeatAt <= 5 * 60_000) {
+        reasons.push('fresh_hook_heartbeat');
+    }
+    return reasons;
+}
+function clearInvalidActivePointer(repoRoot, pointer) {
+    if (pointer.state === 'valid')
+        return;
+    const directory = (0, node_path_1.join)(repoRoot, '.neurcode');
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(directory, 'active-session.json'), JSON.stringify({ sessionId: null }, null, 2) + '\n', 'utf8');
+}
 function buildLocalGovernanceStatus(options = {}) {
     const repoRoot = (0, v0_governance_1.resolveRepoRoot)(options.dir || process.cwd());
     const session = loadLocalGovernanceSession(repoRoot, options.sessionId);
@@ -267,6 +461,19 @@ function buildLocalGovernanceStatus(options = {}) {
         };
     }
     const recentEvents = session.events.slice(-10);
+    const staleness = (0, v0_governance_1.getProfileStaleness)(repoRoot);
+    const profileAction = (0, v0_governance_1.profileFreshnessActionForSession)(staleness, session.profileHash);
+    const pendingProfileDecisions = (0, profile_drift_recovery_1.pendingProfileDriftDecisions)(session);
+    const profileFreshness = (0, v0_governance_1.buildProfileFreshnessSignal)(staleness, profileAction, {
+        sessionProfileHash: session.profileHash,
+        ...(profileAction === 'session_restart_required'
+            ? {
+                recoveryReason: 'active_session_profile_changed',
+                recoveryCommand: profile_drift_recovery_1.PROFILE_DRIFT_RECOVERY_COMMAND,
+                unresolvedHumanDecisions: pendingProfileDecisions.length > 0,
+            }
+            : {}),
+    });
     const latestBlock = [...session.events].reverse().find((event) => event.type === 'check_block');
     const latestApprovalContext = approvalContextFrom(latestBlock);
     const suggestedApprovalPath = latestApprovalContext?.suggestedApprovalPath ||
@@ -280,6 +487,7 @@ function buildLocalGovernanceStatus(options = {}) {
         status: session.status,
         goal: session.contract.goal,
         profileHash: session.profileHash,
+        profileFreshness,
         scopeMode: session.contract.scopeMode,
         planCoherenceMode: session.contract.planCoherenceMode ?? 'warn',
         agentPlan: session.contract.agentPlan ?? null,
@@ -341,6 +549,14 @@ function localGovernanceStatusCommand(options = {}) {
     console.log(`Session: ${chalk.white(activeStatus.sessionId)} ${activeStatus.active ? chalk.green('active') : chalk.dim(activeStatus.status)}`);
     console.log(`Goal:    ${chalk.white(truncate(activeStatus.goal))}`);
     console.log(`Scope:   ${chalk.white(activeStatus.scopeMode)}`);
+    console.log(`Profile: ${chalk.white(activeStatus.profileFreshness.status)} cache · ` +
+        `${chalk.white(activeStatus.profileFreshness.sessionCompatibility)} session`);
+    if (activeStatus.profileFreshness.sessionCompatibility === 'incompatible') {
+        console.log(chalk.yellow(`Hashes:  session ${activeStatus.profileHash.slice(0, 12)} · ` +
+            `current ${activeStatus.profileFreshness.currentProfileHash.slice(0, 12)}`));
+        console.log(chalk.yellow(`Recover: ${profile_drift_recovery_1.PROFILE_DRIFT_RECOVERY_COMMAND} ` +
+            `(--force abandons unresolved operator state${activeStatus.profileFreshness.unresolvedHumanDecisions ? '; unresolved decisions are present' : ''})`));
+    }
     console.log(`Plan:    ${chalk.white(activeStatus.planCoherenceMode)}${activeStatus.agentPlanRevision ? chalk.dim(` · rev ${activeStatus.agentPlanRevision}`) : ''}`);
     console.log(`Agent:   ${chalk.white(activeStatus.agentInvocation.status.replace(/_/g, ' '))}` +
         chalk.dim(` · score ${activeStatus.agentInvocation.score}`) +
@@ -413,7 +629,8 @@ async function resetStaleGovernanceSessionCommand(options = {}) {
     const maxAgeMinutes = Number.isFinite(options.maxAgeMinutes)
         ? Math.max(0, Number(options.maxAgeMinutes))
         : 120;
-    const active = (0, governance_runtime_1.loadActiveSession)(repoRoot);
+    const pointer = activePointerInspection(repoRoot);
+    const records = scanSessionRecords(repoRoot);
     const output = (payload, statusCode = 0) => {
         if (options.json) {
             console.log(JSON.stringify(payload, null, 2));
@@ -433,92 +650,175 @@ async function resetStaleGovernanceSessionCommand(options = {}) {
         }
         process.exitCode = statusCode;
     };
-    if (!active || active.status !== 'active') {
+    if (records.active.length === 0) {
         output({
             ok: true,
             reset: false,
             repoRoot,
             reason: 'no_active_session',
+            pointerState: pointer.state,
+            malformedRecords: records.malformed,
             message: 'No active in-flow governance session found.',
         });
         return;
     }
-    const ageMinutes = sessionAgeMinutes(active, now);
-    const pending = pendingApprovalBlock(active, now);
-    const stale = ageMinutes >= maxAgeMinutes;
-    if (!stale && options.force !== true) {
+    const recovered = [];
+    const skipped = [];
+    for (const active of records.active) {
+        const ageMinutes = sessionAgeMinutes(active, now);
+        const pending = pendingApprovalBlock(active, now);
+        const stale = ageMinutes >= maxAgeMinutes;
+        const liveness = activeSessionLiveness(repoRoot, active.sessionId, now);
+        const reasonCode = recoveryReasonCode(pointer, active.sessionId);
+        if (liveness.length > 0) {
+            skipped.push({
+                sessionId: active.sessionId,
+                reason: 'session_live',
+                reasonCode,
+                liveness,
+                ageMinutes: Number(ageMinutes.toFixed(2)),
+            });
+            continue;
+        }
+        if (!stale && options.force !== true) {
+            skipped.push({
+                sessionId: active.sessionId,
+                reason: 'session_not_stale',
+                reasonCode,
+                ageMinutes: Number(ageMinutes.toFixed(2)),
+                pendingApproval: pending,
+            });
+            continue;
+        }
+        if (pending && options.force !== true) {
+            skipped.push({
+                sessionId: active.sessionId,
+                reason: 'pending_approval',
+                reasonCode,
+                ageMinutes: Number(ageMinutes.toFixed(2)),
+                filePath: pending.filePath,
+                owners: pending.owners,
+                suggestedApprovalPath: pending.suggestedApprovalPath,
+            });
+            continue;
+        }
+        const pointerReferenced = pointer.state === 'valid' && pointer.sessionId === active.sessionId;
+        (0, governance_runtime_1.appendEvent)(repoRoot, active.sessionId, {
+            type: 'user_decision',
+            ts: now.toISOString(),
+            decision: pointerReferenced ? 'reset_stale_session' : 'recover_orphaned_session',
+            detail: {
+                source: 'local_cli',
+                recovery: true,
+                reasonCode,
+                pointerState: pointer.state,
+                force: options.force === true,
+                maxAgeMinutes,
+                ageMinutes: Number(ageMinutes.toFixed(2)),
+                pendingApproval: pending,
+                livenessChecks: ['bounded_event_age', 'guard_supervisor_process', 'hook_heartbeat'],
+            },
+        });
+        const livePointerPath = (0, node_path_1.join)(repoRoot, '.neurcode', 'active-session.json');
+        const preservedLivePointer = pointer.state === 'valid' && pointer.sessionId !== active.sessionId && (0, node_fs_1.existsSync)(livePointerPath)
+            ? (0, node_fs_1.readFileSync)(livePointerPath, 'utf8')
+            : null;
+        let finished = null;
+        try {
+            finished = (0, governance_runtime_1.finishSession)(repoRoot, active.sessionId, { reason: reasonCode });
+        }
+        finally {
+            if (preservedLivePointer !== null) {
+                (0, node_fs_1.writeFileSync)(livePointerPath, preservedLivePointer, 'utf8');
+            }
+        }
+        if (!finished) {
+            skipped.push({ sessionId: active.sessionId, reason: 'finish_failed', reasonCode });
+            continue;
+        }
+        const supervisor = (0, agent_guard_supervisor_1.inspectAgentGuardSupervisor)(repoRoot, finished.sessionId);
+        if (supervisor.state?.sessionId === finished.sessionId) {
+            (0, agent_guard_supervisor_1.stopSupervisorOnSessionCompletion)(repoRoot);
+        }
+        await (0, runtime_live_1.publishRuntimeLiveStatus)(repoRoot, finished);
+        const replay = (0, governance_runtime_1.replaySession)(finished);
+        recovered.push({
+            sessionId: finished.sessionId,
+            previousGoal: finished.contract.goal,
+            status: finished.status,
+            reasonCode,
+            replayHash: finished.replayHash,
+            replayVerified: replay.matchesOriginal,
+            ageMinutes: Number(ageMinutes.toFixed(2)),
+            forced: options.force === true,
+            recordPath: `.neurcode/sessions/${finished.sessionId}.json`,
+            evidencePath: (0, node_path_1.relative)(repoRoot, (0, governance_runtime_1.aiChangeRecordPath)(repoRoot, finished.sessionId)).replace(/\\/g, '/'),
+        });
+    }
+    if (recovered.length > 0) {
+        clearInvalidActivePointer(repoRoot, pointer);
+        const first = recovered[0];
         output({
             ok: true,
-            reset: false,
+            reset: true,
             repoRoot,
-            sessionId: active.sessionId,
-            reason: 'session_not_stale',
-            ageMinutes: Number(ageMinutes.toFixed(2)),
+            sessionId: recovered.length === 1 ? first.sessionId : undefined,
+            status: recovered.length === 1 ? first.status : 'finished',
+            replayHash: recovered.length === 1 ? first.replayHash : undefined,
+            ageMinutes: recovered.length === 1 ? first.ageMinutes : undefined,
             maxAgeMinutes,
-            pendingApproval: pending,
-            message: `Active session ${active.sessionId} is not stale yet (${ageMinutes.toFixed(1)}m < ${maxAgeMinutes}m).`,
+            forced: options.force === true,
+            pointerState: pointer.state,
+            recoveredCount: recovered.length,
+            recovered,
+            skipped,
+            malformedRecords: records.malformed,
+            message: `Recovered ${recovered.length} stale or orphaned active session record${recovered.length === 1 ? '' : 's'}.`,
         });
         return;
     }
-    if (pending && options.force !== true) {
+    const primary = skipped.find((item) => item.sessionId === pointer.sessionId) ?? skipped[0];
+    if (primary?.reason === 'pending_approval') {
         output({
             ok: false,
             reset: false,
             repoRoot,
-            sessionId: active.sessionId,
-            reason: 'pending_approval',
-            ageMinutes: Number(ageMinutes.toFixed(2)),
+            ...primary,
             maxAgeMinutes,
-            filePath: pending.filePath,
-            owners: pending.owners,
-            suggestedApprovalPath: pending.suggestedApprovalPath,
+            pointerState: pointer.state,
+            malformedRecords: records.malformed,
             message: 'Active session is waiting on an unresolved approval; refusing to reset without --force.',
             next: [
-                `Approve exactly ${pending.suggestedApprovalPath} from the dashboard or MCP.`,
+                `Approve exactly ${primary.suggestedApprovalPath} from the dashboard or MCP.`,
                 'Or run `neurcode session reset-stale --force` if this is abandoned rehearsal state.',
             ],
         }, 2);
         return;
     }
-    (0, governance_runtime_1.appendEvent)(repoRoot, active.sessionId, {
-        type: 'user_decision',
-        ts: now.toISOString(),
-        decision: 'reset_stale_session',
-        detail: {
-            source: 'local_cli',
-            force: options.force === true,
-            maxAgeMinutes,
-            ageMinutes: Number(ageMinutes.toFixed(2)),
-            pendingApproval: pending,
-        },
-    });
-    const finished = (0, governance_runtime_1.finishSession)(repoRoot, active.sessionId);
-    if (!finished) {
+    if (primary?.reason === 'finish_failed') {
         output({
             ok: false,
             reset: false,
             repoRoot,
-            sessionId: active.sessionId,
-            reason: 'finish_failed',
-            message: `Could not finish active session ${active.sessionId}.`,
+            ...primary,
+            pointerState: pointer.state,
+            malformedRecords: records.malformed,
+            message: `Could not finish active session ${primary.sessionId}.`,
         }, 1);
         return;
     }
-    (0, agent_guard_supervisor_1.stopSupervisorOnSessionCompletion)(repoRoot);
-    await (0, runtime_live_1.publishRuntimeLiveStatus)(repoRoot, finished);
     output({
         ok: true,
-        reset: true,
+        reset: false,
         repoRoot,
-        sessionId: finished.sessionId,
-        previousGoal: finished.contract.goal,
-        status: finished.status,
-        replayHash: finished.replayHash,
-        ageMinutes: Number(ageMinutes.toFixed(2)),
+        ...primary,
         maxAgeMinutes,
-        forced: options.force === true,
-        recordPath: `.neurcode/sessions/${finished.sessionId}.json`,
-        message: `Finished active session ${finished.sessionId} and cleared the active pointer.`,
+        pointerState: pointer.state,
+        skipped,
+        malformedRecords: records.malformed,
+        message: primary?.reason === 'session_live'
+            ? `Session ${primary.sessionId} has current process or heartbeat liveness evidence and was preserved.`
+            : `Active session ${primary?.sessionId} is not stale yet (${Number(primary?.ageMinutes ?? 0).toFixed(1)}m < ${maxAgeMinutes}m).`,
     });
 }
 async function replanGovernanceSessionCommand(options = {}) {
@@ -1547,9 +1847,9 @@ function structuralUnderstandingCommand(options = {}) {
         process.exitCode = 1;
         return;
     }
-    let diffText = '';
+    let diffFiles = [];
     try {
-        diffText = resolveUnderstandingDiff(repoRoot, options);
+        diffFiles = resolveUnderstandingDiffFiles(repoRoot, options);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -1562,7 +1862,6 @@ function structuralUnderstandingCommand(options = {}) {
         process.exitCode = 1;
         return;
     }
-    const diffFiles = diffText.trim() ? (0, diff_parser_1.parseDiff)(diffText) : [];
     const profile = (0, v0_governance_1.getProfileStaleness)(repoRoot).currentProfile;
     const artifact = (0, structural_understanding_1.buildStructuralUnderstanding)(repoRoot, diffFiles, {
         session,
@@ -1679,157 +1978,294 @@ async function listSessionsCommand(options) {
  * End a session
  */
 async function endSessionCommand(options) {
+    return endSessionCommandWithDependencies(options);
+}
+function endSessionOutput(options, payload, exitCode = 0) {
+    if (options.json) {
+        console.log(JSON.stringify({ ...payload, exitCode }, null, 2));
+    }
+    else if (payload.ok === true) {
+        console.log(chalk.green(String(payload.message || 'Session ended.')));
+        if (payload.sessionId)
+            console.log(chalk.dim(`Session: ${payload.sessionId}`));
+        if (payload.replayHash)
+            console.log(chalk.dim(`replayHash: ${payload.replayHash}`));
+    }
+    else {
+        console.error(chalk.red(String(payload.message || payload.error || 'Session end failed.')));
+        const candidates = Array.isArray(payload.candidates) ? payload.candidates : [];
+        for (const candidate of candidates) {
+            const item = candidate;
+            console.error(chalk.dim(`  ${item.sessionId || 'unknown'}: ${item.command || ''}`));
+        }
+    }
+    process.exitCode = exitCode;
+}
+async function finishLocalGovernanceSession(repoRoot, session) {
+    if (session.status === 'finished') {
+        return {
+            ok: true,
+            ended: false,
+            mode: 'local',
+            status: 'already_finished',
+            sessionId: session.sessionId,
+            replayHash: session.replayHash || null,
+            message: `Local governance session ${session.sessionId} is already finished.`,
+        };
+    }
+    (0, governance_runtime_1.appendEvent)(repoRoot, session.sessionId, {
+        type: 'user_decision',
+        ts: new Date().toISOString(),
+        decision: 'local_session_end_requested',
+        message: 'Operator ended the local governance session.',
+        detail: {
+            source: 'local_cli',
+            command: 'session end',
+        },
+    });
+    const finished = (0, governance_runtime_1.finishSession)(repoRoot, session.sessionId, {
+        reason: 'local_session_end_requested',
+    });
+    if (!finished)
+        throw new Error(`Local governance session ${session.sessionId} could not be finished.`);
+    (0, agent_guard_supervisor_1.stopSupervisorOnSessionCompletion)(repoRoot);
+    let liveStatusPublished = true;
     try {
-        const config = (0, config_1.loadConfig)();
-        if (!config.apiKey) {
-            config.apiKey = (0, config_1.requireApiKey)();
+        await (0, runtime_live_1.publishRuntimeLiveStatus)(repoRoot, finished);
+    }
+    catch {
+        liveStatusPublished = false;
+    }
+    const replay = (0, governance_runtime_1.replaySession)(finished);
+    return {
+        ok: true,
+        ended: true,
+        mode: 'local',
+        status: finished.status,
+        sessionId: finished.sessionId,
+        replayHash: finished.replayHash,
+        replayVerified: replay.matchesOriginal,
+        liveStatusPublished,
+        recordPath: `.neurcode/sessions/${finished.sessionId}.json`,
+        evidencePath: (0, node_path_1.relative)(repoRoot, (0, governance_runtime_1.aiChangeRecordPath)(repoRoot, finished.sessionId)).replace(/\\/g, '/'),
+        message: `Local governance session ${finished.sessionId} ended with replay-valid evidence.`,
+    };
+}
+async function endSessionCommandWithDependencies(options, dependencies = {}) {
+    const repoRoot = (0, v0_governance_1.resolveRepoRoot)(options.dir || process.cwd());
+    const isInteractive = dependencies.isInteractive ??
+        (() => Boolean(process.stdin.isTTY && process.stdout.isTTY));
+    const prompt = dependencies.prompt ?? promptUser;
+    try {
+        if (options.sessionId) {
+            const local = (0, governance_runtime_1.loadSession)(repoRoot, options.sessionId);
+            if (local) {
+                endSessionOutput(options, await finishLocalGovernanceSession(repoRoot, local));
+                return;
+            }
+            if (options.local) {
+                endSessionOutput(options, {
+                    ok: false,
+                    ended: false,
+                    mode: 'local',
+                    reason: 'local_session_not_found',
+                    sessionId: options.sessionId,
+                    message: `Local governance session ${options.sessionId} was not found.`,
+                }, 2);
+                return;
+            }
         }
-        const client = new api_client_1.ApiClient(config);
-        let sessionId = options.sessionId;
-        // If no session ID provided, try to get from state
-        if (!sessionId) {
-            const stateSessionId = (0, state_1.getSessionId)();
-            sessionId = stateSessionId || undefined;
-            if (!sessionId) {
-                // List active sessions and let user choose
-                (0, messages_1.printInfo)('No Active Session', 'Looking for active sessions...');
-                const sessions = await client.getSessions(config.projectId, 10);
-                const activeSessions = sessions.filter(s => s.status === 'active');
-                if (activeSessions.length === 0) {
-                    (0, messages_1.printInfo)('No Active Sessions', 'There are no active sessions to end.');
+        else {
+            const records = scanSessionRecords(repoRoot);
+            if (records.active.length === 1) {
+                endSessionOutput(options, await finishLocalGovernanceSession(repoRoot, records.active[0]));
+                return;
+            }
+            if (records.active.length > 1) {
+                if (!isInteractive()) {
+                    endSessionOutput(options, {
+                        ok: false,
+                        ended: false,
+                        mode: 'local',
+                        reason: 'multiple_local_sessions_noninteractive',
+                        candidates: records.active.map((session) => ({
+                            sessionId: session.sessionId,
+                            command: `neurcode session end --session-id ${session.sessionId}`,
+                        })),
+                        malformedRecords: records.malformed,
+                        message: 'Multiple active local governance sessions were found; noninteractive selection is disabled.',
+                    }, 2);
                     return;
                 }
-                if (activeSessions.length === 1) {
-                    sessionId = activeSessions[0].sessionId;
-                    const title = activeSessions[0].title || activeSessions[0].intentDescription || 'Untitled';
-                    (0, messages_1.printInfo)('Found Active Session', `Ending: ${title}`);
-                }
-                else {
-                    // Multiple active sessions - let user choose
-                    (0, messages_1.printSection)('Multiple Active Sessions');
-                    activeSessions.forEach((session, index) => {
-                        const title = session.title || session.intentDescription || 'Untitled';
-                        console.log(chalk.cyan(`  ${index + 1}.`), chalk.white(title));
-                        console.log(chalk.dim(`     ${session.sessionId.substring(0, 20)}...`));
-                    });
-                    console.log('');
-                    const answer = await promptUser(chalk.bold('Select session to end (1-' + activeSessions.length + '): '));
-                    const choice = parseInt(answer, 10);
-                    if (choice >= 1 && choice <= activeSessions.length) {
-                        sessionId = activeSessions[choice - 1].sessionId;
-                    }
-                    else {
-                        (0, messages_1.printError)('Invalid Selection', undefined, ['Please run the command again and select a valid number']);
-                        process.exit(1);
-                    }
+                console.log(chalk.bold('Multiple active local governance sessions'));
+                records.active.forEach((session, index) => {
+                    console.log(`  ${index + 1}. ${session.sessionId} · ${truncate(session.contract.goal, 72)}`);
+                });
+                const answer = await prompt(`Select local session to end (1-${records.active.length}): `);
+                const selected = Number.parseInt(answer, 10);
+                if (!Number.isInteger(selected) || selected < 1 || selected > records.active.length) {
+                    endSessionOutput(options, {
+                        ok: false,
+                        ended: false,
+                        mode: 'local',
+                        reason: 'invalid_local_selection',
+                        message: 'No local session was ended.',
+                    }, 2);
+                    return;
                 }
+                endSessionOutput(options, await finishLocalGovernanceSession(repoRoot, records.active[selected - 1]));
+                return;
+            }
+            if (options.local) {
+                endSessionOutput(options, {
+                    ok: true,
+                    ended: false,
+                    mode: 'local',
+                    reason: 'no_active_local_session',
+                    malformedRecords: records.malformed,
+                    message: 'No active local governance session found.',
+                });
+                return;
             }
         }
-        if (!sessionId) {
-            (0, messages_1.printError)('No Session Specified', undefined, [
-                'No session ID provided and no active session found',
-                'Usage: neurcode session end [session-id]',
-                'Or set a session: neurcode init'
-            ]);
-            process.exit(1);
+        let config = null;
+        let client = dependencies.cloudClient;
+        if (!client) {
+            config = (0, config_1.loadConfig)();
+            if (!config.apiKey)
+                config.apiKey = (0, config_1.requireApiKey)();
+            client = new api_client_1.ApiClient(config);
         }
-        // Get session details first
-        try {
-            const sessionData = await client.getSession(sessionId);
-            const session = sessionData.session;
-            if (session.status === 'completed') {
-                (0, messages_1.printWarning)('Session Already Completed', `Session "${session.title || session.intentDescription || sessionId}" is already ended.`);
+        let sessionId = options.sessionId;
+        if (!sessionId) {
+            const stateSessionId = (0, state_1.getSessionId)() || undefined;
+            if (stateSessionId && (0, governance_runtime_1.loadSession)(repoRoot, stateSessionId)) {
+                const local = (0, governance_runtime_1.loadSession)(repoRoot, stateSessionId);
+                endSessionOutput(options, await finishLocalGovernanceSession(repoRoot, local));
                 return;
             }
-            if (session.status === 'cancelled') {
-                (0, messages_1.printWarning)('Session Already Cancelled', `Session "${session.title || session.intentDescription || sessionId}" was already cancelled.`);
+            sessionId = stateSessionId;
+        }
+        if (!sessionId) {
+            const sessions = await client.getSessions(options.projectId || config?.projectId, 20);
+            const active = sessions.filter((session) => session.status === 'active');
+            if (active.length === 0) {
+                endSessionOutput(options, {
+                    ok: true,
+                    ended: false,
+                    mode: 'cloud',
+                    reason: 'no_active_cloud_session',
+                    message: 'No active local or cloud session found.',
+                });
                 return;
             }
-            // Show session summary
-            const title = session.title || session.intentDescription || 'Untitled Session';
-            const filesCount = sessionData.files?.length || 0;
-            (0, messages_1.printSection)('Session Summary');
-            console.log(chalk.white(`   Title: ${title}`));
-            console.log(chalk.white(`   Files Changed: ${filesCount}`));
-            console.log(chalk.dim(`   Session ID: ${sessionId}`));
-            console.log('');
-            // Confirm before ending
-            const confirm = await promptUser(chalk.bold('End this session? (y/n): '));
-            if (confirm.toLowerCase() !== 'y' && confirm.toLowerCase() !== 'yes') {
-                (0, messages_1.printInfo)('Cancelled', 'Session was not ended.');
+            if (active.length > 1 && !isInteractive()) {
+                endSessionOutput(options, {
+                    ok: false,
+                    ended: false,
+                    mode: 'cloud',
+                    reason: 'multiple_cloud_sessions_noninteractive',
+                    candidates: active.map((session) => ({
+                        sessionId: session.sessionId,
+                        command: `neurcode session end --session-id ${session.sessionId}`,
+                    })),
+                    message: 'Multiple active cloud sessions were found; noninteractive selection is disabled.',
+                }, 2);
                 return;
             }
-            await client.endSession(sessionId);
-            // Clear session ID from local state if it matches the ended session
-            try {
-                const currentSessionId = (0, state_1.getSessionId)();
-                if (currentSessionId === sessionId) {
-                    const { clearSessionId } = await Promise.resolve().then(() => __importStar(require('../utils/state')));
-                    clearSessionId();
-                }
-            }
-            catch {
-                // Non-critical - continue if state clearing fails
+            if (active.length === 1) {
+                sessionId = active[0].sessionId;
             }
-            const firstName = await (0, messages_1.getUserFirstName)();
-            await (0, messages_1.printSuccessBanner)('Session Completed', `Great work, ${firstName}! Your session has been marked as complete.`);
-            (0, messages_1.printSuccess)('Session Ended Successfully', `"${title}" is now marked as completed.\n   View in dashboard: dashboard.neurcode.com`);
-            // Display Session ROI Summary
-            try {
-                // Fetch ROI summary from API
-                const apiUrl = config.apiUrl || process.env.NEURCODE_API_URL || 'https://api.neurcode.com';
-                const roiUrl = `${apiUrl}/api/v1/roi/summary?timeRange=7d`;
-                const roiResponse = await fetch(roiUrl, {
-                    headers: {
-                        'Authorization': `Bearer ${config.apiKey}`,
-                        'Content-Type': 'application/json',
-                    },
-                }).catch(() => null);
-                if (roiResponse && roiResponse.ok) {
-                    const roiData = await roiResponse.json().catch(() => null);
-                    if (roiData && roiData.totalCapitalSaved) {
-                        const capitalSaved = typeof roiData.totalCapitalSaved === 'string'
-                            ? parseFloat(roiData.totalCapitalSaved)
-                            : roiData.totalCapitalSaved;
-                        const formattedAmount = capitalSaved.toFixed(2);
-                        const dashboardUrl = 'https://neurcode.com/dashboard';
-                        console.log('');
-                        console.log(chalk.cyan('📊'), chalk.bold.white('Current Session ROI:'), chalk.green.bold(`+$${formattedAmount}`));
-                        console.log(chalk.dim(`   View full report: ${dashboardUrl}`));
-                        console.log('');
-                    }
+            else {
+                active.forEach((session, index) => {
+                    const title = session.title || session.intentDescription || 'Untitled';
+                    console.log(`  ${index + 1}. ${title} · ${session.sessionId}`);
+                });
+                const answer = await prompt(`Select cloud session to end (1-${active.length}): `);
+                const selected = Number.parseInt(answer, 10);
+                if (!Number.isInteger(selected) || selected < 1 || selected > active.length) {
+                    endSessionOutput(options, {
+                        ok: false,
+                        ended: false,
+                        mode: 'cloud',
+                        reason: 'invalid_cloud_selection',
+                        message: 'No cloud session was ended.',
+                    }, 2);
+                    return;
                 }
-            }
-            catch {
-                // Silently fail - ROI summary is a nice-to-have
+                sessionId = active[selected - 1].sessionId;
             }
         }
-        catch (error) {
-            if (error.message?.includes('not found') || error.message?.includes('404')) {
-                (0, messages_1.printError)('Session Not Found', error, [
-                    `Session "${sessionId}" could not be found`,
-                    'List your sessions: neurcode session list',
-                    'Verify the session ID is correct'
-                ]);
-            }
-            else {
-                throw error;
-            }
+        if (!sessionId) {
+            endSessionOutput(options, {
+                ok: false,
+                ended: false,
+                mode: 'cloud',
+                reason: 'cloud_session_not_resolved',
+                message: 'No cloud session could be resolved.',
+            }, 2);
+            return;
         }
-    }
-    catch (error) {
-        if (error instanceof Error) {
-            if (error.message.includes('401') || error.message.includes('403')) {
-                await (0, messages_1.printAuthError)(error);
+        const sessionData = await client.getSession(sessionId);
+        const session = sessionData.session;
+        if (session.status === 'completed' || session.status === 'cancelled') {
+            endSessionOutput(options, {
+                ok: true,
+                ended: false,
+                mode: 'cloud',
+                status: session.status,
+                sessionId,
+                message: `Cloud session ${sessionId} is already ${session.status}.`,
+            });
+            return;
+        }
+        if (isInteractive()) {
+            const confirm = await prompt(`End cloud session ${sessionId}? (y/n): `);
+            if (!['y', 'yes'].includes(confirm.toLowerCase())) {
+                endSessionOutput(options, {
+                    ok: true,
+                    ended: false,
+                    mode: 'cloud',
+                    reason: 'operator_cancelled',
+                    sessionId,
+                    message: 'Cloud session was not ended.',
+                });
+                return;
             }
-            else {
-                (0, messages_1.printError)('Failed to End Session', error);
+        }
+        await client.endSession(sessionId);
+        try {
+            if ((0, state_1.getSessionId)() === sessionId) {
+                const { clearSessionId } = await Promise.resolve().then(() => __importStar(require('../utils/state')));
+                clearSessionId();
             }
         }
-        else {
-            (0, messages_1.printError)('Failed to End Session', String(error));
+        catch {
+            // Legacy local cloud pointer cleanup is best-effort.
         }
-        process.exit(1);
+        endSessionOutput(options, {
+            ok: true,
+            ended: true,
+            mode: 'cloud',
+            status: 'completed',
+            sessionId,
+            message: `Cloud session ${sessionId} ended successfully.`,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const notFound = /not found|404/i.test(message);
+        endSessionOutput(options, {
+            ok: false,
+            ended: false,
+            mode: 'unknown',
+            reason: notFound ? 'session_not_found' : 'session_end_failed',
+            sessionId: options.sessionId || null,
+            error: message,
+            message: notFound
+                ? `Session ${options.sessionId || ''} was not found locally or in the cloud.`.trim()
+                : `Failed to end session: ${message}`,
+        }, notFound ? 2 : 1);
     }
 }
 /**