@marcomigozzi/trailhead 0.14.0 → 0.16.0

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
+}

package/plugins/trailhead/hooks/mod/session-registry.ts

@@ -0,0 +1,65 @@
+// Liveness di una sessione Claude Code dal registro del motore (<config>/sessions/<pid>.json,
+// con `sessionId` e `pid`). Nessuna chiamata al motore qui: fs e controllo del pid sono iniettati.
+// Il registro e' interno e non tipizzato, quindi ogni dubbio (cartella illeggibile, file non
+// parsabile, registro vuoto) vale "unknown", mai "gone".
+
+export type Liveness = 'live' | 'gone' | 'unknown'
+
+export type RegistryDeps = {
+  // I nomi dei file della cartella del registro; rifiuta se non si legge.
+  list: (dir: string) => Promise<string[]>
+  read: (path: string) => Promise<string>
+  // true/false se il pid si sa vivo/morto, null se la piattaforma non lo dice (conta la sola presenza).
+  pidAlive: (pid: number) => Promise<boolean | null>
+}
+
+type Entry = { sessionId: string; pid: number }
+
+const parseEntry = (text: string): Entry | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return null
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const r = raw as Record<string, unknown>
+  if (typeof r.sessionId !== 'string' || r.sessionId === '') return null
+  if (!Number.isInteger(r.pid) || (r.pid as number) <= 0) return null
+  return { sessionId: r.sessionId, pid: r.pid as number }
+}
+
+export async function sessionLiveness(dir: string, sessionId: string, deps: RegistryDeps): Promise<Liveness> {
+  let names: string[]
+  try {
+    names = (await deps.list(dir)).filter(name => name.endsWith('.json'))
+  } catch {
+    return 'unknown'
+  }
+  let parsed = 0
+  let doubtful = false
+  for (const name of names) {
+    let entry: Entry | null = null
+    try {
+      entry = parseEntry(await deps.read(`${dir}/${name}`))
+    } catch {
+      entry = null
+    }
+    if (entry === null) {
+      doubtful = true
+      continue
+    }
+    parsed += 1
+    if (entry.sessionId !== sessionId) continue
+    let alive: boolean | null
+    try {
+      alive = await deps.pidAlive(entry.pid)
+    } catch {
+      alive = null
+    }
+    if (alive !== false) return 'live'
+  }
+  // Nessuna voce leggibile (la sessione corrente dovrebbe esserci) o file che non si leggono: non si sa.
+  if (parsed === 0 || doubtful) return 'unknown'
+  return 'gone'
+}

package/plugins/trailhead/hooks/mod/turn-state.ts

@@ -0,0 +1,14 @@
+// Whether a main-loop turn is running, shared by the band (register.tsx) and the map pane, which each
+// need it and may not hook the same event twice with the same matcher. Module state: a hot reload
+// resets it to idle, which only costs a held press being released early.
+let isRunning = false
+
+export const markTurnStart = (): void => {
+  isRunning = true
+}
+
+export const markTurnComplete = (): void => {
+  isRunning = false
+}
+
+export const isMainTurnRunning = (): boolean => isRunning

package/plugins/trailhead/hooks/mod/whiteboard-follow.ts

