@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/plugins/trailhead/tests/repo-pin.test.ts

@@ -0,0 +1,123 @@
+import { expect, test } from 'claude-code/testing'
+
+import { checkoutArg, isPinCheckout, isSamePin, nextPin, pinOf, pinPath, remoteId, repoFromGit } from '../hooks/mod/repo-pin'
+
+const repo = (remote: string | null, root = '/repo') => ({ root, remote })
+const GH = { host: 'github.com', slug: 'o/r' }
+
+test('remoteId reads host and owner/name from every remote form, with or without .git', () => {
+  expect(remoteId('https://github.com/o/r.git')).toEqual(GH)
+  expect(remoteId('https://github.com/o/r')).toEqual(GH)
+  expect(remoteId('https://github.com/o/r/')).toEqual(GH)
+  expect(remoteId('ssh://git@github.com/o/r.git')).toEqual(GH)
+  expect(remoteId('git@github.com:o/r.git')).toEqual(GH)
+  expect(remoteId('git@github.com:o/r')).toEqual(GH)
+  expect(remoteId('  git@github.com:o/r.git\n')).toEqual(GH)
+})
+
+test('remoteId accepts a user, a port, any case of the host, and Enterprise hosts', () => {
+  expect(remoteId('https://user@github.com/o/r.git')).toEqual(GH)
+  expect(remoteId('ssh://git@github.com:22/o/r')).toEqual(GH)
+  expect(remoteId('https://GitHub.com/o/r.git')).toEqual(GH)
+  expect(remoteId('git@GitHub.COM:o/r.git')).toEqual(GH)
+  expect(remoteId('git@ghe.example.com:o/r.git')).toEqual({ host: 'ghe.example.com', slug: 'o/r' })
+  expect(remoteId('https://ghe.example.com:8443/o/r')).toEqual({ host: 'ghe.example.com', slug: 'o/r' })
+  expect(remoteId('github.com:o/r')).toEqual(GH)
+})
+
+test('remoteId is host-aware: any host gives its own, a local path none', () => {
+  expect(remoteId('https://gitlab.com/a/b.git')).toEqual({ host: 'gitlab.com', slug: 'a/b' })
+  expect(remoteId('ssh://git@github.com/ToRvaLDz/trailhead.git')).toEqual({ host: 'github.com', slug: 'ToRvaLDz/trailhead' })
+  expect(remoteId('/srv/git/trailhead.git')).toBeNull()
+})
+
+test('remoteId refuses a host or owner/name with characters a link must not carry', () => {
+  expect(remoteId('https://github.com/o​/r.git')).toBeNull()
+  expect(remoteId('git@github.com:o/r‮.git')).toBeNull()
+  expect(remoteId('git@gh⁦e.example.com:o/r.git')).toBeNull()
+  expect(remoteId('https://github.com/o/r<x>.git')).toBeNull()
+  expect(remoteId('git@github.com:my.org/r_1-x.git')).toEqual({ host: 'github.com', slug: 'my.org/r_1-x' })
+})
+
+test('remoteId is null for no remote or one that is not host/owner/name', () => {
+  expect(remoteId(null)).toBeNull()
+  expect(remoteId('')).toBeNull()
+  expect(remoteId('/srv/git/r.git')).toBeNull()
+  expect(remoteId('../r.git')).toBeNull()
+  expect(remoteId('https://github.com/o')).toBeNull()
+  expect(remoteId('file:///srv/o/r.git')).toBeNull()
+})
+
+test('pinOf pins the checkout toplevel when given, else the repo root', () => {
+  expect(pinOf(null)).toBeNull()
+  expect(pinOf(repo(null))).toBeNull()
+  expect(pinOf(repo('git@github.com:o/r.git'))).toEqual({ root: '/repo', ...GH })
+  expect(pinOf(repo('git@github.com:o/r.git'), '/repo-t5')).toEqual({ root: '/repo-t5', ...GH })
+})
+
+test('nextPin keeps the last pin when the check finds no usable repo, and follows a different one', () => {
+  const kept = { root: '/repo', ...GH }
+  expect(nextPin(kept, null)).toBe(kept)
+  expect(nextPin(kept, repo(null))).toBe(kept)
+  expect(nextPin(kept, repo('/srv/git/r.git'))).toBe(kept)
+  expect(nextPin(null, null)).toBeNull()
+  expect(nextPin(null, repo('git@github.com:o/r.git'))).toEqual(kept)
+  expect(nextPin(kept, repo('git@github.com:o/r.git'))).toBe(kept)
+  expect(nextPin(kept, repo('git@github.com:o/other.git', '/other'))).toEqual({ root: '/other', host: 'github.com', slug: 'o/other' })
+  expect(nextPin(kept, repo('git@github.com:o/r.git'), '/repo-t5')).toEqual({ root: '/repo-t5', ...GH })
+})
+
+test('isSamePin compares root and repo identity', () => {
+  const a = { root: '/repo', ...GH }
+  expect(isSamePin(a, { ...a })).toBe(true)
+  expect(isSamePin(a, { ...a, root: '/repo-t5' })).toBe(false)
+  expect(isSamePin(a, { ...a, host: 'ghe.example.com' })).toBe(false)
+  expect(isSamePin(null, null)).toBe(true)
+  expect(isSamePin(a, null)).toBe(false)
+})
+
+test('pinPath joins a repo-relative path under the pinned root', () => {
+  expect(pinPath({ root: '/repo', ...GH }, '.trailhead/active-map')).toBe('/repo/.trailhead/active-map')
+  expect(pinPath({ root: '/repo/', ...GH }, '.trailhead/active-map')).toBe('/repo/.trailhead/active-map')
+})
+
+test('isPinCheckout holds only for the pinned repo, checked out at the pinned root', () => {
+  const pin = { root: '/repo', ...GH }
+  expect(isPinCheckout(pin, repo('git@github.com:o/r.git'), '/repo')).toBe(true)
+  expect(isPinCheckout(pin, repo('git@github.com:o/r.git', '/main'), '/repo')).toBe(true)
+  expect(isPinCheckout(pin, repo('git@github.com:o/r.git'), '/repo-t5')).toBe(false)
+  expect(isPinCheckout(pin, repo('git@github.com:o/other.git'), '/repo')).toBe(false)
+  expect(isPinCheckout(pin, repo(null), '/repo')).toBe(false)
+  expect(isPinCheckout(pin, null, null)).toBe(false)
+  expect(isPinCheckout(pin, repo('git@github.com:o/r.git'), null)).toBe(false)
+  expect(isPinCheckout(null, repo('git@github.com:o/r.git'), '/repo')).toBe(false)
+})
+
+test('repoFromGit builds the repo from the two git outputs', () => {
+  expect(repoFromGit({ exitCode: 0, stdout: '/w/p\n' }, { exitCode: 0, stdout: 'git@github.com:o/p.git\n' })).toEqual({ root: '/w/p', remote: 'git@github.com:o/p.git' })
+})
+
+test('repoFromGit is null outside a repo, so the last pin stays', () => {
+  const current = { root: '/w/p', host: 'github.com', slug: 'o/p' }
+  const repo = repoFromGit({ exitCode: 128, stdout: '' }, { exitCode: 128, stdout: '' })
+  expect(repo).toBeNull()
+  expect(nextPin(current, repo)).toBe(current)
+  expect(repoFromGit(null, null)).toBeNull()
+})
+
+test('repoFromGit keeps a repo with no origin remote unpinned, so the last pin stays', () => {
+  const current = { root: '/w/p', host: 'github.com', slug: 'o/p' }
+  const repo = repoFromGit({ exitCode: 0, stdout: '/w/q\n' }, { exitCode: 2, stdout: '' })
+  expect(repo).toEqual({ root: '/w/q', remote: null })
+  expect(nextPin(current, repo)).toBe(current)
+})
+
+test('checkoutArg hands the root over as one shell-safe word the helper decodes back', () => {
+  for (const root of ['/repo', '/with space/r', "/it's/r", '/-dash/r', '/uni\u00e8\u4e2d/r', '/a"b$c`d']) {
+    const arg = checkoutArg({ ...GH, root })
+    expect(arg).toMatch(/^--in=[A-Za-z0-9_-]+$/)
+    const token = arg.slice('--in='.length)
+    const bytes = Uint8Array.from(atob(token.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(token.length / 4) * 4, '=')), c => c.charCodeAt(0))
+    expect(new TextDecoder().decode(bytes)).toBe(root)
+  }
+})

