elanous 0.2.29 → 0.2.32

package/src/git-fs/index.ts

@@ -9,7 +9,7 @@
 // on its own cadence (dashboard throttles to ~2s).
 
 import { resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { execFile, spawnSync } from 'node:child_process';
 import { findGitDir, type LocatedGit } from './locate.js';
 import { readGitHead } from './read-head.js';
 import { GitFileWatcher } from './watcher.js';
@@ -31,13 +31,62 @@ export { probeDirty, probeAheadBehind, parsePorcelain } from './dirty.js';
 const SNAPSHOT_TIMEOUT_MS = 5_000;
 const SNAPSHOT_STATUS_MAX_CHARS = 2_000;
 const GIT_SNAPSHOT_TTL_MS = 3_000;
+/** A cached snapshot older than this is rebuilt in the background on the next periodic dirty tick. */
+const GIT_SNAPSHOT_KEEP_WARM_MS = 30_000;
 
 interface GitSnapshotCacheEntry {
   at: number;
+  /** Monotonic store ordering — `at` can flip within the same millisecond. */
+  version: number;
   value: string | null;
 }
 
 const gitSnapshotCache = new Map<string, GitSnapshotCacheEntry>();
+/** The entry an invalidation (known write · HEAD move) just evicted. Only the
+ *  stale-while-revalidate turn path reads it, and only while it is younger than
+ *  its window: the turn is served the last snapshot (its header states when it
+ *  was taken) while the background rebuild runs, instead of rebuilding
+ *  synchronously on the event loop. Any later store supersedes it. */
+const gitSnapshotLastKnown = new Map<string, GitSnapshotCacheEntry>();
+
+function storeGitSnapshot(key: string, entry: Omit<GitSnapshotCacheEntry, 'version'>): void {
+  gitSnapshotCache.set(key, { ...entry, version: bumpGitSnapshotVersion(key) });
+  gitSnapshotLastKnown.delete(key);
+}
+
+function evictGitSnapshot(key: string): boolean {
+  const entry = gitSnapshotCache.get(key);
+  if (!entry) return false;
+  gitSnapshotCache.delete(key);
+  gitSnapshotLastKnown.set(key, entry);
+  return true;
+}
+/** One background snapshot rebuild per cwd and invalidation generation. */
+const gitSnapshotInFlight = new Map<string, { generation: string; promise: Promise<string | null> }>();
+
+/** Per-key monotonic store version: async rebuilds never overwrite a newer
+ *  sync value, not even when both land in the same millisecond (`at`
+ *  comparisons can flip). Generation guards invalidation races instead. */
+const gitSnapshotVersion = new Map<string, number>();
+
+function gitSnapshotVersionOf(key: string): number {
+  return gitSnapshotVersion.get(key) ?? 0;
+}
+
+function bumpGitSnapshotVersion(key: string): number {
+  const version = gitSnapshotVersionOf(key) + 1;
+  gitSnapshotVersion.set(key, version);
+  return version;
+}
+
+/** Test-only hold seam (production null): parks an async rebuild after its
+ *  reads and before its store, so «a write during a rebuild wins» is provable
+ *  deterministically instead of by racing timers. */
+let gitSnapshotRebuildHold: (() => void | Promise<void>) | null = null;
+
+export function __setGitSnapshotRebuildHoldForTest(hold: (() => void | Promise<void>) | null): void {
+  gitSnapshotRebuildHold = hold;
+}
 
 interface CacheEntry {
   located: LocatedGit;
@@ -97,8 +146,15 @@ function ensureEntry(cwd: string): CacheEntry | null {
   // Re-read HEAD + retarget watcher whenever a watched file changes.
   // One handler covers all listeners so we don't race each subscriber.
   watcher.subscribe(() => {
+    const before = entry.head;
     entry.head = readGitHead(entry.located);
     entry.watcher.retargetForHead(entry.head);
+    // A branch/ref move makes every cached snapshot's branch + log lines wrong. Only a real
+    // move: macOS fs.watch also replays the ref write that happened just before the watch was
+    // installed (measured: refs/heads/main «change» right after the first build), and that
+    // spurious event must not evict a fresh snapshot.
+    if (headMoved(before, entry.head)) invalidateAllGitSnapshots();
+    else debug.log('git-fs.snapshot', 'watch-event-head-unchanged', { root: entry.located.root });
     for (const fn of entry.listeners) {
       try { fn(); } catch { /* noop */ }
     }
@@ -179,8 +235,8 @@ function viewOf(entry: CacheEntry): GitStatusView {
 /** Non-blocking twin of `refreshDirty` for the TUI: the probes run as
  *  async subprocesses so a slow `git status` (large worktree, loaded
  *  host) never stalls key input. Same throttle; concurrent calls share
- *  one probe, except that `force` (a known write just happened) never
- *  reuses a probe that started before it. */
+ *  one probe. `force` also marks cached LLM snapshots stale and rebuilds
+ *  them in the background — a known write happened. */
 export function refreshDirtyAsync(
   cwd: string,
   opts: { minIntervalMs?: number; force?: boolean } = {},
@@ -188,26 +244,40 @@ export function refreshDirtyAsync(
   let entry: CacheEntry | null;
   try { entry = ensureEntry(cwd); } catch (error) { return Promise.reject(error); }
   if (!entry) return Promise.resolve({ head: null, dirty: null, aheadBehind: null, lastDirtyProbeAt: 0 });
-  // An in-flight probe (possibly a forced, post-write one) is newer than the last stored view.
+  // An in-flight probe (possibly a forced, post-write one) is newer than the last stored view —
+  // a throttled call joins it instead of returning the pre-write view (#27493 contract).
   const running = dirtyInFlight.get(entry);
   if (running && !opts.force) return running;
   const min = opts.minIntervalMs ?? 2_000;
   if (!opts.force && entry.lastDirtyProbeAt > 0 && Date.now() - entry.lastDirtyProbeAt < min) {
     return Promise.resolve(viewOf(entry));
   }
-  const target = entry;
-  const root = target.located.root;
+  const probe = probeDirtyAsyncFor(entry, { fresh: !!opts.force });
+  // After the post-write probe is queued, so the snapshot rebuild joins it instead of an older one.
+  if (opts.force) invalidateGitSnapshots(cwd);
+  // Keep-warm: the dashboard's periodic (non-forced) dirty tick also re-warms a snapshot that is in
+  // use, so a turn typed after an idle stretch is served within the stale window instead of falling
+  // back to the synchronous build. Only snapshots already cached are kept warm.
+  else if (gitSnapshotCache.has(resolve(cwd)) || gitSnapshotLastKnown.has(resolve(cwd))) void refreshGitSnapshotAsync(cwd, { ifOlderThanMs: GIT_SNAPSHOT_KEEP_WARM_MS });
+  return probe;
+}
+
+/** Share the in-flight probe, unless the caller needs one that started after
+ *  now (`fresh`: a known write just happened) — then queue a new probe behind it. */
+function probeDirtyAsyncFor(entry: CacheEntry, opts: { fresh: boolean }): Promise<GitStatusView> {
+  const running = dirtyInFlight.get(entry);
+  if (running && !opts.fresh) return running;
+  const root = entry.located.root;
   const start = (): Promise<GitStatusView> => Promise.all([probeDirtyAsync(root), probeAheadBehindAsync(root)])
     .then(([dirty, aheadBehind]) => {
-      target.dirty = dirty;
-      target.aheadBehind = aheadBehind;
-      target.lastDirtyProbeAt = Date.now();
-      return viewOf(target);
+      entry.dirty = dirty;
+      entry.aheadBehind = aheadBehind;
+      entry.lastDirtyProbeAt = Date.now();
+      return viewOf(entry);
     });
-  // A forced probe queues behind the running one so it reads the post-write tree.
   const probe = (running ? running.then(start, start) : start())
-    .finally(() => { if (dirtyInFlight.get(target) === probe) dirtyInFlight.delete(target); });
-  dirtyInFlight.set(target, probe);
+    .finally(() => { if (dirtyInFlight.get(entry) === probe) dirtyInFlight.delete(entry); });
+  dirtyInFlight.set(entry, probe);
   return probe;
 }
 
@@ -217,7 +287,7 @@ export function refreshDirtyAsync(
  *  fresh state after mutations. Returns null outside a git repo. */
 export function buildGitSnapshot(
   cwd: string,
-  opts: { now?: () => number; ttlMs?: number } = {},
+  opts: { now?: () => number; ttlMs?: number; staleWhileRevalidateMs?: number } = {},
 ): string | null {
   const now = opts.now ?? Date.now;
   const ttlMs = opts.ttlMs ?? GIT_SNAPSHOT_TTL_MS;
@@ -228,41 +298,157 @@ export function buildGitSnapshot(
     debug.log('git-fs.snapshot', 'cache-hit', { cwd, ageMs: at - cached.at });
     return cached.value;
   }
+  // Stale-while-revalidate (TUI turn path): serve the recent snapshot now
+  // and rebuild it off the event loop for the next turn.
+  if (cached && opts.staleWhileRevalidateMs !== undefined && at - cached.at < opts.staleWhileRevalidateMs) {
+    debug.log('git-fs.snapshot', 'stale-hit', { cwd, ageMs: at - cached.at });
+    void refreshGitSnapshotAsync(cwd);
+    return cached.value;
+  }
+  // Invalidated (known write · HEAD move) and the background rebuild has not
+  // stored yet: serve the evicted snapshot rather than a synchronous rebuild —
+  // the TYPING-LAG this path exists to remove. Bounded by the same window.
+  const evicted = !cached ? gitSnapshotLastKnown.get(key) : undefined;
+  if (evicted && opts.staleWhileRevalidateMs !== undefined && at - evicted.at < opts.staleWhileRevalidateMs) {
+    debug.log('git-fs.snapshot', 'stale-after-invalidate', { cwd, ageMs: at - evicted.at, rebuilding: gitSnapshotInFlight.has(key) });
+    void refreshGitSnapshotAsync(cwd);
+    return evicted.value;
+  }
 
   const view = refreshDirty(cwd, { force: true });
   let value: string | null = null;
   if (view.head) {
-    const branch = view.head.branch ?? `HEAD@${view.head.sha?.slice(0, 7) ?? 'unknown'}`;
-    const mainBranch = detectDefaultBranch(cwd);
-    const status = runGit(cwd, ['status', '--short']);
-    const recentLog = runGit(cwd, ['log', '--oneline', '-n', '5']);
-    const userName = runGit(cwd, ['config', 'user.name']);
-    const truncatedStatus = status.length > SNAPSHOT_STATUS_MAX_CHARS
-      ? `${status.slice(0, SNAPSHOT_STATUS_MAX_CHARS)}\n... (truncated; run git status for more)`
-      : status;
-
-    const parts = [
-      'This is the git status at the start of this turn. It is a snapshot and will not update during the turn.',
-      `Current branch: ${branch}${view.head.isWorktree ? ' (worktree)' : ''}`,
-      mainBranch ? `Main branch: ${mainBranch}` : '',
-      userName ? `Git user: ${userName}` : '',
-      view.aheadBehind
-        ? `Upstream: ahead ${view.aheadBehind.ahead}, behind ${view.aheadBehind.behind}`
-        : '',
-      `Status:\n${truncatedStatus || '(clean)'}`,
-      `Recent commits:\n${recentLog || '(none)'}`,
-    ].filter(Boolean);
-    value = parts.join('\n\n');
+    value = composeGitSnapshot(view, {
+      mainBranch: detectDefaultBranch(cwd),
+      status: runGit(cwd, ['status', '--short']),
+      recentLog: runGit(cwd, ['log', '--oneline', '-n', '5']),
+      userName: runGit(cwd, ['config', 'user.name']),
+      generatedAt: at,
+    });
   }
 
-  gitSnapshotCache.set(key, { at, value });
+  storeGitSnapshot(key, { at, value });
   debug.log('git-fs.snapshot', 'built', { cwd, ageMs: 0 });
   return value;
 }
 
+function composeGitSnapshot(
+  view: GitStatusView,
+  git: { mainBranch: string | null; status: string; recentLog: string; userName: string; generatedAt: number },
+): string {
+  const head = view.head!;
+  const branch = head.branch ?? `HEAD@${head.sha?.slice(0, 7) ?? 'unknown'}`;
+  const truncatedStatus = git.status.length > SNAPSHOT_STATUS_MAX_CHARS
+    ? `${git.status.slice(0, SNAPSHOT_STATUS_MAX_CHARS)}\n... (truncated; run git status for more)`
+    : git.status;
+  const parts = [
+    `This is the git status as of ${new Date(git.generatedAt).toISOString()}. It is a snapshot and will not update during the turn.`,
+    `Current branch: ${branch}${head.isWorktree ? ' (worktree)' : ''}`,
+    git.mainBranch ? `Main branch: ${git.mainBranch}` : '',
+    git.userName ? `Git user: ${git.userName}` : '',
+    view.aheadBehind
+      ? `Upstream: ahead ${view.aheadBehind.ahead}, behind ${view.aheadBehind.behind}`
+      : '',
+    `Status:\n${truncatedStatus || '(clean)'}`,
+    `Recent commits:\n${git.recentLog || '(none)'}`,
+  ].filter(Boolean);
+  return parts.join('\n\n');
+}
+
+/** Rebuild the snapshot for `cwd` with async subprocesses and store it.
+ *  Concurrent calls share one rebuild. Never throws. `ifOlderThanMs` turns it
+ *  into a keep-warm tick: a cached snapshot younger than that is left alone. */
+export function refreshGitSnapshotAsync(cwd: string, opts: { ifOlderThanMs?: number } = {}): Promise<string | null> {
+  const key = resolve(cwd);
+  const cached = gitSnapshotCache.get(key);
+  if (cached && opts.ifOlderThanMs !== undefined && Date.now() - cached.at < opts.ifOlderThanMs) {
+    return Promise.resolve(cached.value);
+  }
+  const generation = snapshotGeneration(key);
+  const running = gitSnapshotInFlight.get(key);
+  if (running && running.generation === generation) return running.promise;
+  const startedAt = Date.now();
+  const startVersion = gitSnapshotVersionOf(key);
+  const rebuild = (async (): Promise<string | null> => {
+    const entry = ensureEntry(cwd);
+    // Joins the in-flight probe; callers that need a post-write/post-move probe queue a fresh one first.
+    const view = entry ? await probeDirtyAsyncFor(entry, { fresh: false }) : getGitStatusView(cwd);
+    let value: string | null = null;
+    if (view.head) {
+      const [mainBranch, status, recentLog, userName] = await Promise.all([
+        detectDefaultBranchAsync(cwd),
+        runGitAsync(cwd, ['status', '--short']),
+        runGitAsync(cwd, ['log', '--oneline', '-n', '5']),
+        runGitAsync(cwd, ['config', 'user.name']),
+      ]);
+      // «as of» = when the reads finished, not when the rebuild was queued.
+      value = composeGitSnapshot(view, { mainBranch, status, recentLog, userName, generatedAt: Date.now() });
+    }
+    // Test-only hold seam: reads are done, the store decision is next.
+    if (gitSnapshotRebuildHold) await gitSnapshotRebuildHold();
+    // An invalidation that landed mid-rebuild wins: keep the entry stale.
+    // A newer entry (e.g. a synchronous build that overlapped this rebuild) is
+    // kept — ordered by monotonic version, never by `at` (same-ms flips).
+    const current = gitSnapshotCache.get(key);
+    if (snapshotGeneration(key) === generation && !(current && current.version > startVersion)) {
+      storeGitSnapshot(key, { at: startedAt, value });
+    }
+    debug.log('git-fs.snapshot', 'rebuilt-async', { cwd, ms: Date.now() - startedAt });
+    return value;
+  })()
+    .catch(() => null)
+    .finally(() => { if (gitSnapshotInFlight.get(key)?.promise === rebuild) gitSnapshotInFlight.delete(key); });
+  gitSnapshotInFlight.set(key, { generation, promise: rebuild });
+  return rebuild;
+}
+
+/** Invalidation generations: a rebuild only stores its result when no
+ *  invalidation (per cwd or global) landed while it was running. */
+const gitSnapshotGeneration = new Map<string, number>();
+let allGitSnapshotsGeneration = 0;
+
+function snapshotGeneration(key: string): string {
+  return `${allGitSnapshotsGeneration}:${gitSnapshotGeneration.get(key) ?? 0}`;
+}
+
+function invalidateAllGitSnapshots(): void {
+  // Snapshots that were in use (cached or being rebuilt) are re-warmed for the next turn.
+  const inUse = new Set([...gitSnapshotCache.keys(), ...gitSnapshotInFlight.keys()]);
+  for (const key of [...gitSnapshotCache.keys()]) evictGitSnapshot(key);
+  allGitSnapshotsGeneration += 1;
+  // Probes already running read the old ref's upstream — queue one fresh probe per repo behind
+  // them, so the rebuilds below join it instead.
+  const entries = new Set<CacheEntry>();
+  for (const key of inUse) {
+    const entry = ensureEntry(key);
+    if (entry) entries.add(entry);
+  }
+  for (const entry of entries) void probeDirtyAsyncFor(entry, { fresh: true });
+  for (const key of inUse) void refreshGitSnapshotAsync(key);
+}
+
+/** A known write happened: the cached snapshot must not be served again.
+ *  When a snapshot was in use (cached or being rebuilt), rebuild it in the
+ *  background so the next turn usually still hits. */
+function invalidateGitSnapshots(cwd: string): void {
+  const key = resolve(cwd);
+  const wasCached = evictGitSnapshot(key);
+  const wasRebuilding = gitSnapshotInFlight.has(key);
+  gitSnapshotGeneration.set(key, (gitSnapshotGeneration.get(key) ?? 0) + 1);
+  // An in-flight rebuild of the old generation will be discarded — schedule its replacement.
+  if (wasCached || wasRebuilding) void refreshGitSnapshotAsync(cwd);
+}
+
+function headMoved(before: GitHeadInfo | null | undefined, after: GitHeadInfo | null | undefined): boolean {
+  if (!before || !after) return before !== after;
+  return before.branch !== after.branch || before.sha !== after.sha || before.detached !== after.detached;
+}
+
 /** Explicitly discard cached git snapshots, including cached non-repositories. */
 export function clearGitSnapshotCache(): void {
   gitSnapshotCache.clear();
+  gitSnapshotLastKnown.clear();
+  allGitSnapshotsGeneration += 1;
 }
 
 function detectDefaultBranch(cwd: string): string | null {
@@ -281,6 +467,34 @@ function detectDefaultBranch(cwd: string): string | null {
   return null;
 }
 
+async function detectDefaultBranchAsync(cwd: string): Promise<string | null> {
+  const symbolic = await runGitAsync(cwd, ['symbolic-ref', 'refs/remotes/origin/HEAD']);
+  if (symbolic.startsWith('refs/remotes/origin/')) {
+    return symbolic.slice('refs/remotes/origin/'.length).trim() || null;
+  }
+  for (const candidate of ['main', 'master', 'develop']) {
+    if (await gitSucceeds(cwd, ['show-ref', '--verify', '--quiet', `refs/heads/${candidate}`])) return candidate;
+  }
+  return null;
+}
+
+function gitSucceeds(cwd: string, args: string[]): Promise<boolean> {
+  return new Promise((resolveOk) => {
+    try { execFile('git', args, { cwd, timeout: SNAPSHOT_TIMEOUT_MS }, (error) => resolveOk(!error)); }
+    catch { resolveOk(false); }
+  });
+}
+
+function runGitAsync(cwd: string, args: string[]): Promise<string> {
+  return new Promise((resolveOut) => {
+    try {
+      execFile('git', args, { cwd, encoding: 'utf8', timeout: SNAPSHOT_TIMEOUT_MS, maxBuffer: 2 * 1024 * 1024 }, (error, stdout) => {
+        resolveOut(error ? '' : String(stdout ?? '').trim());
+      });
+    } catch { resolveOut(''); }
+  });
+}
+
 function runGit(cwd: string, args: string[]): string {
   const res = spawnSync('git', args, {
     cwd,
@@ -292,10 +506,23 @@ function runGit(cwd: string, args: string[]): string {
   return String(res.stdout ?? '').trim();
 }
 
+/** Test helper — the cached snapshot for `cwd` without building one. */
+export function __peekGitSnapshot(cwd: string): string | null | undefined {
+  return gitSnapshotCache.get(resolve(cwd))?.value;
+}
+
+/** Test helper — what a HEAD move does to cached snapshots. */
+export function __invalidateAllGitSnapshotsForTest(): void {
+  invalidateAllGitSnapshots();
+}
+
 /** Test helper — drop the cache + dispose every watcher. */
 export function __resetGitFsCache(): void {
   for (const [, entry] of cache) entry.watcher.dispose();
   cache.clear();
   clearGitSnapshotCache();
+  gitSnapshotInFlight.clear();
   dirtyInFlight.clear();
+  gitSnapshotGeneration.clear();
+  gitSnapshotVersion.clear();
 }

package/src/github/remote-call.ts

@@ -0,0 +1,81 @@
+import { debug } from '../debug/log.js';
+
+/** One measured execution at a GitHub boundary. Never put an URL, arguments, token, or body here. */
+export interface GithubRemoteCall {
+  kind: 'rest' | 'graphql' | 'gh-command' | 'git-clone' | 'git-fetch' | 'git-push';
+  caller: string;
+  route: string;
+  method?: string;
+  host: string;
+  scopeId?: string;
+  runId?: string;
+  retry?: number;
+}
+
+export interface GithubRemoteOutcome<T> {
+  failed: boolean;
+  result?: T;
+  error?: unknown;
+}
+
+export interface GithubRemoteCallOptions<T> {
+  /** Return an observed HTTP status only; CLI success alone is not HTTP 200. */
+  status?: (outcome: GithubRemoteOutcome<T>) => number | undefined;
+  now?: () => number;
+  emit?: (category: string, event: string, data: Record<string, unknown>) => void;
+}
+
+/** Execute the real call and record exactly one completion, including failures. Observation cannot change the result. */
+export async function runGithubRemoteCall<T>(
+  call: GithubRemoteCall,
+  execute: () => Promise<T>,
+  options: GithubRemoteCallOptions<T> = {},
+): Promise<T> {
+  const now = options.now ?? Date.now;
+  const safeNow = (): number | undefined => {
+    try { const value = now(); return Number.isFinite(value) ? value : undefined; } catch { return undefined; }
+  };
+  const started = safeNow();
+  let outcome: GithubRemoteOutcome<T> = { failed: false };
+  try {
+    const result = await execute();
+    outcome = { failed: false, result };
+    return result;
+  } catch (error) {
+    outcome = { failed: true, error };
+    throw error;
+  } finally {
+    let status: number | undefined;
+    try { status = options.status?.(outcome); } catch { /* telemetry must not alter the call */ }
+    const ended = safeNow();
+    const data: Record<string, unknown> = {
+      kind: call.kind,
+      caller: call.caller,
+      route: call.route,
+      method: call.method ?? 'unmeasured',
+      host: call.host,
+      scopeId: call.scopeId ?? 'unmeasured',
+      runId: call.runId ?? '',
+      retry: call.retry ?? 'unmeasured',
+      status: status ?? 'unmeasured',
+      ok: !outcome.failed,
+      durationMs: started === undefined || ended === undefined ? 'unmeasured' : Math.max(0, ended - started),
+    };
+    try { (options.emit ?? debug.log.bind(debug))('github.transport', 'complete', data); } catch { /* same rule */ }
+  }
+}
+
+/** Only a real GitHub remote belongs in the Git transport denominator. */
+export function isGithubGitRemote(remote: string): boolean {
+  let host: string | undefined;
+  if (remote.includes('://')) {
+    try {
+      const url = new URL(remote);
+      if (!['http:', 'https:', 'ssh:', 'git:'].includes(url.protocol)) return false;
+      host = url.hostname;
+    } catch { return false; }
+  } else {
+    host = /^(?:[^@\s]+@)?([^:/\s]+):[^\s]+$/.exec(remote)?.[1];
+  }
+  return host === 'github.com' || host === 'ssh.github.com';
+}

package/src/goals/registry.ts

@@ -75,8 +75,18 @@ export function hydrateGoalFromSnapshot(): Goal | null {
       persistSnapshot(null);
       return null;
     }
-    current = parsed;
-    debug.log('goal', 'snapshot.hydrated', { id: current.id, status: current.status });
+    // TUI-GOAL-LOOP-FRICTION(#35) — 프로세스가 죽어 있던 시간은 이 목표가 «돈» 시간이 아니다.
+    //   active 로 되살아나면 벽시계 기준을 지금으로 다시 잡는다(낡은 createdAt 기준 4.9억 ms 소진 오판 방지).
+    const now = Date.now();
+    const staleStart = goalWallClockStart(parsed);
+    current = parsed.status === 'active'
+      ? { ...parsed, activeSince: now, usage: { ...parsed.usage, elapsedMs: 0 } }
+      : parsed;
+    debug.log('goal', 'snapshot.hydrated', {
+      id: current.id, status: current.status,
+      wallClockRestarted: parsed.status === 'active',
+      staleElapsedMs: Math.max(0, now - staleStart),
+    });
     notify(current, null);
     return getCurrentGoal();
   } catch (error) {
@@ -100,12 +110,25 @@ export function generateGoalId(): string {
   return `g-${ts}-${rand}`;
 }
 
+/** TUI-GOAL-LOOP-FRICTION(#35) — 벽시계 예산의 기준 시각 = 이번에 active 로 들어선 때.
+ *  옛 스냅숏(activeSince 없음)만 createdAt 으로 떨어진다. */
+export function goalWallClockStart(goal: Goal): number {
+  return typeof goal.activeSince === 'number' && Number.isFinite(goal.activeSince)
+    ? goal.activeSince
+    : goal.createdAt;
+}
+
+/** 이번 활성화 기준 벽시계 경과(ms). 시계가 거꾸로 가도 음수는 내지 않는다. */
+export function goalWallClockElapsedMs(goal: Goal, now: number): number {
+  return Math.max(0, now - goalWallClockStart(goal));
+}
+
 export function getCurrentGoal(): Goal | null {
   if (!current) return null;
   // Refresh elapsed ms on read so callers don't see stale values.
   return {
     ...current,
-    usage: { ...current.usage, elapsedMs: Date.now() - current.createdAt },
+    usage: { ...current.usage, elapsedMs: goalWallClockElapsedMs(current, Date.now()) },
   };
 }
 
@@ -155,6 +178,7 @@ export function startGoal(input: GoalCreateInput): { ok: true; goal: Goal } | {
     status: 'active',
     createdAt: now,
     updatedAt: now,
+    activeSince: now,
     budget,
     usage: { turnsUsed: 0, tokensUsed: 0, tokensMeasured: true, elapsedMs: 0 },
     linkedTaskId: input.linkedTaskId,
@@ -173,8 +197,22 @@ export function setStatus(next: GoalStatus, reason?: string): { ok: true; goal:
     return { ok: false, error: { code: 'GoalNotFound', message: 'No active goal.' } };
   }
   const prev = { ...current };
-  current = { ...current, status: next, updatedAt: Date.now() };
+  const now = Date.now();
+  // TUI-GOAL-LOOP-FRICTION(#35) — paused·budget-limited·resume_required → active 는 «새 활성화»다.
+  //   벽시계는 여기서 다시 잰다 — 멈춰 있던 시간(며칠)을 이번 실행 예산에 싣지 않는다.
+  const reactivated = next === 'active' && prev.status !== 'active';
+  current = {
+    ...current,
+    status: next,
+    updatedAt: now,
+    ...(reactivated ? { activeSince: now, usage: { ...current.usage, elapsedMs: 0 } } : {}),
+  };
   debug.log('goal', 'status', { id: current.id, from: prev.status, to: next, reason: reason ?? '' });
+  if (reactivated) {
+    debug.log('goal', 'wall-clock-restart', {
+      id: current.id, from: prev.status, priorElapsedMs: goalWallClockElapsedMs(prev, now),
+    });
+  }
   try {
     writeGoalTransitionLedger({
       timestamp: new Date().toISOString(),
@@ -210,7 +248,7 @@ export function recordTurn(opts: { tokens?: number; verdict?: Goal['lastVerdict'
       turnsUsed: current.usage.turnsUsed + 1,
       tokensUsed: current.usage.tokensUsed + (opts.tokens ?? 0),
       tokensMeasured: current.usage.tokensMeasured && opts.tokens !== undefined,
-      elapsedMs: Date.now() - current.createdAt,
+      elapsedMs: goalWallClockElapsedMs(current, Date.now()),
     },
     lastVerdict: opts.verdict ?? current.lastVerdict,
     lastSummary: opts.summary ?? current.lastSummary,
@@ -251,7 +289,9 @@ const NO_GOAL_BUDGET_DIAGNOSTICS: GoalBudgetDiagnostics = {
 export function evaluateGoalBudget(goal: Goal, now: number): GoalBudgetDiagnostics {
   const { turnsUsed, tokensUsed, elapsedMs, tokensMeasured } = goal.usage;
   const { maxTurns, tokenBudget, wallClockMaxMs } = goal.budget;
-  const elapsedWallClockMs = Math.max(elapsedMs, now - goal.createdAt);
+  // TUI-GOAL-LOOP-FRICTION(#35) — 기준 = 이번 활성화 시작(activeSince · 옛 스냅숏만 createdAt).
+  //   usage.elapsedMs 도 같은 기준으로만 쓰인다(재활성화·hydrate 때 0 으로 되돌린다).
+  const elapsedWallClockMs = Math.max(elapsedMs, goalWallClockElapsedMs(goal, now));
   const exceededAxes = [
     ...(turnsUsed >= maxTurns ? [{ axis: 'maxTurns' as const, used: turnsUsed, limit: maxTurns }] : []),
     ...(tokenBudget > 0 && tokensUsed >= tokenBudget

package/src/goals/types.ts

@@ -69,7 +69,8 @@ export interface GoalUsage {
   tokensUsed: number;
   /** Whether every recorded auto-turn supplied a token measurement. */
   tokensMeasured: boolean;
-  /** Wall-clock since createdAt, refreshed on read. */
+  /** Wall-clock since this activation began (`activeSince`, falling back to
+   *  `createdAt` for old snapshots), refreshed on read. */
   elapsedMs: number;
 }
 
@@ -97,6 +98,11 @@ export interface Goal {
   status: GoalStatus;
   /** Epoch ms. */
   createdAt: number;
+  /** TUI-GOAL-LOOP-FRICTION(#35) — epoch ms when the goal last entered `active`
+   *  (start · resume · process restart hydrate). The wall-clock budget is measured
+   *  from here, not from `createdAt`: a goal created days ago and resumed now must
+   *  not report 4.9e8 ms elapsed. Optional so older snapshots still parse. */
+  activeSince?: number;
   /** Last time status transitioned. */
   updatedAt: number;
   budget: GoalBudget;

package/src/graph-runner/runner.ts

@@ -34,6 +34,7 @@ const RELEASE_NODE_COMMANDS: Readonly<Record<string, { recipe: string; command?:
   'checklist-gate': { recipe: 'cmd:checklist-gate', command: 'bun scripts/release-loop/checklist-gate-node.ts' },
   prefetch: { recipe: 'cmd:docs', command: 'bun scripts/release-loop/docs-node.ts --json' },
   gate: { recipe: 'cmd:gate', command: 'bun scripts/release-loop/gate-node.ts --json' },
+  'gate-triage': { recipe: 'cmd:gate-triage', command: 'bun scripts/release-loop/gate-triage-node.ts' },
   'mac-smoke': { recipe: 'cmd:mac-smoke', command: 'bun scripts/release-loop/mac-smoke-node.ts' },
   'export-check': { recipe: 'cmd:export-check', command: 'bun scripts/release-loop/export-check-node.ts' },
   pwa: { recipe: 'cmd:pwa', command: 'bun scripts/release-loop/node-verdict.ts pwa' },

package/src/grok/credential.ts

@@ -478,6 +478,32 @@ export function isGrokSubscriptionExpiring(
   return (opts.now ?? Date.now)() + (opts.bufferMs ?? GROK_REFRESH_BUFFER_MS) >= ms;
 }
 
+/** 구독 만료 상태 — 칸 CRED-EXPIRY-REFRESH 기준 창. 이 안에 만료가 오면 갱신 후보다. */
+export const GROK_EXPIRY_SOON_WINDOW_MS = 2 * 60 * 60 * 1000;
+
+/** 만료 상태 셋 — ⛔ boolean 으로 접으면 「모름」과 «여유»가 «같은 값»이 된다. */
+export type GrokSubscriptionExpiryState = 'healthy' | 'expiring' | 'unknown';
+
+/** 실제로 쓸 구독(key 를 가진 scope 중 가장 늦게 만료되는 것)의 expires_at 만으로 상태를 가른다.
+ *
+ * ⭐ 칸 CRED-EXPIRY-REFRESH 첫 조각 — «토큰 없이» 읽는다:
+ *   · 선택 규칙은 `readSubscriptionToken` 과 «같다»(key 없는 항목의 만료에 속지 않는다).
+ *   · 반환은 상태 «하나»뿐 — 토큰 값은 어떤 형태로도 나가지 않는다.
+ *   · 기존 `isGrokSubscriptionExpiring`(boolean)은 모름을 false 로 접는다 — 이 함수는
+ *     모름을 'unknown' 으로 «별도의 값»으로 낸다. 갱신 유도·호스트 발사는 후속 조각.
+ * · 순수 판정 — 부수효과가 없고, 파일이 못 읽히면 죽이지 않고 'unknown' 을 낸다. */
+export function grokSubscriptionExpiryState(
+  opts: { home?: string; bufferMs?: number; now?: () => number } = {},
+): GrokSubscriptionExpiryState {
+  const raw = readSubscriptionToken(grokAuthFilePath(opts.home))?.expiresAt ?? null;
+  if (raw === null) return 'unknown';
+  const ms = Date.parse(raw);
+  if (!Number.isFinite(ms)) return 'unknown';
+  return (opts.now ?? Date.now)() + (opts.bufferMs ?? GROK_EXPIRY_SOON_WINDOW_MS) >= ms
+    ? 'expiring'
+    : 'healthy';
+}
+
 /** 갱신 경로의 관측 — ⛔ 토큰은 «절대» 싣지 않는다(판정·결과·출처만). */
 function observeGrokAuth(event: string, data: Record<string, unknown>): void {
   try {