@raidiant/notifai 8.0.0 → 9.1.0

package/src/send-attempts.test.ts

@@ -0,0 +1,143 @@
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { NotificationDraftT } from '@raidiant/notifai-protocol'
+import type { MachineCredential } from './credentials.js'
+import {
+  SEND_ATTEMPT_TTL_MS,
+  beginSendAttempt,
+  semanticMediaIds,
+  sendDraftFingerprint,
+  settleSendAttempt,
+} from './send-attempts.js'
+
+const roots: string[] = []
+afterEach(() => {
+  while (roots.length > 0) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function fixture() {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-send-attempt-'))
+  roots.push(root)
+  const env = { XDG_STATE_HOME: path.join(root, 'state') }
+  const credential: MachineCredential = {
+    machineId: 'mac_attempt',
+    machineName: 'Attempt Machine',
+    baseUrl: 'https://app.notifai.test',
+    secret: 'private-machine-secret',
+  }
+  const draft = {
+    schema_version: 1,
+    kind: 'done',
+    project: 'private-project',
+    presentation: { title: 'Sensitive result', body: 'Private body text' },
+    targets: { mode: 'all' },
+  } as NotificationDraftT
+  return { root, env, credential, draft }
+}
+
+describe('opaque interrupted-send recovery', () => {
+  it('matches one exact semantic retry without storing notification content', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    const first = beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(first.ok).toBe(true)
+    if (!first.ok) return
+
+    const files = readdirSync(path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts'))
+    expect(files).toHaveLength(1)
+    const file = path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts', files[0]!)
+    const stored = readFileSync(file, 'utf8')
+    expect(stored).not.toContain('Sensitive result')
+    expect(stored).not.toContain('Private body text')
+    if (process.platform !== 'win32') expect(statSync(file).mode & 0o777).toBe(0o600)
+    if (process.platform !== 'win32') {
+      expect(statSync(path.dirname(file)).mode & 0o777).toBe(0o700)
+    }
+
+    const retry = beginSendAttempt({ env, credential, fingerprint, retry: true, now: 11 })
+    expect(retry).toMatchObject({
+      ok: true,
+      attemptId: first.attemptId,
+      idempotencyKey: first.idempotencyKey,
+      replay: true,
+    })
+    settleSendAttempt(env, first.attemptId)
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 12 })).toMatchObject({
+      ok: false,
+      code: 'retry_not_found',
+    })
+  })
+
+  it('does not follow a symlink presented as an attempt record', () => {
+    const { root, env, credential, draft } = fixture()
+    if (process.platform === 'win32') return
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    const first = beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(first.ok).toBe(true)
+    if (!first.ok) return
+    const directory = path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts')
+    const file = path.join(directory, `${first.attemptId}.json`)
+    const target = path.join(root, 'foreign.json')
+    writeFileSync(target, readFileSync(file, 'utf8'))
+    rmSync(file)
+    symlinkSync(target, file)
+
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 11 })).toMatchObject({
+      ok: false,
+      code: 'retry_not_found',
+    })
+    expect(readFileSync(target, 'utf8')).toContain(first.idempotencyKey)
+  })
+
+  it('refuses ambiguity instead of choosing between identical unresolved events', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 11 })
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 12 })).toMatchObject({
+      ok: false,
+      code: 'retry_ambiguous',
+    })
+  })
+
+  it('invalidates attempts after expiry or credential rotation', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(
+      beginSendAttempt({
+        env,
+        credential,
+        fingerprint,
+        retry: true,
+        now: 10 + SEND_ATTEMPT_TTL_MS + 1,
+      }),
+    ).toMatchObject({ ok: false, code: 'retry_not_found' })
+
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 20 })
+    const rotated = { ...credential, secret: 'rotated-secret' }
+    expect(
+      beginSendAttempt({
+        env,
+        credential: rotated,
+        fingerprint: sendDraftFingerprint(draft, rotated),
+        retry: true,
+        now: 21,
+      }),
+    ).toMatchObject({ ok: false, code: 'retry_not_found' })
+  })
+
+  it('fingerprints local media bytes without retaining paths or bytes', () => {
+    const { root } = fixture()
+    const file = path.join(root, 'private.png')
+    writeFileSync(file, 'first bytes')
+    const first = semanticMediaIds([file], root)
+    writeFileSync(file, 'different bytes')
+    const second = semanticMediaIds([file], root)
+    expect(first).not.toEqual(second)
+    expect(first[0]).not.toContain(file)
+    expect(first[0]).not.toContain('first bytes')
+  })
+})