package/plugins/trailhead/tests/session-registry.test.ts

@@ -0,0 +1,50 @@
+import { expect, test } from 'claude-code/testing'
+
+import { sessionLiveness } from '../hooks/mod/session-registry'
+import type { RegistryDeps } from '../hooks/mod/session-registry'
+
+const DIR = '/home/u/.claude/sessions'
+const entry = (sessionId: string, pid: number) => JSON.stringify({ sessionId, pid })
+
+// Un registro finto: nome file -> testo; i pid in `alive` sono vivi, `null` = la piattaforma non lo dice.
+const deps = (files: Record<string, string> | Error, alive: number[] | null = []): RegistryDeps => ({
+  list: async () => {
+    if (files instanceof Error) throw files
+    return Object.keys(files)
+  },
+  read: async path => {
+    if (files instanceof Error) throw files
+    const text = files[path.slice(DIR.length + 1)]
+    if (text === undefined) throw new Error('ENOENT')
+    return text
+  },
+  pidAlive: async pid => (alive === null ? null : alive.includes(pid)),
+})
+
+test('a session with a live pid is live', async () => {
+  const files = { '10.json': entry('s-A', 10), '11.json': entry('s-B', 11) }
+  expect(await sessionLiveness(DIR, 's-A', deps(files, [10, 11]))).toBe('live')
+})
+
+test('a session whose entry is missing, or whose pid is dead, is gone', async () => {
+  const files = { '10.json': entry('s-A', 10), '11.json': entry('s-B', 11) }
+  expect(await sessionLiveness(DIR, 's-OLD', deps(files, [10, 11]))).toBe('gone')
+  expect(await sessionLiveness(DIR, 's-A', deps(files, [11]))).toBe('gone')
+})
+
+test('with no way to check a pid the entry alone says live', async () => {
+  const files = { '10.json': entry('s-A', 10) }
+  expect(await sessionLiveness(DIR, 's-A', deps(files, null))).toBe('live')
+})
+
+test('an unreadable registry is unknown, never gone', async () => {
+  expect(await sessionLiveness(DIR, 's-A', deps(new Error('EACCES')))).toBe('unknown')
+  expect(await sessionLiveness(DIR, 's-A', deps({}))).toBe('unknown')
+  expect(await sessionLiveness(DIR, 's-A', deps({ 'x.key': 'secret' }))).toBe('unknown')
+})
+
+test('a file that does not parse keeps a missing session unknown, but not a found live one', async () => {
+  const files = { '9.json': '{nope', '10.json': entry('s-A', 10), '11.json': JSON.stringify({ sessionId: 's-C' }) }
+  expect(await sessionLiveness(DIR, 's-OLD', deps(files, [10]))).toBe('unknown')
+  expect(await sessionLiveness(DIR, 's-A', deps(files, [10]))).toBe('live')
+})