@@ -0,0 +1,98 @@
+// Pure rules of the map panel following the whiteboard (#306): when this session takes a whiteboard
+// ticket the panel shows the whiteboard once, and a whiteboard ticket created from a map raises a hint.
+// No atoms and no engine calls here, so the rules are easy to test.
+import type { WorkState } from '../../types'
+
+export const WHITEBOARD_LABEL = 'trailhead:whiteboard'
+
+export type Follow = { follow: boolean; memo: number | null }
+
+// Follow once per ticket: the memo is the last ticket followed, kept by the caller across a /clear.
+// A null state (no file, cleared by Resolve) changes nothing; a map ticket, a foreign or an orphaned state
+// is never followed and leaves the memo as it was.
+export const nextFollow = (memo: number | null, state: WorkState | null, own: number | null, isOrphaned: boolean): Follow => {
+  if (state === null || state.map !== null || isOrphaned || own === null || state.ticket !== own) return { follow: false, memo }
+  return state.ticket === memo ? { follow: false, memo } : { follow: true, memo: state.ticket }
+}
+
+// The command split into shell segments of words: quotes group (and are dropped), a backslash escapes outside
+// single quotes, a backslash-newline joins lines, and an unquoted `;`, `&`, `|` or newline ends a segment.
+// Enough shell for reading flags, not a full parser: no expansion, no heredocs.
+const SEPARATORS = new Set([';', '&', '|', '\n'])
+
+function segmentsOf(command: string): string[][] {
+  const segments: string[][] = []
+  let words: string[] = []
+  let word: string | null = null
+  let quote: '"' | "'" | null = null
+  const endWord = () => {
+    if (word !== null) words = [...words, word]
+    word = null
+  }
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i]
+    if (quote !== null) {
+      if (ch === quote) quote = null
+      else if (ch === '\\' && quote === '"' && i + 1 < command.length) word = (word ?? '') + command[++i]
+      else word = (word ?? '') + ch
+    } else if (ch === '\\' && command[i + 1] === '\n') i++
+    else if (ch === '\\' && i + 1 < command.length) word = (word ?? '') + command[++i]
+    else if (ch === '"' || ch === "'") {
+      quote = ch
+      word = word ?? ''
+    } else if (SEPARATORS.has(ch)) {
+      endWord()
+      if (words.length > 0) segments.push(words)
+      words = []
+    } else if (/\s/.test(ch)) endWord()
+    else word = (word ?? '') + ch
+  }
+  endWord()
+  if (words.length > 0) segments.push(words)
+  return segments
+}
+
+const isCreate = (words: string[]): boolean => {
+  const at = words.indexOf('issue')
+  return words.includes('gh') && at >= 0 && words[at + 1] === 'create'
+}
+
+// The values of every label flag: `--label X`, `--label=X`, `-l X`, `-lX`.
+function labelValues(words: string[]): string[] {
+  const values: string[] = []
+  words.forEach((w, i) => {
+    if ((w === '--label' || w === '-l') && i + 1 < words.length) values.push(words[i + 1])
+    else if (w.startsWith('--label=')) values.push(w.slice('--label='.length))
+    else if (w.startsWith('-l') && !w.startsWith('--') && w.length > 2) values.push(w.slice(2))
+  })
+  return values
+}
+
+// A `gh issue create` whose label flags (repeated, `=` or space, comma lists, quoted) carry the whiteboard
+// label. Only the create's own segment counts, so a label named in another command never does.
+export const isWhiteboardCreate = (command: string): boolean =>
+  segmentsOf(command)
+    .filter(isCreate)
+    .some(words => labelValues(words).some(v => v.split(',').some(label => label.trim() === WHITEBOARD_LABEL)))
+
+const ISSUE_URL = /\/issues\/(\d+)\s*$/
+
+const textOf = (value: unknown): string | null => {
+  if (typeof value === 'string') return value
+  const stdout = (value as { stdout?: unknown } | null)?.stdout
+  return typeof stdout === 'string' ? stdout : null
+}
+
+// The number `gh issue create` printed (the issue URL is its last line), from what `next(e)` resolved to:
+// the Bash `result` is `{ stdout }` or a plain string; the call's `text` is the fallback. An errored call,
+// or output with no issue URL, gives none.
+export const createdIssueNumber = (call: unknown): number | null => {
+  const c = call as { result?: unknown; text?: unknown; isError?: unknown } | null
+  if (c === null || typeof c !== 'object' || c.isError === true) return null
+  const out = textOf(c.result) ?? textOf(c.text)
+  const m = out === null ? null : ISSUE_URL.exec(out.trimEnd())
+  return m === null ? null : Number(m[1])
+}
+
+// The toast box is narrow: a few words.
+export const whiteboardHint = (n: number): string => `new whiteboard ticket #${n}: open Whiteboard`

package/plugins/trailhead/hooks/mod/work-state-locate.ts