package/src/send-attempts.ts

@@ -0,0 +1,188 @@
+import { createHash, createHmac, randomBytes } from 'node:crypto'
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+} from 'node:fs'
+import path from 'node:path'
+import type { NotificationDraftT } from '@raidiant/notifai-protocol'
+import { atomicWriteFileSync } from './atomic-file.js'
+import { stateDir } from './config.js'
+import type { MachineCredential } from './credentials.js'
+
+interface SendAttemptRecord {
+  version: 1
+  attempt_id: string
+  fingerprint: string
+  idempotency_key: string
+  credential_tag: string
+  machine_id: string
+  service: string
+  created_at: string
+  expires_at: string
+}
+
+export const SEND_ATTEMPT_TTL_MS = 24 * 60 * 60 * 1000
+
+/** Stable pre-upload media identities used only inside the keyed draft digest. */
+export function semanticMediaIds(images: readonly string[], cwd: string): string[] {
+  return images.map((image) => {
+    if (image.startsWith('med_')) return image
+    const digest = createHash('sha256')
+    if (/^https?:\/\//i.test(image)) digest.update(`url\0${image}`)
+    else digest.update('file\0').update(readFileSync(path.resolve(cwd, image)))
+    return `med_retry_${digest.digest('base64url')}`
+  })
+}
+
+function directory(env: NodeJS.ProcessEnv): string {
+  return path.join(stateDir(env), 'send-attempts')
+}
+
+function credentialTag(credential: MachineCredential): string {
+  return createHmac('sha256', credential.secret)
+    .update('notifai-send-attempt-credential-v1')
+    .digest('base64url')
+}
+
+/** A keyed digest proves equality without persisting notification content. */
+export function sendDraftFingerprint(
+  draft: NotificationDraftT,
+  credential: MachineCredential,
+): string {
+  return createHmac('sha256', credential.secret)
+    .update('notifai-send-draft-v1\0')
+    .update(JSON.stringify(draft))
+    .digest('base64url')
+}
+
+function parseRecord(file: string): SendAttemptRecord | null {
+  let descriptor: number | undefined
+  try {
+    const before = lstatSync(file)
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+    if (before.isSymbolicLink() || !before.isFile() || (uid !== undefined && before.uid !== uid)) {
+      return null
+    }
+    const flags = constants.O_RDONLY | (process.platform === 'win32' ? 0 : constants.O_NOFOLLOW)
+    descriptor = openSync(file, flags)
+    const opened = fstatSync(descriptor)
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) return null
+    const value = JSON.parse(readFileSync(descriptor, 'utf8')) as Partial<SendAttemptRecord>
+    return value.version === 1 &&
+      typeof value.attempt_id === 'string' &&
+      typeof value.fingerprint === 'string' &&
+      typeof value.idempotency_key === 'string' &&
+      typeof value.credential_tag === 'string' &&
+      typeof value.machine_id === 'string' &&
+      typeof value.service === 'string' &&
+      typeof value.created_at === 'string' &&
+      typeof value.expires_at === 'string'
+      ? value as SendAttemptRecord
+      : null
+  } catch {
+    return null
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor)
+  }
+}
+
+function liveRecords(
+  env: NodeJS.ProcessEnv,
+  credential: MachineCredential,
+  now: number,
+): SendAttemptRecord[] {
+  const dir = directory(env)
+  if (!existsSync(dir)) return []
+  const directoryStat = lstatSync(dir)
+  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+  if (
+    directoryStat.isSymbolicLink() ||
+    !directoryStat.isDirectory() ||
+    (uid !== undefined && directoryStat.uid !== uid)
+  ) return []
+  const tag = credentialTag(credential)
+  const records: SendAttemptRecord[] = []
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue
+    const file = path.join(dir, name)
+    const record = parseRecord(file)
+    const expired = record === null || Date.parse(record.expires_at) <= now
+    const rotated = record !== null && (
+      record.machine_id !== credential.machineId ||
+      record.service !== credential.baseUrl ||
+      record.credential_tag !== tag
+    )
+    if (expired || rotated) {
+      rmSync(file, { force: true })
+      continue
+    }
+    records.push(record)
+  }
+  return records
+}
+
+export type BeginAttempt =
+  | { ok: true; attemptId: string; idempotencyKey: string; replay: boolean }
+  | { ok: false; code: 'retry_not_found' | 'retry_ambiguous'; message: string }
+
+export function beginSendAttempt(options: {
+  env: NodeJS.ProcessEnv
+  credential: MachineCredential
+  fingerprint: string
+  retry: boolean
+  idempotencyKey?: string
+  now?: number
+}): BeginAttempt {
+  const now = options.now ?? Date.now()
+  const live = liveRecords(options.env, options.credential, now)
+  if (options.retry) {
+    const matches = live.filter((record) => record.fingerprint === options.fingerprint)
+    if (matches.length === 0) {
+      return {
+        ok: false,
+        code: 'retry_not_found',
+        message: 'No unresolved opaque attempt matches this exact send on the current Approved Machine.',
+      }
+    }
+    if (matches.length > 1) {
+      return {
+        ok: false,
+        code: 'retry_ambiguous',
+        message: 'More than one unresolved opaque attempt matches this exact send; refusing to guess or create another notification.',
+      }
+    }
+    const match = matches[0]!
+    return { ok: true, attemptId: match.attempt_id, idempotencyKey: match.idempotency_key, replay: true }
+  }
+
+  const attemptId = `sat_${randomBytes(12).toString('base64url')}`
+  const idempotencyKey = options.idempotencyKey ?? `cli-${randomBytes(12).toString('base64url')}`
+  const record: SendAttemptRecord = {
+    version: 1,
+    attempt_id: attemptId,
+    fingerprint: options.fingerprint,
+    idempotency_key: idempotencyKey,
+    credential_tag: credentialTag(options.credential),
+    machine_id: options.credential.machineId,
+    service: options.credential.baseUrl,
+    created_at: new Date(now).toISOString(),
+    expires_at: new Date(now + SEND_ATTEMPT_TTL_MS).toISOString(),
+  }
+  atomicWriteFileSync(
+    path.join(directory(options.env), `${attemptId}.json`),
+    `${JSON.stringify(record)}\n`,
+    { mode: 0o600, directoryMode: 0o700, requireCurrentUserOwner: true },
+  )
+  return { ok: true, attemptId, idempotencyKey, replay: false }
+}
+
+export function settleSendAttempt(env: NodeJS.ProcessEnv, attemptId: string): void {
+  rmSync(path.join(directory(env), `${attemptId}.json`), { force: true })
+}

