helloagents 3.0.7 → 3.0.9-beta.1

package/scripts/notify-context.mjs

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { buildCommandRouteHint, buildStateSyncHint, buildWorkflowRouteHint } from './workflow-state.mjs';
+import { buildCommandRouteHint, buildStateSyncHint, buildWorkflowRouteHint, readStateSnapshot } from './workflow-state.mjs';
 import { buildCapabilityHint } from './capability-registry.mjs';
 import {
   buildProjectStorageBlock,
@@ -31,11 +31,6 @@ function resolveStandbyHostRoot(host) {
 }
 
 function resolveReadRoot({ cwd, pkgRoot, host, settings }) {
-  const projectRoot = join(cwd, 'skills', 'helloagents');
-  if (existsSync(projectRoot)) {
-    return { source: 'project', root: projectRoot };
-  }
-
   if (settings.install_mode === 'standby') {
     const standbyRoot = resolveStandbyHostRoot(host);
     if (standbyRoot && existsSync(standbyRoot)) {
@@ -48,7 +43,7 @@ function resolveReadRoot({ cwd, pkgRoot, host, settings }) {
 
 function buildReadRootBlock(readRoot) {
   if (!readRoot?.root) return '';
-  return `## 当前 HelloAGENTS 读取根目录\n\`\`\`json\n${JSON.stringify(readRoot, null, 2)}\n\`\`\``;
+  return `## 本轮 HelloAGENTS 读取根目录\n\`\`\`json\n${JSON.stringify(readRoot, null, 2)}\n\`\`\``;
 }
 
 export function resolveCanonicalCommandSkill(skillName) {
@@ -74,16 +69,14 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
   summaryParts.push('以下信息在上下文压缩前保存，确保压缩后不丢失关键状态。');
 
   const cwd = payload.cwd || process.cwd();
-  const statePath = join(cwd, '.helloagents', 'STATE.md');
-  const stateSyncHint = buildStateSyncHint(cwd);
-  if (existsSync(statePath)) {
-    try {
-      const stateContent = readFileSync(statePath, 'utf-8');
-      summaryParts.push('');
-      summaryParts.push('## 恢复快照（从 STATE.md 读取，只用于找回上次停在哪）');
-      summaryParts.push('恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续。');
-      summaryParts.push(stateContent);
-    } catch {}
+  const workflowOptions = { payload };
+  const stateSnapshot = readStateSnapshot(cwd, workflowOptions);
+  const stateSyncHint = buildStateSyncHint(cwd, workflowOptions);
+  if (stateSnapshot.exists && stateSnapshot.content) {
+    summaryParts.push('');
+    summaryParts.push(`## 恢复快照（从 ${stateSnapshot.statePath.replace(/\\/g, '/')} 读取，只用于找回上次停在哪）`);
+    summaryParts.push('恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续。');
+    summaryParts.push(stateSnapshot.content);
   }
 
   let bootstrap = '';
@@ -108,7 +101,7 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
     summaryParts.push(readRootBlock);
   }
 
-  const projectStorageBlock = buildProjectStorageBlock(cwd);
+  const projectStorageBlock = buildProjectStorageBlock(cwd, workflowOptions);
   if (projectStorageBlock) {
     summaryParts.push('');
     summaryParts.push(projectStorageBlock);
@@ -128,13 +121,15 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
   return summaryParts.join('\n');
 }
 
-export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host, cwd }) {
+export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host, cwd, payload = {} }) {
+  const workflowOptions = { payload };
   const packageRootBlock = buildPackageRootBlock(pkgRoot);
   const readRootBlock = buildReadRootBlock(resolveReadRoot({ cwd, pkgRoot, host, settings }));
-  const workflowHint = buildWorkflowRouteHint(cwd);
-  const capabilityHint = buildCapabilityHint({ cwd });
-  const projectStorageBlock = buildProjectStorageBlock(cwd);
-  const stateSyncHint = buildStateSyncHint(cwd);
+  const workflowHint = buildWorkflowRouteHint(cwd, workflowOptions);
+  const capabilityHint = buildCapabilityHint({ cwd, options: workflowOptions });
+  const projectStorageBlock = buildProjectStorageBlock(cwd, workflowOptions);
+  const stateSnapshot = readStateSnapshot(cwd, workflowOptions);
+  const stateSyncHint = buildStateSyncHint(cwd, workflowOptions);
   const settingsBlock = Object.keys(settings).length
     ? `\n\n## 当前用户设置\n\`\`\`json\n${JSON.stringify(settings, null, 2)}\n\`\`\``
     : '';
@@ -148,31 +143,33 @@ export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host,
   if (stateSyncHint) context += `\n\n## STATE.md 提醒\n${stateSyncHint}`;
   context += settingsBlock;
   if (source === 'resume' || source === 'compact') {
-    context += '\n\n> ⚠️ 会话已恢复/压缩，请先读取 `.helloagents/STATE.md` 恢复工作状态；先看当前用户消息确认仍是同一任务，再按 STATE.md 接续。';
+    context += `\n\n> ⚠️ 会话已恢复/压缩，请先读取当前 \`state_path\` 指向的 \`${stateSnapshot.statePath.replace(/\\/g, '/')}\` 恢复工作状态；先看当前用户消息确认仍是同一任务，再按 STATE.md 接续。`;
   }
   return context;
 }
 
-export function buildRouteInstruction({ skillName, extraRules = '', cwd, pkgRoot, host, settings }) {
+export function buildRouteInstruction({ skillName, extraRules = '', cwd, pkgRoot, host, settings, payload = {} }) {
+  const workflowOptions = { payload };
   const readRoot = resolveReadRoot({ cwd, pkgRoot, host, settings });
   const canonicalSkillName = resolveCanonicalCommandSkill(skillName);
   const skillPath = join(readRoot.root, 'skills', 'commands', canonicalSkillName, 'SKILL.md');
   const aliasNote = buildAliasRouteNote(skillName);
-  const commandHint = buildCommandRouteHint(canonicalSkillName, cwd);
-  const capabilityHint = buildCapabilityHint({ cwd, skillName: canonicalSkillName });
-  const projectStorageHint = buildProjectStorageHint(cwd);
+  const commandHint = buildCommandRouteHint(canonicalSkillName, cwd, workflowOptions);
+  const capabilityHint = buildCapabilityHint({ cwd, skillName: canonicalSkillName, options: workflowOptions });
+  const projectStorageHint = buildProjectStorageHint(cwd, workflowOptions);
   return `用户使用了 ~${skillName} 命令。当前命令技能文件已解析为：${skillPath}。请直接读取这个 SKILL.md；不要再探测其他 helloagents 路径。${aliasNote ? ` ${aliasNote}` : ''}${projectStorageHint ? ` ${projectStorageHint}` : ''}${commandHint ? ` ${commandHint}` : ''}${capabilityHint ? ` ${capabilityHint}` : ''}${extraRules}`;
 }
 
-export function buildSemanticRouteInstruction(cwd) {
-  const workflowHint = buildWorkflowRouteHint(cwd);
-  const capabilityHint = buildCapabilityHint({ cwd });
-  const projectStorageHint = buildProjectStorageHint(cwd);
+export function buildSemanticRouteInstruction(cwd, payload = {}) {
+  const workflowOptions = { payload };
+  const workflowHint = buildWorkflowRouteHint(cwd, workflowOptions);
+  const capabilityHint = buildCapabilityHint({ cwd, options: workflowOptions });
+  const projectStorageHint = buildProjectStorageHint(cwd, workflowOptions);
   return [
     '当前消息未使用 ~command。',
     '请根据用户请求的真实意图选路，不依赖关键词表。',
     'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆链路。',
-    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动选路。',
+    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动编排并自动衔接后续阶段。',
     '若判定为 T3，默认先走 ~plan / ~prd；纯审查/验证请求才优先 ~verify。',
     `涉及 UI 任务时，设计决策优先级：当前活跃 plan / PRD → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → 通用 UI 规则。`,
     projectStorageHint,

package/scripts/notify-route.mjs

@@ -17,6 +17,7 @@ function buildHelpExtraRules(skillName) {
 
 function routeExplicitCommand({
   prompt,
+  payload,
   cwd,
   host,
   pkgRoot,
@@ -51,6 +52,7 @@ function routeExplicitCommand({
     pkgRoot,
     host,
     settings,
+    payload,
   }))
   return true
 }
@@ -80,6 +82,7 @@ export function handleRouteCommand({
 
   if (routeExplicitCommand({
     prompt,
+    payload,
     cwd,
     host,
     pkgRoot,
@@ -100,9 +103,9 @@ export function handleRouteCommand({
       host,
       event: 'semantic_route_prompted',
       source: 'route',
-      recommendation: getWorkflowRecommendation(cwd),
+      recommendation: getWorkflowRecommendation(cwd, { payload }),
     })
-    suppress(buildSemanticRouteInstruction(cwd))
+    suppress(buildSemanticRouteInstruction(cwd, payload))
     return
   }
 

package/scripts/notify-source.mjs

@@ -1,42 +1,13 @@
 import { basename, normalize, resolve } from 'node:path'
 
+import { resolveSessionToken } from './session-token.mjs'
+
 const HOST_LABELS = {
   codex: 'Codex',
   claude: 'Claude Code',
   gemini: 'Gemini',
 }
 
-const PAYLOAD_SESSION_KEYS = [
-  'sessionId',
-  'session_id',
-  'session',
-  'conversationId',
-  'conversation_id',
-  'conversation',
-  'threadId',
-  'thread_id',
-  'thread',
-  'windowId',
-  'window_id',
-  'window',
-  'tabId',
-  'tab_id',
-  'tab',
-  'requestId',
-  'request_id',
-]
-
-const ENV_SESSION_KEYS = [
-  'HELLOAGENTS_NOTIFY_SESSION_ID',
-  'WT_SESSION',
-  'TERM_SESSION_ID',
-  'KITTY_WINDOW_ID',
-  'ALACRITTY_WINDOW_ID',
-  'WINDOWID',
-  'WEZTERM_PANE',
-  'TAB_ID',
-]
-
 function normalizePath(filePath = '') {
   if (!filePath) return ''
   try {
@@ -61,34 +32,6 @@ function resolveProjectLabel(cwd = '') {
   return label || normalized.replace(/\\/g, '/')
 }
 
-function sanitizeSessionToken(value = '') {
-  const raw = String(value).trim().replace(/^[#:\s]+/, '')
-  const segments = raw
-    .split(/[^a-zA-Z0-9]+/)
-    .filter(Boolean)
-  const cleaned = segments.length > 1
-    ? segments[segments.length - 1]
-    : raw.replace(/[^a-zA-Z0-9_-]/g, '')
-
-  if (!cleaned) return ''
-  if (/^\d+$/.test(cleaned)) return cleaned
-  return cleaned.slice(0, 8)
-}
-
-function resolveSessionToken(payload, env, ppid) {
-  for (const key of PAYLOAD_SESSION_KEYS) {
-    const value = sanitizeSessionToken(readStringCandidate(payload, key))
-    if (value) return value
-  }
-
-  for (const key of ENV_SESSION_KEYS) {
-    const value = sanitizeSessionToken(env?.[key] || '')
-    if (value) return value
-  }
-
-  return ppid ? String(ppid) : ''
-}
-
 export function resolveNotificationSource({
   host = '',
   cwd = '',
@@ -98,7 +41,7 @@ export function resolveNotificationSource({
 } = {}) {
   const hostLabel = HOST_LABELS[host] || 'Agent'
   const projectLabel = resolveProjectLabel(readStringCandidate(payload, 'cwd') || cwd)
-  const sessionToken = resolveSessionToken(payload, env, ppid)
+  const sessionToken = resolveSessionToken({ payload, env, ppid })
   const parts = [hostLabel]
 
   if (projectLabel) parts.push(projectLabel)

package/scripts/notify.mjs

@@ -10,11 +10,12 @@ import { homedir } from 'node:os';
 import { playSound as _playSound, desktopNotify as _desktopNotify } from './notify-ui.mjs';
 import { resolveNotificationSource } from './notify-source.mjs';
 import { buildCompactionContext, buildInjectContext, buildRouteInstruction, buildSemanticRouteInstruction, resolveCanonicalCommandSkill } from './notify-context.mjs';
-import { claimsTaskComplete, shouldIgnoreCodexNotifyClient, shouldIgnoreFormattedSubagent } from './notify-events.mjs';
+import { claimsTaskComplete, shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
 import { handleRouteCommand, resolveBootstrapFile } from './notify-route.mjs';
 import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress } from './notify-shared.mjs';
 import { clearRouteContext, writeRouteContext } from './runtime-context.mjs';
 import { appendReplayEvent, startReplaySession } from './replay-state.mjs';
+import { clearTurnState, readTurnState } from './turn-state.mjs';
 import { getWorkflowRecommendation } from './workflow-state.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -114,6 +115,20 @@ function readCompletionText(payload = {}) {
     || '';
 }
 
+function readMainTurnState(cwd) {
+  const turnState = readTurnState(cwd);
+  return turnState?.role === 'main' ? turnState : null;
+}
+
+function consumeMainTurnState(cwd, turnState) {
+  if (turnState?.role === 'main') clearTurnState(cwd);
+}
+
+function shouldProcessCloseout(turnState, lastMsg) {
+  if (turnState) return turnState.kind === 'complete';
+  return claimsTaskComplete(lastMsg);
+}
+
 function cmdPreCompact() {
   const payload = readStdinJson();
   const cwd = payload.cwd || process.cwd();
@@ -140,6 +155,7 @@ function cmdPreCompact() {
 
 function cmdRoute() {
   const payload = readStdinJson();
+  clearTurnState(payload.cwd || process.cwd());
   handleRouteCommand({
     payload,
     host: HOST,
@@ -192,8 +208,10 @@ function cmdInject() {
     pkgRoot: PKG_ROOT,
     host: HOST,
     cwd,
+    payload,
   });
   clearRouteContext();
+  clearTurnState(cwd);
   suppressedOutput(EVENT_NAME.SessionStart, context || undefined);
 }
 
@@ -201,13 +219,17 @@ function cmdStop() {
   const payload = readStdinJson();
   const lastMsg = readCompletionText(payload);
   const cwd = payload.cwd || process.cwd();
+  const turnState = readMainTurnState(cwd);
+  const shouldProcess = shouldProcessCloseout(turnState, lastMsg);
   clearRouteContext();
-  if (runRalphLoop(payload)) {
+  if (shouldProcess && runRalphLoop(payload)) {
+    consumeMainTurnState(cwd, turnState);
     playSound('warning');
     desktopNotify('warning', buildNotifyExtra(payload));
     return;
   }
-  if (claimsTaskComplete(lastMsg) && runDeliveryGate(payload)) {
+  if (shouldProcess && runDeliveryGate(payload)) {
+    consumeMainTurnState(cwd, turnState);
     playSound('warning');
     desktopNotify('warning', buildNotifyExtra(payload));
     return;
@@ -215,8 +237,11 @@ function cmdStop() {
 
   const settings = getSettings();
   const level = settings.notify_level ?? 0;
-  if (level === 2 || level === 3) playSound('complete');
-  if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(payload));
+  if (shouldProcess) {
+    if (level === 2 || level === 3) playSound('complete');
+    if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(payload));
+  }
+  consumeMainTurnState(cwd, turnState);
   emptySuppress();
 }
 
@@ -243,17 +268,23 @@ function cmdCodexNotify() {
   }
   if (type !== 'agent-turn-complete') return;
 
-  const lastMsg = data['last-assistant-message'] || '';
-  const settings = getSettings();
-  if (shouldIgnoreFormattedSubagent(lastMsg, settings.output_format !== false)) return;
-
   const cwd = data.cwd || process.cwd();
-  if (claimsTaskComplete(lastMsg) && runRalphLoop({ cwd })) {
+  const turnState = readMainTurnState(cwd);
+  if (!turnState) return;
+  if (turnState.kind !== 'complete') {
+    consumeMainTurnState(cwd, turnState);
+    return;
+  }
+
+  const settings = getSettings();
+  if (runRalphLoop(data)) {
+    consumeMainTurnState(cwd, turnState);
     playSound('warning');
     desktopNotify('warning', buildNotifyExtra(data));
     return;
   }
-  if (claimsTaskComplete(lastMsg) && runDeliveryGate({ cwd })) {
+  if (runDeliveryGate(data)) {
+    consumeMainTurnState(cwd, turnState);
     playSound('warning');
     desktopNotify('warning', buildNotifyExtra(data));
     return;
@@ -262,6 +293,7 @@ function cmdCodexNotify() {
   const level = settings.notify_level ?? 0;
   if (level === 2 || level === 3) playSound('complete');
   if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(data));
+  consumeMainTurnState(cwd, turnState);
 }
 
 const cmd = process.argv[2] || '';

package/scripts/project-storage.mjs

@@ -5,10 +5,13 @@ import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, normalize, resolve } from 'node:path'
 
 import { DEFAULTS } from './cli-config.mjs'
+import { resolveSessionToken } from './session-token.mjs'
 
 export const PROJECT_DIR_NAME = '.helloagents'
 const PROJECTS_DIR_NAME = 'projects'
+const PROJECT_SESSIONS_DIR_NAME = 'sessions'
 const PROJECT_STORE_MODES = new Set(['local', 'repo-shared'])
+const DEFAULT_STATE_SESSION_TOKEN = 'default'
 
 function safeJson(filePath) {
   try {
@@ -31,6 +34,19 @@ function runGitRevParse(cwd, args = []) {
   }
 }
 
+function runGitCommand(cwd, args = []) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf-8',
+      timeout: 5_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    return ''
+  }
+}
+
 function resolveGitTopLevel(cwd) {
   const absolute = runGitRevParse(cwd, ['--path-format=absolute', '--show-toplevel'])
   if (absolute) return normalize(absolute)
@@ -54,6 +70,16 @@ function sanitizeRepoName(value = '') {
   return normalized || 'project'
 }
 
+function sanitizeStateScopeSegment(value = '', fallback = '') {
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+  return normalized || fallback
+}
+
 function buildProjectKey(cwd) {
   const repoRoot = resolveGitTopLevel(cwd)
   const commonDir = resolveGitCommonDir(cwd, repoRoot)
@@ -87,6 +113,15 @@ function formatPromptPath(pathValue = '') {
   return pathValue ? normalize(pathValue).replace(/\\/g, '/') : ''
 }
 
+function resolveGitBranchName(cwd) {
+  const branchName = runGitRevParse(cwd, ['--abbrev-ref', 'HEAD'])
+  if (branchName && branchName !== 'HEAD') return branchName
+
+  const symbolicBranchName = runGitCommand(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+  if (symbolicBranchName && symbolicBranchName !== 'HEAD') return symbolicBranchName
+  return ''
+}
+
 export function normalizeProjectStoreMode(value) {
   const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
   return PROJECT_STORE_MODES.has(normalized) ? normalized : DEFAULTS.project_store_mode
@@ -105,8 +140,38 @@ export function getProjectActivationDir(cwd) {
   return join(cwd, PROJECT_DIR_NAME)
 }
 
-export function getProjectStatePath(cwd) {
-  return join(getProjectActivationDir(cwd), 'STATE.md')
+export function getProjectSessionStateScope(cwd, {
+  payload = {},
+  env = process.env,
+  ppid = process.ppid,
+} = {}) {
+  const rawSessionToken = resolveSessionToken({
+    payload,
+    env,
+    ppid,
+    allowPpidFallback: false,
+  })
+  const branchName = sanitizeStateScopeSegment(resolveGitBranchName(cwd), 'detached')
+  const sessionToken = sanitizeStateScopeSegment(rawSessionToken, DEFAULT_STATE_SESSION_TOKEN)
+  const sessionDir = join(
+    getProjectActivationDir(cwd),
+    PROJECT_SESSIONS_DIR_NAME,
+    branchName,
+    sessionToken,
+  )
+
+  return {
+    stateScope: 'session',
+    stateSessionToken: sessionToken,
+    stateSessionMode: rawSessionToken ? 'host-session' : 'default',
+    stateBranch: branchName,
+    sessionDir,
+    statePath: join(sessionDir, 'STATE.md'),
+  }
+}
+
+export function getProjectStatePath(cwd, options = {}) {
+  return getProjectSessionStateScope(cwd, options).statePath
 }
 
 export function isRepoSharedProjectStore(cwd) {
@@ -122,10 +187,10 @@ export function getProjectStoreDir(cwd) {
   return join(homedir(), PROJECT_DIR_NAME, PROJECTS_DIR_NAME, projectKey.key)
 }
 
-export function getProjectStoreSummary(cwd) {
+export function getProjectStoreSummary(cwd, options = {}) {
   const activationDir = getProjectActivationDir(cwd)
   const storeDir = getProjectStoreDir(cwd)
-  const statePath = getProjectStatePath(cwd)
+  const stateScope = getProjectSessionStateScope(cwd, options)
   const projectKey = buildProjectKey(cwd)
   const projectStoreMode = getProjectStoreMode(cwd)
 
@@ -133,14 +198,20 @@ export function getProjectStoreSummary(cwd) {
     projectStoreMode,
     activationDir,
     storeDir,
-    statePath,
+    statePath: stateScope.statePath,
+    stateScope: stateScope.stateScope,
+    stateSessionToken: stateScope.stateSessionToken,
+    stateSessionMode: stateScope.stateSessionMode,
+    stateBranch: stateScope.stateBranch,
+    sessionStateDir: stateScope.sessionDir,
     usesSharedStore: projectStoreMode === 'repo-shared',
     projectKey: projectKey.key,
     repoRoot: projectKey.repoRoot,
     commonDir: projectKey.commonDir,
     promptActivationDir: formatPromptPath(activationDir),
     promptStoreDir: formatPromptPath(storeDir),
-    promptStatePath: formatPromptPath(statePath),
+    promptStatePath: formatPromptPath(stateScope.statePath),
+    promptSessionStateDir: formatPromptPath(stateScope.sessionDir),
   }
 }
 
@@ -203,14 +274,21 @@ export function describeProjectStoreFile(cwd, relativePath = '') {
   return `逻辑路径 \`${logicalPath}\`（实际存储：\`${actualPath}\`）`
 }
 
-export function buildProjectStorageHint(cwd) {
-  const summary = getProjectStoreSummary(cwd)
-  if (!summary.usesSharedStore) return ''
-  return `项目存储：\`project_store_mode=repo-shared\`；本地激活/运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\`。`
+export function buildProjectStorageHint(cwd, options = {}) {
+  const summary = getProjectStoreSummary(cwd, options)
+  const hints = []
+  hints.push(`当前恢复快照统一写入 \`${summary.promptStatePath}\``)
+  if (summary.stateSessionMode === 'default') {
+    hints.push(`当前宿主未提供稳定会话标识，因此落到分支级默认会话槽位 \`${summary.stateSessionToken}\``)
+  }
+  if (summary.usesSharedStore) {
+    hints.push(`项目存储：\`project_store_mode=repo-shared\`；本地激活/运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\``)
+  }
+  return hints.join('。') + (hints.length > 0 ? '。' : '')
 }
 
-export function buildProjectStorageBlock(cwd) {
-  const summary = getProjectStoreSummary(cwd)
+export function buildProjectStorageBlock(cwd, options = {}) {
+  const summary = getProjectStoreSummary(cwd, options)
   if (!summary.usesSharedStore && !existsSync(summary.activationDir)) {
     return ''
   }
@@ -218,18 +296,32 @@ export function buildProjectStorageBlock(cwd) {
   const details = {
     project_store_mode: summary.projectStoreMode,
     activation_dir: summary.promptActivationDir,
+    state_scope: summary.stateScope,
     state_path: summary.promptStatePath,
+    state_branch: summary.stateBranch,
+    state_session_token: summary.stateSessionToken,
+    state_session_mode: summary.stateSessionMode,
+    session_state_dir: summary.promptSessionStateDir,
     knowledge_base_dir: summary.promptStoreDir,
     uses_shared_store: summary.usesSharedStore,
   }
 
+  const explanations = []
+  explanations.push('说明：恢复快照只认 `state_path` 这一个权威路径，不再读写旧的项目级 `.helloagents/STATE.md`。')
+  if (summary.stateSessionMode === 'default') {
+    explanations.push('说明：当前宿主未提供稳定会话标识，因此自动使用分支级默认会话槽位，仍保持新目录结构。')
+  }
+  if (summary.usesSharedStore) {
+    explanations.push('说明：`STATE.md` 与 `.ralph-*.json` 继续写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
+  } else {
+    explanations.push('说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。')
+  }
+
   return [
     '## 当前项目存储',
     '```json',
     JSON.stringify(details, null, 2),
     '```',
-    summary.usesSharedStore
-      ? '说明：`STATE.md` 与 `.ralph-*.json` 继续写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。'
-      : '说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。',
+    ...explanations,
   ].join('\n')
 }

package/scripts/session-token.mjs

@@ -0,0 +1,73 @@
+const PAYLOAD_SESSION_KEYS = [
+  'sessionId',
+  'session_id',
+  'session',
+  'conversationId',
+  'conversation_id',
+  'conversation',
+  'threadId',
+  'thread_id',
+  'thread',
+  'windowId',
+  'window_id',
+  'window',
+  'tabId',
+  'tab_id',
+  'tab',
+  'requestId',
+  'request_id',
+]
+
+const ENV_SESSION_KEYS = [
+  'HELLOAGENTS_NOTIFY_SESSION_ID',
+  'WT_SESSION',
+  'TERM_SESSION_ID',
+  'KITTY_WINDOW_ID',
+  'ALACRITTY_WINDOW_ID',
+  'WINDOWID',
+  'WEZTERM_PANE',
+  'TAB_ID',
+]
+
+function readStringCandidate(input, key) {
+  if (!input || typeof input !== 'object') return ''
+  const value = input[key]
+  if (typeof value === 'string') return value.trim()
+  if (typeof value === 'number') return String(value)
+  return ''
+}
+
+export function sanitizeSessionToken(value = '') {
+  const raw = String(value).trim().replace(/^[#:\s]+/, '')
+  const segments = raw
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+  const cleaned = segments.length > 1
+    ? segments[segments.length - 1]
+    : raw.replace(/[^a-zA-Z0-9_-]/g, '')
+
+  if (!cleaned) return ''
+  if (/^\d+$/.test(cleaned)) return cleaned
+  return cleaned.slice(0, 8)
+}
+
+export function resolveSessionToken({
+  payload = {},
+  env = process.env,
+  ppid = process.ppid,
+  allowPpidFallback = true,
+} = {}) {
+  for (const key of PAYLOAD_SESSION_KEYS) {
+    const value = sanitizeSessionToken(readStringCandidate(payload, key))
+    if (value) return value
+  }
+
+  for (const key of ENV_SESSION_KEYS) {
+    const value = sanitizeSessionToken(env?.[key] || '')
+    if (value) return value
+  }
+
+  return allowPpidFallback && ppid ? String(ppid) : ''
+}
+
+export { ENV_SESSION_KEYS, PAYLOAD_SESSION_KEYS }