package/plugins/trailhead/tests/whiteboard-follow.test.ts

@@ -0,0 +1,90 @@
+import { expect, test } from 'claude-code/testing'
+
+import type { WorkState } from '../types'
+import { createdIssueNumber, isWhiteboardCreate, nextFollow, whiteboardHint } from '../hooks/mod/whiteboard-follow'
+
+const state = (over: Partial<WorkState> = {}): WorkState => ({ map: null, ticket: 301, ...over }) as WorkState
+
+test('nextFollow follows an own whiteboard ticket once', () => {
+  expect(nextFollow(null, state(), 301, false)).toEqual({ follow: true, memo: 301 })
+  expect(nextFollow(301, state(), 301, false)).toEqual({ follow: false, memo: 301 })
+})
+
+test('nextFollow follows a different whiteboard ticket again', () => {
+  expect(nextFollow(301, state({ ticket: 302 }), 302, false)).toEqual({ follow: true, memo: 302 })
+})
+
+test('nextFollow never follows a map ticket, a foreign or orphaned state, or no own ticket', () => {
+  expect(nextFollow(null, state({ map: 12 }), 301, false)).toEqual({ follow: false, memo: null })
+  expect(nextFollow(null, state(), 999, false)).toEqual({ follow: false, memo: null })
+  expect(nextFollow(null, state(), null, false)).toEqual({ follow: false, memo: null })
+  expect(nextFollow(null, state(), 301, true)).toEqual({ follow: false, memo: null })
+})
+
+test('nextFollow keeps the memo on a null state', () => {
+  expect(nextFollow(301, null, null, false)).toEqual({ follow: false, memo: 301 })
+})
+
+test('isWhiteboardCreate reads every label form of an issue create', () => {
+  const yes = [
+    'gh issue create -t t --label trailhead:whiteboard',
+    'gh issue create -t t --label a,trailhead:whiteboard',
+    'gh issue create -t t --label=trailhead:whiteboard',
+    'gh issue create -t t -l trailhead:whiteboard',
+    'gh issue create -t t --label bug --label trailhead:whiteboard',
+    'gh issue create -t t --label "trailhead:whiteboard"',
+    "gh issue create -t t --label 'bug,trailhead:whiteboard' -b x",
+    'gh -R o/r issue create -l trailhead:whiteboard',
+  ]
+  for (const c of yes) expect(isWhiteboardCreate(c)).toBe(true)
+})
+
+test('isWhiteboardCreate refuses other labels, other verbs and other commands', () => {
+  const no = [
+    'gh issue create -t t --label trailhead:whiteboardx',
+    'gh issue create -t t --label trailhead:map',
+    'gh issue create -t t',
+    'gh issue create -t "trailhead:whiteboard"',
+    'gh issue edit 3 --add-label trailhead:whiteboard',
+    'gh issue create -t t --label bug; echo --label trailhead:whiteboard',
+    'echo --label trailhead:whiteboard',
+  ]
+  for (const c of no) expect(isWhiteboardCreate(c)).toBe(false)
+})
+
+test('isWhiteboardCreate reads continued lines, quoted separators and the attached short flag', () => {
+  const yes = [
+    'gh issue create \\\n  --title x \\\n  --label trailhead:whiteboard',
+    'gh issue create --title "a & b" --label trailhead:whiteboard',
+    'gh issue create --title "a; b | c" --label trailhead:whiteboard',
+    'gh issue create --body "a\nb" --label trailhead:whiteboard',
+    'gh issue create -t t -ltrailhead:whiteboard',
+    'cd /x && gh issue create -t t --label trailhead:whiteboard',
+  ]
+  for (const c of yes) expect(isWhiteboardCreate(c)).toBe(true)
+})
+
+test('isWhiteboardCreate ignores a label flag written inside a quoted argument', () => {
+  expect(isWhiteboardCreate('gh issue create --title "fix -l trailhead:whiteboard"')).toBe(false)
+  expect(isWhiteboardCreate("gh issue create -b 'see --label trailhead:whiteboard' -t t")).toBe(false)
+})
+
+test('createdIssueNumber reads the last-line issue URL from stdout, a string or the text', () => {
+  const url = 'https://github.com/o/r/issues/310'
+  expect(createdIssueNumber({ result: { stdout: `${url}\n`, stderr: '' } })).toBe(310)
+  expect(createdIssueNumber({ result: `creating\n${url}\n` })).toBe(310)
+  expect(createdIssueNumber({ result: {}, text: url })).toBe(310)
+})
+
+test('createdIssueNumber gives none on an error, no URL or a bad shape', () => {
+  expect(createdIssueNumber({ isError: true, result: 'https://github.com/o/r/issues/310' })).toBeNull()
+  expect(createdIssueNumber({ result: { stdout: 'ok' } })).toBeNull()
+  expect(createdIssueNumber({ result: { stdout: 'https://github.com/o/r/issues/310/extra' } })).toBeNull()
+  expect(createdIssueNumber(undefined)).toBeNull()
+  expect(createdIssueNumber('x')).toBeNull()
+  expect(createdIssueNumber({ result: 5 })).toBeNull()
+})
+
+test('whiteboardHint names the ticket in a few words', () => {
+  expect(whiteboardHint(310)).toBe('new whiteboard ticket #310: open Whiteboard')
+})