@@ -0,0 +1,191 @@
+// Where the session's work state lives when it is not in the pinned checkout (#270): the engine writes
+// it in the per-ticket workspace (a git worktree or a sibling clone `<repo>-t<n>`), while the session
+// may sit in the main checkout. Pure parts first, then the engine part that looks the state up.
+import type { EngineInterface } from 'claude-code'
+
+import { isMissing, parseWorkState } from './work-state-view'
+import { MAX_FAILURES, parseWorktreeBranches } from './worktree-porcelain'
+
+const STATE_PATH = '.trailhead/work-state.json'
+const LOOKUP_TIMEOUT_MS = 5_000
+
+export const dirname = (path: string): string => path.replace(/\/+$/, '').replace(/\/[^/]*$/, '') || '/'
+const basename = (path: string): string => path.replace(/\/+$/, '').replace(/^.*\//, '')
+export const trim = (path: string): string => (path.length > 1 ? path.replace(/\/+$/, '') : path)
+
+// The checkout paths of `git worktree list --porcelain`, in the order git prints them (main first).
+export const parseWorktrees = (porcelain: string): string[] => parseWorktreeBranches(porcelain).map(w => w.path)
+
+// The per-ticket clones beside the main working tree: `<basename>-t<digits>`, sorted.
+export const siblingClones = (mainRoot: string, names: readonly string[]): string[] => {
+  const base = basename(mainRoot).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const parent = dirname(mainRoot)
+  const pattern = new RegExp(`^${base}-t\\d+$`)
+  return names
+    .filter(name => pattern.test(name))
+    .sort()
+    .map(name => `${parent === '/' ? '' : parent}/${name}`)
+}
+
+// Where to look, in order: the worktrees, then the sibling clones.
+// The pinned root is the own read, which already missed; no path twice.
+export const candidates = (pinned: string, worktrees: readonly string[], siblings: readonly string[]): string[] => {
+  const all = [...worktrees, ...siblings].map(trim)
+  return all.filter((path, i) => path !== trim(pinned) && all.indexOf(path) === i)
+}
+
+// A state is this session's only when it names the session: a state with no session, or another's, is not adopted.
+export const isOwnState = (text: string, session: string): boolean => parseWorkState(text)?.session === session
+
+// A state that names another session (a state with no session is nobody's, shown as is).
+export const isForeignState = (text: string, session: string): boolean => {
+  const owner = parseWorkState(text)?.session
+  return owner !== undefined && owner !== null && owner !== session
+}
+
+// The first candidate's text that is this session's state.
+export const pickOwn = (texts: readonly (string | null)[], session: string): number => texts.findIndex(text => text !== null && isOwnState(text, session))
+
+// The checkout where this session's state was last found, with the repo it belongs to; machinery, like
+// `remembered` in repo-pin.ts. A checkout of another repo is never tried.
+let lastFound: { key: string; root: string } | null = null
+
+// A hit ends the run of failed lookups for the repo.
+export const noteFound = (found: { key: string; root: string } | null): void => {
+  lastFound = found
+  if (found !== null) for (const memo of failures.keys()) if (memo.startsWith(`${found.key}|`)) failures.delete(memo)
+}
+// Whether the state was last found in this repo, in a checkout other than the pinned one.
+export const wasFoundElsewhere = (key: string, pinned: string): boolean =>
+  lastFound !== null && lastFound.key === key && trim(lastFound.root) !== trim(pinned)
+
+// A scan that found nothing is not repeated for NO_STATE_MS, per repo and session. Time comes from the
+// engine clock; without one nothing is kept.
+const NO_STATE_MS = 10_000
+const misses = new Map<string, number>()
+// A scan that failed is remembered for a shorter while, with how many failed in a row: past MAX_FAILURES
+// the caller stops keeping the last state and treats the file as missing.
+const FAILED_MS = 3_000
+const failures = new Map<string, { at: number | null; count: number }>()
+
+// Writes a miss time, dropping the misses whose window has ended.
+const remember = (map: Map<string, number>, key: string, now: number, windowMs: number): void => {
+  for (const [k, at] of map) if (now - at >= windowMs) map.delete(k)
+  map.set(key, now)
+}
+
+export const resetLocate = (): void => {
+  lastFound = null
+  misses.clear()
+  failures.clear()
+}
+
+async function nowOf($: EngineInterface): Promise<number | null> {
+  try {
+    return await $.clock.now()
+  } catch {
+    return null
+  }
+}
+
+// null: the listing itself failed (not the same as an empty one). Path and branch of each checkout.
+export async function listWorktreeBranches($: EngineInterface, root: string): Promise<{ path: string; branch: string | null }[] | null> {
+  try {
+    const out = await $.process.run(['git', 'worktree', 'list', '--porcelain'], { cwd: root, timeoutMs: LOOKUP_TIMEOUT_MS })
+    return out.exitCode === 0 ? parseWorktreeBranches(out.stdout) : null
+  } catch {
+    return null
+  }
+}
+
+async function listWorktrees($: EngineInterface, root: string): Promise<string[] | null> {
+  return (await listWorktreeBranches($, root))?.map(w => w.path) ?? null
+}
+
+export async function listSiblings($: EngineInterface, mainRoot: string): Promise<string[] | null> {
+  try {
+    const entries = await $.fs.list(dirname(mainRoot))
+    return siblingClones(mainRoot, entries.filter(entry => entry.kind === 'dir').map(entry => entry.name))
+  } catch {
+    return null
+  }
+}
+
+// The file's text; null when it is not there, undefined when the read failed any other way.
+export async function readAt($: EngineInterface, root: string): Promise<string | null | undefined> {
+  try {
+    return (await $.fs.read(`${root}/${STATE_PATH}`)) as string
+  } catch (err) {
+    return isMissing(err) ? null : undefined
+  }
+}
+
+export type Lookup = { kind: 'found'; text: string; root: string } | { kind: 'none' } | { kind: 'failed' }
+
+const NONE: Lookup = { kind: 'none' }
+
+async function scan($: EngineInterface, pinned: string, session: string): Promise<{ kind: 'found'; text: string; root: string } | { kind: 'miss'; hadFailure: boolean }> {
+  const worktrees = await listWorktrees($, pinned)
+  const siblings = await listSiblings($, worktrees?.[0] ?? pinned)
+  const roots = candidates(pinned, worktrees ?? [], siblings ?? [])
+  const texts = await Promise.all(roots.map(root => readAt($, root)))
+  const i = pickOwn(texts.map(text => text ?? null), session)
+  if (i !== -1) return { kind: 'found', text: texts[i] as string, root: roots[i] }
+  return { kind: 'miss', hadFailure: worktrees === null || siblings === null || texts.includes(undefined) }
+}
+
+// This session's state from another checkout of the repo. 'none' is a clean miss; 'failed' means the
+// lookup itself broke (git, the listing, a read), so the caller keeps what it had. `fresh` skips the
+// no-state memory (a helper call just wrote a state).
+export async function locateOwnState($: EngineInterface, pin: { key: string; root: string }, session: string, fresh = false): Promise<Lookup> {
+  const memo = `${pin.key}|${session}`
+  try {
+    // The remembered checkout of this repo is read first and alone, so a steady state costs no process.
+    const first = lastFound !== null && lastFound.key === pin.key && trim(lastFound.root) !== trim(pin.root) ? lastFound.root : null
+    const fast = first === null ? null : await readAt($, first)
+    if (first !== null && typeof fast === 'string' && isOwnState(fast, session)) {
+      failures.delete(memo)
+      return { kind: 'found', text: fast, root: first }
+    }
+    const now = await nowOf($)
+    const seen = misses.get(memo)
+    const failed = failures.get(memo)
+    if (!fresh && now !== null && seen !== undefined && now - seen < NO_STATE_MS) return NONE
+    if (!fresh && now !== null && failed?.at != null && now - failed.at < FAILED_MS) return failedLookup(failed.count)
+    const result = await scan($, pin.root, session)
+    if (result.kind === 'miss' && result.hadFailure) {
+      const count = (failed?.count ?? 0) + 1
+      setFailure(memo, count, now)
+      return failedLookup(count)
+    }
+    failures.delete(memo)
+    if (result.kind === 'found') {
+      misses.delete(memo)
+      noteFound({ key: pin.key, root: result.root })
+      return result
+    }
+    if (now !== null) remember(misses, memo, now, NO_STATE_MS)
+    if (lastFound?.key === pin.key) noteFound(null)
+    return NONE
+  } catch {
+    return failedLookup(bump(memo, await nowOf($)))
+  }
+}
+
+// Failed lookups in a row count against the keep: the MAX_FAILURES-th reads as a missing file.
+const failedLookup = (count: number): Lookup => (count >= MAX_FAILURES ? NONE : { kind: 'failed' })
+
+// The run of failures for the key; only a success ends it, however far apart the failures are. Writing
+// one drops the runs of other keys that are long gone.
+const FAILURE_KEEP_MS = 600_000
+
+function setFailure(memo: string, count: number, now: number | null): void {
+  for (const [k, v] of failures) if (k !== memo && (v.at === null || (now !== null && now - v.at >= FAILURE_KEEP_MS))) failures.delete(k)
+  failures.set(memo, { at: now, count })
+}
+
+function bump(memo: string, now: number | null): number {
+  const count = (failures.get(memo)?.count ?? 0) + 1
+  setFailure(memo, count, now)
+  return count
+}

package/plugins/trailhead/hooks/mod/work-state-prompt.ts

@@ -8,12 +8,8 @@ const ELLIPSIS = '…'
 const encoder = new TextEncoder()
 const bytes = (text: string): number => encoder.encode(text).length
 
-// owner/name from a GitHub origin URL (https, scp form, ssh); null for anything else.
-export const repoSlug = (remote: string | null): string | null => {
-  if (remote === null) return null
-  const m = /^(?:https?:\/\/|ssh:\/\/git@|git@)github\.com[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(remote.trim())
-  return m === null ? null : `${m[1]}/${m[2]}`
-}
+// The repo the links point at: host and owner/name of the pin.
+export type LinkRepo = { host: string; slug: string }
 
 // Flat single line, cut by code point so a surrogate pair is never split.
 // Zero-width and bidi controls are dropped, so the title cannot hide or reorder text.
@@ -40,7 +36,7 @@ const capBytes = (text: string): string => {
   return out
 }
 
-const link = (slug: string | null, n: number): string => (slug === null ? '' : ` https://github.com/${slug}/issues/${n}`)
+const link = (repo: LinkRepo | null, n: number): string => (repo === null ? '' : ` https://${repo.host}/${repo.slug}/issues/${n}`)
 
 const stepLine = (step: string | null): string => {
   const live = 'may have moved on since this snapshot; .trailhead/work-state.json holds the live one'
@@ -48,13 +44,13 @@ const stepLine = (step: string | null): string => {
   return `Step: ${step ?? 'unknown'} (${live})`
 }
 
-export const promptSection = (state: WorkState | null, orphaned: boolean, slug: string | null): string | null => {
+export const promptSection = (state: WorkState | null, orphaned: boolean, repo: LinkRepo | null): string | null => {
   if (state === null || state.ticket === null || orphaned) return null
   const title = state.title === null ? '' : ` "${cutTitle(state.title)}"`
   const lines = [
     '# trailhead work state',
-    state.map === null ? 'Map: none (whiteboard ticket)' : `Map: #${state.map}${link(slug, state.map)}`,
-    `Ticket: #${state.ticket}${title}${link(slug, state.ticket)}`,
+    state.map === null ? 'Map: none (whiteboard ticket)' : `Map: #${state.map}${link(repo, state.map)}`,
+    `Ticket: #${state.ticket}${title}${link(repo, state.ticket)}`,
     stepLine(state.step),
   ]
   if (state.auto) lines.push('Mode: autonomous run')
@@ -62,8 +58,10 @@ export const promptSection = (state: WorkState | null, orphaned: boolean, slug:
   return capBytes(lines.join('\n'))
 }
 
-// What a rebuild keys on: step and autoDone are left out so the text stays cache-stable.
-export const snapshotKey = (state: WorkState | null, orphaned: boolean): string =>
-  JSON.stringify(
-    state === null ? [null, orphaned] : [state.map, state.ticket, state.title, orphaned, state.auto],
-  )
+// What a rebuild keys on: step and autoDone are left out so the text stays cache-stable. The repo is in it,
+// so a pin that moves rebuilds the links.
+export const snapshotKey = (state: WorkState | null, orphaned: boolean, repo: LinkRepo | null): string =>
+  JSON.stringify([
+    repo === null ? null : `${repo.host}/${repo.slug}`,
+    ...(state === null ? [null, orphaned] : [state.map, state.ticket, state.title, orphaned, state.auto]),
+  ])