@raidiant/notifai 4.0.0 → 6.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('not specified; the destination uses its normal behavior')
+    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

@@ -83,9 +83,9 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     label: 'Send questions to my devices',
     group: 'questions',
     kind: 'boolean',
-    summary: 'Whether a registered question may reach your phone and Mac at all',
+    summary: 'Whether a registered question may reach your iPhone 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',
@@ -113,8 +124,8 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     },
     summary: 'Set the sound notifications from here use',
     detail:
-      'Setting this pins one sound for every notification sent from here. Kind remains semantic status metadata and never changes native-banner attention.\n\nLeave this unset to omit the sound field and let the destination use its normal behavior. A common explicit preference is `none`, to make a noisy project completely silent.',
-    unsetMeans: 'not specified; the destination uses its normal behavior',
+      '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,11 +135,11 @@ 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: 'Set how insistently notifications from here arrive',
     detail:
-      '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 never changes it.\n\nLeave this unset to omit the field and let the destination use its normal behavior. `time_sensitive` can pierce a Focus mode, so reserve it for cases that genuinely earn it.',
+      '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: {

package/src/config.test.ts

@@ -177,6 +177,15 @@ describe('config precedence', () => {
     expect(config.wait_seconds.value).toBe(2)
     expect(config.wait_seconds.source).toBe('flag')
   })
