@raidiant/notifai 0.5.0 → 1.0.0

package/src/commands.ts

@@ -36,7 +36,7 @@ import {
   configBounds,
   configDefaultValue,
   findProjectConfigPath,
-  findProjectLocalConfigPath,
+  personalProjectConfigPath,
   globalConfigPath,
   loadConfig,
   sessionConfigPath,
@@ -46,6 +46,7 @@ import {
   type LogLevel,
 } from './config.js'
 import { acceptedValues, configInfo } from './config-schema.js'
+import { packageVersion, skillsSource } from './release.js'
 import { atomicWriteFileSync } from './atomic-file.js'
 import { withTargetFileLock } from './file-lock.js'
 import {
@@ -56,8 +57,8 @@ import {
 import type { CredentialStore, MachineCredential } from './credentials.js'
 import {
   firstBlocker,
-  openItems,
   type Readiness,
+  type ReadinessRefresh,
   type ReadinessState,
   type StateStatus,
 } from './readiness.js'
@@ -99,12 +100,18 @@ import {
   applyPlan,
   buildCursorHookConfig,
   buildHookConfig,
+  collapseUnusedCodexRepresentation,
   codexLayerDir,
+  codexLayerPaths,
+  codexRepresentationProblems,
   codexTrustProblems,
   codexProjectRoot,
   detectHarness,
+  detectedHarnesses,
   findInstallations,
   handlerEvent,
+  hookDefinitionFiles,
+  inspectCodexLayer,
   loadCursorSettings,
   loadSettings,
   mergeCursorHooks,
@@ -115,7 +122,7 @@ import {
   type Harness,
   type Installation,
 } from './install-hooks.js'
-import { HARNESS_CAPABILITIES } from './harnesses.js'
+import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js'
 import {
   claudeWakeRoute,
   inspectClaudeInbox,
@@ -130,6 +137,8 @@ import {
 import {
   inspectHookAdapter,
   installHookAdapter,
+  isNpxAdapterTarget,
+  type HookAdapterTarget,
 } from './hook-adapter.js'
 import {
   isOurOpencodePlugin,
@@ -161,6 +170,12 @@ export interface CommandIo {
    */
   interactive?: boolean
   select?(message: string, options: { value: string; label: string; hint?: string }[]): Promise<string | null>
+  /** Interactive multi-select. `initial` are pre-selected values. */
+  multiselect?(
+    message: string,
+    options: { value: string; label: string; hint?: string }[],
+    initial?: string[],
+  ): Promise<string[] | null>
   intro?(title: string): Promise<void>
   outro?(message: string): Promise<void>
   note?(message: string, title?: string): Promise<void>
@@ -187,6 +202,8 @@ export interface CommandDeps {
   cwd: string
   /** Test seam; production fixes the hook adapter under os.homedir(). */
   hookAdapterHome?: string
+  /** Test seam; production uses this process's Node and CLI paths. */
+  hookInstallTarget?: HookAdapterTarget
   /** Test seam; production uses fetch against base_url. */
   clientFactory?: (baseUrl: string, bearer: string | null, options?: ClientOptions) => ApiClient
   /** Test seam for bounded polling without wall-clock sleeps. */
@@ -2124,19 +2141,79 @@ export interface HooksInstallFlags {
   scriptPath?: string
 }
 
+/** True when this process is `npx` / `npm exec`, not a global or linked install. */
+export function runningViaNpx(env: NodeJS.ProcessEnv, scriptPath: string): boolean {
+  if (env['npm_command'] === 'exec') return true
+  return scriptPath.includes(`${path.sep}_npx${path.sep}`)
+}
+
+function fileHookInstallTarget(
+  target: HookAdapterTarget | undefined,
+): { execPath: string; scriptPath: string } | undefined {
+  if (target === undefined || isNpxAdapterTarget(target)) return undefined
+  return target
+}
+
+function resolveHookAdapterTarget(deps: CommandDeps, flags: HooksInstallFlags): HookAdapterTarget {
+  if (deps.hookInstallTarget !== undefined && isNpxAdapterTarget(deps.hookInstallTarget)) {
+    return deps.hookInstallTarget
+  }
+  const fileTarget = fileHookInstallTarget(deps.hookInstallTarget)
+  const execPath = flags.execPath ?? fileTarget?.execPath ?? process.execPath
+  const scriptPath = flags.scriptPath ?? fileTarget?.scriptPath ?? process.argv[1] ?? 'notifai'
+  if (runningViaNpx(deps.env, scriptPath)) {
+    const version = packageVersion()
+    const npmCli = deps.env['npm_execpath']
+    if (version === null) {
+      throw new Error(
+        'Could not read this CLI version, so an npx hook target cannot be pinned. Install `@raidiant/notifai` globally and rerun `notifai hooks install`.',
+      )
+    }
+    if (typeof npmCli !== 'string' || npmCli === '') {
+      throw new Error(
+        'This process looks like npx but npm_execpath is missing. Install `@raidiant/notifai` globally and rerun `notifai hooks install`.',
+      )
+    }
+    return { kind: 'npx', execPath, npmCli, spec: `@raidiant/notifai@${version}` }
+  }
+  return { execPath, scriptPath }
+}
+
+function printHooksInstallClose(deps: CommandDeps, harness: Harness, file: string): void {
+  const label = HARNESS_LABELS[harness]
+  if (deps.io.interactive === true && deps.io.note) {
+    void deps.io.note(`${file}\nSend one ${label} prompt, then run \`notifai doctor\`.`, `${label} hooks installed`)
+    return
+  }
+  deps.io.out(`Installed ${harness} hooks in ${file}`)
+  deps.io.out(`Send one ${label} prompt, then check \`notifai doctor\`.`)
+}
+
 export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags): number {
+  if (flags.harness === undefined) {
+    const detected = detectedHarnesses(deps.cwd, deps.env)
+    if (detected.length === 0) {
+      deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`)
+      return EXIT.usage
+    }
+    let ok = true
+    for (const harness of detected) {
+      if (hooksInstallCommand(deps, { ...flags, harness }) !== EXIT.ok) ok = false
+    }
+    return ok ? EXIT.ok : EXIT.failed
+  }
   const harness = resolveHarness(deps, flags.harness)
   if (!harness) return EXIT.usage
-  const execPath = flags.execPath ?? process.execPath
-  const scriptPath = flags.scriptPath ?? process.argv[1] ?? 'notifai'
+  const adapterTarget = resolveHookAdapterTarget(deps, flags)
+  const scriptPath =
+    flags.scriptPath ?? fileHookInstallTarget(adapterTarget)?.scriptPath ?? process.argv[1] ?? 'notifai'
   let adapterPath: string
   try {
-    adapterPath = installHookAdapter({ execPath, scriptPath }, deps.hookAdapterHome).path
+    adapterPath = installHookAdapter(adapterTarget, deps.hookAdapterHome).path
   } catch (err) {
     deps.io.err(`Could not prepare the stable hook adapter: ${String(err)}`)
     return EXIT.failed
   }
-  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   const file = settingsFile(harness, flags.global ?? false, deps.cwd, deps.env)
 
   // OpenCode's adapter is a generated plugin module rather than a handler
@@ -2149,9 +2226,8 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   }
 
   if (harness === 'cursor') {
-    let merged: ReturnType<typeof mergeCursorHooks>
     try {
-      merged = withTargetFileLock(file, () => {
+      withTargetFileLock(file, () => {
         const document = loadCursorSettings(file)
         const result = mergeCursorHooks(
           document,
@@ -2168,26 +2244,16 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       deps.io.err(String(err))
       return EXIT.failed
     }
-    deps.io.out(`Installed ${harness} hooks in ${file}`)
-    if (merged.replaced.length > 0) deps.io.out(`  replaced: ${merged.replaced.join(', ')}`)
-    if (merged.added.length > 0) deps.io.out(`  added: ${merged.added.join(', ')}`)
-    if (flags.global) {
-      deps.io.out('Send one Cursor prompt, then check `notifai doctor`. If the hook has not fired,')
-      deps.io.out('start a new Cursor session and try one prompt again.')
-    } else {
-      deps.io.out('Send one Cursor prompt, then check `notifai doctor`. If the hook has not fired,')
-      deps.io.out('start a new Cursor session and try one prompt again.')
-    }
-    deps.io.out('Cursor hooks can emit a native follow-up, but its agent shell does not expose')
-    deps.io.out('the exact conversation id needed to register safely. `notifai ask` therefore')
-    deps.io.out('fails closed; use blocking `notifai send --reply` for questions.')
+    printHooksInstallClose(deps, harness, file)
     return EXIT.ok
   }
 
-  let merged: ReturnType<typeof mergeHooks>
+  let foreignStopCount = 0
+  let collapsedFrom: string | null = null
   try {
-    merged = withTargetFileLock(file, () => {
+    withTargetFileLock(file, () => {
       const document = loadSettings(file)
+      foreignStopCount = foreignStopHandlers(document).length
       const result = mergeHooks(
         document,
         buildHookConfig({
@@ -2199,62 +2265,47 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       applyPlan(file, result.document)
       return result
     })
+    if (harness === 'codex') {
+      collapsedFrom = collapseUnusedCodexRepresentation(
+        file,
+        scriptPath,
+        codexLayerPaths(flags.global ?? false, deps.cwd, deps.env),
+      )
+    }
   } catch (err) {
     deps.io.err(String(err))
     return EXIT.failed
   }
 
-  deps.io.out(`Installed ${harness} hooks in ${file}`)
-  if (merged.replaced.length > 0) deps.io.out(`  replaced: ${merged.replaced.join(', ')}`)
-  if (merged.added.length > 0) deps.io.out(`  added: ${merged.added.join(', ')}`)
-  if (merged.removed.length > 0) {
-    deps.io.out(`  removed: ${merged.removed.join(', ')} (this build no longer serves them)`)
-  }
-  deps.io.out('')
-  deps.io.out(
-    config.ask_grace_seconds.value === 0
-      ? 'A question registered with `notifai ask` goes to your devices immediately when the agent turn ends, whether or not you are at this machine.'
-      : `A question registered with \`notifai ask\` stays in the terminal for ${config.ask_grace_seconds.value}s from registration and then goes to your devices whether or not you are at this machine.`,
-  )
   if (harness === 'codex') {
     const layer = flags.global ? null : codexLayerDir(deps.cwd)
-    if (layer !== null) {
-      // Codex reads project hooks from the main repository but only looks when
-      // a `.codex` directory sits at or above cwd, so a worktree install has to
-      // write one file and create one directory in two different places. Doing
-      // it silently would leave the next person deriving this the hard way
-      //.
-      mkdirSync(layer, { recursive: true })
-      deps.io.out('')
-      deps.io.out('You are in a worktree. Codex reads project hooks from the main repository,')
-      deps.io.out(`so they were written to ${file}. ${layer} was created so this`)
-      deps.io.out('worktree discovers that file. Each other worktree needs its own `.codex`')
-      deps.io.out('directory; rerun this installer from that worktree to create it.')
-    }
+    if (layer !== null) mkdirSync(layer, { recursive: true })
   }
-  deps.io.out('')
-  if (harness === 'claude-code') {
-    // Codex deliberately gets no counterpart line: its Stop definition is
-    // byte-identical to the one earlier builds wrote, so nothing about its
-    // trust state changed and saying so would invent a gate that is not there.
+  printHooksInstallClose(deps, harness, file)
+  if (collapsedFrom !== null) {
+    deps.io.out(`Collapsed ${collapsedFrom} onto ${file} so this layer has one representation.`)
+  }
+  if (foreignStopCount > 0) {
     deps.io.out(
-      `The Stop handler is asynchronous: it returns at once, so your turn ends normally, and it waits for your answer out of band for up to ${CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS}s before delivering it back into this session. That timeout is written explicitly because Claude Code kills a background hook at its own 600s default and reports nothing when it does.`,
+      "This layer already has a Stop handler. Codex runs every matching handler, so Notifai's Stop and the existing one will both fire.",
     )
-    deps.io.out('')
-  }
-  if (harness === 'claude-code' && flags.global !== true) {
-    deps.io.out('Claude Code reloads project hook files without a restart. Send one new prompt,')
-    deps.io.out('then check `notifai doctor` to confirm that the hook fired.')
-  } else if (harness === 'claude-code') {
-    deps.io.out('Send one new Claude Code prompt, then check `notifai doctor`. If the hook has')
-    deps.io.out('not fired, start a new Claude Code session and try one prompt again.')
-  } else {
-    deps.io.out('Send one Codex prompt, then check `notifai doctor`. If the hook has not fired,')
-    deps.io.out('start a new Codex session and try one prompt again.')
+  }
+  if (harness === 'codex') {
+    for (const problem of codexRepresentationProblems(deps.cwd, deps.env)) {
+      deps.io.out(problem)
+    }
   }
   return EXIT.ok
 }
 
+function foreignStopHandlers(document: { hooks?: Record<string, { hooks?: { command: string }[] }[]> }): { command: string }[] {
+  const groups = document.hooks?.['Stop']
+  if (!Array.isArray(groups)) return []
+  return groups
+    .flatMap((group) => group.hooks ?? [])
+    .filter((handler) => !/ hook (user-prompt-submit|stop|session-end)\b/.test(handler.command))
+}
+
 /**
  * Writes the OpenCode plugin, replacing any Notifai plugin already there —
  * including one a different checkout wrote, matched on the managed marker for
@@ -2284,16 +2335,7 @@ function installOpencodePlugin(
     deps.io.err(String(err))
     return EXIT.failed
   }
-  deps.io.out(`Installed the OpenCode plugin at ${file}`)
-  deps.io.out('')
-  deps.io.out('It maps chat.message to presence, session.idle to question escalation, and')
-  deps.io.out('session.deleted to local cleanup through the same `notifai hook` commands')
-  deps.io.out('the other harnesses run. Permission prompts stay in OpenCode.')
-  deps.io.out('OpenCode does not expose a proven exactly-once continuation after session.idle,')
-  deps.io.out('so `notifai ask` fails closed there. Use blocking `notifai send --reply` when')
-  deps.io.out('the answer must return to the agent without another human prompt.')
-  deps.io.out('')
-  deps.io.out('Restart OpenCode: it loads plugins once at start.')
+  printHooksInstallClose(deps, 'opencode', file)
   return EXIT.ok
 }
 
@@ -2349,28 +2391,33 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
     )
     return EXIT.ok
   }
-  let stripped: ReturnType<typeof removeHooks> | null
+  const files = hookDefinitionFiles(harness, flags.global ?? false, deps.cwd, deps.env)
+  const existing = files.filter((candidate) => existsSync(candidate))
+  if (existing.length === 0) {
+    deps.io.out(`Nothing to remove: ${file} does not exist.`)
+    return EXIT.ok
+  }
+  let removedAny = false
   try {
-    stripped = withTargetFileLock(file, () => {
-      if (!existsSync(file)) return null
-      const document = loadSettings(file)
-      const result = removeHooks(document, scriptPath)
-      applyPlan(file, result.document)
-      return result
-    })
+    for (const candidate of existing) {
+      const stripped = withTargetFileLock(candidate, () => {
+        const document = loadSettings(candidate)
+        const result = removeHooks(document, scriptPath)
+        applyPlan(candidate, result.document)
+        return result
+      })
+      if (stripped.replaced.length > 0) {
+        removedAny = true
+        deps.io.out(`Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${candidate}`)
+      }
+    }
   } catch (err) {
     deps.io.err(String(err))
     return EXIT.failed
   }
-  if (stripped === null) {
-    deps.io.out(`Nothing to remove: ${file} does not exist.`)
-    return EXIT.ok
+  if (!removedAny) {
+    deps.io.out(`No Notifai hooks found in ${existing.join(', ')}`)
   }
-  deps.io.out(
-    stripped.replaced.length > 0
-      ? `Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${file}`
-      : `No Notifai hooks found in ${file}`,
-  )
   return EXIT.ok
 }
 
@@ -2385,6 +2432,13 @@ function assertOwnedRegularFile(file: string): void {
   }
 }
 
+const HARNESS_LABEL: Record<Harness, string> = {
+  'claude-code': 'Claude Code',
+  codex: 'Codex',
+  cursor: 'Cursor',
+  opencode: 'OpenCode',
+}
+
 function resolveHarness(deps: CommandDeps, requested: string | undefined): Harness | null {
   if (requested !== undefined) {
     if ((HARNESSES as readonly string[]).includes(requested)) return requested as Harness
@@ -2393,7 +2447,7 @@ function resolveHarness(deps: CommandDeps, requested: string | undefined): Harne
     )
     return null
   }
-  const detected = detectHarness(deps.cwd)
+  const detected = detectHarness(deps.cwd, deps.env)
   if (!detected) {
     deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`)
     return null
@@ -2401,6 +2455,48 @@ function resolveHarness(deps: CommandDeps, requested: string | undefined): Harne
   return detected
 }
 
+/**
+ * Which harnesses to wire. An explicit `--harness` still wins as a singleton.
+ * Otherwise: every detected harness, or a human picker when detection is empty
+ * or names more than one.
+ */
+async function pickHarnessesToInstall(
+  deps: CommandDeps,
+  requested?: string,
+): Promise<Harness[] | null> {
+  if (requested !== undefined) {
+    const harness = resolveHarness(deps, requested)
+    return harness === null ? null : [harness]
+  }
+  const detected = detectedHarnesses(deps.cwd, deps.env)
+  if (detected.length === 1) return detected
+  if (deps.io.interactive === true && deps.io.multiselect) {
+    const picked = await deps.io.multiselect(
+      'Which agent harnesses should Notifai wire here?',
+      HARNESSES.map((name) => ({
+        value: name,
+        label: HARNESS_LABEL[name],
+        ...(detected.includes(name) ? { hint: 'detected on this machine' } : {}),
+      })),
+      detected,
+    )
+    if (picked === null) return null
+    const unknown = picked.filter((name) => !(HARNESSES as readonly string[]).includes(name))
+    if (unknown.length > 0) {
+      deps.io.err(`Unknown harness "${unknown[0]}". Supported: ${HARNESSES.join(', ')}.`)
+      return null
+    }
+    return picked as Harness[]
+  }
+  if (detected.length === 0) {
+    deps.io.err(
+      `Could not tell which harness to wire. Run: notifai hooks install --harness <${HARNESSES.join('|')}>`,
+    )
+    return null
+  }
+  return detected
+}
+
 // ---------------------------------------------------------------------------
 // config show / set / unset
 // ---------------------------------------------------------------------------
@@ -2412,7 +2508,14 @@ export function configShowCommand(
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
   if (flags.json) {
     const output = Object.fromEntries(
-      CONFIG_KEYS.map((key) => [key, { value: config[key].value, source: config[key].source }]),
+      CONFIG_KEYS.map((key) => [
+        key,
+        {
+          value: config[key].value,
+          source: config[key].source,
+          summary: configInfo(key).summary,
+        },
+      ]),
     )
     deps.io.out(JSON.stringify(output, null, 2))
     return EXIT.ok
@@ -2621,7 +2724,7 @@ async function configMutationTarget(
     const selected = await deps.io.select('Where should this setting live?', [
       { value: 'global', label: 'This machine', hint: 'applies across projects' },
       { value: 'project', label: 'This project (shared)', hint: '.notifai/config.toml' },
-      { value: 'local', label: 'This project (personal)', hint: 'keep config.local.toml gitignored' },
+      { value: 'local', label: 'This project (personal)', hint: 'stored on this machine, not in the repo' },
     ])
     if (selected === null) {
       deps.io.err('No configuration layer selected.')
@@ -2633,7 +2736,7 @@ async function configMutationTarget(
   const targetPath = flags.session
     ? sessionConfigPath(flags.session, deps.env)
     : layer === 'local'
-      ? (findProjectLocalConfigPath(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'config.local.toml'))
+      ? personalProjectConfigPath(deps.cwd, deps.env)
       : layer === 'project'
         ? (findProjectConfigPath(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'config.toml'))
         : globalConfigPath(deps.env)
@@ -2912,13 +3015,22 @@ export function logsCommand(deps: CommandDeps, flags: LogsFlags): number {
 // ---------------------------------------------------------------------------
 
 /**
- * Where `npx skills add` fetches the optional agent skill from. In skills CLI
- * 1.5.x, `owner/repo@name` selects a skill; a Git ref belongs after `#`.
- * Keep this immutable and public because the command is printed to users.
+ * Where `npx skills add` fetches the optional agent skill from, derived from
+ * this build's own version so the pin cannot drift from the release it names.
+ * Null when the build cannot establish its version; see `./release.js`.
+ */
+export const SKILLS_SOURCE: string | null = skillsSource()
+
+/**
+ * How to refer to the pin in user-facing text.
+ *
+ * Only reached in a corrupted install, where naming the tag is impossible but
+ * saying nothing would be worse — the sentence still has to read as English.
  */
-export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.5.0'
+const SKILLS_SOURCE_LABEL = SKILLS_SOURCE ?? 'the public release tag matching this CLI'
 
 function skillSourceParts(): { source: string; ref: string } | null {
+  if (SKILLS_SOURCE === null) return null
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
   return match === null ? null : { source: match[1]!, ref: match[2]! }
 }
@@ -2955,7 +3067,7 @@ async function skillReadiness(
       id: 'skill',
       title: 'Agent guidance skill',
       status: 'ready',
-      detail: `installed from ${SKILLS_SOURCE} in the ${installed.scope} scope`,
+      detail: `installed from ${SKILLS_SOURCE_LABEL} in the ${installed.scope} scope`,
     }
   }
 
@@ -2970,7 +3082,7 @@ async function skillReadiness(
     detail:
       errors.length > 0
         ? `could not verify installer-managed state in ${scopeText} (${errors.join('; ')})`
-        : `not installed from ${SKILLS_SOURCE} in ${scopeText}`,
+        : `not installed from ${SKILLS_SOURCE_LABEL} in ${scopeText}`,
     remedy: {
       by: 'cli',
       summary: 'install the skill agents follow when deciding to notify',
@@ -3117,8 +3229,8 @@ function observedCompanionReceipt(
  * gap, so re-running is how you check the setup as much as how you create it.
  * With a human at a terminal it walks them through the missing pieces; run by
  * an agent it never prompts — each optional step is answered by a flag, and
- * whatever only the user can do (signing in, pairing a companion device) is printed as
- * the exact command to hand back to them.
+ * whatever only the user can do (signing in, pairing a companion device) is
+ * printed as the next human action. An agent runs every CLI command itself.
  */
 /**
  * Close a gap the CLI is allowed to close on its own, without asking.
@@ -3149,21 +3261,13 @@ async function closeGap(
   }
 
   if (state.id === 'hooks') {
-    let harness = detectHarness(deps.cwd)
-    if (harness === null && deps.io.interactive === true && deps.io.select) {
-      const picked = await deps.io.select(
-        'Which agent harness do you use here?',
-        HARNESSES.map((name) => ({ value: name, label: name })),
-      )
-      if (picked !== null) harness = picked as Harness
+    const harnesses = await pickHarnessesToInstall(deps)
+    if (harnesses === null || harnesses.length === 0) return 'failed'
+    let ok = true
+    for (const harness of harnesses) {
+      if (hooksInstallCommand(deps, { harness }) !== EXIT.ok) ok = false
     }
-    if (harness === null) {
-      deps.io.err(
-        `Could not tell which harness to wire. Run: notifai hooks install --harness <${HARNESSES.join('|')}>`,
-      )
-      return 'failed'
-    }
-    return hooksInstallCommand(deps, { harness }) === EXIT.ok ? 'closed' : 'failed'
+    return ok ? 'closed' : 'failed'
   }
 
   if (state.id === 'skill') {
@@ -3171,6 +3275,14 @@ async function closeGap(
       deps.io.err('Skill installation failed — the native `npx skills` flow is unavailable.')
       return 'failed'
     }
+    // Refuse rather than reach for a mutable ref: installing the skill from a
+    // moving branch is the one outcome the pin exists to prevent.
+    if (SKILLS_SOURCE === null) {
+      deps.io.err(
+        'Skill installation failed — this build cannot determine its own version, so there is no release tag to install from.',
+      )
+      return 'failed'
+    }
     const scopeText = flags.skillsScope === undefined ? 'the scope you choose' : `${flags.skillsScope} scope`
     deps.io.out(`Starting the native npx skills setup for the notifai agent skill (${scopeText})...`)
     const addOptions = {
@@ -3499,6 +3611,13 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
   return 'pending'
 }
 
+/** Closing a local gap cannot have changed the service, the keychain, or devices. */
+function refreshAfterClose(id: string): readonly ReadinessRefresh[] | undefined {
+  return id === 'project' || id === 'hooks' || id === 'skill' || id === 'question-routing-settings'
+    ? ['local']
+    : undefined
+}
+
 /** Whether an optional gap should be closed, given flags and who is watching. */
 function wantsOptional(deps: CommandDeps, state: ReadinessState, flags: InitFlags): Promise<boolean> {
   // Naming the project is init's whole reason to touch the filesystem, costs
@@ -3558,12 +3677,13 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
   }
   await deps.io.intro?.('Notifai setup')
 
-  const reassess = () =>
-    assessReadiness(
-      deps,
-      flags.skillsScope === undefined ? {} : { skillScope: flags.skillsScope },
-    )
-  let readiness = await reassess()
+  const skillOpts = flags.skillsScope === undefined ? {} : { skillScope: flags.skillsScope }
+  let readiness = await assessReadiness(deps, skillOpts)
+  const reassess = (refresh?: readonly ReadinessRefresh[]) =>
+    assessReadiness(deps, {
+      ...skillOpts,
+      ...(refresh === undefined ? {} : { previous: readiness, refresh }),
+    })
   let failed = false
   const attempted = new Set<string>()
 
@@ -3594,7 +3714,7 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
         const result = await closeGap(deps, state, flags)
         if (result === 'failed') failed = true
         if (result === 'failed' && state.status === 'optional-gap') {
-          readiness = await reassess()
+          readiness = await reassess(refreshAfterClose(state.id))
           advanced = true
           break
         }
@@ -3602,7 +3722,7 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
           stop = true
           break
         }
-        readiness = await reassess()
+        readiness = await reassess(refreshAfterClose(state.id))
         advanced = true
         break
       }
@@ -3615,7 +3735,7 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
           stop = true
           break
         }
-        readiness = await reassess()
+        readiness = await reassess(refreshAfterClose(state.id))
         advanced = true
         break
       }
@@ -3664,37 +3784,81 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
     if (stop || !advanced) break
   }
 
-  readiness = await reassess()
-  for (const state of readiness.states.filter((s) => s.status === 'ready')) {
-    deps.io.out(`${state.title}: ${state.detail}`)
+  await printInitClose(deps, readiness, flags)
+  const blocker = firstBlocker(readiness)
+  if (blocker === null) return failed ? EXIT.failed : EXIT.ok
+  return failed || deps.io.interactive !== true ? EXIT.failed : EXIT.ok
+}
+
+function isHookSubstate(id: string): boolean {
+  return id === 'hooks' || id.startsWith('hooks-') || id === 'question-routing-settings'
+}
+
+function leftoverOptionals(readiness: Readiness, flags: InitFlags): ReadinessState[] {
+  return readiness.states.filter((state) => {
+    if (state.status !== 'optional-gap') return false
+    if (isHookSubstate(state.id)) return false
+    if (state.id === 'skill' && flags.skills === false) return false
+    return true
+  })
+}
+
+function printOptionalLeftovers(deps: CommandDeps, leftovers: readonly ReadinessState[]): void {
+  for (const state of leftovers) {
+    deps.io.out(`Optional, not set up — ${remedyLine(state)}`)
   }
+}
 
+function questionsWillRoute(readiness: Readiness): boolean {
+  const hooks = readiness.states.find((state) => state.id === 'hooks')
+  const settings = readiness.states.find((state) => state.id === 'question-routing-settings')
+  return hooks?.status === 'ready' && settings?.status !== 'gap'
+}
+
+async function printInitClose(
+  deps: CommandDeps,
+  readiness: Readiness,
+  flags: InitFlags,
+): Promise<void> {
   const blocker = firstBlocker(readiness)
+  const canSend = readiness.states.find((state) => state.id === 'devices')?.status === 'ready'
+  const questions = questionsWillRoute(readiness)
+  const leftovers = leftoverOptionals(readiness, flags)
+
+  if (deps.io.interactive === true) {
+    if (blocker === null) {
+      const lines = [
+        canSend ? 'You can send notifications.' : 'You are signed in.',
+        questions
+          ? 'Questions will reach your devices.'
+          : 'Questions stay in the terminal until hooks are installed.',
+      ]
+      await deps.io.note?.(lines.join('\n'), 'Ready')
+      printOptionalLeftovers(deps, leftovers)
+      deps.io.out('All set. Agents in this project can notify you and ask questions.')
+      await deps.io.outro?.('All set ✨')
+      return
+    }
+    await deps.io.note?.(`${blocker.title} — ${blocker.detail}\n${remedyLine(blocker)}`, 'Next')
+    deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`)
+    deps.io.out(`  ${remedyLine(blocker)}`)
+    if (blocker.remedy?.by === 'user-elsewhere' || blocker.remedy?.by === 'user-here') {
+      deps.io.out('  Then re-run `notifai init` and it will pick up from here.')
+    }
+    await deps.io.outro?.('One step remains (above)')
+    return
+  }
+
   if (blocker === null) {
-    const skipped = openItems(readiness).filter(
-      (state) => !(state.id === 'skill' && flags.skills === false),
-    )
-    for (const state of skipped) deps.io.out(`Optional, not set up — ${remedyLine(state)}`)
+    printOptionalLeftovers(deps, leftovers)
     deps.io.out('All set. Agents in this project can notify you and ask questions.')
-    await deps.io.outro?.('All set ✨')
-    return failed ? EXIT.failed : EXIT.ok
+    return
   }
-
-  // Exactly one. Everything else waits until this is done, because the next
-  // gap is frequently a consequence of this one and naming it now would send
-  // the reader off to fix something that is not actually wrong.
-  deps.io.out('')
   deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`)
   deps.io.out(`  ${remedyLine(blocker)}`)
-  // Both "do it here" and "do it elsewhere" leave setup mid-journey; re-run is
-  // how the rest is recovered either way.
   if (blocker.remedy?.by === 'user-elsewhere' || blocker.remedy?.by === 'user-here') {
     deps.io.out('  Then re-run `notifai init` and it will pick up from here.')
   }
-  await deps.io.outro?.('One step remains (above)')
-  // An agent must be able to branch on setup being blocked without parsing
-  // prose. A present human may deliberately leave and resume later.
-  return failed || deps.io.interactive !== true ? EXIT.failed : EXIT.ok
 }
 
 // ---------------------------------------------------------------------------
@@ -3740,6 +3904,66 @@ async function contractCheck(client: ApiClient): Promise<{ name: string; ok: boo
   }
 }
 
+function projectReadiness(deps: CommandDeps, config: CliConfig): ReadinessState {
+  const configPath = path.join(deps.cwd, '.notifai', 'config.toml')
+  const projectSlug = config.project.value
+  return projectSlug !== null
+    ? {
+        id: 'project',
+        title: 'Project identity',
+        status: 'ready',
+        detail: `"${projectSlug}" (${config.project.source})`,
+      }
+    : {
+        id: 'project',
+        title: 'Project identity',
+        // Not a blocker: a send without a project simply carries no project
+        // identity. init always sets one because it is free and reversible,
+        // but an unlabelled setup works, so this must not go red.
+        status: 'optional-gap',
+        detail: `not set in ${configPath} — sends from here carry no project identity`,
+        remedy: {
+          by: 'cli',
+          summary: 'name this project after its directory',
+          command: 'notifai init',
+        },
+      }
+}
+
+function remoteStatesFrom(previous: Readiness): {
+  credential: ReadinessState
+  server: ReadinessState
+  contract: ReadinessState
+  auth: ReadinessState
+  devices: ReadinessState
+  proof: ReadinessState
+} | null {
+  const pick = (id: string): ReadinessState | undefined => previous.states.find((state) => state.id === id)
+  const credential = pick('credential')
+  const server = pick('server')
+  const contract = pick('contract')
+  const auth = pick('auth')
+  const devices = pick('devices')
+  const proof = pick('proof')
+  if (
+    credential === undefined ||
+    server === undefined ||
+    contract === undefined ||
+    auth === undefined ||
+    devices === undefined ||
+    proof === undefined
+  ) {
+    return null
+  }
+  return { credential, server, contract, auth, devices, proof }
+}
+
+function remoteInvalidatedByConfig(previous: Readiness, config: CliConfig): boolean {
+  if (config.base_url.source === 'default') return false
+  const server = previous.states.find((state) => state.id === 'server')
+  return server === undefined || !server.detail.includes(config.base_url.value)
+}
+
 /**
  * Read the whole setup once, in dependency order.
  *
@@ -3751,38 +3975,46 @@ async function contractCheck(client: ApiClient): Promise<{ name: string; ok: boo
  */
 export async function assessReadiness(
   deps: CommandDeps,
-  options: { skillScope?: SkillScope } = {},
+  options: {
+    skillScope?: SkillScope
+    previous?: Readiness
+    refresh?: readonly ReadinessRefresh[]
+  } = {},
 ): Promise<Readiness> {
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const previous = options.previous
+  const refresh = options.refresh
+  if (previous !== undefined && refresh !== undefined && refresh.length === 0) return previous
+
+  const reuseRemote =
+    previous !== undefined &&
+    refresh !== undefined &&
+    !refresh.includes('remote') &&
+    !remoteInvalidatedByConfig(previous, config)
+  if (reuseRemote) {
+    const reused = remoteStatesFrom(previous)
+    if (reused !== null) {
+      return {
+        states: [
+          projectReadiness(deps, config),
+          reused.credential,
+          reused.server,
+          reused.contract,
+          reused.auth,
+          ...hookStates(deps),
+          await skillReadiness(deps, options.skillScope),
+          reused.devices,
+          reused.proof,
+        ],
+      }
+    }
+  }
+
   const states: ReadinessState[] = []
   let accountClient: ApiClient | null = null
   let accountDevices: RoutableDevice[] | null = null
 
-  const configPath = path.join(deps.cwd, '.notifai', 'config.toml')
-  const projectSlug = config.project.value
-  states.push(
-    projectSlug !== null
-      ? {
-          id: 'project',
-          title: 'Project identity',
-          status: 'ready',
-          detail: `"${projectSlug}" (${config.project.source})`,
-        }
-      : {
-          id: 'project',
-          title: 'Project identity',
-          // Not a blocker: a send without a project simply carries no project
-          // identity. init always sets one because it is free and reversible,
-          // but an unlabelled setup works, so this must not go red.
-          status: 'optional-gap',
-          detail: `not set in ${configPath} — sends from here carry no project identity`,
-          remedy: {
-            by: 'cli',
-            summary: 'name this project after its directory',
-            command: 'notifai init',
-          },
-        },
-  )
+  states.push(projectReadiness(deps, config))
 
   const credential = deps.store.load()
   states.push(
@@ -3825,10 +4057,10 @@ export async function assessReadiness(
           id: 'server',
           title: 'Service',
           status: 'gap',
-          detail: `cannot reach ${baseUrl} (${config.base_url.source})`,
+          detail: `cannot reach ${baseUrl}`,
           remedy: {
             by: 'user-here',
-            summary: 'check your network, or the base_url shown above',
+            summary: 'check your network',
             command: 'notifai doctor',
           },
         },
@@ -4054,8 +4286,12 @@ async function setupProofState(
   }
 }
 
-export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }): Promise<number> {
-  const readiness = await assessReadiness(deps)
+export async function doctorCommand(
+  deps: CommandDeps,
+  flags: { json?: boolean },
+  options: { readiness?: Readiness } = {},
+): Promise<number> {
+  const readiness = options.readiness ?? (await assessReadiness(deps))
   const blocker = firstBlocker(readiness)
   const ok = blocker === null
 
@@ -4299,6 +4535,21 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
       .join(', '),
   })
 
+  const wired = new Set(installations.map((installation) => installation.harness))
+  const unwired = detectedHarnesses(deps.cwd, deps.env).filter((harness) => !wired.has(harness))
+  if (unwired.length > 0) {
+    checks.push({
+      name: 'hooks (detected)',
+      ok: false,
+      informational: true,
+      detail: `${unwired.map((harness) => HARNESS_LABEL[harness]).join(', ')} detected on this machine but not wired`,
+      remedy: {
+        summary: 'install hooks for every detected harness',
+        command: 'notifai hooks install',
+      },
+    })
+  }
+
   const { active, contested } = resolveActiveHarness(
     deps.env,
     deps.cwd,
@@ -4438,7 +4689,11 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
       harness,
       installations: installations.filter((i) => i.harness === harness),
     }))
-    .filter((entry) => entry.installations.length > 1)
+    .filter(
+      (entry) =>
+        entry.installations.some((installation) => installation.global) &&
+        entry.installations.some((installation) => !installation.global),
+    )
   if (duplicated.length > 0) {
     checks.push({
       name: 'hooks (duplicates)',
@@ -4452,6 +4707,26 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
     })
   }
 
+  const representationProblems = codexRepresentationProblems(deps.cwd, deps.env)
+  if (representationProblems.length > 0) {
+    const collapseCommand = representationProblems.some((problem) => problem.includes('--global'))
+      ? 'notifai hooks install --harness codex --global'
+      : 'notifai hooks install --harness codex'
+    checks.push({
+      name: 'hooks (codex representation)',
+      ok: false,
+      detail: representationProblems.join('; '),
+      ...(representationProblems.some((problem) => problem.includes('to collapse onto'))
+        ? {
+            remedy: {
+              summary: 'collapse this Codex layer onto a single hook file',
+              command: collapseCommand,
+            },
+          }
+        : {}),
+    })
+  }
+
   if (active !== null && activeInstallations.length > 0) {
     const admissionProblems = activeQuestionRouteProblems(deps, active, installations)
     checks.push({
@@ -4651,14 +4926,19 @@ function codexStrayWorktreeCheck(
   const layer = codexLayerDir(deps.cwd)
   if (layer === null) return null
   const root = codexProjectRoot(deps.cwd)
-  const stray = path.join(path.dirname(layer), '.codex', 'hooks.json')
-  if (!existsSync(path.join(root, '.codex', 'hooks.json'))) return null
+  const project = inspectCodexLayer(codexLayerPaths(false, deps.cwd, deps.env))
+  if (project.jsonEvents.length === 0 && project.tomlEvents.length === 0) return null
+  const strayJson = path.join(path.dirname(layer), '.codex', 'hooks.json')
+  const strayToml = path.join(path.dirname(layer), '.codex', 'config.toml')
   const problems: string[] = []
   if (!existsSync(layer)) {
     problems.push(`${layer} is missing, so Codex never looks for project hooks here`)
   }
-  if (existsSync(stray)) {
-    problems.push(`${stray} is never read — Codex reads ${root}/.codex/hooks.json instead`)
+  if (existsSync(strayJson) && path.resolve(strayJson) !== path.resolve(project.paths.hooksJson)) {
+    problems.push(`${strayJson} is never read — Codex reads ${project.writeTarget} instead`)
+  }
+  if (existsSync(strayToml) && path.resolve(strayToml) !== path.resolve(project.paths.configToml)) {
+    problems.push(`${strayToml} is never read — Codex reads ${project.writeTarget} instead`)
   }
   return {
     name: 'hooks (codex worktree)',
@@ -4723,6 +5003,17 @@ export function realIo(env: NodeJS.ProcessEnv = process.env): CommandIo {
       const answer = await p.select({ message, options })
       return p.isCancel(answer) ? null : (answer as string)
     },
+    multiselect: async (message, options, initial) => {
+      if (!interactive()) return null
+      const p = await clack()
+      const answer = await p.multiselect({
+        message,
+        options,
+        required: true,
+        ...(initial !== undefined && initial.length > 0 ? { initialValues: initial } : {}),
+      })
+      return p.isCancel(answer) ? null : (answer as string[])
+    },
     intro: async (title) => {
       if (!interactive()) return
       ;(await clack()).intro(title)