@raidiant/notifai 0.2.1 → 0.4.0

package/src/main.ts

@@ -9,16 +9,20 @@ import {
   authStatusCommand,
   capabilitiesCommand,
   closeCommand,
+  configExplainCommand,
   configSetCommand,
   configShowCommand,
+  configUnsetCommand,
   devicesCommand,
   doctorCommand,
+  hookDefersDiagnosticsUntilAfterCleanup,
   hookRunCommand,
   hooksInstallCommand,
   hooksUninstallCommand,
   initCommand,
   loginCommand,
   logoutCommand,
+  logsCommand,
   realIo,
   repliesCommand,
   sendCommand,
@@ -29,6 +33,20 @@ import { defaultCredentialStore } from './credentials.js'
 import { HARNESSES } from './install-hooks.js'
 import type { Platform } from '@raidiant/notifai-protocol'
 import { nativeSkills, type SkillScope } from './native-skills.js'
+import { GROUP, SEND_GROUP, helpConfiguration, rootHelpFooter } from './ui/help.js'
+
+import { readStdinWithTimeout } from './hook-input.js'
+import { bootstrapLogger } from './logging.js'
+
+/**
+ * The local record for this invocation.
+ *
+ * Built before the command tree so that the very first thing recorded is the
+ * command starting — including for a command that goes on to fail before it has
+ * resolved anything. It configures itself from disk and disables itself if it
+ * cannot write, so nothing below has to handle it failing.
+ */
+const logger = bootstrapLogger()
 
 const deps: CommandDeps = {
   io: realIo(),
@@ -36,36 +54,7 @@ const deps: CommandDeps = {
   env: process.env,
   cwd: process.cwd(),
   nativeSkills,
-}
-
-/**
- * Harness hooks deliver their event payload on stdin. Bounded on both time and
- * size: a wrapper that opens the pipe without writing would otherwise hold the
- * read until the harness killed the hook, delaying the user's own prompt.
- */
-async function readStdin(timeoutMs = 2000, maxBytes = 1_000_000): Promise<string> {
-  if (process.stdin.isTTY) return ''
-  return new Promise((resolve) => {
-    const chunks: Buffer[] = []
-    let total = 0
-    let settled = false
-    const finish = (): void => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      process.stdin.destroy()
-      resolve(Buffer.concat(chunks).toString('utf8'))
-    }
-    const timer = setTimeout(finish, timeoutMs)
-    timer.unref?.()
-    process.stdin.on('data', (chunk: Buffer) => {
-      total += chunk.length
-      if (total > maxBytes) return finish()
-      chunks.push(chunk)
-    })
-    process.stdin.on('end', finish)
-    process.stdin.on('error', finish)
-  })
+  logger,
 }
 
 /**
@@ -89,13 +78,103 @@ function version(): string {
   return 'unknown'
 }
 
+/**
+ * The full command path, e.g. `config set`, so a filter on `cmd` distinguishes
+ * subcommands that share a leaf name.
+ */
+function commandPath(command: Command): string {
+  const parts: string[] = []
+  for (let node: Command | null = command; node?.parent != null; node = node.parent) {
+    parts.unshift(node.name())
+  }
+  return parts.join(' ') || 'notifai'
+}
+
+/**
+ * Which flags were passed, without their values.
+ *
+ * The flag names answer nearly every question worth asking of an invocation —
+ * was `--reply` set, was `--all` — while the values are notification content
+ * and user text that has no business being recorded merely because a command
+ * ran. Values are available under `log_level = debug`, which is a deliberate act.
+ */
+function flagNames(argv: readonly string[]): string[] {
+  return argv.filter((token) => token.startsWith('--'))
+}
+
+const startedAt = Date.now()
+process.on('exit', (code) => {
+  logger.info('cli.end', {
+    exit: code,
+    duration_ms: Date.now() - startedAt,
+    flags: flagNames(process.argv.slice(2)),
+  })
+})
+
 const program = new Command('notifai')
   .description('Send native device notifications from agents and local programs')
   .version(version())
+  .configureHelp(helpConfiguration)
+  // Lazy on purpose. `addHelpText` also takes a string, but that builds the
+  // footer on every invocation — including the hook that runs in front of
+  // every prompt the user types, which never renders help at all.
+  .addHelpText('after', () => rootHelpFooter())
+  // Commander's default is to print the full help and exit 0 for an unknown
+  // `help` topic, so `notifai help nonsense` looked like it had worked. A
+  // reader who mistyped a command deserves to be told, and a script deserves
+  // a nonzero code.
+  .showSuggestionAfterError(true)
+  // Commander drops the implicit `help [command]` as soon as the program
+  // itself has an action handler — which the interactive default below gives
+  // it. Without this, adding that default would silently break
+  // `notifai help send` for everyone who reaches for it before `--help`.
+  .helpCommand(true)
+  // Where the implicit help command lands; every other command names its own.
+  .commandsGroup(GROUP.help)
+  .hook('preAction', (_program, actionCommand) => {
+    logger.bind({ cmd: commandPath(actionCommand) })
+    // SessionEnd uses the hook policy shared with commands.ts: local cleanup
+    // precedes every diagnostic that can wait on the shared log lock.
+    const deferDiagnostics =
+      actionCommand.name() === 'hook' &&
+      hookDefersDiagnosticsUntilAfterCleanup(actionCommand.processedArgs[0])
+    // Values only at `debug`; `cli.end` carries the flag names at every level.
+    if (!deferDiagnostics) {
+      logger.debug('cli.start', {
+        version: version(),
+        argv: process.argv.slice(2),
+        cwd: process.cwd(),
+      })
+    }
+  })
+
+/**
+ * Bare `notifai`.
+ *
+ * At a human terminal this opens the interactive app; anywhere else it prints
+ * help exactly as before. The check is the same one every other prompt in this
+ * CLI is gated on — stdin and stdout both TTYs, not CI, `NOTIFAI_NO_INPUT`
+ * unset — because an agent that reaches a prompt does not fail, it hangs
+ * for ever waiting on a stdin nobody is typing into.
+ *
+ * The import is dynamic so that the prompt library, the banner and the whole
+ * interactive tree cost nothing to the paths that never draw them — `send`,
+ * `ask`, and the hook that runs in front of every prompt the user types.
+ */
+program.action(async () => {
+  if (deps.io.interactive !== true) {
+    program.outputHelp()
+    return
+  }
+  const { interactiveCommand } = await import('./interactive.js')
+  process.exit(await interactiveCommand(deps, version()))
+})
 
 // Setup leads: `init` is the single entry command for first-run friendliness.
 program
   .command('init')
+  .helpGroup(GROUP.start)
+  .summary('Set this project up, step by step')
   .description(
     'Set up Notifai here, idempotently: sign-in, project id, hooks, device readiness, live receipt proof. ' +
       'Interactive at a human terminal; never prompts otherwise (agents: pass flags)',
@@ -112,6 +191,8 @@ program
 
 program
   .command('doctor')
+  .helpGroup(GROUP.daily)
+  .summary('Check every part of the setup')
   .description('Audit config, credential, server, contract, device, hook, and saved receipt proof; exits nonzero when any line is FAIL (no live send)')
   .option('--json', 'machine-readable output')
   .action(async (opts: { json?: boolean }) => {
@@ -120,6 +201,8 @@ program
 
 program
   .command('login')
+  .helpGroup(GROUP.start)
+  .summary('Sign in and pair this machine')
   .description('Pair this machine with your Notifai account via browser approval')
   .option('--name <name>', 'machine name shown in the dashboard (default: hostname)')
   .option('--base-url <url>', 'Notifai server URL')
@@ -130,12 +213,18 @@ program
 
 program
   .command('logout')
+  .helpGroup(GROUP.advanced)
+  .summary('Remove the stored machine credential')
   .description('Remove the stored machine credential')
   .action(() => {
     process.exit(logoutCommand(deps))
   })
 
-const auth = program.command('auth').description('Authentication helpers')
+const auth = program
+  .command('auth')
+  .description('Authentication helpers')
+  .summary('Machine identity and account plan')
+  .helpGroup(GROUP.advanced)
 auth
   .command('status')
   .description('Show the stored machine identity')
@@ -153,6 +242,8 @@ auth
 
 program
   .command('devices')
+  .helpGroup(GROUP.daily)
+  .summary('List your devices and whether they can receive')
   .description('List registered devices and their delivery readiness')
   .option('--json', 'machine-readable output')
   .action(async (opts: { json?: boolean }) => {
@@ -161,6 +252,8 @@ program
 
 program
   .command('capabilities')
+  .helpGroup(GROUP.advanced)
+  .summary('Show what a platform can render')
   .description('Show a platform capability contract')
   .option('--platform <platform>', 'platform to describe (default: ios)')
   .option('--json', 'machine-readable output')
@@ -170,26 +263,31 @@ program
 
 const send = program
   .command('send')
+  .helpGroup(GROUP.agent)
+  .summary('Send a notification')
   .description('Send a notification')
+  .optionsGroup(SEND_GROUP.content)
   .requiredOption('--title <title>', 'notification title')
   .requiredOption('--body <body>', 'notification body')
-  .option('--subtitle <subtitle>')
+  .option('--subtitle <subtitle>', 'a line between the title and the body')
   .option('--detail <markdown>', 'long-form markdown shown only in the app, never on the banner')
   .option('--detail-file <path>', 'read --detail from a file (use - for stdin)')
-  .option('--event <event>', 'agent event name, e.g. tests_passed')
+  .option('--image <path|url|media_id>', 'upload or attach an image')
+  .optionsGroup(SEND_GROUP.routing)
   .option('--kind <kind>', 'what this is: update (default) | done | question (requires --reply)')
   .option('--project <id>', 'project identifier, e.g. my-app (lazily registered)')
-  .option('--session <id>', 'session identity (env: NOTIFAI_SESSION); presentation varies by surface')
   .option('--device <id>', 'target a device id (repeatable)', (v: string, all: string[]) => [...all, v], [])
   .option('--all', 'target all routable devices (overrides configured devices)')
-  .option('--ttl <seconds>', 'delivery window in seconds', (v: string) => Number(v))
-  .option('--collapse-key <key>', 'replace earlier notifications with the same key')
-  .option('--platform <platform>', 'limit optional fields to ios or macos (default: both)')
+  .option('--session <id>', 'session identity (env: NOTIFAI_SESSION); presentation varies by surface')
+  .option('--event <event>', 'agent event name, e.g. tests_passed')
+  .optionsGroup(SEND_GROUP.presentation)
   .option('--sound <sound>', 'default | done | attention | alert | none')
-  .option('--thread-id <id>', 'group related notifications')
   .option('--level <level>', 'interruption level: passive | active | time_sensitive')
-  .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[]) => [...all, v], [])
-  .option('--image <path|url|media_id>', 'upload or attach an image')
+  .option('--collapse-key <key>', 'replace earlier notifications with the same key')
+  .option('--thread-id <id>', 'group related notifications')
+  .option('--ttl <seconds>', 'delivery window in seconds', (v: string) => Number(v))
+  .option('--platform <platform>', 'limit optional fields to ios or macos (default: both)')
+  .optionsGroup(SEND_GROUP.reply)
   .option('--reply', 'enable the inline reply action and block for the answer')
   .option('--reply-timeout <seconds>', 'how long to wait for a reply (default: 900)', (v: string) => Number(v))
   .option('--reply-window <seconds>', 'how long the server accepts a reply (default: 3600)', (v: string) => Number(v))
@@ -202,8 +300,10 @@ const send = program
   // Kept registered, and always a usage error with --reply, so the caller gets
   // a message pointing at `ask` instead of "unknown option".
   .option('--no-block', 'rejected with --reply; use `notifai ask` to ask and end the turn')
+  .optionsGroup(SEND_GROUP.advanced)
   .option('--wait <seconds>', 'how long to wait for provider outcomes', (v: string) => Number(v))
   .option('--no-wait', 'return immediately after acceptance')
+  .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[]) => [...all, v], [])
   .option('--idempotency-key <key>', 'safe-retry key (default: random)')
   .option('--base-url <url>', 'Notifai server URL')
   .option('--json', 'print the full submission receipt as JSON')
@@ -247,6 +347,8 @@ send.addHelpText(
 
 program
   .command('replies [request_id]')
+  .helpGroup(GROUP.agent)
+  .summary('Retrieve replies to a question')
   .description('Retrieve replies for a notification request')
   .option('--pending', 'use the pushed question pending for this project session')
   .option('--wait <seconds>', 'how long to wait for a reply', (v: string) => Number(v))
@@ -258,6 +360,8 @@ program
 
 program
   .command('status <request_id>')
+  .helpGroup(GROUP.agent)
+  .summary('Show the evidence trail for a request')
   .description('Show the evidence trail for a notification request')
   .option('--json', 'machine-readable output')
   .action(async (requestId: string, opts: { json?: boolean }) => {
@@ -266,6 +370,8 @@ program
 
 program
   .command('ask [question]')
+  .helpGroup(GROUP.agent)
+  .summary('Register a question, then end the turn')
   .description('Register a question for the turn-end hook to route under your presence settings')
   .option(
     '--choice <label>',
@@ -320,13 +426,18 @@ program
 
 program
   .command('close <request_id>')
+  .helpGroup(GROUP.agent)
+  .summary('Retire a question so late answers are rejected')
   .description('Retire a question so late answers are rejected rather than lost')
   .action(async (requestId: string) => {
     process.exit(await closeCommand(deps, requestId))
   })
 
+// Hidden, not removed. It is an entry point the hook installer writes into a
+// harness config file, never something a person types — and listing it beside
+// `send` invited exactly one reading, which is that you were supposed to.
 program
-  .command('hook <event>')
+  .command('hook <event>', { hidden: true })
   .description('Internal: run a harness hook (reads hook JSON on stdin)')
   // Inert, and the point of it is that it is inert: the installed command line
   // carries a marker that says "Notifai wrote this" independently of which
@@ -336,17 +447,21 @@ program
   .action(async (event: string, opts: { harness?: string }) => {
     const harness = HARNESSES.find((candidate) => candidate === opts.harness)
     process.exit(
-      await hookRunCommand(deps, event, readStdin, harness),
+      await hookRunCommand(deps, event, () => readStdinWithTimeout(), harness),
     )
   })
 
-const hooks = program.command('hooks').description('Install harness hooks for registered-question routing')
+const hooks = program
+  .command('hooks')
+  .description('Install harness hooks for registered-question routing')
+  .summary('Wire a harness to route questions to your devices')
+  .helpGroup(GROUP.advanced)
 hooks
   .command('install')
   .description('Wire this harness to route registered questions to your devices')
   .option(
     '--harness <name>',
-    'claude-code | codex | cursor | opencode (default: detected; OpenCode delivers answers on the next prompt)',
+    'claude-code | codex | cursor | opencode (default: detected)',
   )
   .option('--global', 'install for every project instead of just this one')
   .action((opts: { harness?: string; global?: boolean }) => {
@@ -361,15 +476,55 @@ hooks
     process.exit(hooksUninstallCommand(deps, opts))
   })
 
-const config = program.command('config').description('Show or change configuration')
+program
+  .command('logs')
+  .helpGroup(GROUP.daily)
+  .summary('Show what this machine recorded about what it did')
+  .description(
+    'Read the local record of commands, notifications, and the question decisions harness hooks made. ' +
+      'Bounded and scoped to this project by default; never leaves this machine',
+  )
+  .option('-n, --limit <count>', 'how many records to show (default: 30)', (v: string) => Number(v))
+  .option('--all', 'lift the default limit, up to a hard cap')
+  .option('--since <when>', 'only records newer than this: 10m, 2h, 1d, or an ISO 8601 instant')
+  .option('--level <level>', 'minimum severity: error | info | debug (error shows only failures)')
+  .option('--event <name>', 'only this event; repeatable', (v: string, all: string[]) => [...all, v], [])
+  .option('--run <id>', 'everything one command invocation did')
+  .option('--request <id>', 'everything about one notification request')
+  .option('--session <id>', 'only this harness session')
+  .option('--project <id>', 'only this project')
+  .option('--all-projects', 'do not scope to the project in this directory')
+  .option('--grep <text>', 'only records containing this text')
+  .option('--json', 'one JSON record per line on stdout')
+  .option('--path', 'print the log file paths instead of the records')
+  .option('--clear', 'delete the log files')
+  .action((opts: Record<string, unknown>) => {
+    const flags = { ...opts } as Parameters<typeof logsCommand>[1]
+    if (Array.isArray(flags.event) && flags.event.length === 0) delete flags.event
+    process.exit(logsCommand(deps, flags))
+  })
+
+const config = program
+  .command('config')
+  .description('Show or change settings')
+  .summary('Show or change settings')
+  .helpGroup(GROUP.daily)
 config
   .command('show')
-  .description('Show the resolved configuration')
-  .option('--explain', 'show where each value comes from')
+  .description('Show every setting, what it does, and where its value came from')
+  .option('--explain', 'include advanced settings and the file each value came from')
+  .option('--plain', 'the flat key = value form, even at a terminal')
   .option('--json', 'machine-readable output')
-  .action((opts: { json?: boolean; explain?: boolean }) => {
+  .action((opts: { json?: boolean; explain?: boolean; plain?: boolean }) => {
     process.exit(configShowCommand(deps, opts))
   })
+config
+  .command('explain <key>')
+  .description('Explain one setting in full: what it does, what it accepts, what it is now')
+  .option('--json', 'machine-readable output')
+  .action((key: string, opts: { json?: boolean }) => {
+    process.exit(configExplainCommand(deps, key, opts))
+  })
 config
   .command('set <key> <value>')
   .description(
@@ -388,5 +543,22 @@ config
       process.exit(await configSetCommand(deps, key, value, opts))
     },
   )
+config
+  .command('unset <key>')
+  .description(
+    'Remove a configuration value so the next layer or shipped default applies (choose a layer interactively; unattended defaults machine-global and requires --yes)',
+  )
+  .option('--project', 'remove from the shared .notifai/config.toml instead')
+  .option('--local', 'remove from personal .notifai/config.local.toml')
+  .option('--session <id>', 'remove from one session')
+  .option('--yes', 'skip the confirmation gate')
+  .action(
+    async (
+      key: string,
+      opts: { project?: boolean; local?: boolean; session?: string; yes?: boolean },
+    ) => {
+      process.exit(await configUnsetCommand(deps, key, opts))
+    },
+  )
 
 await program.parseAsync(process.argv)

package/src/opencode-plugin.ts

@@ -30,7 +30,7 @@ export const OPENCODE_PLUGIN_MARKER = '// notifai managed opencode plugin'
 export const OPENCODE_PLUGIN_FILENAME = 'notifai.js'
 
 /** Bump when an installed generated file must be rewritten to remain functional. */
-const OPENCODE_ADAPTER_VERSION = 4
+const OPENCODE_ADAPTER_VERSION = 5
 
 export function opencodePluginDir(
   global: boolean,
@@ -51,8 +51,8 @@ export function opencodePluginPath(
 }
 
 export interface OpencodePluginOptions {
-  execPath: string
-  scriptPath: string
+  /** The same stable user-level adapter every command-hook harness invokes. */
+  adapterPath: string
   /** Child-process lifetime; covers grace, reply wait, and teardown headroom. */
   timeoutSeconds: number
 }
@@ -60,23 +60,23 @@ export interface OpencodePluginOptions {
 /**
  * The generated module.
  *
- * Written as a string rather than compiled from a source file because it has to
- * embed the absolute interpreter and script paths — a bare `notifai` on PATH
- * fails silently under a plugin host the same way it does under a hook shell.
+ * Written as a string rather than compiled from a source file because OpenCode
+ * loads a plugin module rather than a command definition. It embeds only the
+ * stable user-level adapter path; mutable runtime and CLI targets live behind
+ * that adapter exactly as they do for every other harness.
  *
  * Everything it does is build the hook envelope OpenCode's event gives it and
  * hand that to the CLI on stdin. It deliberately fails open: an adapter error
  * never changes OpenCode's own behavior.
  */
 export function opencodePluginSource(options: OpencodePluginOptions): string {
-  const { execPath, scriptPath, timeoutSeconds } = options
+  const { adapterPath, timeoutSeconds } = options
   return `${OPENCODE_PLUGIN_MARKER}
 // Generated by \`notifai hooks install --harness opencode\`. Edits are lost on
 // the next install; change the CLI instead, which is where the logic lives.
 import { spawn } from "node:child_process"
 
-const EXEC = ${JSON.stringify(execPath)}
-const SCRIPT = ${JSON.stringify(scriptPath)}
+const ADAPTER = ${JSON.stringify(adapterPath)}
 const TIMEOUT_MS = ${timeoutSeconds * 1000}
 const ADAPTER_VERSION = ${OPENCODE_ADAPTER_VERSION}
 
@@ -88,7 +88,7 @@ function runHook(event, envelope) {
   return new Promise((resolve) => {
     let child
     try {
-      child = spawn(EXEC, [SCRIPT, "hook", event, "--owner", "notifai", "--harness", "opencode"], {
+      child = spawn(ADAPTER, ["hook", event, "--owner", "notifai", "--harness", "opencode"], {
         env: process.env,
         shell: false,
         stdio: ["pipe", "pipe", "pipe"],
@@ -216,17 +216,16 @@ export function isOurOpencodePlugin(contents: string): boolean {
  */
 export function opencodePluginTarget(
   contents: string,
-): { exec: string; script: string; current: boolean; timeoutSeconds?: number } | null {
+): { adapter: string; current: boolean; timeoutSeconds?: number } | null {
   if (!isOurOpencodePlugin(contents)) return null
-  const exec = /^const EXEC = (".*")$/m.exec(contents)?.[1]
-  const script = /^const SCRIPT = (".*")$/m.exec(contents)?.[1]
+  const adapter = /^const ADAPTER = (".*")$/m.exec(contents)?.[1]
+  const legacyScript = /^const SCRIPT = (".*")$/m.exec(contents)?.[1]
   const version = Number(/^const ADAPTER_VERSION = (\d+)$/m.exec(contents)?.[1] ?? 1)
   const timeoutMs = Number(/^const TIMEOUT_MS = (\d+)$/m.exec(contents)?.[1] ?? Number.NaN)
-  if (exec === undefined || script === undefined) return null
+  if (adapter === undefined && legacyScript === undefined) return null
   try {
     return {
-      exec: JSON.parse(exec) as string,
-      script: JSON.parse(script) as string,
+      adapter: JSON.parse(adapter ?? legacyScript!) as string,
       current: version === OPENCODE_ADAPTER_VERSION,
       ...(Number.isFinite(timeoutMs) ? { timeoutSeconds: timeoutMs / 1000 } : {}),
     }

package/src/session-end-log-lock-worker.test.ts

@@ -0,0 +1,35 @@
+import { existsSync, writeFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { withFileLock } from './file-lock.js'
+
+const workerMode = process.env['NOTIFAI_SESSION_END_LOG_LOCK_WORKER_MODE']
+const sleep = new Int32Array(new SharedArrayBuffer(4))
+
+function waitFor(file: string): void {
+  const deadline = Date.now() + 15_000
+  while (!existsSync(file)) {
+    if (Date.now() >= deadline) throw new Error(`timed out waiting for ${file}`)
+    Atomics.wait(sleep, 0, 0, 2)
+  }
+}
+
+if (workerMode === undefined) {
+  describe('SessionEnd log lock worker', () => {
+    it('stays dormant outside the CLI deadline regression', () => {
+      expect(workerMode).toBeUndefined()
+    })
+  })
+} else {
+  describe('SessionEnd log lock worker', () => {
+    it('holds a live bakery ticket until the parent releases it', () => {
+      withFileLock(
+        process.env['NOTIFAI_SESSION_END_LOG_LOCK_PATH']!,
+        () => {
+          writeFileSync(process.env['NOTIFAI_SESSION_END_LOG_LOCK_READY']!, workerMode)
+          waitFor(process.env['NOTIFAI_SESSION_END_LOG_LOCK_RELEASE']!)
+        },
+        { waitMs: 15_000 },
+      )
+    })
+  })
+}

package/src/skill.test.ts

@@ -34,6 +34,17 @@ describe('Notifai agent skill', () => {
     }
   })
 
+  it('tells the agent where to look when something did not happen', () => {
+    // The log's whole value is diagnostic, so the skill has to name the case
+    // that produces it — a question that was registered and never travelled.
+    expect(skill).toContain('notifai logs')
+    expect(skill).toContain('--request <id>')
+    expect(skill).toContain('hook.gate')
+    expect(skill).toContain('notifications-off')
+    // And that it is the user's data, on the user's machine.
+    expect(skill).toContain('stays on this machine')
+  })
+
   it('moves per-harness mechanics into progressive disclosure', () => {
     expect(skill).toContain('[Harness setup and recovery](references/harness-setup.md)')
     for (const harness of ['Claude Code', 'Codex', 'Cursor', 'OpenCode']) {

package/src/ui/banner.ts

@@ -0,0 +1,95 @@
+/**
+ * The wordmark shown when a human opens the interactive app.
+ *
+ * Three tiers, chosen by what the terminal can actually render rather than by
+ * what looks best in a screenshot: box-drawing blocks when the terminal is wide
+ * and Unicode-capable, a pure-ASCII form that survives anywhere, and a plain
+ * word when neither fits. A banner that wraps is worse than no banner, so the
+ * width check is not optional.
+ *
+ * The art is embedded rather than rendered at run time. It is one fixed word
+ * that will never change, and shipping a font engine to redraw a constant on
+ * every launch would cost every install — including the agents that never see
+ * it — for no benefit.
+ */
+import { gradientBlock, style, terminalWidth, unicode } from './theme.js'
+
+/** ANSI Shadow. 50 columns, 6 rows. */
+const BLOCK = [
+  '███╗   ██╗ ██████╗ ████████╗██╗███████╗ █████╗ ██╗',
+  '████╗  ██║██╔═══██╗╚══██╔══╝██║██╔════╝██╔══██╗██║',
+  '██╔██╗ ██║██║   ██║   ██║   ██║█████╗  ███████║██║',
+  '██║╚██╗██║██║   ██║   ██║   ██║██╔══╝  ██╔══██║██║',
+  '██║ ╚████║╚██████╔╝   ██║   ██║██║     ██║  ██║██║',
+  '╚═╝  ╚═══╝ ╚═════╝    ╚═╝   ╚═╝╚═╝     ╚═╝  ╚═╝╚═╝',
+]
+
+/** Pure ASCII. 34 columns, 4 rows — safe on any terminal, any code page. */
+const ASCII = [
+  '  _  _  ___ _____ ___ ___ _   ___ ',
+  ' | \\| |/ _ \\_   _|_ _| __/_\\ |_ _|',
+  ' | .` | (_) || |  | || _/ _ \\ | | ',
+  ' |_|\\_|\\___/ |_| |___|_/_/ \\_\\___|',
+]
+
+export type BannerSize = 'block' | 'ascii' | 'word'
+
+export function bannerSize(columns = terminalWidth()): BannerSize {
+  if (unicode && columns >= 54) return 'block'
+  if (columns >= 38) return 'ascii'
+  return 'word'
+}
+
+/** The wordmark as rendered lines, gradient included. */
+export function bannerLines(columns = terminalWidth()): string[] {
+  switch (bannerSize(columns)) {
+    case 'block':
+      return gradientBlock(BLOCK)
+    case 'ascii':
+      return gradientBlock(ASCII)
+    case 'word':
+      return gradientBlock(['N O T I F A I'])
+  }
+}
+
+/**
+ * Reveal the wordmark one row at a time.
+ *
+ * Deliberately brief and deliberately skippable: this runs before someone can
+ * do anything, so it may not become a wait. It is skipped entirely when output
+ * is not a TTY, when `NOTIFAI_NO_ANIMATION` is set, and under `CI`.
+ */
+export async function printBanner(
+  options: { animate?: boolean; env?: NodeJS.ProcessEnv; write?: (line: string) => void } = {},
+): Promise<void> {
+  const env = options.env ?? process.env
+  const write = options.write ?? ((line: string) => process.stdout.write(`${line}\n`))
+  const lines = bannerLines()
+  const animate =
+    options.animate !== false &&
+    process.stdout.isTTY === true &&
+    (env['NOTIFAI_NO_ANIMATION'] ?? '') === '' &&
+    (env['CI'] ?? '') === ''
+
+  write('')
+  for (const line of lines) {
+    // Two columns, matching the tagline and the status card beneath it. Flush
+    // left, the wordmark reads as a separate thing sitting above the app.
+    write(`  ${line}`)
+    if (animate) await new Promise((resolve) => setTimeout(resolve, 26))
+  }
+  write('')
+}
+
+/**
+ * One line of orientation under the wordmark — and it must stay one line.
+ * Wrapped onto two it stops reading as a subtitle and starts reading as the
+ * first paragraph of something, so a narrow terminal gets the version alone.
+ */
+export function tagline(version: string, columns = terminalWidth()): string {
+  const full = 'Native notifications for agents and local programs'
+  // Two leading columns of indent, two trailing for the version.
+  return columns >= full.length + 12
+    ? `${style.dim(full)}  ${style.dim(`v${version}`)}`
+    : style.dim(`v${version}`)
+}