package/src/send.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import {
+  accidentalEscapedNewlineMessage,
+  hasAccidentalEscapedNewlines,
+  rejectAccidentalEscapedNewlines,
+} from './send.js'
+
+describe('accidental escaped newlines', () => {
+  it('catches a shell-quoted backslash-n body', () => {
+    expect(hasAccidentalEscapedNewlines('line1\\nline2')).toBe(true)
+    expect(rejectAccidentalEscapedNewlines('line1\\nline2', false)).toBe(
+      accidentalEscapedNewlineMessage(),
+    )
+  })
+
+  it('preserves real multiline Markdown', () => {
+    expect(hasAccidentalEscapedNewlines('line1\nline2')).toBe(false)
+    expect(rejectAccidentalEscapedNewlines('line1\nline2', false)).toBeNull()
+  })
+
+  it('lets an explicit flag keep visible backslash-n text', () => {
+    expect(rejectAccidentalEscapedNewlines('use \\n in the sample', true)).toBeNull()
+  })
+
+  it('does not treat an escaped backslash plus n as accidental', () => {
+    expect(hasAccidentalEscapedNewlines('escape as \\\\n')).toBe(false)
+  })
+})

package/src/send.ts

@@ -31,7 +31,6 @@ export interface SendFlags {
   /** The one canonical Markdown body. */
   body: string
   subtitle?: string
-  event?: string
   /** What this notification is; absent means update. */
   kind?: string
   project?: string
@@ -80,6 +79,34 @@ export interface SendFlags {
    * questions and their retirements ride the wire as what they are.
    */
   lifecycle?: LifecycleT
+  /**
+   * Allow the two-character sequence backslash-n to be sent as visible text.
+   * Without this, a likely accidental escaped newline is refused.
+   */
+  literalBackslashN?: boolean
+}
+
+/** A backslash-n pair that was not itself escaped as a literal backslash. */
+const ACCIDENTAL_ESCAPED_NEWLINE = /(?:^|[^\\])\\n/
+
+export function hasAccidentalEscapedNewlines(body: string): boolean {
+  return ACCIDENTAL_ESCAPED_NEWLINE.test(body)
+}
+
+export function accidentalEscapedNewlineMessage(): string {
+  return [
+    'This body contains the two-character sequence \\n, which is sent literally and shows as \\n on the device.',
+    'To send a real line break, pass a multiline --body or --body-file -.',
+    'If you meant the visible characters \\n, pass --literal-backslash-n.',
+  ].join('\n')
+}
+
+export function rejectAccidentalEscapedNewlines(
+  body: string | undefined,
+  allowLiteral: boolean | undefined,
+): string | null {
+  if (allowLiteral === true || body === undefined) return null
+  return hasAccidentalEscapedNewlines(body) ? accidentalEscapedNewlineMessage() : null
 }
 
 export type DraftBuild =
@@ -309,7 +336,6 @@ export function buildDraft(
 
   const draft: NotificationDraftT = {
     schema_version: NOTIFICATION_SCHEMA_VERSION,
-    ...(flags.event !== undefined ? { event: flags.event } : {}),
     ...(flags.kind !== undefined
       ? { kind: flags.kind as (typeof NOTIFICATION_KINDS)[number] }
       : {}),

package/src/session-activation.ts

@@ -0,0 +1,62 @@
+import type { HookHarness } from './hooks.js'
+import { Buffer } from 'node:buffer'
+import { GUIDANCE_CONTEXT_MAX_BYTES, boundedEffectiveGuidance } from './guidance-render.js'
+
+const ROOT_OWNERSHIP =
+  'Notifai is active for this session. The effective, provenance-marked guidance below governs Notification Requests. ' +
+  'Missing CLI readiness is handled through `notifai init --json`. ' +
+  'The root agent owns User-visible Notification Requests unless it explicitly delegates that ownership; workers report Agent Events to the parent.'
+
+export const WORKER_ACTIVATION_CONTEXT =
+  'Notifai worker context: report Agent Events to the parent; do not send User-visible Notification Requests unless the parent explicitly delegated that ownership. If delegated, run `notifai guidance` before composing one.'
+
+export const MISSING_LIFECYCLE_GUIDANCE_CONTEXT =
+  'Notifai is active, but lifecycle guidance could not be loaded. Run `notifai guidance` once before deciding whether or how to send a Notification Request.'
+
+function rootActivationContext(cwd: string, env: NodeJS.ProcessEnv): string {
+  const guidance = boundedEffectiveGuidance({
+    cwd,
+    env,
+    maxBytes: GUIDANCE_CONTEXT_MAX_BYTES - Buffer.byteLength(`${ROOT_OWNERSHIP}\n\n`, 'utf8'),
+  })
+  return `${ROOT_OWNERSHIP}\n\n${guidance.ok ? guidance.content : guidance.fallback}`
+}
+
+/** One lifecycle meaning, encoded for each harness output contract. */
+export function sessionActivationOutput(
+  harness: HookHarness | undefined,
+  hookEventName: 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit',
+  cwd: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const context = hookEventName === 'SubagentStart'
+    ? WORKER_ACTIVATION_CONTEXT
+    : rootActivationContext(cwd, env)
+  if (harness === 'opencode') return context
+  if (harness === 'cursor') {
+    return JSON.stringify({ additional_context: context })
+  }
+  if (harness === 'claude-code' || harness === 'codex') {
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName,
+        additionalContext: context,
+      },
+    })
+  }
+  return undefined
+}
+
+/**
+ * Cursor currently accepts sessionStart context without reliably delivering it
+ * to the model. Its native post-Stop follow-up is the narrow fallback and is
+ * claimed once per conversation by the hook-state layer.
+ */
+export function cursorStopActivationOutput(
+  cwd: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return JSON.stringify({
+    followup_message: rootActivationContext(cwd, env),
+  })
+}

