@raidiant/notifai 8.0.0 → 9.1.0

package/src/commands-doctor.ts

@@ -9,7 +9,6 @@ import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js'
 import { inspectHookAdapter } from './hook-adapter.js'
 import {
   readLiveProjectSessionPointers,
-  readMatchingProjectSessionPointer,
   readProjectSessionPointer,
   readSessionState,
 } from './hooks.js'
@@ -33,6 +32,7 @@ import { inferInvocationContext } from './invocation-context.js'
 import type { SkillScope } from './native-skills.js'
 import {
   firstBlocker,
+  readinessJson,
   type Readiness,
   type ReadinessRefresh,
   type ReadinessState,
@@ -40,9 +40,11 @@ import {
 } from './readiness.js'
 import { packageVersion } from './release.js'
 import type { Tone } from './ui/theme.js'
+import type { MachineCredential } from './credentials.js'
 import {
   EXIT,
   UPDATE_CLI_COMMAND,
+  diagnoseIgnoredOriginOverride,
   loadLoggedConfig,
   makeClient,
   resolvedBaseUrl,
@@ -56,8 +58,27 @@ import {
   type ActiveHarnessSession,
 } from './commands-harness-context.js'
 import { stopShapeProblems } from './commands-hook-shape.js'
-import { HOOK_EVENTS, activeQuestionRouteProblems, hookActivationAdvice } from './commands-hooks.js'
-import { observedCompanionReceipt, readSetupProof } from './commands-setup-proof.js'
+import {
+  HOOK_EVENTS,
+  activeQuestionRouteProblems,
+  hookActivationAdvice,
+  requiredHookEvents,
+} from './commands-hooks.js'
+import { cliBinReadiness } from './cli-bin.js'
+import {
+  latestPublishedCliVersion,
+  newerPublishedCli,
+  shouldConsultCliRegistry,
+  thisCliVersion,
+} from './cli-release.js'
+import {
+  SETUP_PROOF_STALE_MS,
+  observedCompanionReceipt,
+  readSetupProof,
+  setupProofProject,
+  setupProofIsStale,
+  setupProofApplies,
+} from './commands-setup-proof.js'
 import { skillReadiness } from './commands-skill.js'
 
 // ---------------------------------------------------------------------------
@@ -236,10 +257,14 @@ function remoteStatesFrom(previous: Readiness): {
   return { credential, server, contract, auth, devices, proof }
 }
 
-function remoteInvalidatedByConfig(previous: Readiness, config: CliConfig): boolean {
-  if (config.base_url.source === 'default') return false
+function remoteInvalidatedByConfig(
+  previous: Readiness,
+  config: CliConfig,
+  credential: MachineCredential | null,
+): boolean {
+  const origin = resolvedBaseUrl(config, credential)
   const server = previous.states.find((state) => state.id === 'server')
-  return server === undefined || !server.detail.includes(config.base_url.value)
+  return server === undefined || !server.detail.includes(origin)
 }
 
 /**
@@ -257,9 +282,12 @@ export async function assessReadiness(
     skillScope?: SkillScope
     previous?: Readiness
     refresh?: readonly ReadinessRefresh[]
+    json?: boolean
   } = {},
 ): Promise<Readiness> {
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const credential = deps.store.load()
+  if (credential) diagnoseIgnoredOriginOverride(deps.io, config, credential)
   const previous = options.previous
   const refresh = options.refresh
   if (previous !== undefined && refresh !== undefined && refresh.length === 0) return previous
@@ -268,12 +296,13 @@ export async function assessReadiness(
     previous !== undefined &&
     refresh !== undefined &&
     !refresh.includes('remote') &&
-    !remoteInvalidatedByConfig(previous, config)
+    !remoteInvalidatedByConfig(previous, config, credential)
   if (reuseRemote) {
     const reused = remoteStatesFrom(previous)
     if (reused !== null) {
       return {
         states: [
+          cliBinReadiness(deps.env, deps.hookPlatform ?? process.platform),
           projectReadiness(deps, config),
           reused.credential,
           reused.server,
@@ -292,9 +321,9 @@ export async function assessReadiness(
   let accountClient: ApiClient | null = null
   let accountDevices: RoutableDevice[] | null = null
 
+  states.push(cliBinReadiness(deps.env, deps.hookPlatform ?? process.platform))
   states.push(projectReadiness(deps, config))
 
-  const credential = deps.store.load()
   states.push(
     credential
       ? {
@@ -457,10 +486,39 @@ export async function assessReadiness(
   }
 
   states.push(await setupProofState(deps, config, accountClient, accountDevices))
+  await applyRegistryRecommendation(deps, options.json === true, states)
 
   return { states }
 }
 
+async function applyRegistryRecommendation(
+  deps: CommandDeps,
+  json: boolean,
+  states: ReadinessState[],
+): Promise<void> {
+  if (
+    !shouldConsultCliRegistry({
+      ...(deps.io.interactive === undefined ? {} : { interactive: deps.io.interactive }),
+      json,
+      env: deps.env,
+    })
+  ) {
+    return
+  }
+  const latest = await latestPublishedCliVersion(deps.fetchImpl)
+  const newer = newerPublishedCli(thisCliVersion(), latest)
+  if (newer === null) return
+  const contract = states.find((state) => state.id === 'contract')
+  if (contract === undefined || contract.status === 'gap') return
+  contract.status = 'optional-gap'
+  contract.detail = 'A newer Notifai is available.'
+  contract.remedy = {
+    by: 'user-here',
+    summary: 'update Notifai',
+    command: UPDATE_CLI_COMMAND,
+  }
+}
+
 async function setupProofState(
   deps: CommandDeps,
   config: CliConfig,
@@ -486,12 +544,10 @@ async function setupProofState(
     }
   }
 
-  const proof = readSetupProof(deps)
-  const target =
-    proof === null
-      ? null
-      : companions.find((device) => device.device_id === proof.device_id)
-  if (proof === null || proof.project !== config.project.value || target === undefined) {
+  const project = setupProofProject(deps, config.project.value)
+  const proof = readSetupProof(deps, project)
+  const applies = setupProofApplies(proof, project, companions.map((device) => device.device_id))
+  if (!applies) {
     return {
       id: 'proof',
       title: 'Delivery proof',
@@ -518,6 +574,20 @@ async function setupProofState(
         detail: `Companion Receipt (the app's delivery confirmation) observed from ${observed.delivery.device_name} at ${observed.observedAt} (${proof.request_id})`,
       }
     }
+    const now = (deps.now ?? Date.now)()
+    if (setupProofIsStale(proof, now)) {
+      return {
+        id: 'proof',
+        title: 'Delivery proof',
+        status: 'gap',
+        detail: `${proof.request_id} is older than ${SETUP_PROOF_STALE_MS / 36e5}h with no Companion Receipt; init will send a replacement`,
+        remedy: {
+          by: 'cli',
+          summary: 'replace the stale verification notification',
+          command: 'notifai init',
+        },
+      }
+    }
     return {
       id: 'proof',
       title: 'Delivery proof',
@@ -549,7 +619,8 @@ export async function doctorCommand(
   flags: { json?: boolean },
   options: { readiness?: Readiness } = {},
 ): Promise<number> {
-  const readiness = options.readiness ?? (await assessReadiness(deps))
+  const readiness =
+    options.readiness ?? (await assessReadiness(deps, flags.json === true ? { json: true } : {}))
   const blocker = firstBlocker(readiness)
   const ok = blocker === null
 
@@ -558,7 +629,7 @@ export async function doctorCommand(
   if (flags.json || deps.io.interactive !== true) {
     deps.io.out(
       JSON.stringify(
-        { ok, exit_code: ok ? EXIT.ok : EXIT.failed, states: readiness.states },
+        { ...readinessJson(readiness), ok, exit_code: ok ? EXIT.ok : EXIT.failed },
         null,
         2,
       ),
@@ -834,17 +905,11 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
           }),
     })
     if (activeInstallations.length > 0) {
-      const pointer =
-        active.sessionId === undefined
-          ? null
-          : readMatchingProjectSessionPointer(
-              deps.cwd,
-              deps.env,
-              (deps.now ?? Date.now)(),
-              active.sessionId,
-              active.harness,
-            )
-      if (pointer === null) {
+      const exactState = active.sessionId === undefined
+        ? null
+        : readSessionState(active.sessionId, deps.env)
+      const activated = exactState?.harness === active.harness && exactState.last_prompt_at !== undefined
+      if (!activated) {
         // The normal condition of hooks installed moments ago: the pointer
         // appears when the harness next fires a hook, and no command can
         // force that. Informational, so `init` walks on to the states it can
@@ -853,7 +918,7 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
           name: 'hooks (active session)',
           ok: false,
           informational: true,
-          detail: `active ${active.label} session has not published a live pointer — send one ${active.label} prompt, then check again`,
+          detail: `active ${active.label} session has not published exact lifecycle state — send one ${active.label} prompt, then check again`,
           remedy: {
             summary: `send one ${active.label} prompt — its hook publishes the routing pointer`,
             command: 'notifai doctor',
@@ -863,7 +928,7 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
         checks.push({
           name: 'hooks (active session)',
           ok: true,
-          detail: `the concurrent project index contains the active ${active.label} session`,
+          detail: `the exact active ${active.label} session has published lifecycle state`,
         })
       }
     }
@@ -879,13 +944,25 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
       })
       .map((h) => `${h.event} -> ${handlerEvent(h.command)} in ${i.file}`),
   )
+  const missing = installations.flatMap((installation) => {
+    const required = requiredHookEvents(installation.harness)
+    const installed = new Set(
+      installation.handlers
+        .map((handler) => handlerEvent(handler.command))
+        .filter((event): event is string => event !== null),
+    )
+    const absent = required.filter((event) => !installed.has(event))
+    return absent.length === 0
+      ? []
+      : [`${installation.file} is missing ${absent.join(', ')}`]
+  })
   checks.push({
     name: 'hooks (stale)',
-    ok: stale.length === 0,
+    ok: stale.length === 0 && missing.length === 0,
     detail:
-      stale.length === 0
-        ? 'every installed handler names an event this build serves'
-        : `${stale.join('; ')} — rerun \`notifai hooks install\` to drop ${stale.length === 1 ? 'it' : 'them'}`,
+      stale.length === 0 && missing.length === 0
+        ? 'every installed handler names an event this build serves, and every required lifecycle handler is present'
+        : `${[...stale, ...missing].join('; ')} — rerun \`notifai hooks install\` to refresh the complete lifecycle set`,
   })
 
   const adapterProblems = installations.flatMap((installation) =>
@@ -940,7 +1017,10 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
   // Project and global definitions for one harness both fire. Stable adapter
   // identity deliberately makes their command bytes equal, so comparing
   // command targets would now hide this duplicate rather than diagnose it.
-  // Different harnesses remain independent: only the active one runs.
+  // Cursor is the exception to harness independence because it may also load
+  // Claude's user hook file. The shared adapter detects Cursor's hook-only
+  // environment and makes that compatibility copy a no-op; the native Cursor
+  // definition remains the single routing owner.
   const duplicated = [...new Set(installations.map((i) => i.harness))]
     .map((harness) => ({
       harness,
@@ -1016,13 +1096,9 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
         ? (readLiveProjectSessionPointers(deps.cwd, deps.env, (deps.now ?? Date.now)()).find(
             (pointer) => pointer.harness === active.harness,
           ) ?? null)
-        : readMatchingProjectSessionPointer(
-            deps.cwd,
-            deps.env,
-            (deps.now ?? Date.now)(),
-            active.sessionId,
-            active.harness,
-          )
+        : readSessionState(active.sessionId, deps.env).harness === active.harness
+          ? { sessionId: active.sessionId, harness: active.harness }
+          : null
   const firedState = firedPointer === null ? null : readSessionState(firedPointer.sessionId, deps.env)
   const promptFired = firedState?.last_prompt_at !== undefined
   const stopFired = firedState?.last_stop_at !== undefined

package/src/commands-guidance.ts

@@ -1,8 +1,7 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
-import { describeSource } from './config-schema.js'
 import { EXIT, type CommandDeps } from './commands-core.js'
-import { SHIPPED_GUIDANCE, shippedGuidanceTopic } from './guidance-content.js'
+import { GUIDANCE_TRUST_PREAMBLE, SHIPPED_GUIDANCE, shippedGuidanceTopic } from './guidance-content.js'
 import {
   GUIDANCE_TOPIC_MAX_BYTES,
   GUIDANCE_TOPIC_PATTERN,
@@ -11,40 +10,43 @@ import {
   personalProjectGuidanceDir,
   resolveGuidance,
 } from './guidance.js'
+import { renderGuidance } from './guidance-render.js'
 
 // ---------------------------------------------------------------------------
 // guidance show / set / unset
 // ---------------------------------------------------------------------------
 
 /**
- * The whole effective guidance, ready to be followed as read. Each topic is
- * printed under a provenance comment so a reader can tell the user's standing
- * word from the shipped default without the output stopping being Markdown.
+ * The whole effective guidance, ready to be followed as read.
+ *
+ * The trust preamble comes first and belongs to the CLI: it says who supplied
+ * each topic and what no topic may ask for. Each topic then follows its own
+ * marker, so a reader can tell the User's standing word from a repository's
+ * house rules from the shipped default without the output stopping being
+ * Markdown.
  */
 export function guidanceShowCommand(deps: CommandDeps, flags: { json?: boolean }): number {
   const topics = resolveGuidance({ cwd: deps.cwd, env: deps.env })
   if (flags.json) {
     deps.io.out(
       JSON.stringify(
-        topics.map((topic) => ({
-          name: topic.name,
-          source: topic.source,
-          summary: topic.summary,
-          content: topic.content,
-        })),
+        {
+          trust: GUIDANCE_TRUST_PREAMBLE,
+          topics: topics.map((topic) => ({
+            name: topic.name,
+            source: topic.source,
+            authority: topic.authority,
+            summary: topic.summary,
+            content: topic.content,
+          })),
+        },
         null,
         2,
       ),
     )
     return EXIT.ok
   }
-  const blocks = topics.map((topic) => {
-    const { label, path: filePath } = describeSource(topic.source)
-    const origin = topic.source === 'default' ? 'shipped default' : label
-    const provenance = filePath === null ? origin : `${origin} · ${filePath}`
-    return `<!-- ${topic.name} · ${provenance} -->\n${topic.content.trimEnd()}`
-  })
-  deps.io.out(blocks.join('\n\n'))
+  deps.io.out(renderGuidance(topics))
   return EXIT.ok
 }
 
@@ -72,7 +74,7 @@ async function guidanceMutationTarget(
   deps: CommandDeps,
   topic: string,
   flags: GuidanceMutationFlags,
-): Promise<string | null> {
+): Promise<{ path: string; layer: GuidanceLayer } | null> {
   if (!GUIDANCE_TOPIC_PATTERN.test(topic)) {
     deps.io.err(
       `"${topic}" is not a topic name. Use lowercase letters, digits, "-" and "_", e.g. ${SHIPPED_GUIDANCE.map((t) => t.name).join(', ')}.`,
@@ -88,9 +90,9 @@ async function guidanceMutationTarget(
     deps.io.select
   ) {
     const selected = await deps.io.select('Where should this guidance live?', [
-      { value: 'global', label: 'This machine', hint: 'applies across projects' },
-      { value: 'project', label: 'This project (shared)', hint: '.notifai/guidance/' },
-      { value: 'local', label: 'This project (personal)', hint: 'stored on this machine, not in the repo' },
+      { value: 'global', label: 'This machine', hint: 'your standing word, applies across projects' },
+      { value: 'project', label: 'This project (shared)', hint: '.notifai/guidance/ — committed, read as project policy' },
+      { value: 'local', label: 'This project (personal)', hint: 'your standing word here, stored outside the repo' },
     ])
     if (selected === null) {
       deps.io.err('No guidance layer selected.')
@@ -98,7 +100,7 @@ async function guidanceMutationTarget(
     }
     layer = selected as GuidanceLayer
   }
-  return path.join(guidanceLayerDir(deps, layer), `${topic}.md`)
+  return { path: path.join(guidanceLayerDir(deps, layer), `${topic}.md`), layer }
 }
 
 /**
@@ -130,19 +132,28 @@ export async function guidanceSetCommand(
       shipped === undefined
         ? `Add guidance topic "${topic}"`
         : `Replace the shipped "${topic}" guidance for this scope`
-    const confirmed = await deps.io.confirm(`${replaces} at ${target}?`)
+    const confirmed = await deps.io.confirm(`${replaces} at ${target.path}?`)
     if (!confirmed) {
       deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.')
       return EXIT.usage
     }
   }
 
-  mkdirSync(path.dirname(target), { recursive: true })
-  writeFileSync(target, text.endsWith('\n') ? text : `${text}\n`)
-  deps.io.out(`Wrote ${topic} to ${target}`)
+  mkdirSync(path.dirname(target.path), { recursive: true })
+  writeFileSync(target.path, text.endsWith('\n') ? text : `${text}\n`)
+  deps.io.out(`Wrote ${topic} to ${target.path}`)
   if (shipped !== undefined) {
     deps.io.out(`This file now replaces the shipped "${topic}" guidance wherever it applies.`)
   }
+  // A shared file is committed and travels to everyone who clones this
+  // repository, where it is read as the project's policy rather than as
+  // anyone's personal standing word. Worth saying at the moment of writing:
+  // the same sentence means something different in the two locations.
+  if (target.layer === 'project') {
+    deps.io.out(
+      'This is shared project policy: it is committed, everyone working here reads it, and it is never read as the User\'s own standing word. Use --local for a personal preference.',
+    )
+  }
   return EXIT.ok
 }
 
@@ -153,18 +164,18 @@ export async function guidanceUnsetCommand(
 ): Promise<number> {
   const target = await guidanceMutationTarget(deps, topic, flags)
   if (target === null) return EXIT.usage
-  if (!existsSync(target)) {
-    deps.io.out(`${topic} is not set at ${target}`)
+  if (!existsSync(target.path)) {
+    deps.io.out(`${topic} is not set at ${target.path}`)
     return EXIT.ok
   }
   if (!flags.yes) {
-    const confirmed = await deps.io.confirm(`Remove ${target}?`)
+    const confirmed = await deps.io.confirm(`Remove ${target.path}?`)
     if (!confirmed) {
       deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.')
       return EXIT.usage
     }
   }
-  rmSync(target, { force: true })
-  deps.io.out(`Removed ${target}; the inherited guidance now applies.`)
+  rmSync(target.path, { force: true })
+  deps.io.out(`Removed ${target.path}; the inherited guidance now applies.`)
   return EXIT.ok
 }

package/src/commands-harness-context.ts

@@ -1,4 +1,4 @@
-import { readLiveProjectSessionPointers } from './hooks.js'
+import { readLiveProjectSessionPointers, readSessionState } from './hooks.js'
 import { type Harness } from './install-hooks.js'
 
 /**
@@ -96,6 +96,29 @@ export function resolveActiveHarness(
   const first = candidates[0]
   if (first === undefined) return { active: null, contested: [] }
   if (candidates.length === 1) return { active: first, contested: [] }
+
+  // Exact lifecycle state is machine-global and survives a command moving to
+  // another linked checkout. Prefer it before the checkout-local compatibility
+  // pointer. A unique newest hook event proves which nested harness owns this
+  // shell; ties and missing evidence remain contested and fail closed.
+  const evidenced = candidates.flatMap((candidate) => {
+    if (candidate.sessionId === undefined) return []
+    const state = readSessionState(candidate.sessionId, env)
+    if (state.harness !== candidate.harness) return []
+    const activity = Math.max(
+      state.last_prompt_at ?? 0,
+      state.last_stop_at ?? 0,
+      state.activation_context_emitted_at ?? 0,
+    )
+    return activity > 0 ? [{ candidate, activity }] : []
+  })
+  if (evidenced.length > 0) {
+    evidenced.sort((left, right) => right.activity - left.activity)
+    if (evidenced.length === 1 || evidenced[0]!.activity > evidenced[1]!.activity) {
+      return { active: evidenced[0]!.candidate, contested: [] }
+    }
+    return { active: first, contested: candidates }
+  }
   for (const pointer of readLiveProjectSessionPointers(cwd, env, now)) {
     const owner = candidates.find(
       (candidate) =>