package/plugins/trailhead/tests/work-state-locate.test.ts

@@ -0,0 +1,33 @@
+import { expect, test } from 'claude-code/testing'
+
+import { candidates, isOwnState, parseWorktrees, pickOwn, siblingClones } from '../hooks/mod/work-state-locate'
+
+const state = (session: string | null) =>
+  JSON.stringify({ map: null, ticket: 270, title: 'T', step: 'execute', auto: false, autoDone: 0, session, updatedAt: null })
+
+test('parseWorktrees keeps the checkout paths in git order, spaces included', () => {
+  const out = 'worktree /repo\nHEAD abc\nbranch refs/heads/main\n\nworktree /my work/repo-t270\nHEAD def\ndetached\n\nworktree /repo-t5/\nbare\n'
+  expect(parseWorktrees(out)).toEqual(['/repo', '/my work/repo-t270', '/repo-t5'])
+  expect(parseWorktrees('')).toEqual([])
+  expect(parseWorktrees('fatal: not a git repository')).toEqual([])
+})
+
+test('siblingClones matches <basename>-t<digits> only, sorted, under the main root parent', () => {
+  const names = ['repo-t12', 'repo', 'repo-t5', 'repo-t5x', 'repo-tx', 'other-t3', 'repo-t5-old', 'repoXt7']
+  expect(siblingClones('/home/me/repo', names)).toEqual(['/home/me/repo-t12', '/home/me/repo-t5'])
+  expect(siblingClones('/r.x', ['r.x-t1', 'rax-t2'])).toEqual(['/r.x-t1'])
+})
+
+test('candidates drops the pinned root and duplicates, worktrees before siblings', () => {
+  expect(candidates('/repo', ['/repo', '/repo-t1', '/repo-t2'], ['/repo-t2', '/repo-t3'])).toEqual(['/repo-t1', '/repo-t2', '/repo-t3'])
+  expect(candidates('/repo/', ['/repo'], [])).toEqual([])
+})
+
+test('only a state naming this session is adopted', () => {
+  expect(isOwnState(state('A'), 'A')).toBe(true)
+  expect(isOwnState(state('B'), 'A')).toBe(false)
+  expect(isOwnState(state(null), 'A')).toBe(false)
+  expect(isOwnState('{not json', 'A')).toBe(false)
+  expect(pickOwn([null, state(null), state('B'), state('A'), state('A')], 'A')).toBe(3)
+  expect(pickOwn([null, state('B')], 'A')).toBe(-1)
+})

