oh-my-codex 0.12.4 → 0.12.6

package/src/scripts/notify-hook/auto-nudge.ts

@@ -4,11 +4,18 @@
  * automatically send a continuation prompt so the agent keeps working.
  */
 
-import { readFile, writeFile } from 'fs/promises';
-import { join } from 'path';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { asNumber, safeString } from './utils.js';
-import { readJsonIfExists, getScopedStateDirsForCurrentSession, readdir } from './state-io.js';
+import {
+  getScopedStateDirsForCurrentSession,
+  getScopedStatePath,
+  readJsonIfExists,
+  readScopedJsonIfExists,
+  readdir,
+  writeScopedJson,
+} from './state-io.js';
 import { runProcess } from './process-runner.js';
 import { logTmuxHookEvent } from './log.js';
 import { evaluatePaneInjectionReadiness, mapPaneInjectionReadinessReason, sendPaneInput } from './team-tmux-guard.js';
@@ -26,6 +33,7 @@ import {
 export const SKILL_ACTIVE_STATE_FILE = 'skill-active-state.json';
 export const DEEP_INTERVIEW_BLOCKED_APPROVAL_INPUTS = ['yes', 'y', 'proceed', 'continue', 'ok', 'sure', 'go ahead', 'next i should'];
 export const DEEP_INTERVIEW_INPUT_LOCK_MESSAGE = 'Deep interview is active; auto-approval shortcuts are blocked until the interview finishes.';
+export const DEFAULT_AUTO_NUDGE_RESPONSE = 'continue with the current task only if it is already authorized';
 const DEEP_INTERVIEW_ERROR_PATTERNS = [' error', ' failed', ' failure', ' exception', 'unable to continue', 'cannot continue', 'could not continue'];
 const DEEP_INTERVIEW_ABORT_PATTERNS = ['aborted', 'cancelled', 'canceled'];
 const DEEP_INTERVIEW_ABORT_INPUTS = new Set(['abort', 'cancel', 'stop']);
@@ -171,29 +179,30 @@ export function inferSkillPhaseFromText(text, currentPhase = 'planning') {
   return normalizeSkillPhase(currentPhase);
 }
 
-async function loadSkillActiveState(stateDir) {
-  const raw = await readJsonIfExists(join(stateDir, SKILL_ACTIVE_STATE_FILE), null);
+async function loadSkillActiveState(stateDir, sessionId) {
+  const raw = await readScopedJsonIfExists(stateDir, SKILL_ACTIVE_STATE_FILE, sessionId, null);
   return normalizeSkillActiveState(raw);
 }
 
-async function persistSkillActiveState(stateDir, state) {
-  await writeFile(join(stateDir, SKILL_ACTIVE_STATE_FILE), JSON.stringify(state, null, 2)).catch(() => {});
+async function persistSkillActiveState(stateDir, sessionId, state) {
+  await writeScopedJson(stateDir, SKILL_ACTIVE_STATE_FILE, sessionId, state).catch(() => {});
 }
 
 
-export async function isDeepInterviewStateActive(stateDir) {
-  const modeState = await readJsonIfExists(join(stateDir, 'deep-interview-state.json'), null);
+export async function isDeepInterviewStateActive(stateDir, sessionId) {
+  const modeState = await readScopedJsonIfExists(stateDir, 'deep-interview-state.json', sessionId, null);
   return Boolean(modeState && modeState.active === true);
 }
 
-export async function isDeepInterviewInputLockActive(stateDir) {
-  const skillState = await loadSkillActiveState(stateDir);
+export async function isDeepInterviewInputLockActive(stateDir, sessionId) {
+  const skillState = await loadSkillActiveState(stateDir, sessionId);
   return isDeepInterviewAutoApprovalLocked(skillState);
 }
 
 export async function resolveAutoNudgeSignature(stateDir, payload, lastMessage = '') {
   const normalizedMessage = normalizeAutoNudgeSignatureText(lastMessage);
-  const hudState = await readJsonIfExists(join(stateDir, 'hud-state.json'), null);
+  const invocationSessionId = resolveInvocationSessionId(payload);
+  const hudState = await readScopedJsonIfExists(stateDir, 'hud-state.json', invocationSessionId, null);
   const hudTurnAt = safeString(hudState?.last_turn_at).trim();
   const hudTurnCount = Number.isFinite(hudState?.turn_count) ? hudState.turn_count : null;
   const hudMessage = normalizeAutoNudgeSignatureText(hudState?.last_agent_output || hudState?.last_agent_message || '');
@@ -218,70 +227,65 @@ function latestUserInputFromPayload(payload) {
 }
 
 export const DEFAULT_STALL_PATTERNS = [
-  'if you want',
-  'would you like',
-  'shall i',
-  'next i can',
   'continue with',
   'continue on',
-  'do you want me to',
-  'let me know if',
-  'do you want',
-  'want me to',
-  'let me know',
-  'just let me know',
-  'i can also',
-  'i could also',
   'pick up with',
-  'next step',
-  'next steps',
-  'ready to proceed',
-  'i\'m ready to',
   'keep going',
-  'should i',
-  'whenever you',
-  'say go',
-  'say yes',
-  'type continue',
   'and i\'ll continue',
-  'and i\'ll proceed',
   'keep driving',
   'keep pushing',
   'move forward',
   'drive forward',
-  'proceed from here',
   'i\'ll continue from',
 ];
 
 const SEMANTIC_STALL_PROMPT_PATTERNS = [
-  /\bif you want\b/g,
-  /\bwould you like\b/g,
-  /\bshall i\b/g,
-  /\bshould i\b/g,
-  /\bdo you want(?: me)? to\b/g,
-  /\bwant me to\b/g,
-  /\blet me know(?: if)?\b/g,
-  /\bjust let me know\b/g,
-  /\bi can also\b/g,
-  /\bi could also\b/g,
-  /\bnext i can\b/g,
   /\bcontinue (?:with|on)\b/g,
   /\bpick up with\b/g,
-  /\bnext steps?\b/g,
-  /\bready to proceed\b/g,
-  /\bi'?m ready to\b/g,
   /\bkeep going\b/g,
-  /\bwhenever you\b/g,
-  /\bsay (?:go|yes)\b/g,
-  /\btype continue\b/g,
-  /\band i'?ll (?:continue|proceed)\b/g,
+  /\band i'?ll continue\b/g,
   /\bkeep (?:driving|pushing)\b/g,
   /\bmove forward\b/g,
   /\bdrive forward\b/g,
-  /\bproceed from here\b/g,
   /\bi'?ll continue from\b/g,
 ];
 
+const PLANNING_ONLY_STALL_PATTERNS = [
+  'plan',
+  'planning',
+  'approach',
+  'proposal',
+  'options',
+  'review',
+  'feedback',
+  'spec',
+  'design',
+  'next step',
+  'next steps',
+  'ready to proceed',
+];
+
+const PERMISSION_SEEKING_STALL_PATTERNS = [
+  'if you want',
+  'would you like',
+  'shall i',
+  'should i',
+  'do you want me to',
+  'do you want',
+  'want me to',
+  'let me know if',
+  'let me know',
+  'just let me know',
+  'i can also',
+  'i could also',
+  'next i can',
+  'whenever you',
+  'say go',
+  'say yes',
+  'type continue',
+  'proceed from here',
+];
+
 function normalizeStallDetectionText(text) {
   return stripOrchestrationIntentTags(safeString(text))
     .replace(/\r\n?/g, '\n')
@@ -315,6 +319,52 @@ export function normalizeAutoNudgeSignatureText(text) {
   return normalized;
 }
 
+function normalizePatternList(patterns) {
+  return patterns.map((pattern) => normalizeStallDetectionText(pattern)).filter(Boolean);
+}
+
+function usesDefaultStallPatterns(patterns) {
+  const normalizedPatterns = normalizePatternList(patterns);
+  const normalizedDefaults = normalizePatternList(DEFAULT_STALL_PATTERNS);
+  return normalizedPatterns.length === normalizedDefaults.length
+    && normalizedPatterns.every((pattern, index) => pattern === normalizedDefaults[index]);
+}
+
+function matchesNormalizedPatterns(normalizedText, normalizedPatterns) {
+  if (!normalizedText || normalizedPatterns.length === 0) return false;
+  const tail = normalizedText.slice(-800);
+  const lines = tail.split('\n').filter((line) => line.trim());
+  const hotZone = lines.slice(-3).join('\n');
+  if (normalizedPatterns.some((pattern) => hotZone.includes(pattern))) return true;
+  return normalizedPatterns.some((pattern) => tail.includes(pattern));
+}
+
+function looksLikePlanningOnlyContinuation(normalizedText) {
+  return matchesNormalizedPatterns(normalizedText, normalizePatternList(PLANNING_ONLY_STALL_PATTERNS));
+}
+
+function looksLikePermissionSeekingContinuation(normalizedText) {
+  return matchesNormalizedPatterns(normalizedText, normalizePatternList(PERMISSION_SEEKING_STALL_PATTERNS));
+}
+
+/**
+ * Pattern to identify test-runner output lines (status symbols, PASS/FAIL prefixes).
+ * These lines may incidentally contain stall-pattern words inside test names and
+ * should be excluded before running stall detection on pane captures.
+ */
+const CAPTURE_TEST_LINE_RE = /^\s*(?:[✓✗✕×●✔✘▶◆○]|(?:PASS|FAIL|SKIP|ERROR)\s)/u;
+
+/**
+ * Strip lines that look like test-runner output so stall patterns inside test
+ * names (e.g. "✓ should continue with the next step") do not trigger a nudge.
+ */
+function filterCapturedTestLines(text) {
+  return safeString(text)
+    .split('\n')
+    .filter((line) => !CAPTURE_TEST_LINE_RE.test(line))
+    .join('\n');
+}
+
 function summarizePaneCaptureForLog(captured, maxLines = 6) {
   const lines = safeString(captured)
     .replace(/\r\n?/g, '\n')
@@ -358,6 +408,12 @@ export function normalizeAutoNudgeConfig(raw) {
   };
 }
 
+export function resolveEffectiveAutoNudgeResponse(response) {
+  const normalized = safeString(response).trim();
+  if (!normalized) return DEFAULT_AUTO_NUDGE_RESPONSE;
+  return isBlockedAutoApprovalInput(normalized) ? DEFAULT_AUTO_NUDGE_RESPONSE : normalized;
+}
+
 export async function loadAutoNudgeConfig() {
   const codexHomePath = process.env.CODEX_HOME || join(homedir(), '.codex');
   const configPath = join(codexHomePath, '.omx-config.json');
@@ -373,16 +429,16 @@ async function localTmuxInjectionDisabled(cwd) {
   return tmuxHookExplicitlyDisablesInjection(raw);
 }
 
-export function detectStallPattern(text, patterns) {
+export function detectStallPattern(text, patterns, currentPhase = '') {
   if (!text || typeof text !== 'string') return false;
   const normalized = normalizeStallDetectionText(text);
   if (!normalized) return false;
-  const tail = normalized.slice(-800);
-  const normalizedPatterns = patterns.map((pattern) => normalizeStallDetectionText(pattern)).filter(Boolean);
-  const lines = tail.split('\n').filter((line) => line.trim());
-  const hotZone = lines.slice(-3).join('\n');
-  if (normalizedPatterns.some((pattern) => hotZone.includes(pattern))) return true;
-  return normalizedPatterns.some((pattern) => tail.includes(pattern));
+  const normalizedPatterns = normalizePatternList(patterns);
+  if (!matchesNormalizedPatterns(normalized, normalizedPatterns)) return false;
+  if (!usesDefaultStallPatterns(patterns)) return true;
+  if (looksLikePermissionSeekingContinuation(normalized)) return false;
+  if (safeString(currentPhase).trim().toLowerCase() === 'planning') return false;
+  return !looksLikePlanningOnlyContinuation(normalized);
 }
 
 export async function capturePane(paneId, lines = 10) {
@@ -426,6 +482,7 @@ export async function resolveNudgePaneTarget(stateDir: any, cwd = '', payload: a
 
 export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
   const config = await loadAutoNudgeConfig();
+  const effectiveResponse = resolveEffectiveAutoNudgeResponse(config.response);
   if (!config.enabled) return;
   if (await localTmuxInjectionDisabled(cwd)) {
     await logTmuxHookEvent(logsDir, {
@@ -450,7 +507,8 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
 
   const lastMessage = safeString(payload['last-assistant-message'] || payload.last_assistant_message || '');
   const latestUserInput = latestUserInputFromPayload(payload);
-  let skillState = await loadSkillActiveState(stateDir);
+  const invocationSessionId = resolveInvocationSessionId(payload);
+  let skillState = await loadSkillActiveState(stateDir, invocationSessionId);
   let releaseReason = null;
 
   try {
@@ -460,23 +518,23 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
       skillState.active = inferredPhase !== 'completing';
       skillState.updated_at = new Date().toISOString();
       releaseReason = inferDeepInterviewReleaseReason({ skillState, latestUserInput, lastMessage });
-      await persistSkillActiveState(stateDir, skillState);
+      await persistSkillActiveState(stateDir, invocationSessionId, skillState);
     }
 
-    const nudgeStatePath = join(stateDir, 'auto-nudge-state.json');
-    let nudgeState = await readJsonIfExists(nudgeStatePath, null);
+    const nudgeStatePath = await getScopedStatePath(stateDir, 'auto-nudge-state.json', invocationSessionId);
+    let nudgeState = await readScopedJsonIfExists(stateDir, 'auto-nudge-state.json', invocationSessionId, null);
     if (!nudgeState || typeof nudgeState !== 'object') {
       nudgeState = { nudgeCount: 0, lastNudgeAt: '', lastSignature: '', lastSemanticSignature: '' };
     }
     const paneId = await resolveNudgePaneTarget(stateDir, cwd, payload);
 
-    let detected = detectStallPattern(lastMessage, config.patterns);
+    let detected = detectStallPattern(lastMessage, config.patterns, skillState?.phase);
     let source = 'payload';
     let captured = '';
 
     if (!detected && paneId) {
       captured = await capturePane(paneId);
-      detected = detectStallPattern(captured, config.patterns);
+      detected = detectStallPattern(filterCapturedTestLines(captured), config.patterns, skillState?.phase);
       source = 'capture-pane';
     }
 
@@ -523,6 +581,7 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
     if (!isFallbackWatcherSource && config.stallMs > 0) {
       nudgeState.pendingSignature = signature;
       nudgeState.pendingSince = new Date().toISOString();
+      await mkdir(dirname(nudgeStatePath), { recursive: true }).catch(() => {});
       await writeFile(nudgeStatePath, JSON.stringify(nudgeState, null, 2)).catch(() => {});
       await logTmuxHookEvent(logsDir, {
         timestamp: new Date().toISOString(),
@@ -556,10 +615,10 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
         timestamp: new Date().toISOString(),
         type: 'auto_nudge_blocked',
         pane_id: paneId,
-        response: config.response,
+        response: effectiveResponse,
         source,
         blocked_by: 'deep-interview-lock',
-        block_kind: isBlockedAutoApprovalInput(config.response, skillState.input_lock?.blocked_inputs)
+        block_kind: isBlockedAutoApprovalInput(effectiveResponse, skillState.input_lock?.blocked_inputs)
           ? 'blocked-auto-approval'
           : 'input-lock-active',
         message: blockedMessage,
@@ -576,7 +635,7 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
     try {
       const sendResult = await sendPaneInput({
         paneTarget: paneId,
-        prompt: `${config.response} ${DEFAULT_MARKER}`,
+        prompt: `${effectiveResponse} ${DEFAULT_MARKER}`,
         submitKeyPresses: 2,
         submitDelayMs: 100,
       });
@@ -590,20 +649,14 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
       nudgeState.lastSemanticSignature = semanticSignature;
       nudgeState.pendingSignature = '';
       nudgeState.pendingSince = '';
+      await mkdir(dirname(nudgeStatePath), { recursive: true }).catch(() => {});
       await writeFile(nudgeStatePath, JSON.stringify(nudgeState, null, 2)).catch(() => {});
 
-      if (skillState && skillState.phase === 'planning') {
-        skillState.phase = 'executing';
-        skillState.active = true;
-        skillState.updated_at = nowIso;
-        await persistSkillActiveState(stateDir, skillState);
-      }
-
       await logTmuxHookEvent(logsDir, {
         timestamp: nowIso,
         type: 'auto_nudge',
         pane_id: paneId,
-        response: config.response,
+        response: effectiveResponse,
         source,
         nudge_count: nudgeState.nudgeCount,
       });
@@ -618,7 +671,7 @@ export async function maybeAutoNudge({ cwd, stateDir, logsDir, payload }) {
   } finally {
     if (releaseReason && skillState && isDeepInterviewAutoApprovalLocked(skillState)) {
       releaseDeepInterviewInputLock(skillState, releaseReason, new Date().toISOString());
-      await persistSkillActiveState(stateDir, skillState).catch(() => {});
+      await persistSkillActiveState(stateDir, invocationSessionId, skillState).catch(() => {});
     }
   }
 }

package/src/scripts/notify-hook/managed-tmux.ts

@@ -1,9 +1,10 @@
 import { execFileSync } from 'child_process';
 import { readFileSync } from 'fs';
-import { basename, dirname, resolve as resolvePath } from 'path';
+import { basename, dirname } from 'path';
 import { readSessionState, isSessionStale } from '../../hooks/session.js';
 import { runProcess } from './process-runner.js';
 import { safeString } from './utils.js';
+import { sameFilePath } from '../../utils/paths.js';
 
 function sanitizeTmuxToken(value: string): string {
   const cleaned = safeString(value)
@@ -56,6 +57,10 @@ export function resolveInvocationSessionId(payload: any): string {
   ).trim();
 }
 
+function readNativeSessionId(sessionState: { native_session_id?: unknown; codex_session_id?: unknown }): string {
+  return safeString(sessionState.native_session_id || sessionState.codex_session_id || '').trim();
+}
+
 function readCurrentTmuxSessionName(): string {
   if (!process.env.TMUX) return '';
   try {
@@ -135,23 +140,32 @@ export async function resolveManagedSessionContext(cwd: string, payload: any, {
     if (!sessionState) {
       return { managed: false, reason: 'missing_session_state', invocationSessionId, sessionState: null, expectedTmuxSessionName: '', currentTmuxSessionName: '' };
     }
-    if (resolvePath(safeString(sessionState.cwd || cwd)) !== resolvePath(cwd)) {
+    if (!sameFilePath(safeString(sessionState.cwd || cwd), cwd)) {
       return { managed: false, reason: 'cwd_mismatch', invocationSessionId, sessionState, expectedTmuxSessionName: '', currentTmuxSessionName: '' };
     }
-    if (safeString(sessionState.session_id).trim() !== invocationSessionId) {
+    const canonicalSessionId = safeString(sessionState.session_id).trim();
+    const nativeSessionId = readNativeSessionId(sessionState);
+    const allowedInvocationIds = new Set([canonicalSessionId, nativeSessionId].filter(Boolean));
+    if (!allowedInvocationIds.has(invocationSessionId)) {
       return { managed: false, reason: 'session_id_mismatch', invocationSessionId, sessionState, expectedTmuxSessionName: '', currentTmuxSessionName: '' };
     }
     if (isSessionStale(sessionState)) {
       return { managed: false, reason: 'stale_session', invocationSessionId, sessionState, expectedTmuxSessionName: '', currentTmuxSessionName: '' };
     }
 
-    const expectedTmuxSessionName = buildExpectedManagedTmuxSessionName(cwd, invocationSessionId);
+    const authoritativeSessionCwd = safeString(sessionState.cwd || cwd).trim() || cwd;
+    const expectedTmuxSessionName = buildExpectedManagedTmuxSessionName(
+      authoritativeSessionCwd,
+      canonicalSessionId || invocationSessionId,
+    );
     const currentTmuxSessionName = readCurrentTmuxSessionName();
     if (currentTmuxSessionName && currentTmuxSessionName === expectedTmuxSessionName) {
       return {
         managed: true,
         reason: 'tmux_session_match',
         invocationSessionId,
+        canonicalSessionId,
+        nativeSessionId,
         sessionState,
         expectedTmuxSessionName,
         currentTmuxSessionName,
@@ -163,6 +177,8 @@ export async function resolveManagedSessionContext(cwd: string, payload: any, {
         managed: true,
         reason: currentTmuxSessionName ? 'pid_ancestry_match_tmux_mismatch' : 'pid_ancestry_match',
         invocationSessionId,
+        canonicalSessionId,
+        nativeSessionId,
         sessionState,
         expectedTmuxSessionName,
         currentTmuxSessionName: '',
@@ -173,6 +189,8 @@ export async function resolveManagedSessionContext(cwd: string, payload: any, {
       managed: false,
       reason: currentTmuxSessionName ? 'tmux_session_mismatch' : 'pid_ancestry_mismatch',
       invocationSessionId,
+      canonicalSessionId,
+      nativeSessionId,
       sessionState,
       expectedTmuxSessionName,
       currentTmuxSessionName,

package/src/scripts/notify-hook/operational-events.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from 'child_process';
 import { basename, dirname } from 'path';
 import { safeString } from './utils.js';
+import { upsertCurrentTaskBaseline } from '../../team/current-task-baseline.js';
 
 const TEST_SEGMENT_PATTERNS = [
   /^npm\s+(?:run\s+)?test\b/i,
@@ -216,6 +217,26 @@ export function buildOperationalContext({
   };
   const resolvedSessionName = resolveOperationalSessionName(cwd, sessionId, sessionName);
 
+  if (repoMeta.repo_path && repoMeta.branch) {
+    try {
+      const lifecycleStatus = normalizedEvent === 'pr-merged'
+        ? 'merged'
+        : normalizedEvent === 'pr-closed'
+          ? 'closed'
+          : undefined;
+      upsertCurrentTaskBaseline(repoMeta.repo_path, {
+        branch_name: repoMeta.branch,
+        worktree_path: repoMeta.worktree_path,
+        issue_number: detectedIssue,
+        pr_number: detectedPrInfo.pr_number,
+        pr_url: detectedPrInfo.pr_url,
+        ...(lifecycleStatus ? { status: lifecycleStatus } : {}),
+      });
+    } catch {
+      // best effort only; operational context building must stay non-fatal
+    }
+  }
+
   return {
     normalized_event: normalizedEvent,
     ...(resolvedSessionName ? { session_name: resolvedSessionName } : {}),

package/src/scripts/notify-hook/ralph-session-resume.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'fs';
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'fs/promises';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
 import { captureTmuxPaneFromEnv } from '../../state/mode-state-context.js';
+import { readUsableSessionState } from '../../hooks/session.js';
 import { resolveCodexPane } from '../tmux-hook-engine.js';
 import { safeString } from './utils.js';
 
@@ -128,7 +129,7 @@ function isActiveRalphCandidate(state: Record<string, unknown> | null): state is
 }
 
 async function readCurrentOmxSessionId(stateDir: string): Promise<string> {
-  const session = await readJson(join(stateDir, 'session.json'));
+  const session = await readUsableSessionState(resolve(stateDir, '..', '..'));
   const sessionId = safeString(session?.session_id).trim();
   return SESSION_ID_PATTERN.test(sessionId) ? sessionId : '';
 }

package/src/scripts/notify-hook/state-io.ts

@@ -2,8 +2,10 @@
  * State file I/O helpers for notify-hook modules.
  */
 
-import { readFile, readdir } from 'fs/promises';
-import { join } from 'path';
+import { mkdir, readFile, readdir, writeFile } from 'fs/promises';
+import { dirname, join, resolve } from 'path';
+import { existsSync } from 'fs';
+import { readUsableSessionState } from '../../hooks/session.js';
 import { asNumber, safeString } from './utils.js';
 
 const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
@@ -16,18 +18,93 @@ export function readJsonIfExists(path: string, fallback: any): Promise<any> {
     .catch(() => fallback);
 }
 
-export async function getScopedStateDirsForCurrentSession(baseStateDir: string): Promise<string[]> {
-  const sessionPath = join(baseStateDir, 'session.json');
-  try {
-    const session = JSON.parse(await readFile(sessionPath, 'utf-8'));
-    const sessionId = safeString(session && session.session_id ? session.session_id : '');
-    if (SESSION_ID_PATTERN.test(sessionId)) {
-      return [join(baseStateDir, 'sessions', sessionId)];
+function isSafeStateFileName(fileName: string): boolean {
+  return fileName.length > 0
+    && !fileName.includes('..')
+    && !fileName.includes('/')
+    && !fileName.includes('\\');
+}
+
+export async function readCurrentSessionId(baseStateDir: string): Promise<string | undefined> {
+  const cwd = resolve(baseStateDir, '..', '..');
+  const session = await readUsableSessionState(cwd);
+  const sessionId = safeString(session?.session_id);
+  return SESSION_ID_PATTERN.test(sessionId) ? sessionId : undefined;
+}
+
+export async function resolveScopedStateDir(
+  baseStateDir: string,
+  explicitSessionId?: string,
+): Promise<string> {
+  const currentSessionId = await readCurrentSessionId(baseStateDir);
+  if (currentSessionId) {
+    return join(baseStateDir, 'sessions', currentSessionId);
+  }
+
+  const normalizedExplicit = safeString(explicitSessionId).trim();
+  if (SESSION_ID_PATTERN.test(normalizedExplicit)) {
+    const explicitDir = join(baseStateDir, 'sessions', normalizedExplicit);
+    if (existsSync(explicitDir)) {
+      return explicitDir;
     }
-  } catch {
-    // No session file or malformed - fall back to global only
   }
-  return [baseStateDir];
+  return baseStateDir;
+}
+
+export async function getScopedStateDirsForCurrentSession(
+  baseStateDir: string,
+  explicitSessionId?: string,
+  options: { includeRootFallback?: boolean } = {},
+): Promise<string[]> {
+  const scopedDir = await resolveScopedStateDir(baseStateDir, explicitSessionId);
+  if (scopedDir === baseStateDir || options.includeRootFallback !== true) {
+    return [scopedDir];
+  }
+  return [scopedDir, baseStateDir];
+}
+
+export async function getScopedStatePath(
+  baseStateDir: string,
+  fileName: string,
+  explicitSessionId?: string,
+): Promise<string> {
+  if (!isSafeStateFileName(fileName)) {
+    throw new Error(`unsafe state file name: ${fileName}`);
+  }
+  return join(await resolveScopedStateDir(baseStateDir, explicitSessionId), fileName);
+}
+
+export async function readScopedJsonIfExists(
+  baseStateDir: string,
+  fileName: string,
+  explicitSessionId: string | undefined,
+  fallback: any,
+  options: { includeRootFallback?: boolean } = {},
+): Promise<any> {
+  if (!isSafeStateFileName(fileName)) {
+    throw new Error(`unsafe state file name: ${fileName}`);
+  }
+  const candidateDirs = await getScopedStateDirsForCurrentSession(
+    baseStateDir,
+    explicitSessionId,
+    options,
+  );
+  for (const dir of candidateDirs) {
+    const value = await readJsonIfExists(join(dir, fileName), fallback);
+    if (value !== fallback) return value;
+  }
+  return fallback;
+}
+
+export async function writeScopedJson(
+  baseStateDir: string,
+  fileName: string,
+  explicitSessionId: string | undefined,
+  value: unknown,
+): Promise<void> {
+  const targetPath = await getScopedStatePath(baseStateDir, fileName, explicitSessionId);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, JSON.stringify(value, null, 2));
 }
 
 export function normalizeTmuxState(raw: any): any {