@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/plugins/trailhead/hooks/mod/register.tsx

@@ -6,26 +6,47 @@
 import { atom, read, update } from 'claude-code'
 import type { EngineInterface, Register } from 'claude-code'
 
-import type { PromptSnapshot, WorkState } from '../../types'
-import { registerMapPane } from './map-pane'
-import { promptSection, repoSlug, snapshotKey } from './work-state-prompt'
-import { fit, isMissing, nextOwnTicket, parseWorkState, pipeline, sameValue, statusLine } from './work-state-view'
+import type { AutoRun, PromptSnapshot, RepoPin, RunCounts, WorkState } from '../../types'
+import { RESUME_HINT, runLabel, showsResumeHint } from './auto-run-view'
+import { clearRunCounts, readRunCounts, scanRun } from './auto-run'
+import { followWhiteboard, onPinMove, registerMapPane } from './map-pane'
+import { pinKey, pinPath, refreshPin } from './repo-pin'
+import { isMainTurnRunning, markTurnComplete, markTurnStart } from './turn-state'
+import { isForeignState, isOwnState, locateOwnState, noteFound, wasFoundElsewhere } from './work-state-locate'
+import { sessionLiveness } from './session-registry'
+import { promptSection, snapshotKey } from './work-state-prompt'
+import { ELSEWHERE, fit, isMissing, nextOwnTicket, parseWorkState, pipeline, sameValue, statusLine } from './work-state-view'
 import type { StageStatus } from './work-state-view'
 
 export const workState = atom({ plugin: 'trailhead', key: 'workState' } as const, null as WorkState | null)
+// A foreign state is "orphaned" (not this session's, nothing in play); `isElsewhere` says the session
+// that wrote it is not known gone, so the wording is neutral and offers no resume.
 export const isOrphaned = atom({ plugin: 'trailhead', key: 'isOrphaned' } as const, false)
+export const isElsewhere = atom({ plugin: 'trailhead', key: 'isElsewhere' } as const, false)
 // The ticket this session works, kept across a work-state file other sessions share.
 export const ownTicket = atom({ plugin: 'trailhead', key: 'ownTicket' } as const, null as number | null)
 export const promptSnapshot = atom({ plugin: 'trailhead', key: 'promptSnapshot' } as const, null as PromptSnapshot | null)
+// The repo pin refreshPin keeps (repo-pin.ts); the module scan wants the atom spelled in the file that reads it,
+// so this copy and the one in repo-pin.ts must keep the same { plugin, key }.
+const repoPin = atom({ plugin: 'trailhead', key: 'repoPin' } as const, null as RepoPin | null)
+
+// L'ultimo run trovato accanto al main checkout, i suoi conteggi di scope e il flag di ripresa (Esc o compattazione).
+export const autoRun = atom({ plugin: 'trailhead', key: 'autoRun' } as const, null as AutoRun | null)
+export const runCounts = atom({ plugin: 'trailhead', key: 'runCounts' } as const, null as RunCounts | null)
+export const autoInterrupted = atom({ plugin: 'trailhead', key: 'autoInterrupted' } as const, false)
 
 const STATE_PATH = '.trailhead/work-state.json'
 const HELPER = 'trailhead-work-state.js'
 const ACCENT = '#7aa2f7'
 const GREEN = '#9ece6a'
 const AMBER = '#e0af68'
+const AUTO_COMMAND = 'trailhead:auto'
 const SECTION_ID = 'trailhead:work-state'
+const STALE_NOTE =
+  'No trailhead ticket is in play any more: the earlier `# trailhead work state` section of the system prompt is stale.'
 
 type Dollar = EngineInterface
+type RefreshInit = { isStart?: boolean; fresh?: boolean }
 
 // The status text last pinned; the sentinel makes the first refresh set or clear it.
 // (A hot reload resets it, which only costs one repeated status call.)
@@ -34,8 +55,7 @@ let shownStatus: string | undefined | typeof UNSET = UNSET
 // Refreshes run one after the other, so two events never interleave their writes.
 let queue: Promise<void> = Promise.resolve()
 
