@raidiant/notifai 3.0.1 → 5.0.0

package/src/config-schema.test.ts

@@ -86,7 +86,7 @@ describe('formatValue', () => {
   it('explains what an unset value means instead of printing null', () => {
     // `sound = null` is accurate and tells the reader nothing about what will
     // happen; the whole complaint about the old output in one line.
-    expect(formatValue('sound', null)).toBe('each notification uses the sound for its kind')
+    expect(formatValue('sound', null)).toBe('not set; each kind brings its own sound')
     expect(formatValue('devices', null)).toBe('every device that can receive')
   })
 

package/src/config-schema.ts

@@ -85,7 +85,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     kind: 'boolean',
     summary: 'Whether a registered question may reach your phone and Mac at all',
     detail:
-      'The master switch for question routing. When this is off, a question an agent registers with `notifai ask` stays in the terminal and never leaves this machine, whatever the presence settings say. Turn it off to stop being reached for a while without uninstalling the harness hooks.',
+      'The master switch for question routing. When this is off, a question an agent registers with `notifai ask` stays in the terminal and never leaves this machine, whatever else is configured. Turn it off to stop being reached for a while without uninstalling the harness hooks.',
     example: 'true',
   },
   ask_grace_seconds: {
@@ -99,6 +99,17 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     example: '0',
   },
 
+  reply_window_seconds: {
+    label: 'How long an answer is accepted',
+    group: 'questions',
+    kind: 'integer',
+    unit: 's',
+    summary: 'How long the service keeps accepting your answer to a question',
+    detail:
+      'A question stays answerable for this long after it is asked. The default is a day, so a question that arrives while you are away is still yours to answer when you come back.\n\nThis is not how long anything waits on you. The agent ends its turn immediately; if it is still running when you answer, the answer reaches it directly, and otherwise it is delivered at that session\'s next turn. Shortening this only makes an answer arrive too late to be accepted.',
+    example: '86400',
+  },
+
   sound: {
     label: 'Sound',
     group: 'delivery',
@@ -107,14 +118,14 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     choiceHints: {
       default: 'the standard notification tone',
       done: 'the completion chime',
-      attention: 'used for questions that want an answer',
+      attention: 'a distinct attention tone',
       alert: 'the most insistent tone',
       none: 'silent — arrives without a sound',
     },
-    summary: 'Override the sound every notification uses',
+    summary: 'Set the sound notifications from here use',
     detail:
-      'Normally the sound comes from what the notification is: progress updates are silent, completions get the done chime, questions get the attention tone. Setting this pins one sound for everything sent from here, overriding those profiles.\n\nA common use is `none`, to make a noisy project completely silent.',
-    unsetMeans: 'each notification uses the sound for its kind',
+      'Setting this pins one sound for every notification sent from here, whatever kind it is.\n\nLeave it unset and each notification arrives with the sound its kind implies: the completion chime when work finished, the most insistent tone when it failed, a distinct attention tone for a question or blocked work, and the standard tone for ordinary news. A common explicit preference is `none`, to make a noisy project completely silent.',
+    unsetMeans: 'not set; each kind brings its own sound',
   },
   interruption_level: {
     label: 'Interruption level',
@@ -124,12 +135,12 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     choiceHints: {
       passive: 'no sound or wake — waits in the notification list',
       active: 'wakes the screen and plays the sound',
-      time_sensitive: 'may break through Focus modes',
+      time_sensitive: 'marks the notification urgent; Focus breakthrough is not available yet',
     },
-    summary: 'Override how insistently notifications arrive',
+    summary: 'Set how insistently notifications from here arrive',
     detail:
-      'How hard a notification tries to reach you, in the operating system\'s terms. Like the sound, this is normally decided by what the notification is; setting it pins one level for everything.\n\n`time_sensitive` can pierce a Focus mode, so it is worth reserving for the cases that genuinely earn it.',
-    unsetMeans: 'each notification uses the level for its kind',
+      'How hard a notification tries to reach you, in the operating system\'s terms. Setting this pins one level for everything sent from here; kind chooses the sound, never this.\n\nLeave this unset to omit the field and let the destination use its normal behavior. `time_sensitive` is accepted and marks the notification urgent, but Focus breakthrough is not available yet — run `notifai capabilities` for what a platform actually honours.',
+    unsetMeans: 'not specified; the destination uses its normal behavior',
   },
   devices: {
     label: 'Default devices',
@@ -178,8 +189,8 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     kind: 'string',
     summary: 'The name this project reports itself as',
     detail:
-      'Stamped on every notification sent from this directory, and how the companion apps group and filter what arrives. Normally set once in `.notifai/config.toml` and committed, so everyone working on the repository reports the same name.',
-    unsetMeans: 'notifications arrive without a project',
+      'Stamped on every notification sent from this directory, and how the companion apps group and filter what arrives. When unset, the CLI infers a stable identifier from Git (shared across linked worktrees) or the current directory. Set it in `.notifai/config.toml` only when that inferred name is not the identity you want.',
+    unsetMeans: 'inferred from Git or the current directory',
     example: 'my-app',
   },
   notify_criteria: {

package/src/config.test.ts

@@ -98,6 +98,25 @@ describe('harness config layers', () => {
     })
   })
 