+
+  it('uses the prior default when a newer CLI wrote an unknown enum value', () => {
+    const { env, cwd } = setup({
+      globalToml: 'sound = "future-sound"\ninterruption_level = "future-level"\n',
+    })
+    const config = loadConfig({ cwd, env })
+    expect(config.sound).toEqual({ value: null, source: 'default' })
+    expect(config.interruption_level).toEqual({ value: null, source: 'default' })
+  })
 })
 
 describe('draft building', () => {
@@ -191,20 +200,32 @@ describe('draft building', () => {
       presentation: { title: 'T', body: 'B' },
       targets: { mode: 'all' },
       delivery: { ttl_seconds: 86400, collapse_key: null },
+      // An unlabelled draft is ordinary news, and news has a sound.
+      platform: { ios: { sound: 'default' }, macos: { sound: 'default' } },
     })
   })
 
   it.each([
-    {},
-    { kind: 'done' },
-    { kind: 'failed' },
-    { kind: 'blocked' },
-    { reply: true },
-  ])('never derives sound or interruption level from kind: %j', (flags) => {
+    { 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).toBeUndefined()
+    expect(build.draft.platform?.ios?.sound).toBe(sound)
+    expect(build.draft.platform?.ios?.interruption_level).toBeUndefined()
+  })
+
+  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', () => {
@@ -233,12 +254,32 @@ 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('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', () => {

package/src/config.ts

@@ -1,8 +1,12 @@
+import {
+  CLI_SOUNDS,
+  INTERRUPTION_LEVELS,
+  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'
 import { parse as parseToml } from 'smol-toml'
-import type { CLI_SOUNDS, INTERRUPTION_LEVELS } from '@raidiant/notifai-protocol'
 import { configHome, stateHome } from './platform.js'
 
 /**
@@ -87,6 +91,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 +108,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 +123,7 @@ export const NUMERIC_CONFIG_KEYS: readonly ConfigKey[] = [
   'wait_seconds',
   'ttl_seconds',
   'ask_grace_seconds',
+  'reply_window_seconds',
   'log_max_bytes',
   'log_max_files',
 ]
@@ -128,6 +136,8 @@ export const NUMERIC_CONFIG_KEYS: readonly ConfigKey[] = [
  * is the same discipline the numeric bounds follow.
  */
 export const ENUM_CONFIG_VALUES: Partial<Record<ConfigKey, readonly string[]>> = {
+  sound: CLI_SOUNDS,
+  interruption_level: INTERRUPTION_LEVELS,
   log_level: LOG_LEVELS,
 }
 
@@ -149,6 +159,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 +315,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".
@@ -413,6 +430,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/credentials.test.ts

@@ -168,7 +168,10 @@ describe('FileStore', () => {
     if (process.platform !== 'win32') {
       expect(statSync(file).mode & 0o777).toBe(0o600)
     }
-    expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual(SAMPLE)
+    expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual({
+      format: 'notifai.machine-credential.v1',
+      ...SAMPLE,
+    })
     expect(store.load()).toEqual(SAMPLE)
     store.save(OTHER)
     expect(store.load()).toEqual(OTHER)
@@ -190,6 +193,27 @@ describe('FileStore', () => {
     writeRaw(file, `${JSON.stringify({ machineId: 'mach_fixture' })}\n`)
     expect(new FileStore(env).load()).toBeNull()
   })
+
+  it('reads the unversioned v1 shape while making every new save explicit', () => {
+    const { env } = sandbox('file-unversioned-v1')
+    const file = path.join(env.XDG_CONFIG_HOME!, 'notifai', 'credentials.json')
+    writeRaw(file, `${JSON.stringify(SAMPLE)}\n`)
+    const store = new FileStore(env)
+    expect(store.load()).toEqual(SAMPLE)
+    store.save(SAMPLE)
+    expect(JSON.parse(readFileSync(file, 'utf8'))).toMatchObject({
+      format: 'notifai.machine-credential.v1',
+    })
+  })
+
+  it('does not interpret or erase a credential from a future format epoch', () => {
+    const { env } = sandbox('file-future-format')
+    const file = path.join(env.XDG_CONFIG_HOME!, 'notifai', 'credentials.json')
+    const future = `${JSON.stringify({ format: 'notifai.machine-credential.v2', ...SAMPLE })}\n`
+    writeRaw(file, future)
+    expect(new FileStore(env).load()).toBeNull()
+    expect(readFileSync(file, 'utf8')).toBe(future)
+  })
 })
 
 describe('WindowsDpapiStore', () => {

package/src/credentials.ts

@@ -44,6 +44,7 @@ export interface CredentialStoreOptions {
 }
 
 const SERVICE = 'io.notifai.cli'
+const CREDENTIAL_FORMAT = 'notifai.machine-credential.v1'
 const DPAPI_FORMAT = 'notifai.dpapi.current-user.v1'
 const DPAPI_ENTROPY = 'io.notifai.cli'
 const DPAPI_TIMEOUT_MS = 15_000
@@ -136,7 +137,7 @@ export class KeychainStore implements CredentialStore {
         '-a',
         'machine',
         '-w',
-        JSON.stringify(credential),
+        JSON.stringify(serializeCredential(credential)),
       ],
       { stdio: 'ignore' },
     )
@@ -189,7 +190,7 @@ export class FileStore implements CredentialStore {
   }
 
   save(credential: MachineCredential): void {
-    atomicWriteFileSync(this.filePath(), `${JSON.stringify(credential, null, 2)}\n`, {
+    atomicWriteFileSync(this.filePath(), `${JSON.stringify(serializeCredential(credential), null, 2)}\n`, {
       mode: 0o600,
       preserveMode: false,
       requireCurrentUserOwner: true,
@@ -251,7 +252,7 @@ export class WindowsDpapiStore implements CredentialStore {
     if (file === null) {
       throw new Error('Windows credential store path is not configured (LOCALAPPDATA is missing)')
     }
-    const blob = this.protect(Buffer.from(JSON.stringify(credential), 'utf8'))
+    const blob = this.protect(Buffer.from(JSON.stringify(serializeCredential(credential)), 'utf8'))
     atomicWriteFileSync(file, `${JSON.stringify({ format: DPAPI_FORMAT, data: blob })}\n`, {
       mode: 0o600,
       preserveMode: false,
@@ -302,6 +303,10 @@ export class WindowsDpapiStore implements CredentialStore {
   }
 }
 
+function serializeCredential(credential: MachineCredential): Record<string, string> {
+  return { format: CREDENTIAL_FORMAT, ...credential }
+}
+
 function parseCredentialJson(raw: string): MachineCredential | null {
   try {
     return parseCredential(JSON.parse(raw) as unknown)
@@ -313,6 +318,11 @@ function parseCredentialJson(raw: string): MachineCredential | null {
 function parseCredential(raw: unknown): MachineCredential | null {
   if (raw === null || typeof raw !== 'object') return null
   const value = raw as Record<string, unknown>
+  const format = value['format']
+  // Unversioned credentials are the pre-epoch v1 representation. A future
+  // format is left untouched on disk/keychain and treated as unavailable;
+  // interpreting it as v1 could silently change authentication meaning.
+  if (format !== undefined && format !== CREDENTIAL_FORMAT) return null
   const machineId = value['machineId']
   const secret = value['secret']
   const baseUrl = value['baseUrl']

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. */