package/plugins/trailhead/tests/work-state-prompt-hook.test.ts

@@ -27,7 +27,10 @@ const rig = (on: On) => {
     file: null as string | null,
     remote: REMOTE as string | null,
     repoFails: false,
+    // The hosts `gh auth status --hostname` accepts besides github.com.
+    authHosts: [] as string[],
     skipCompact: false,
+    denyLatch: false,
     composes: 0,
     repoReads: 0,
     writes: 0,
@@ -42,11 +45,21 @@ const rig = (on: On) => {
     if (r.repoFails) return { deny: 'repo read failed' }
     return { value: { root: '/repo', remote: r.remote, internal: false } }
   })
+  on('session.cwd', () => ({ value: '/repo' }))
+  on('process.run', (_$, e) => {
+    const out = (exitCode: number, stdout = '') => ({ value: { exitCode, stdout, stderr: '', isStdoutTruncated: false, isStderrTruncated: false } })
+    if (e.argv[0] === 'git') return out(0, '/repo\n')
+    return out(r.authHosts.includes(e.argv[4] ?? '') ? 0 : 1)
+  })
   on('ui.status', () => ({ value: undefined }))
   on('state.set', { plugin: 'trailhead' }, (_$, e, next) => {
     r.writes += 1
     return next(e)
   })