+  it('uses NOTIFAI_SESSION_ID for the session layer and ignores the deleted env name', () => {
+    const { env, cwd } = setup({
+      sessionToml: 'ask_grace_seconds = 45\n',
+      sessionId: 'exact-session',
+    })
+    expect(
+      loadConfig({
+        cwd,
+        env: { ...env, NOTIFAI_SESSION_ID: 'exact-session' },
+      }).ask_grace_seconds.value,
+    ).toBe(45)
+    expect(
+      loadConfig({
+        cwd,
+        env: { ...env, NOTIFAI_SESSION: 'exact-session' },
+      }).ask_grace_seconds.value,
+    ).toBe(0)
+  })
+
   it('keeps hostile or colliding session ids inside their own file', () => {
     const { env, cwd } = setup({
       sessionToml: 'ask_grace_seconds = 99\n',
@@ -172,28 +191,35 @@ describe('draft building', () => {
       presentation: { title: 'T', body: 'B' },
       targets: { mode: 'all' },
       delivery: { ttl_seconds: 86400, collapse_key: null },
-      platform: {
-        ios: { sound: null, interruption_level: 'passive' },
-        macos: { sound: null, interruption_level: 'passive' },
-      },
+      // An unlabelled draft is ordinary news, and news has a sound.
+      platform: { ios: { sound: 'default' }, macos: { sound: 'default' } },
     })
   })
 
   it.each([
-    { flags: {}, sound: null, level: 'passive' },
-    { flags: { kind: 'done' }, sound: 'done', level: 'passive' },
-    { flags: { reply: true }, sound: 'attention', level: 'active' },
-  ])('derives the $sound / $level kind profile from $flags', ({ flags, sound, level }) => {
+    { flags: {}, sound: 'default' },
+    { flags: { kind: 'update' }, sound: 'default' },
+    { flags: { kind: 'done' }, sound: 'done' },
+    { flags: { kind: 'failed' }, sound: 'alert' },
+    { flags: { kind: 'blocked' }, sound: 'attention' },
+    { flags: { kind: 'question' }, sound: 'attention' },
+    { flags: { reply: true }, sound: 'attention' },
+  ])('gives $flags the $sound sound when nobody chose one', ({ flags, sound }) => {
     const config = loadConfig({ cwd: base.cwd, env: base.env })
     const build = buildDraft(config, { title: 'T', body: 'B', ...flags })
     if (!build.ok) throw new Error(build.error)
-    expect(build.draft.platform).toEqual({
-      ios: { sound, interruption_level: level },
-      macos: { sound, interruption_level: level },
-    })
+    expect(build.draft.platform?.ios?.sound).toBe(sound)
+    expect(build.draft.platform?.ios?.interruption_level).toBeUndefined()
   })
 
-  it('orders explicit flags over user config over the kind profile', () => {
+  it('lets an explicit sound outrank the kind it would have derived', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const explicit = buildDraft(config, { title: 'T', body: 'B', kind: 'failed', sound: 'none' })
+    if (!explicit.ok) throw new Error(explicit.error)
+    expect(explicit.draft.platform?.ios?.sound).toBeNull()
+  })
+
+  it('orders explicit flags over saved user config', () => {
     const { env, cwd } = setup({
       projectToml: 'sound = "alert"\ninterruption_level = "active"\n',
     })
@@ -219,23 +245,157 @@ describe('draft building', () => {
     })
   })
 
-  it('keeps a blocking reply answerable for one hour by default', () => {
+  it('keeps a question answerable for a day by default', () => {
+    // A question asked before someone steps away should still be theirs to
+    // answer when they come back; the CLI used to cut the wire contract's own
+    // default down to an hour.
     const config = loadConfig({ cwd: base.cwd, env: base.env })
     const build = buildDraft(config, { title: 'Question', body: 'Deploy?', reply: true })
     if (!build.ok) throw new Error(build.error)
 
-    expect(build.draft.reply?.expires_in_seconds).toBe(3_600)
+    expect(build.draft.reply?.expires_in_seconds).toBe(86_400)
   })
 
-  it('stamps the project from flag or project config', () => {
+  it('lets the user shorten or lengthen how long an answer is accepted', () => {
+    const { env, cwd } = setup({ projectToml: 'reply_window_seconds = 7200\n' })
+    const config = loadConfig({ cwd, env })
+    const build = buildDraft(config, { title: 'Question', body: 'Deploy?', reply: true })
+    if (!build.ok) throw new Error(build.error)
+    expect(build.draft.reply?.expires_in_seconds).toBe(7_200)
+
+    const explicit = buildDraft(config, {
+      title: 'Question',
+      body: 'Deploy?',
+      reply: true,
+      replyWindow: 600,
+    })
+    if (!explicit.ok) throw new Error(explicit.error)
+    expect(explicit.draft.reply?.expires_in_seconds).toBe(600)
+  })
+
+  it('orders explicit and configured Project identity over inference', () => {
     const { env, cwd } = setup({ projectToml: 'project = "my-app"\n' })
     const config = loadConfig({ cwd, env })
-    const fromConfig = buildDraft(config, { title: 'T', body: 'B' })
+    const fromConfig = buildDraft(
+      config,
+      { title: 'T', body: 'B' },
+      { inferredProject: 'inferred-app' },
+    )
     if (!fromConfig.ok) throw new Error(fromConfig.error)
     expect(fromConfig.draft.project).toBe('my-app')
-    const fromFlag = buildDraft(config, { title: 'T', body: 'B', project: 'other-app' })
+    const fromFlag = buildDraft(
+      config,
+      { title: 'T', body: 'B', project: 'other-app' },
+      { inferredProject: 'inferred-app' },
+    )
     if (!fromFlag.ok) throw new Error(fromFlag.error)
     expect(fromFlag.draft.project).toBe('other-app')
+
+    const inferredCase = setup({})
+    const unset = loadConfig({ cwd: inferredCase.cwd, env: inferredCase.env })
+    const inferred = buildDraft(
+      unset,
+      { title: 'T', body: 'B' },
+      { inferredProject: 'inferred-app' },
+    )
+    if (!inferred.ok) throw new Error(inferred.error)
+    expect(inferred.draft.project).toBe('inferred-app')
+  })
+
+  it('carries Source Context without copying authoring overrides into legacy fields', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(
+      config,
+      { title: 'T', body: 'B', sessionId: 'opaque', sessionLabel: 'Visible' },
+      {
+        source: {
+          session_id: 'opaque',
+          session_label: 'Visible',
+          harness: 'codex',
+          branch: 'main',
+          worktree: 'topic',
+        },
+      },
+    )
+    if (!build.ok) throw new Error(build.error)
+    expect(build.draft.source).toEqual({
+      session_id: 'opaque',
+      session_label: 'Visible',
+      harness: 'codex',
+      branch: 'main',
+      worktree: 'topic',
+    })
+    expect(build.draft).not.toHaveProperty('session')
+  })
+
+  it('rewrites positional media references and preserves canonical ids', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(config, {
+      title: 'Visual result',
+      body: '![first](media:1) then ![second](media:2) and ![existing](media:med_keep)',
+      image: ['med_first', 'med_second', 'med_attached'],
+      imageAlt: ['First image', 'Second image'],
+    })
+    if (!build.ok) throw new Error(build.error)
+    expect(build.draft.presentation.body).toBe(
+      '![first](media:med_first) then ![second](media:med_second) and ![existing](media:med_keep)',
+    )
+    expect(build.draft.presentation.body).not.toMatch(/media:[1-8](?!\d)/)
+    expect(build.draft.presentation.media).toEqual([
+      { media_id: 'med_first', alt: 'First image' },
+      { media_id: 'med_second', alt: 'Second image' },
+      { media_id: 'med_attached' },
+    ])
+  })
+
+  it('preserves sparse alt text in an internal ordered media manifest', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(config, {
+      title: 'Visual result',
+      body: '![second](media:2)',
+      media: [
+        { media_id: 'med_first' },
+        { media_id: 'med_second', alt: 'Second image' },
+      ],
+    })
+    if (!build.ok) throw new Error(build.error)
+    expect(build.draft.presentation.body).toBe('![second](media:med_second)')
+    expect(build.draft.presentation.media).toEqual([
+      { media_id: 'med_first' },
+      { media_id: 'med_second', alt: 'Second image' },
+    ])
+  })
+
+  it('names an out-of-range positional media reference', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(config, {
+      title: 'Visual result',
+      body: '![missing](media:3)',
+      image: ['med_first', 'med_second'],
+    })
+    expect(build).toEqual({
+      ok: false,
+      error: 'Body reference "media:3" has no matching --image occurrence.',
+    })
+  })
+
+  it('validates media cardinality and alt pairing', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    expect(
+      buildDraft(config, {
+        title: 'T',
+        body: 'B',
+        image: Array.from({ length: 9 }, (_, index) => `med_${index}`),
+      }),
+    ).toMatchObject({ ok: false, error: expect.stringContaining('at most 8') })
+    expect(
+      buildDraft(config, {
+        title: 'T',
+        body: 'B',
+        image: ['med_one'],
+        imageAlt: ['one', 'two'],
+      }),
+    ).toMatchObject({ ok: false, error: expect.stringContaining('2 --image-alt') })
   })
 
   it('carries --kind and rejects one outside the vocabulary', () => {

package/src/config.ts

@@ -1,3 +1,4 @@
+import { REPLY_MAX_WINDOW_SECONDS } from '@raidiant/notifai-protocol'
 import { createHash } from 'node:crypto'
 import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import path from 'node:path'
@@ -87,6 +88,8 @@ export interface CliConfig {
    * usefulness.
    */
   log_max_bytes: ResolvedValue<number>
+  /** How long the server keeps accepting an answer to a question. */
+  reply_window_seconds: ResolvedValue<number>
   /** Log files kept in total, the active one included. */
   log_max_files: ResolvedValue<number>
 }
@@ -102,6 +105,7 @@ export const CONFIG_KEYS = [
   'notify_criteria',
   'ask_notifications',
   'ask_grace_seconds',
+  'reply_window_seconds',
   'log_level',
   'log_max_bytes',
   'log_max_files',
@@ -116,6 +120,7 @@ export const NUMERIC_CONFIG_KEYS: readonly ConfigKey[] = [
   'wait_seconds',
   'ttl_seconds',
   'ask_grace_seconds',
+  'reply_window_seconds',
   'log_max_bytes',
   'log_max_files',
 ]
@@ -149,6 +154,9 @@ const DEFAULTS = {
   // Questions reach devices as soon as the turn ends. A terminal-first grace
   // window is an opt-in delay on top of that.
   ask_grace_seconds: 0,
+  // A day. The wire contract's own default, and long enough that a question
+  // asked before someone steps away is still answerable when they come back.
+  reply_window_seconds: 86_400,
   // On by default: the log is the only account of what a headless hook did, and
   // a diagnostic nobody switched on before the thing went wrong is not one.
   log_level: 'info',
@@ -302,6 +310,10 @@ const NUMERIC_BOUNDS: Partial<Record<ConfigKey, { min: number; max: number }>> =
   // longest window a user can choose still leaves an answer window the server
   // will accept — with room to spare for a timer that wakes late.
   ask_grace_seconds: { min: 0, max: 360 },
+  // The floor is the shortest window the wire contract accepts; the ceiling is
+  // the point past which a question would outlive the retained content it
+  // refers to.
+  reply_window_seconds: { min: 60, max: REPLY_MAX_WINDOW_SECONDS },
   // The floor keeps rotation from thrashing (a file smaller than a handful of
   // records would rotate on nearly every write); the ceiling is the point past
   // which "local diagnostics" has become "a database on your disk".
@@ -380,7 +392,7 @@ export function loadConfig(options: {
   const projectRaw = projectPath ? readTomlFile(projectPath) : {}
   const projectLocalPath = findProjectLocalConfigPath(cwd, env)
   const projectLocalRaw = projectLocalPath ? readTomlFile(projectLocalPath) : {}
-  const sessionId = options.sessionId ?? env['NOTIFAI_SESSION']
+  const sessionId = options.sessionId ?? env['NOTIFAI_SESSION_ID']
   const sessionPath = sessionId ? sessionConfigPath(sessionId, env) : null
   const sessionRaw = sessionPath && existsSync(sessionPath) ? readTomlFile(sessionPath) : {}
 
@@ -413,6 +425,7 @@ export function loadConfig(options: {
     notify_criteria: resolve('notify_criteria'),
     ask_notifications: resolve('ask_notifications'),
     ask_grace_seconds: resolve('ask_grace_seconds'),
+    reply_window_seconds: resolve('reply_window_seconds'),
     log_level: resolve('log_level'),
     log_max_bytes: resolve('log_max_bytes'),
     log_max_files: resolve('log_max_files'),

package/src/file-lock.test.ts

@@ -206,6 +206,47 @@ describe('cross-process file lock', () => {
   }, 30_000)
 })
 
+describe('rendezvous contention', () => {
+  // The last contender out removes the rendezvous directory, so a contender
+  // registering at that instant races the removal. Both tests drive that race
+  // from the registering observation, which is the window the racing releaser
+  // would otherwise have to hit by luck — on a loaded machine it does.
+  function raceAtRegistration(interfere: (lock: string) => void): void {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-rendezvous-'))
+    const lock = path.join(root, 'shared.lock')
+    let raced = false
+    let entered = 0
+
+    withFileLock(lock, () => { entered += 1 }, {
+      observe(observation) {
+        if (observation.phase !== 'registering' || raced) return
+        raced = true
+        interfere(lock)
+      },
+    })
+
+    expect(raced).toBe(true)
+    expect(entered).toBe(1)
+    // Release still cleans up after itself, whichever rendezvous it ended in.
+    expect(existsSync(lock)).toBe(false)
+    rmSync(root, { recursive: true, force: true })
+  }
+
+  it('registers again when a releasing contender removed the rendezvous', () => {
+    raceAtRegistration((lock) => rmSync(lock, { recursive: true }))
+  })
+
+  it('holds the rendezvous it landed in, not the one it scanned', () => {
+    // A third contender recreates the directory before this one publishes, so
+    // the entry lands in a directory whose identity nobody has recorded yet.
+    // Treating that as tampering used to break the caller outright.
+    raceAtRegistration((lock) => {
+      rmSync(lock, { recursive: true })
+      mkdirSync(lock, { mode: 0o700 })
+    })
+  })
+})
+
 describe('target file transaction lock', () => {
   it('refuses a symlinked target parent before publishing a contender', () => {
     const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))

package/src/file-lock.ts

@@ -22,6 +22,14 @@ import path from 'node:path'
  * process cannot remove a later owner's entry; because process liveness, rather
  * than age, decides recovery, a delayed holder is never mistaken for a dead one.
  *
+ * The rendezvous directory lives only as long as it has entries: the last
+ * contender out removes it, so an idle machine keeps no lock state. That makes
+ * the directory itself a contended resource. A contender registering while
+ * another releases can find it gone, half-deleted, or already replaced by a
+ * third contender, and none of those is a broken lock — so publication retries
+ * within the caller's deadline and pins its rendezvous only once its own entry
+ * is in the directory, which is the moment removal becomes impossible.
+ *
  * Acquisition is deliberately bounded because both harness hooks and logging
  * must fail open rather than hold an agent turn indefinitely.
  */
@@ -32,6 +40,8 @@ const ENTRY_PATTERN = /^(choosing|ticket-(\d+))-(\d+)-([0-9a-f]+)$/
 const lockSleep = new Int32Array(new SharedArrayBuffer(4))
 
 export type FileLockObservation =
+  /** The rendezvous has been scanned and this contender is about to publish. */
+  | { phase: 'registering'; entry: string }
   | { phase: 'choosing-published'; entry: string }
   | { phase: 'stale-entry'; entry: string }
   | { phase: 'waiting'; blockers: string[] }
@@ -125,6 +135,16 @@ function assertOwnedDirectory(directory: string): FileIdentity {
   return { dev: stat.dev, ino: stat.ino }
 }
 
+/**
+ * The rendezvous a contender was using is no longer the directory at that path.
+ *
+ * Fatal once an entry is published — a contender's own entry makes the
+ * directory non-empty, so no cooperating releaser can remove it. Before
+ * publication it means only that a releaser removed an empty rendezvous while
+ * this contender was registering in it, which is ordinary contention.
+ */
+class RendezvousReplaced extends Error {}
+
 function assertSameDirectory(directory: string, expected: FileIdentity): void {
   const current = lstatSync(directory)
   if (
@@ -133,7 +153,7 @@ function assertSameDirectory(directory: string, expected: FileIdentity): void {
     current.dev !== expected.dev ||
     current.ino !== expected.ino
   ) {
-    throw new Error(`${directory} changed while the file lock was active.`)
+    throw new RendezvousReplaced(`${directory} changed while the file lock was active.`)
   }
 }
 
@@ -207,6 +227,24 @@ function publishEmpty(file: string): EntryIdentity {
   }
 }
 
+/**
+ * True when a publication attempt lost its rendezvous rather than found a
+ * broken one.
+ *
+ * A releaser removes an empty rendezvous directory the moment the last entry
+ * goes, so a contender registering at that instant sees the removal from
+ * whichever side it reached first. All three are the same event: `ENOENT` when
+ * the directory is already gone, `EINVAL` when APFS reports a directory that is
+ * still being deleted, and a replaced identity when a third contender recreated
+ * it first. None of them says anything about the lock's integrity, because a
+ * contender with no published entry owns nothing yet.
+ */
+function lostTheRendezvous(err: unknown): boolean {
+  if (err instanceof RendezvousReplaced) return true
+  const code = (err as NodeJS.ErrnoException).code
+  return code === 'ENOENT' || code === 'EINVAL'
+}
+
 function publishChoosing(
   directory: string,
   name: string,
@@ -217,21 +255,33 @@ function publishChoosing(
   for (;;) {
     try {
       mkdirSync(directory, { recursive: true, mode: 0o700 })
-      const directoryIdentity = assertOwnedDirectory(directory)
+      const registrar = assertOwnedDirectory(directory)
       chmodSync(directory, 0o700)
       // Recover before registration so a delayed stale cleanup can only name an
       // old owner's unique path, never this contender's future one.
-      liveEntries(directory, directoryIdentity, observe)
+      liveEntries(directory, registrar, observe)
+      observe?.({ phase: 'registering', entry: name })
       const fileIdentity = publishEmpty(file)
-      assertSameDirectory(directory, directoryIdentity)
+      // Pin the rendezvous that holds the entry, not the one scanned before it
+      // existed. `open` resolves the path atomically, so the entry lands in
+      // whichever directory the path named at that instant — and from then on
+      // that directory is non-empty, so no cooperating releaser can remove it.
+      // Reading the identity here therefore names the contender's real
+      // rendezvous even when the scanned one was removed and recreated
+      // underneath it.
+      const directoryIdentity = assertOwnedDirectory(directory)
+      if (!sameEntryIdentity(file, fileIdentity)) {
+        throw new RendezvousReplaced(`${directory} no longer holds ${name}.`)
+      }
       return { file, fileIdentity, directoryIdentity }
     } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
-      // The previous holder removed an empty rendezvous directory between our
-      // mkdir and publication. Recreate it; once our entry exists, no cooperating
-      // releaser can remove the non-empty directory underneath us.
+      if (!lostTheRendezvous(err)) throw err
+      // Recreate it and register again; the deadline, not the number of losses,
+      // decides when contention becomes a failure.
       if (Date.now() >= deadline) {
-        throw new Error(`timed out publishing file lock contender in ${directory}`)
+        throw new Error(
+          `timed out publishing file lock contender in ${directory}: ${(err as Error).message}`,
+        )
       }
       Atomics.wait(lockSleep, 0, 0, FILE_LOCK_POLL_MS)
     }

package/src/harnesses.test.ts

@@ -1,34 +1,42 @@
 import { describe, expect, it } from 'vitest'
-import { HARNESS_CAPABILITIES, HARNESSES } from './harnesses.js'
+import { HARNESS_CAPABILITIES, HARNESS_LABELS, HARNESSES } from './harnesses.js'
 
-describe('harness continuation contract', () => {
-  it('requires one explicit native delivery contract for every shipped harness', () => {
+/**
+ * This file used to hold a verbatim copy of the table below it, which meant
+ * changing a harness contract required changing the same words twice and the
+ * test could never disagree with the code — only with whoever forgot the second
+ * edit. What is worth asserting is the shape the rest of the CLI assumes.
+ */
+describe('harness contract', () => {
+  it('describes every shipped harness, and only those', () => {
     expect(Object.keys(HARNESS_CAPABILITIES).sort()).toEqual([...HARNESSES].sort())
-    expect(HARNESS_CAPABILITIES).toEqual({
-      'claude-code': {
-        stopContinuation: 'decision-block',
-        deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
-        deliveryContract:
-          'the Stop hook returns at once and waits out of band, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
-      },
-      codex: {
-        stopContinuation: 'decision-block',
-        deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
-        deliveryContract:
-          'live Stop continuation while the turn is held; once it returns, a stopped thread is resumed behind its writer lock and anything else waits for the next turn',
-      },
-      cursor: {
-        stopContinuation: 'unsupported',
-        deliveryRoutes: ['unsupported'],
-        deliveryContract:
-          'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
-      },
-      opencode: {
-        stopContinuation: 'unsupported',
-        deliveryRoutes: ['unsupported'],
-        deliveryContract:
-          'no proven answer continuation after session.idle; use a blocking reply command',
-      },
-    })
+    expect(Object.keys(HARNESS_LABELS).sort()).toEqual([...HARNESSES].sort())
+  })
+
+  it('gives a harness that cannot continue a turn no route to pretend with', () => {
+    // `ask` fails closed on these, and the reason it can is that the two facts
+    // agree. A harness claiming a delivery route while declaring it cannot
+    // continue would accept an answer into a void.
+    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+      if (capability.stopContinuation !== 'unsupported') continue
+      expect(capability.deliveryRoutes, harness).toEqual(['unsupported'])
+    }
+  })
+
+  it('gives a harness that can continue a turn at least one real route', () => {
+    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+      if (capability.stopContinuation === 'unsupported') continue
+      expect(capability.deliveryRoutes.length, harness).toBeGreaterThan(0)
+      expect(capability.deliveryRoutes, harness).not.toContain('unsupported')
+      // The journal is the floor under every supported route: without it an
+      // answer that misses its turn has nowhere to wait.
+      expect(capability.deliveryRoutes, harness).toContain('hold-for-next-turn')
+    }
+  })
+
+  it('explains each harness in prose an operator can act on', () => {
+    for (const [harness, capability] of Object.entries(HARNESS_CAPABILITIES)) {
+      expect(capability.deliveryContract.length, harness).toBeGreaterThan(40)
+    }
   })
 })

package/src/harnesses.ts

@@ -18,10 +18,7 @@ export type DeliveryRoute =
   | 'hold-for-next-turn'
   | 'unsupported'
 
-export type StopContinuation =
-  | 'decision-block'
-  | 'followup-message'
-  | 'unsupported'
+export type StopContinuation = 'decision-block' | 'unsupported'
 
 export interface HarnessCapability {
   /** How an answer is admitted to another turn in the already-open session. */