-function pin($: Dollar, state: WorkState | null, orphaned: boolean) {
-  const text = statusLine(state, orphaned)
+function pin($: Dollar, text: string | undefined) {
   if (text === shownStatus) return
   shownStatus = text
   $.ui.status(text)
@@ -47,15 +67,114 @@ async function setWorkState($: Dollar, value: WorkState | null) {
   if (!sameValue(current, value)) await update($, workState, () => value)
 }
 
+async function setRun($: Dollar, value: AutoRun | null) {
+  const current = await read($, autoRun)
+  if (!sameValue(current, value)) await update($, autoRun, () => value)
+}
+
+async function setCounts($: Dollar, value: RunCounts | null) {
+  const current = await read($, runCounts)
+  if (!sameValue(current, value)) await update($, runCounts, () => value)
+}
+
+async function setInterrupted($: Dollar, value: boolean) {
+  const current = await read($, autoInterrupted)
+  if (current !== value) await update($, autoInterrupted, () => value)
+}
+
+// Lo status si ricalcola per ultimo, da tutti gli atom: stato, run, conteggi e suggerimento.
+async function showStatus($: Dollar) {
+  const state = await read($, workState)
+  const run = await read($, autoRun)
+  const hint = showsResumeHint(await read($, autoInterrupted), run)
+  const elsewhere = await read($, isElsewhere)
+  pin($, statusLine(state, await read($, isOrphaned), { run, counts: await read($, runCounts), hint, elsewhere }))
+}
+
+async function mainRootOf($: Dollar): Promise<string | null> {
+  try {
+    return (await $.session.repo())?.root ?? null
+  } catch {
+    return null
+  }
+}
+
+// Il run dei checkout accanto al main (il main working tree, non quello della sessione); solo lettura.
+async function settleRun($: Dollar, state: WorkState | null) {
+  let run: AutoRun | null = null
+  let found: RunCounts | null = null
+  try {
+    const pinned = await read($, repoPin)
+    const main = (await mainRootOf($)) ?? pinned?.root ?? null
+    if (main !== null) {
+      const scanned = await scanRun($, { main, pinned: pinned?.root ?? main, ownState: state })
+      run = scanned.run
+      if (run !== null && pinned !== null) found = await readRunCounts($, pinned, scanned.scope)
+    }
+  } catch (err) {
+    debug($, `trailhead mod: autonomous run scan failed: ${String(err)}`)
+  }
+  if (run === null) clearRunCounts()
+  await setRun($, run)
+  await setCounts($, run === null ? null : found)
+}
+
 async function setOrphaned($: Dollar, value: boolean) {
   const current = await read($, isOrphaned)
   if (current !== value) await update($, isOrphaned, () => value)
 }
 
-// null means "rebuild on the next compose"; written only when it changes.
+async function setElsewhere($: Dollar, value: boolean) {
+  const current = await read($, isElsewhere)
+  if (current !== value) await update($, isElsewhere, () => value)
+}
+
+// Le sessioni chiuse da un /clear di questa: per loro lo stato e' orfano subito, senza guardare il registro.
+const ended = new Set<string>()
+
+// Il registro delle sessioni del motore (<config>/sessions/<pid>.json). Il pid si controlla solo dove c'e'
+// /proc (Linux); altrove conta la presenza della voce. Ogni errore e' "unknown": mai orfano per un dubbio.
+async function registryDir($: Dollar): Promise<string | null> {
+  const config = await $.env.get('CLAUDE_CONFIG_DIR')
+  if (config !== undefined && config !== '') return `${config}/sessions`
+  const home = await $.env.get('HOME')
+  return home === undefined || home === '' ? null : `${home}/.claude/sessions`
+}
+
+async function foreignIsGone($: Dollar, sessionId: string): Promise<boolean> {
+  try {
+    if (ended.has(sessionId)) return true
+    const dir = await registryDir($)
+    if (dir === null) return false
+    const hasProc = await $.fs.exists('/proc/self').catch(() => false)
+    const liveness = await sessionLiveness(dir, sessionId, {
+      list: async path => (await $.fs.list(path)).filter(e => e.kind === 'file').map(e => e.name),
+      read: path => $.fs.read(path) as Promise<string>,
+      pidAlive: async pid => (hasProc ? $.fs.exists(`/proc/${pid}`) : null),
+    })
+    return liveness === 'gone'
+  } catch (err) {
+    debug($, `trailhead mod: session registry lookup failed: ${String(err)}`)
+    return false
+  }
+}
+
+// What the latch was last set to, per session, once the atom write succeeded. Overlapping calls may see the
+// atom as it stood when they began, so the compare-and-set in changeNote trusts this copy first; a hot
+// reload falls back to the atom.
+const told = new Map<string, PromptSnapshot | null>()
+
+async function latchedNow($: Dollar): Promise<PromptSnapshot | null> {
+  const session = await $.session.id()
+  return told.has(session) ? (told.get(session) as PromptSnapshot | null) : read($, promptSnapshot)
+}
+
+// null means "rebuild on the next compose"; written only when it changes. The mirror follows a
+// successful write only, so a denied write leaves the latch (and the mirror) as they were.
 async function setSnapshot($: Dollar, value: PromptSnapshot | null) {
   const current = await read($, promptSnapshot)
   if (!sameValue(current, value)) await update($, promptSnapshot, () => value)
+  told.set(await $.session.id(), value)
 }
 
 const debug = ($: Dollar, message: string) => {
@@ -66,35 +185,69 @@ const debug = ($: Dollar, message: string) => {
   }
 }
 
-// The latched text: rebuilt only when its key changed or the snapshot was reset.
-// A repo that cannot be read only costs the links, never the section.
-async function readSlug($: Dollar): Promise<string | null> {
+// What the state says now: its key and section text, with the links following the pin.
+// The links follow the pin, so a shell `cd` out of the repo never loses them; no pin only costs the links.
+async function liveSnapshot($: Dollar): Promise<PromptSnapshot> {
+  const state = await read($, workState)
+  const orphaned = await read($, isOrphaned)
+  const pinned = await read($, repoPin)
+  const repo = pinned === null ? null : { host: pinned.host, slug: pinned.slug }
+  return { key: snapshotKey(state, orphaned, repo), text: promptSection(state, orphaned, repo) }
+}
+
+// The latch is what the model was told. Only the first persisting compose after a reset (latch null:
+// session start, compaction, /clear) writes it; a later compose returns the latched text, so the system
+// prompt stays what the engine already holds (it composes every turn but keeps sending the first one).
+// After that only prompt.submit advances the latch. A non-persisting (/context) compose never writes.
+async function currentSnapshot($: Dollar, persist: boolean): Promise<PromptSnapshot> {
+  const latched = await read($, promptSnapshot)
+  if (latched !== null) return latched
+  const live = await liveSnapshot($)
+  if (persist) await setSnapshot($, live)
+  return live
+}
+
+// The latch compare-and-set runs one at a time, so two overlapping prompts attach a change once.
+let latchQueue: Promise<unknown> = Promise.resolve()
+function serial<T>(task: () => Promise<T>): Promise<T> {
+  const run = latchQueue.then(task, task)
+  latchQueue = run.catch(() => undefined)
+  return run
+}
+
+// A change after the latch reaches the model as context on the next prompt, once per change; no latch
+// yet means the compose will carry it. The latch moves to the live snapshot here; `previous` is what to
+// put back if the prompt does not enter.
+async function changeNote($: Dollar): Promise<{ note: string | null; previous: PromptSnapshot | null; live: PromptSnapshot | null }> {
+  const none = { note: null, previous: null, live: null }
+  const latched = await latchedNow($)
+  if (latched === null) return none
+  const live = await liveSnapshot($)
+  if (live.key === latched.key) return none
   try {
-    return repoSlug((await $.session.repo())?.remote ?? null)
+    await setSnapshot($, live)
   } catch (err) {
-    debug($, `trailhead mod: repo read failed: ${String(err)}`)
-    return null
+    // The latch stays where it was: the next prompt retries, and this one goes on without the note.
+    debug($, `trailhead mod: latch write failed: ${String(err)}`)
+    return none
   }
+  const note = live.text !== null ? live.text : latched.text === null ? null : STALE_NOTE
+  return { note, previous: latched, live }
 }
 
-// With `persist` false (a /context render) the snapshot is computed but never stored.
-async function currentSnapshot($: Dollar, persist: boolean): Promise<PromptSnapshot> {
-  const state = await read($, workState)
-  const orphaned = await read($, isOrphaned)
-  const key = snapshotKey(state, orphaned)
-  const latched = await read($, promptSnapshot)
-  if (latched !== null && latched.key === key) return latched
-  const slug = state === null || orphaned ? null : await readSlug($)
-  const built = { key, text: promptSection(state, orphaned, slug) }
-  if (persist) await setSnapshot($, built)
-  return built
+// A dropped prompt told the model nothing: put the latch back, unless something else moved it since.
+async function restoreLatch($: Dollar, previous: PromptSnapshot, live: PromptSnapshot) {
+  const current = await latchedNow($)
+  if (current !== null && current.key === live.key) await setSnapshot($, previous)
 }
 
-async function apply($: Dollar, state: WorkState | null, orphaned: boolean) {
+async function apply($: Dollar, state: WorkState | null, orphaned: boolean, elsewhere = false) {
   const isStale = state !== null && orphaned
   await setWorkState($, state)
   await setOrphaned($, isStale)
-  pin($, state, isStale)
+  await setElsewhere($, isStale && elsewhere)
+  await settleRun($, state)
+  await showStatus($)
 }
 
 // Decided from the state read before this refresh replaces it.
@@ -104,10 +257,39 @@ async function setOwnTicket($: Dollar, next: WorkState | null) {
   if (value !== prev) await update($, ownTicket, () => value)
 }
 
-async function refresh($: Dollar) {
+// The state text: the pinned checkout's file, whatever the session cwd is now; without a pin (no GitHub
+// repo ever seen) it stays relative to the cwd, as before. A missing file there sends the lookup to the
+// repo's other checkouts (#270): the engine writes the state in the ticket's own workspace. A clean miss
+// rethrows the own one, so the caller sees what it saw before; a broken lookup, when the state was found
+// elsewhere before, is a transient error that keeps the last state. Another session's state there gets
+// the same lookup, but a miss or a failure leaves it shown (orphaned). `fresh` (a helper call just wrote
+// the state) skips the lookup's no-state memory.
+async function readStateText($: Dollar, init: RefreshInit): Promise<string> {
+  const pin = await refreshPin($, { isStart: init.isStart, onMove: moved => onPinMove($, moved) }).catch(() => null)
+  try {
+    const text = (await $.fs.read(pin === null ? STATE_PATH : pinPath(pin, STATE_PATH))) as string
+    if (pin === null) return text
+    const session = await $.session.id()
+    if (isOwnState(text, session)) noteFound({ key: pinKey(pin), root: pin.root })
+    else if (isForeignState(text, session)) {
+      const found = await locateOwnState($, { key: pinKey(pin), root: pin.root }, session, init.fresh === true)
+      if (found.kind === 'found') return found.text
+    }
+    return text
+  } catch (err) {
+    if (pin === null || !isMissing(err)) throw err
+    const key = pinKey(pin)
+    const found = await locateOwnState($, { key, root: pin.root }, await $.session.id(), init.fresh === true)
+    if (found.kind === 'found') return found.text
+    if (found.kind === 'failed' && wasFoundElsewhere(key, pin.root)) throw new Error('trailhead mod: work state lookup failed')
+    throw err
+  }
+}
+
+async function refresh($: Dollar, init: RefreshInit = {}) {
   let text: string
   try {
-    text = (await $.fs.read(STATE_PATH)) as string
+    text = await readStateText($, init)
   } catch (err) {
     // A missing file means no ticket in play; any other failure is transient: keep the last state.
     if (isMissing(err)) {
@@ -120,11 +302,14 @@ async function refresh($: Dollar) {
   await setOwnTicket($, state)
   if (state === null) return apply($, null, false)
   const session = await $.session.id()
-  return apply($, state, state.session !== null && state.session !== session)
+  const foreign = state.session !== null && state.session !== session
+  // Una sessione straniera e' "altrove" finche' il registro non conferma che e' finita.
+  const gone = foreign && (await foreignIsGone($, state.session as string))
+  return apply($, state, foreign, foreign && !gone)
 }
 
-function safeRefresh($: Dollar): Promise<void> {
-  queue = queue.then(() => refresh($)).catch(err => {
+function safeRefresh($: Dollar, init: RefreshInit = {}): Promise<void> {
+  queue = queue.then(() => refresh($, init)).catch(err => {
     try {
       $.ui.log(`trailhead mod: work state refresh failed: ${String(err)}`, { to: 'debug' })
     } catch {
@@ -134,13 +319,23 @@ function safeRefresh($: Dollar): Promise<void> {
   return queue
 }
 
+async function resumeHintCleared($: Dollar) {
+  try {
+    await setInterrupted($, false)
+    await showStatus($)
+  } catch (err) {
+    debug($, `trailhead mod: resume hint reset failed: ${String(err)}`)
+  }
+}
+
 // A /clear ends the session the state belongs to: show it as orphaned at once.
 async function markOrphaned($: Dollar) {
   const state = await read($, workState)
   // A file with no session is never orphaned, /clear included.
   if (state === null || state.session === null) return
   await setOrphaned($, true)
-  pin($, state, true)
+  await setElsewhere($, false)
+  await showStatus($)
 }
 
 type Look = { dim?: boolean; bold?: boolean; color?: string }
@@ -166,7 +361,8 @@ export const register: Register = on => {
 
   on('session.start', async ($, e, next) => {
     const result = await next(e)
-    await safeRefresh($)
+    await safeRefresh($, { isStart: true })
+    await followWhiteboard($)
     await setSnapshot($, null).catch(err => debug($, `trailhead mod: snapshot reset failed: ${String(err)}`))
     return result
   })
@@ -185,12 +381,41 @@ export const register: Register = on => {
     }
   })
 
+  // A change after the one compose reaches the model here; fail-open, the prompt always goes on.
+  on('prompt.submit', async ($, e, next) => {
+    if (e.command === AUTO_COMMAND) {
+      // Il run riprende: il suggerimento sparisce, a meno che il comando non sia stato scartato.
+      const result = await next(e)
+      if (result.drop === undefined) await resumeHintCleared($)
+      return result
+    }
+    if (e.command !== undefined) return next(e)
+    await safeRefresh($)
+    const { note, previous, live } = await serial(() => changeNote($))
+    const put = () => (previous === null || live === null ? Promise.resolve() : serial(() => restoreLatch($, previous, live)).catch(err => debug($, `trailhead mod: latch restore failed: ${String(err)}`)))
+    let result
+    try {
+      result = await next(note === null ? e : { ...e, context: [...(e.context ?? []), note] })
+    } catch (err) {
+      // Delivery is not confirmed: put the latch back so the next prompt carries the change.
+      await put()
+      throw err
+    }
+    if (result.drop !== undefined) await put()
+    return result
+  }).catch(($, e, next) => {
+    debug($, 'trailhead mod: work state context failed')
+    return next(e)
+  })
+
   // After a compaction the agent re-reads the live state: refresh, then rebuild the snapshot.
   on('session.compact', async ($, e, next) => {
     const result = await next(e)
     // A subagent's or a precomputed compaction installs nothing in the main conversation.
     if (e.agentId !== undefined || e.trigger === 'precompute' || result.messages === undefined) return result
     try {
+      // Una compattazione tra due turni interrompe il run; dentro un turno in corso no (il run prosegue).
+      if (!isMainTurnRunning()) await setInterrupted($, true)
       await safeRefresh($)
       await setSnapshot($, null)
     } catch (err) {
@@ -200,33 +425,52 @@ export const register: Register = on => {
   })
 
   on('turn.start', async ($, e, next) => {
+    // Marked before the chain runs, so a press handled meanwhile already sees the turn.
+    if (e.agentId === undefined) markTurnStart()
     const result = await next(e)
+    if (e.agentId === undefined) {
+      // Il run può proseguire da solo (il completamento di uno slot apre un nuovo turno).
+      await setInterrupted($, false).catch(err => debug($, `trailhead mod: resume hint reset failed: ${String(err)}`))
+    }
     await safeRefresh($)
     return result
   })
 
   on('turn.complete', async ($, e, next) => {
     const result = await next(e)
+    if (e.agentId === undefined) {
+      markTurnComplete()
+      if (e.isAborted) await setInterrupted($, true).catch(err => debug($, `trailhead mod: resume hint set failed: ${String(err)}`))
+    }
     await safeRefresh($)
+    await followWhiteboard($)
     return result
   })
 
   // The helper runs through Bash: read again once the call has run.
   on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
     const result = await next(e)
-    if (typeof e.command === 'string' && e.command.includes(HELPER)) await safeRefresh($)
+    if (typeof e.command === 'string' && e.command.includes(HELPER)) {
+      await safeRefresh($, { fresh: true })
+      await followWhiteboard($)
+    }
     return result
     // This hook never judges the call: if it fails, the call goes on untouched.
   }).catch((_$, e, next) => next(e))
 
   on('session.end', async ($, e, next) => {
+    // The session ends with no turn left running, whatever the reason.
+    markTurnComplete()
     if (e.reason === 'clear') {
+      ended.add(e.sessionId)
       try {
         await markOrphaned($)
       } catch {
         // Never block the session ending.
       }
     }
+    // The ended session's mirror is never read again.
+    told.delete(e.sessionId)
     return next(e)
   })
 
@@ -242,15 +486,30 @@ export const register: Register = on => {
 
   on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
     const state = await read($, workState)
-    const orphaned = await read($, isOrphaned)
-    if (state === null || e.props.hasSurvey) return next(e)
+    const isStale = await read($, isOrphaned)
+    const elsewhere = isStale && (await read($, isElsewhere))
+    const orphaned = isStale && !elsewhere
+    const run = await read($, autoRun)
+    const counts = await read($, runCounts)
+    const hint = showsResumeHint(await read($, autoInterrupted), run)
+    if (e.props.hasSurvey) return next(e)
+    if (state === null) {
+      // Nessuno stato proprio (gli slot non hanno sessione): una riga sola per il run o per il suggerimento.
+      if (run === null) return next(e)
+      const { Box, Text } = $.ui.resolve(e)
+      return (
+        <Box key="run">
+          <Text color={AMBER}>{hint ? RESUME_HINT : runLabel(run, counts)}</Text>
+        </Box>
+      )
+    }
 
     const { Box, Text } = $.ui.resolve(e)
     const { stages, isPaused } = pipeline(state.step)
     const ticketLabel = `#${state.ticket}`
     const room = e.props.bodyColumns - ticketLabel.length - 1
     const title = state.title === null ? null : fit(state.title, room)
-    const tag = orphaned ? '  orphaned, resume?' : isPaused ? '  ‖ paused' : null
+    const tag = elsewhere ? `  ${ELSEWHERE}` : orphaned ? '  orphaned, resume?' : isPaused ? '  ‖ paused' : null
 
     return (
       <Box flexDirection="column">
@@ -281,9 +540,9 @@ export const register: Register = on => {
               </Box>
             )}
           </Box>
-          {state.auto && !orphaned ? (
+          {hint || (state.auto && !isStale) ? (
             <Box key="auto">
-              <Text color={AMBER}>{`auto · ${state.autoDone} done`}</Text>
+              <Text color={AMBER}>{hint ? RESUME_HINT : runLabel(run ?? { done: state.autoDone }, counts)}</Text>
             </Box>
           ) : null}
         </Box>

package/plugins/trailhead/hooks/mod/repo-pin.ts

@@ -0,0 +1,167 @@
+// The repo the session works in, pinned (#268): the map pane and the band read their files and run
+// `gh` against it, so a shell `cd` out of the repo (the session cwd moves) never loses them.
+// Pure parts first, then the engine part that keeps the pin in an atom.
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface } from 'claude-code'
+
+import type { RepoPin } from '../../types'
+import { sameValue } from './work-state-view'
+
+type RepoRead = { root: string; remote: string | null }
+
+// Host and owner/name are kept to the characters a link may carry: they reach the system prompt.
+const URL_REMOTE = /^(?:https?|ssh|git):\/\/(?:[^@/\s]+@)?([A-Za-z0-9.-]+)(?::\d+)?\/([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?\/?$/i
+const SCP_REMOTE = /^(?:[^@/\s]+@)?([A-Za-z0-9.-]+):([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?\/?$/
+
+// Host and owner/name of a remote, any host (github.com or an Enterprise one; `gh` resolves the host
+// itself from the pinned root). The host is lower-cased: DNS names are case-insensitive.
+export const remoteId = (remote: string | null): { host: string; slug: string } | null => {
+  if (remote === null) return null
+  const text = remote.trim()
+  const m = URL_REMOTE.exec(text) ?? (text.includes('://') ? null : SCP_REMOTE.exec(text))
+  return m === null ? null : { host: m[1].toLowerCase(), slug: `${m[2]}/${m[3]}` }
+}
+
+// The repo as a pin: a working copy with a parseable remote. `toplevel` is the checkout's own root
+// (a worktree's, where trailhead keeps its files); `repo.root` is the main working tree's.
+export const pinOf = (repo: RepoRead | null, toplevel: string | null = null): RepoPin | null => {
+  const id = remoteId(repo?.remote ?? null)
+  return repo === null || id === null ? null : { root: toplevel ?? repo.root, ...id }
+}
+
+// What makes two pins the same repo (the root can differ between checkouts of it).
+export const pinKey = (pin: RepoPin): string => `${pin.host}/${pin.slug}`
+export const isSamePin = (a: RepoPin | null, b: RepoPin | null): boolean =>
+  a === null || b === null ? a === b : a.root === b.root && pinKey(a) === pinKey(b)
+
+// Whether the checkout the session is in (what `session.repo()` and its toplevel read) is the pinned one.
+export const isPinCheckout = (pin: RepoPin | null, repo: RepoRead | null, toplevel: string | null): boolean =>
+  pin !== null && toplevel !== null && isSamePin(pin, pinOf(repo, toplevel))
+
+// A check outside any repo, or in one with no usable remote, keeps the last pin; another repo moves it.
+export const nextPin = (current: RepoPin | null, repo: RepoRead | null, toplevel: string | null = null): RepoPin | null => {
+  const found = pinOf(repo, toplevel)
+  if (found === null) return current
+  return isSamePin(current, found) ? current : found
+}
+
+// The pinned checkout as the trailing word of a verb's args: `--in=` plus base64url of the root (alphabet
+// [A-Za-z0-9_-], no padding), so a path with spaces, quotes or a leading `-` stays one shell-safe word. The verb
+// decodes it with templates/trailhead-checkout-in.js and moves there first (#312).
+// No Buffer in the mod's runtime: UTF-8 bytes through btoa, then the url-safe alphabet.
+export const checkoutArg = (pin: RepoPin): string => {
+  const binary = Array.from(new TextEncoder().encode(pin.root), byte => String.fromCharCode(byte)).join('')
+  return `--in=${btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')}`
+}
+
+// A repo-relative path under the pinned root, absolute whatever the session cwd is.
+export const pinPath = (pin: RepoPin, relative: string): string => `${pin.root.replace(/\/+$/, '')}/${relative}`
+
+// Same {plugin, key} as the copies the pane declares: the module scan wants the atom spelled in the file that uses it.
+export const repoPin = atom({ plugin: 'trailhead', key: 'repoPin' } as const, null as RepoPin | null)
+
+// Machinery, not drawn: survives a /clear, which empties the atom while the session stays in its repo.
+let remembered: RepoPin | null = null
+
+// The checkout's own root: `git rev-parse --show-toplevel` in the session's directory, the same one
+// `$.session.repo()` reads, so root and remote always name one checkout. null when it cannot be read;
+// the caller falls back.
+export async function toplevelOf($: EngineInterface): Promise<string | null> {
+  try {
+    const out = await $.process.run(['git', 'rev-parse', '--show-toplevel'], { cwd: await $.session.cwd(), timeoutMs: 5_000 })
+    const top = out.stdout.trim()
+    return out.exitCode === 0 && top.startsWith('/') ? top : null
+  } catch {
+    return null
+  }
+}
+
+// The repo as git answers it, for when the host's `session.repo()` has nothing (#299): the two outputs
+// of `git rev-parse --show-toplevel` and `git remote get-url origin`. null outside a repo; a repo with
+// no origin has a null remote (no usable pin, so the last one stays).
+type GitOut = { exitCode: number; stdout: string }
+export const repoFromGit = (top: GitOut | null, origin: GitOut | null): RepoRead | null => {
+  const root = top !== null && top.exitCode === 0 ? top.stdout.trim() : ''
+  if (!root.startsWith('/')) return null
+  const remote = origin !== null && origin.exitCode === 0 ? origin.stdout.trim() : ''
+  return { root, remote: remote === '' ? null : remote }
+}
+
+// The fallback read: null outside a repo (no second spawn then); `toplevel` is the root git just gave.
+async function gitRepo($: EngineInterface): Promise<{ repo: RepoRead; toplevel: string } | null> {
+  try {
+    const cwd = await $.session.cwd()
+    const run = (argv: string[]) => $.process.run(argv, { cwd, timeoutMs: 5_000 })
+    const top = await run(['git', 'rev-parse', '--show-toplevel'])
+    if (repoFromGit(top, null) === null) return null
+    const repo = repoFromGit(top, await run(['git', 'remote', 'get-url', 'origin']))
+    return repo === null ? null : { repo, toplevel: repo.root }
+  } catch {
+    return null
+  }
+}
+
+// The repo the session is in: the host's answer, else git's (#299). `toplevel` comes with it only on the
+// git path, where it is already read; a throw of the host read reaches the caller. The git fallback covers
+// a host whose `repo()` stays null for a repo created mid-session (anthropics/claude-code#104070): keep it
+// while hosts without the upstream fix are supported, even once a fixed release ships.
+export async function currentRepo($: EngineInterface): Promise<{ repo: RepoRead | null; toplevel: string | null }> {
+  const host = await $.session.repo()
+  if (host !== null) return { repo: host, toplevel: null }
+  return (await gitRepo($)) ?? { repo: null, toplevel: null }
+}
+
+// github.com is served by gh as it is; any other host only once `gh auth status --hostname <host>` succeeds
+// (an Enterprise host the person logged in to). A success is kept for the life of the module (the
+// session's start hooks of the pane and the band both refresh, so it is not reset there). A failure is
+// kept only HOST_RETRY_MS: it may be a network blip or a login still to come, so it is asked again
+// later. A check that could not run at all is not kept, so it is tried again.
+const GITHUB_HOST = 'github.com'
+const HOST_RETRY_MS = 60_000
+// true: served; a number: the time the last check failed.
+const servedHosts = new Map<string, true | number>()
+
+async function isServed($: EngineInterface, host: string, cwd: string): Promise<boolean> {
+  if (host === GITHUB_HOST) return true
+  const known = servedHosts.get(host)
+  if (known === true) return true
+  const now = await $.clock.now()
+  if (known !== undefined && now - known < HOST_RETRY_MS) return false
+  try {
+    const out = await $.process.run(['gh', 'auth', 'status', '--hostname', host], { cwd, timeoutMs: 10_000 })
+    servedHosts.set(host, out.exitCode === 0 ? true : now)
+    return out.exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+// Checks the working copy now and pins what it finds; a failed read keeps the last pin. The host's
+// `session.repo()` can stay null for a repo created mid-session, so git in the cwd answers then (#299). A session
+// start begins from nothing: the pin of an earlier session is not this one's.
+export async function refreshPin($: EngineInterface, init: { isStart?: boolean; onMove?: (pin: RepoPin | null) => Promise<void> } = {}): Promise<RepoPin | null> {
+  const stored = await read($, repoPin)
+  const current = init.isStart === true ? null : (stored ?? remembered)
+  let repo: RepoRead | null = null
+  let toplevel: string | null = null
+  try {
+    const found = await currentRepo($)
+    repo = found.repo
+    const id = remoteId(repo?.remote ?? null)
+    if (repo !== null && id !== null) {
+      toplevel = found.toplevel ?? (await toplevelOf($))
+      // A host gh cannot serve is no usable remote: the last pin stays.
+      if (!(await isServed($, id.host, toplevel ?? repo.root))) repo = null
+    }
+  } catch {
+    // Unreadable repo: keep the last pin.
+  }
+  const pin = nextPin(current, repo, toplevel)
+  remembered = pin
+  if (!sameValue(stored, pin)) {
+    // Right before the atom changes, whoever moves it, so what was read for the old pin goes no later than the change.
+    await init.onMove?.(pin)
+    await update($, repoPin, () => pin)
+  }
+  return pin
+}