package/src/skill.test.ts

@@ -23,6 +23,7 @@ import { GATE_REASONS } from './hooks.js'
 
 const skillPath = new URL('../../../skills/notifai/SKILL.md', import.meta.url)
 const skill = readFileSync(skillPath, 'utf8')
+const description = skill.match(/^description:\s*(.+)$/m)?.[1] ?? ''
 const harnessReference = readFileSync(
   new URL('../../../skills/notifai/references/harness-setup.md', import.meta.url),
   'utf8',
@@ -46,6 +47,32 @@ const section = (heading: string): string => {
 }
 
 describe('Notifai agent skill', () => {
+  it('routes proactively in ordinary sessions without waiting for the user to name Notifai', () => {
+    // The frontmatter description is the only skill text available during
+    // automatic selection. If the ordinary-session trigger lives only in the
+    // body, agents doing unrelated work never load it and therefore never see
+    // the completion rule.
+    expect(description).toMatch(/every agent session/i)
+    expect(description).toMatch(/even when the user does not mention Notifai/i)
+    expect(description).toMatch(/guidance/i)
+
+    const decide = section('## Decide whether to notify')
+    expect(decide).toMatch(/lifecycle context normally includes.*effective guidance/is)
+    expect(decide).toMatch(/context is absent.*read it once before judging an Agent\s+Event/is)
+    expect(decide).toMatch(/parent owns User-visible Notification Requests/i)
+    expect(decide).toMatch(/unless\s+it explicitly delegates/i)
+    expect(decide).toMatch(/workers[\s\S]{0,100}do not send independently/i)
+  })
+
+  it('preserves the original Agent Event across setup and ambiguous delivery', () => {
+    expect(skill).toMatch(
+      /interrupted or killed `send`[\s\S]*do not correlate redacted logs by title[\s\S]*re-run the exact semantic send with\s+`--retry`/i,
+    )
+    expect(skill).toMatch(/opaque matching attempt[\s\S]*refuse ambiguity/i)
+    expect(skill).toMatch(/`no_active_devices`[\s\S]*repeat the\s+(?:exact\s+)?original send/i)
+    expect(skill).toMatch(/verification Notification[\s\S]*does not deliver\s+the original Agent Event/i)
+  })
+
   it('fits inside the budget a skill is actually read within', () => {
     // Long skills are truncated in exactly the long sessions that need them.
     // The old skill sat at ~4,800 tokens; this ceiling keeps a working margin.
@@ -81,7 +108,74 @@ describe('Notifai agent skill', () => {
     for (const topic of ['when-to-notify', 'titles', 'bodies', 'questions', 'acknowledgements']) {
       expect(decide).toContain(`\`${topic}\``)
     }
-    expect(decide).toMatch(/outranks the shipped\s+default and your judgement/i)
+    const authorityOrder = ['from=you', 'from=this repository', 'from=shipped default'].map(
+      (marker) => decide.indexOf(marker),
+    )
+    expect(authorityOrder[0]).toBeGreaterThan(decide.indexOf('notifai guidance'))
+    expect(authorityOrder[1]).toBeGreaterThan(authorityOrder[0]!)
+    expect(authorityOrder[2]).toBeGreaterThan(authorityOrder[1]!)
+  })
+
+  it('separates repository policy from the User and makes non-exfiltration absolute', () => {
+    const decide = section('## Decide whether to notify')
+    const markers = ['from=you', 'from=this repository', 'from=shipped default']
+    const markerPositions = markers.map((marker) => decide.indexOf(marker))
+    expect(markerPositions.every((position) => position >= 0)).toBe(true)
+
+    const numberedLimits = [
+      ...decide.matchAll(/^\d+\. \*\*([^*]+)\.\*\*([\s\S]*?)(?=^\d+\. |\n\n)/gm),
+    ]
+    expect(numberedLimits.map((match) => match[1]?.toLowerCase())).toEqual([
+      'non-exfiltration',
+      'repository authority',
+    ])
+
+    const normalize = (value: string | undefined): string =>
+      (value ?? '').toLowerCase().replace(/\s+/g, ' ')
+    const nonExfiltration = normalize(numberedLimits[0]?.[2])
+    for (const protectedClass of [
+      'credential',
+      'token',
+      'key',
+      'password',
+      'environment',
+      'configuration',
+      'guidance',
+      'log',
+    ]) {
+      expect(nonExfiltration, protectedClass).toContain(protectedClass)
+    }
+    for (const outboundField of [
+      'notification request',
+      'question',
+      'choice',
+      'acknowledgement',
+      'image',
+    ]) {
+      expect(nonExfiltration, outboundField).toContain(outboundField)
+    }
+
+    const authority = normalize(numberedLimits[1]?.[2])
+    for (const protectedAuthority of [
+      'standing word',
+      'settings',
+      'guidance',
+      'cli',
+      'origins',
+      'direct user instruction',
+    ]) {
+      expect(authority, protectedAuthority).toContain(protectedAuthority)
+    }
+
+    const obligations = normalize(decide.slice(numberedLimits[1]?.index ?? 0))
+    const refuse = obligations.indexOf('refuse')
+    const report = obligations.indexOf('tell the user')
+    const noOutboundReport = obligations.search(
+      /(?:do not|never|cannot)[^.]{0,120}notification request/,
+    )
+    expect(refuse).toBeGreaterThanOrEqual(0)
+    expect(report).toBeGreaterThan(refuse)
+    expect(noOutboundReport).toBeGreaterThan(report)
   })
 
   it('names every notification kind the CLI accepts', () => {
@@ -100,6 +194,15 @@ describe('Notifai agent skill', () => {
     expect(skill).not.toMatch(/kind never chooses/i)
   })
 
+  it('routes a blocker through a question whenever the User response resumes the work', () => {
+    // `blocked` and `question` are mutually exclusive on the wire. The skill
+    // must teach the selection boundary or an imperative such as "unlock it"
+    // becomes an unanswerable one-way notification.
+    const selection = `${section('## Send')}\n${section('## Ask a question')}`
+    expect(selection).toMatch(/work needs a User response[\s\S]{0,160}answerable\s+question/i)
+    expect(selection).toMatch(/one-way blocked[\s\S]{0,160}no\s+User\s+reply\s+would\s+resume/i)
+  })
+
   it('keeps every send example valid against the CLI it documents', () => {
     const sends = shellExamples.filter((line) => line.startsWith('notifai send'))
     expect(sends.length).toBeGreaterThan(0)
@@ -121,17 +224,16 @@ describe('Notifai agent skill', () => {
     expect(send).toMatch(/kind and the project travel as their own\s+fields, never in it/i)
   })
 
-  it('names each immutable session once without asking the agent for its id', () => {
+  it('lets callers repeat one immutable semantic session name without supplying its id', () => {
     const send = section('## Send')
     expect(send).toContain('--session-label')
-    expect(send).toMatch(/first Notification\s+Request/i)
     expect(send).toMatch(/2-6 words/i)
-    // The rule is unconditional: the environment's name wins, so the flag is
-    // safe everywhere and the agent never branches on where it is running.
-    expect(send).toMatch(/safe in every environment/i)
+    expect(send).toMatch(/when the current\s+environment exposes an exact session/i)
+    expect(send).toMatch(/without an exact session[\s\S]{0,160}usage\s+error/i)
+    expect(send).toMatch(/omit `--session-label`/i)
     expect(send).toMatch(/name the\s+environment supplies wins/i)
     expect(send).toMatch(/freezes one semantic name/i)
-    expect(send).toMatch(/omit the flag on later sends and\s+questions/i)
+    expect(send).toMatch(/safe to repeat the same `--session-label` on every send and ask/i)
     // The one exception to permanence: garbage names are recoverable.
     expect(send).toMatch(/generated fallback name[\s\S]*replaced by a later\s+semantic name/i)
     expect(send).toMatch(/never pass\s+`--session-id`/i)
@@ -155,6 +257,12 @@ describe('Notifai agent skill', () => {
     expect(ask).toMatch(/exit code 3/i)
   })
 
+  it('teaches that closed choices appear after pressing and holding', () => {
+    const ask = section('## Ask a question')
+    expect(ask).toMatch(/closed choices appear after pressing and holding the\s+notification/i)
+    expect(skill).not.toMatch(/choices are buttons on the banner/i)
+  })
+
   it('makes registration the middle of the asking turn, not the end', () => {
     const ask = section('## Ask a question')
     expect(ask).toMatch(/registering is not the end of the turn/i)
@@ -189,13 +297,20 @@ describe('Notifai agent skill', () => {
     expect(skill).toContain('notifai replies --pending')
   })
 
+  it('teaches retirement of a registration that has not been pushed yet', () => {
+    expect(skill).toContain('notifai close --pending')
+    expect(skill).toContain('question_id')
+    expect(skill).toMatch(/answer\s+in the conversation/i)
+  })
+
   it('makes the agent the operator and the human only the human', () => {
     const setup = section('## Set Notifai up')
     expect(setup).toMatch(/never tell the\s+user to run a command you could have run/i)
     expect(setup).toMatch(/browser/i)
     expect(setup).toMatch(/companion/i)
-    expect(setup).toContain('notifai doctor --json')
-    expect(setup).toContain('notifai init')
+    expect(setup).toContain('notifai init --json')
+    expect(setup).toMatch(/do not follow a successful structured init\s+with doctor/i)
+    expect(setup).toContain('--setup-scope')
   })
 
   it('offers npx only as a pinned fallback behind a real install', () => {
@@ -255,7 +370,6 @@ describe('Notifai agent skill', () => {
       'notifai replies',
       'notifai acknowledge',
       'notifai close',
-      'notifai doctor',
       'notifai init',
       'notifai config show',
       'notifai guidance',
@@ -273,7 +387,7 @@ describe('Notifai agent skill', () => {
       expect(harnessReference).toContain(`**${harness}:**`)
     }
     // The agent runs what a process can run; the human only does the human part.
-    expect(harnessReference).toContain('install hooks yourself')
+    expect(harnessReference).toMatch(/let init install and assess\s+the hooks/i)
     expect(harnessReference).toMatch(/run `notifai login` yourself/i)
     expect(harnessReference).toMatch(/only the user can approve/i)
   })