+  // Only the latch key: the other trailhead atoms keep writing.
+  on('state.set', { plugin: 'trailhead', key: 'promptSnapshot' }, (_$, e, next) =>
+    r.denyLatch ? { deny: 'state is read-only' } : next(e),
+  )
   on('prompt.compose', () => {
     r.composes += 1
     return { sections: ENGINE }
@@ -87,7 +100,7 @@ test('no section without a file, and none when the state is orphaned', async ($,
   expect(await compose($)).toEqual(ENGINE)
 })
 
-test('a step change leaves the text untouched; a ticket change rebuilds it', async ($, on) => {
+test('a step change leaves the text untouched; a ticket change rebuilds it after a compaction', async ($, on) => {
   const r = rig(on)
   r.file = stateText()
   await $.session.start(START)
@@ -97,6 +110,9 @@ test('a step change leaves the text untouched; a ticket change rebuilds it', asy
   expect((mine(await compose($)) as Section).text).toBe(first)
   r.file = stateText({ ticket: 205, title: 'Next ticket', step: 'execute' })
   await turn($)
+  // A later compose never advances the latch: the text stays what the model was told.
+  expect((mine(await compose($)) as Section).text).toBe(first)
+  await $.session.compact({ messages: SUMMARY })
   const next = (mine(await compose($)) as Section).text
   expect(next).toContain('#205 "Next ticket"')
   expect(next).toContain('execute')
@@ -161,7 +177,45 @@ test('no repo remote: numbers without links', async ($, on) => {
   expect(s.text).not.toContain('http')
 })
 
-test('the repo is read at a rebuild only, and the atom is written once per change', async ($, on) => {
+test('the links follow the pin: they survive a cd out of the repo', async ($, on) => {
+  const r = rig(on)
+  r.file = stateText()
+  await $.session.start(START)
+  await compose($)
+  r.remote = null
+  r.file = stateText({ ticket: 205, title: 'Next ticket' })
+  await turn($)
+  await $.session.compact({ messages: SUMMARY })
+  const s = mine(await compose($)) as Section
+  expect(s.text).toContain('#205 "Next ticket" https://github.com/ToRvaLDz/trailhead/issues/205')
+  expect(s.text).toContain('#198 https://github.com/ToRvaLDz/trailhead/issues/198')
+})
+
+test('an Enterprise pin links to its own host', async ($, on) => {
+  const r = rig(on)
+  r.file = stateText()
+  r.remote = 'git@ghe.example.com:acme/app.git'
+  r.authHosts = ['ghe.example.com']
+  await $.session.start(START)
+  const s = mine(await compose($)) as Section
+  expect(s.text).toContain('#204 "Inject the work state" https://ghe.example.com/acme/app/issues/204')
+  expect(s.text).toContain('#198 https://ghe.example.com/acme/app/issues/198')
+})
+
+test('a move of the pin to another repo rebuilds the links, whatever the ticket', async ($, on) => {
+  const r = rig(on)
+  r.file = stateText()
+  await $.session.start(START)
+  expect((mine(await compose($)) as Section).text).toContain('https://github.com/ToRvaLDz/trailhead/issues/204')
+  r.remote = 'https://github.com/o/other.git'
+  await turn($)
+  await $.session.compact({ messages: SUMMARY })
+  const s = mine(await compose($)) as Section
+  expect(s.text).toContain('#204 "Inject the work state" https://github.com/o/other/issues/204')
+  expect(s.text).not.toContain('ToRvaLDz')
+})
+
+test('the repo is not read by a compose, and the atom is written once per change', async ($, on) => {
   const r = rig(on)
   r.file = stateText()
   await $.session.start(START)
@@ -205,3 +259,223 @@ test('an analysis render shows the section but writes nothing', async ($, on) =>
   expect(s.text).toContain('#204')
   expect(r.writes).toBe(writes)
 })
+
+// A plugin's own prompt: the engine stub beneath answers with the context that arrived.
+const submit = async ($: any): Promise<readonly string[]> => ($.prompt.submit({ text: 'next' }) as Promise<{ context?: readonly string[] }>).then(r => r.context ?? [])
+
+test('a state written after the one compose reaches the model as context, once', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  await $.session.start(START)
+  expect(await compose($)).toEqual(ENGINE)
+  r.file = stateText()
+  const first = await submit($)
+  expect(first).toHaveLength(1)
+  expect(first[0]).toContain('#204 "Inject the work state"')
+  expect(await submit($)).toEqual([])
+})
+
+test('a step change alone attaches nothing to the next prompt', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  r.file = stateText()
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText({ step: 'execute' })
+  expect(await submit($)).toEqual([])
+})
+
+test('a state removed after the compose attaches the stale note once', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  r.file = stateText()
+  await $.session.start(START)
+  await compose($)
+  r.file = null
+  const first = await submit($)
+  expect(first).toHaveLength(1)
+  expect(first[0]).toContain('# trailhead work state')
+  expect(first[0]).toContain('stale')
+  expect(await submit($)).toEqual([])
+})
+
+test('before any compose a prompt gets nothing attached', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  r.file = stateText()
+  await $.session.start(START)
+  expect(await submit($)).toEqual([])
+})
+
+test('a failing read never drops the prompt', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText()
+  r.repoFails = true
+  const result = (await $.prompt.submit({ text: 'next' })) as { text?: string }
+  expect(result.text).toBe('next')
+})
+
+// The real engine composes every turn but keeps sending the first system prompt.
+test('an engine compose per turn never advances the latch: the submit still carries the change', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  await $.session.start(START)
+  expect(await compose($, ['lean', 'print', 'skills'])).toEqual(ENGINE)
+  r.file = stateText()
+  await turn($)
+  expect(await compose($, ['lean', 'print', 'skills'])).toEqual(ENGINE)
+  const first = await submit($)
+  expect(first).toHaveLength(1)
+  expect(first[0]).toContain('#204 "Inject the work state"')
+  expect(await submit($)).toEqual([])
+})
+
+test('a compose after the latch is set returns the latched text, not the live one', async ($, on) => {
+  const r = rig(on)
+  r.file = stateText()
+  await $.session.start(START)
+  const first = (mine(await compose($)) as Section).text
+  r.file = stateText({ ticket: 205, title: 'Next ticket' })
+  await turn($)
+  expect((mine(await compose($, ['analysis'])) as Section).text).toBe(first)
+})
+
+test('a prompt dropped beneath keeps the change for the next one', async ($, on) => {
+  const r = rig(on)
+  let drops = 1
+  on('prompt.submit', (_$, e) => (drops-- > 0 ? { drop: 'busy' } : { text: e.text, context: e.context }))
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText()
+  const dropped = (await $.prompt.submit({ text: 'next' })) as { drop?: string }
+  expect(dropped.drop).toBe('busy')
+  const again = await submit($)
+  expect(again).toHaveLength(1)
+  expect(again[0]).toContain('#204')
+  expect(await submit($)).toEqual([])
+})
+
+test('a failing latch write never drops the prompt and the next one delivers the change', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText()
+  r.denyLatch = true
+  const result = (await $.prompt.submit({ text: 'next' })) as { text?: string; context?: readonly string[] }
+  expect(result.text).toBe('next')
+  expect(result.context ?? []).toEqual([])
+  r.denyLatch = false
+  const again = await submit($)
+  expect(again).toHaveLength(1)
+  expect(again[0]).toContain('#204')
+  expect(await submit($)).toEqual([])
+})
+
+test('a hook failing beneath after the note was attached re-delivers it on the next prompt', async ($, on) => {
+  const r = rig(on)
+  let fails = 1
+  on('prompt.submit', (_$, e) => {
+    if (fails-- > 0) throw new Error('boom')
+    return { text: e.text, context: e.context }
+  })
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText()
+  const first = await $.prompt.submit({ text: 'next' }).catch(() => ({ context: [] as string[] }))
+  expect((first as { context?: readonly string[] }).context ?? []).toEqual([])
+  const again = await submit($)
+  expect(again).toHaveLength(1)
+  expect(again[0]).toContain('#204')
+  expect(await submit($)).toEqual([])
+})
+
+test('a pin moved to another repo with the same ticket attaches the section with the new links', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  r.file = stateText()
+  await $.session.start(START)
+  await compose($)
+  r.remote = 'https://github.com/o/other.git'
+  await turn($)
+  const moved = await submit($)
+  expect(moved).toHaveLength(1)
+  expect(moved[0]).toContain('#204 "Inject the work state" https://github.com/o/other/issues/204')
+  expect(moved[0]).not.toContain('ToRvaLDz')
+})
+
+test('two overlapping prompts attach the change once', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText()
+  const all = await Promise.all([submit($), submit($)])
+  expect(all.flat()).toHaveLength(1)
+})
+
+test('a slash command attaches nothing and keeps the change for the next prompt', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText()
+  const cmd = (await $.prompt.submit({ text: '/compact', command: 'compact' })) as { context?: readonly string[] }
+  expect(cmd.context ?? []).toEqual([])
+  expect(await submit($)).toHaveLength(1)
+})
+
+test('an orphaned state after a latched one gives the stale note', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  r.file = stateText()
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText({ session: 'sess-other' })
+  const first = await submit($)
+  expect(first).toHaveLength(1)
+  expect(first[0]).toContain('stale')
+})
+
+test('an existing context is kept and the section appended', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText()
+  const result = (await $.prompt.submit({ text: 'next', context: ['earlier'] })) as { context?: readonly string[] }
+  expect(result.context?.[0]).toBe('earlier')
+  expect(result.context).toHaveLength(2)
+  expect(result.context?.[1]).toContain('#204')
+})
+
+test('a compaction or a clear resets the latch: a prompt before the next compose gets nothing', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  on('classic.SessionStart', () => ({}))
+  r.file = stateText()
+  await $.session.start(START)
+  await compose($)
+  await $.session.compact({ messages: SUMMARY })
+  r.file = stateText({ ticket: 205, title: 'Next ticket' })
+  expect(await submit($)).toEqual([])
+  await compose($)
+  await $.classic.SessionStart({ source: 'clear' })
+  r.file = stateText({ ticket: 206, title: 'Third' })
+  expect(await submit($)).toEqual([])
+})
+
+test('a ticket to ticket change attaches the new section', async ($, on) => {
+  const r = rig(on)
+  on('prompt.submit', (_$, e) => ({ text: e.text, context: e.context }))
+  r.file = stateText()
+  await $.session.start(START)
+  await compose($)
+  r.file = stateText({ ticket: 205, title: 'Next ticket' })
+  const first = await submit($)
+  expect(first).toHaveLength(1)
+  expect(first[0]).toContain('#205 "Next ticket"')
+})