@raidiant/notifai 7.0.2 → 9.0.0

package/src/commands-send-support.ts

@@ -1,8 +1,9 @@
-import { type ListRepliesResponse } from '@raidiant/notifai-protocol'
+import { NOTIFICATION_IMAGE_MAX_BYTES, type ListRepliesResponse } from '@raidiant/notifai-protocol'
 import { sha256Hex } from '@raidiant/notifai-protocol/node'
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { isRetryableReplyPollError, type ApiClient } from './client.js'
+import { fetchMediaUrl } from './url-policy.js'
 import { buildSourceContext, inferInvocationContext } from './invocation-context.js'
 import { readOrcaSessionTitle } from './orca-session-title.js'
 import { type DraftInvocation, type SendFlags } from './send.js'
@@ -15,10 +16,12 @@ function managedSessionTitle(
   active: ActiveHarnessSession | null,
 ): string | undefined {
   if (active?.sessionLabel !== undefined) return active.sessionLabel
+  // The Orca worktree title names the workspace, not one harness: every
+  // harness session Orca starts inside that worktree inherits the same
+  // environment selector, so any active session with an identity to label
+  // may use it. An explicit label still wins without paying for the lookup.
   if (
-    active?.harness !== 'claude-code' ||
-    active.sessionId === undefined ||
-    active.sessionId !== deps.env['CLAUDE_CODE_SESSION_ID'] ||
+    active?.sessionId === undefined ||
     flags.sessionLabel !== undefined ||
     deps.env['NOTIFAI_SESSION_LABEL'] !== undefined
   ) {
@@ -207,17 +210,78 @@ type UploadResult =
   /** `error: null` means `reportError` already said it; do not print it twice. */
   | { ok: false; error: string | null; exit: number }
 
-/** `--image` accepts a media id, a local file path, or an http(s) URL. */
-export async function uploadImage(deps: CommandDeps, client: ApiClient, source: string): Promise<UploadResult> {
+/**
+ * Read a remote image without buffering more than the server will accept.
+ *
+ * Content-Length is an early refusal, not trust: a lying header still hits
+ * the byte cap while the body is read. Supported schemes stay http and https.
+ */
+export async function readCappedBytes(
+  response: Response,
+  maxBytes: number,
+): Promise<Uint8Array | 'too-large'> {
+  const contentLength = Number(response.headers.get('content-length'))
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) return 'too-large'
+  const reader = response.body?.getReader()
+  if (reader === undefined) {
+    const buf = new Uint8Array(await response.arrayBuffer())
+    return buf.byteLength > maxBytes ? 'too-large' : buf
+  }
+  const chunks: Uint8Array[] = []
+  let received = 0
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    received += value.byteLength
+    if (received > maxBytes) {
+      await reader.cancel()
+      return 'too-large'
+    }
+    chunks.push(value)
+  }
+  const out = new Uint8Array(received)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return out
+}
+
+/**
+ * `--image` accepts a media id, a local file path, or an http(s) URL.
+ *
+ * A remote URL is fetched under the media URL policy (`url-policy.ts`):
+ * public HTTPS by default, every redirect hop re-validated, and non-public
+ * destinations only through the User's `media_origins` — never a
+ * repository's. `--image` values routinely arrive from an agent that read
+ * them in a working tree, so the URL is hostile input until proven otherwise.
+ */
+export async function uploadImage(
+  deps: CommandDeps,
+  client: ApiClient,
+  source: string,
+  allowOrigins: readonly string[] = [],
+): Promise<UploadResult> {
   let bytes: Uint8Array
   let mediaType: 'image/jpeg' | 'image/png' | 'image/gif' | undefined
   if (/^https?:\/\//.test(source)) {
     try {
-      const response = await fetch(source)
+      const fetched = await fetchMediaUrl(source, { allowOrigins }, deps.fetchImpl)
+      if (!fetched.ok) return { ok: false, error: fetched.reason, exit: EXIT.usage }
+      const response = fetched.response
       if (!response.ok) return { ok: false, error: `Could not fetch ${source} (${response.status}).`, exit: EXIT.usage }
       const contentType = response.headers.get('content-type')?.split(';')[0]?.trim() ?? ''
       mediaType = (['image/jpeg', 'image/png', 'image/gif'] as const).find((t) => t === contentType)
-      bytes = new Uint8Array(await response.arrayBuffer())
+      const downloaded = await readCappedBytes(response, NOTIFICATION_IMAGE_MAX_BYTES)
+      if (downloaded === 'too-large') {
+        return {
+          ok: false,
+          error: `Remote image exceeds the ${NOTIFICATION_IMAGE_MAX_BYTES} byte media limit.`,
+          exit: EXIT.usage,
+        }
+      }
+      bytes = downloaded
     } catch (err) {
       return { ok: false, error: `Could not fetch ${source}: ${String(err)}`, exit: EXIT.network }
     }

package/src/commands-send.ts

@@ -14,9 +14,11 @@ import {
   buildDraft,
   formatReceipt,
   receiptExitCode,
+  rejectAccidentalEscapedNewlines,
   validateMediaInputs,
   type SendFlags,
 } from './send.js'
+import { recordObservedDeliveryProof } from './commands-setup-proof.js'
 import {
   EXIT,
   authedClient,
@@ -46,14 +48,13 @@ export async function sendCommand(
     wait?: number
     noWait?: boolean
     replyTimeout?: number
-    noBlock?: boolean
     idempotencyKey?: string
     baseUrl?: string
   },
 ): Promise<number> {
-  const hasReplyChoice = Array.isArray(flags.replyChoice)
-    ? flags.replyChoice.length > 0
-    : flags.replyChoice !== undefined
+  const hasChoice = Array.isArray(flags.choice)
+    ? flags.choice.length > 0
+    : flags.choice !== undefined
   if (flags.reply && flags.kind !== undefined && flags.kind !== 'question') {
     deps.io.err(`--kind ${flags.kind} cannot be combined with --reply; a reply request is a question.`)
     return EXIT.usage
@@ -64,7 +65,7 @@ export async function sendCommand(
   if (!flags.reply && flags.kind === undefined) {
     deps.io.err(
       '--kind is required: say what this notification is. ' +
-        'update (news) · done (finished) · failed (terminal failure) · blocked (cannot proceed). ' +
+        'update (news) · done (finished) · failed (terminal failure) · blocked (cannot proceed; no User reply would resume it). ' +
         '--reply makes it a question without --kind.',
     )
     return EXIT.usage
@@ -75,9 +76,9 @@ export async function sendCommand(
   }
   if (
     !flags.reply &&
-    (flags.replyTimeout !== undefined || flags.replyWindow !== undefined || flags.noBlock || hasReplyChoice)
+    (flags.replyTimeout !== undefined || flags.replyWindow !== undefined || hasChoice)
   ) {
-    deps.io.err('Use --reply with --reply-timeout, --reply-window, --reply-choice, or --no-block.')
+    deps.io.err('Use --reply with --reply-timeout, --reply-window, or --choice.')
     return EXIT.usage
   }
   const replyTimeout = flags.replyTimeout ?? 900
@@ -91,13 +92,10 @@ export async function sendCommand(
   // request id. So the user gets a real button, taps it, and nothing happens —
   // worse than a banner that never asked, because it spends their attention
   // and their trust in the channel.
-  //
-  // Both spellings of "do not wait" are rejected, because the defect is the
-  // zero wait and not the flag that produced it.
-  if (flags.reply && (flags.noBlock || replyTimeout === 0)) {
+  if (flags.reply && replyTimeout === 0) {
     deps.io.err(
       'A question needs someone to hear the answer, so --reply cannot be combined ' +
-        'with --no-block or --reply-timeout 0.\n' +
+        'with --reply-timeout 0.\n' +
         'To ask and end the turn, use `notifai ask` — the turn-end hook returns the answer.\n' +
         'To announce finished work, drop --reply and its choices.',
     )
@@ -115,6 +113,11 @@ export async function sendCommand(
     )
     return EXIT.usage
   }
+  const escapedBody = rejectAccidentalEscapedNewlines(flags.body, flags.literalBackslashN)
+  if (escapedBody !== null) {
+    deps.io.err(escapedBody)
+    return EXIT.usage
+  }
   const mediaInputError = validateMediaInputs(flags.image, flags.imageAlt)
   if (mediaInputError !== null) {
     deps.io.err(mediaInputError)
@@ -142,7 +145,7 @@ export async function sendCommand(
       mediaIds.push(image)
       continue
     }
-    const uploaded = await uploadImage(deps, authed.client, image)
+    const uploaded = await uploadImage(deps, authed.client, image, config.media_origins.value)
     if (!uploaded.ok) {
       if (uploaded.error !== null) deps.io.err(uploaded.error)
       return uploaded.exit
@@ -165,17 +168,29 @@ export async function sendCommand(
     for (const issue of validation.errors) deps.io.err(`${issue.path}: ${issue.message}`)
     return EXIT.usage
   }
+  for (const warning of validation.warnings) {
+    deps.io.err(`Heads up (${warning.path}): ${warning.message}`)
+  }
   emitSendWarnings(deps, flags, config)
   if (
     !flags.reply &&
     (flags.title.trim().endsWith('?') || flags.body.trim().endsWith('?'))
   ) {
     deps.io.err(
-      'Heads up: this notification ends with a question but has no reply action. Add --reply (and optionally --reply-choice) so it can be answered from the notification.',
+      'Heads up: this notification ends with a question but has no reply action. Add --reply (and optionally --choice) so it can be answered from the notification.',
     )
   }
   const waitSeconds = flags.noWait ? 0 : config.wait_seconds.value
   const idempotencyKey = flags.idempotencyKey ?? `cli-${randomBytes(12).toString('base64url')}`
+  // Persist the retry identity before entering the ambiguous network boundary.
+  // If the process is killed after the server accepts but before a response,
+  // this is the only durable way to reconstruct the same Agent Event key.
+  log(deps).info('send.attempt', {
+    idempotency_key: idempotencyKey,
+    kind: flags.reply ? 'question' : (flags.kind ?? 'update'),
+    title: flags.title,
+    session_id: source.invocation.source?.session_id ?? null,
+  })
   let receipt: SubmissionReceipt
   try {
     receipt = await authed.client.submit(
@@ -183,7 +198,20 @@ export async function sendCommand(
       waitSeconds,
     )
   } catch (err) {
-    return reportError(deps, err)
+    const exit = reportError(deps, err)
+    if (exit === EXIT.network) {
+      deps.io.err(
+        'The server may have accepted this Notification Request before the connection failed. ' +
+          `Retry the same send with \`--idempotency-key ${idempotencyKey}\` so this Agent Event cannot create a duplicate.`,
+      )
+    }
+    if (err instanceof ApiCallError && err.code === 'no_active_devices') {
+      deps.io.err(
+        'After setup succeeds, repeat this original Notification Request with ' +
+          `\`--idempotency-key ${idempotencyKey}\`; the setup verification request does not replace this Agent Event.`,
+      )
+    }
+    return exit
   }
   const receiptExit = receiptExitCode(receipt)
   // The single most useful line in the log: it ties the local invocation to
@@ -192,7 +220,7 @@ export async function sendCommand(
   log(deps).info('send.submitted', {
     request_id: receipt.request_id,
     kind: flags.reply ? 'question' : (flags.kind ?? 'update'),
-    title: flags.title,
+    title_chars: flags.title.length,
     overall: receipt.overall,
     replayed: receipt.replayed,
     agent_acknowledgement_required: receipt.agent_acknowledgement_required,
@@ -220,23 +248,14 @@ export async function sendCommand(
       receipt.overall === 'provider_accepted_all' &&
       receipt.warnings.length === 0
     if (!quietOrdinarySuccess) deps.io.out(formatReceipt(receipt))
-  } else if (flags.reply) deps.io.out(JSON.stringify({ type: 'receipt', receipt }))
+  }
 
   // A zero wait can no longer reach here: --reply guarantees a positive one.
   if (!flags.reply || receiptExit !== EXIT.ok) {
     if (flags.json) {
       deps.io.out(
         flags.reply
-          ? JSON.stringify({
-              type: 'reply_result',
-              request_id: receipt.request_id,
-              replies: [],
-              agent_acknowledgement_required: receipt.agent_acknowledgement_required,
-              agent_acknowledgement_text_required: receipt.agent_acknowledgement_text_required,
-              agent_acknowledgement: null,
-              acknowledgement_command: null,
-              degraded: false,
-            })
+          ? JSON.stringify(unansweredReplyResultJson(receipt, false))
           : JSON.stringify(receipt, null, 2),
       )
     }
@@ -253,7 +272,7 @@ export async function sendCommand(
     recordReplies(deps, receipt.request_id, result.response.replies)
     if (flags.json) {
       deps.io.out(
-        JSON.stringify(replyResultJson(result.response, result.degraded)),
+        JSON.stringify(replyResultJson(result.response, result.degraded, receipt)),
       )
     } else if (result.response.replies.length > 0) {
       printReplies(deps, result.response.replies)
@@ -282,9 +301,9 @@ export async function sendCommand(
     }
     return result.timedOut ? EXIT.noReply : EXIT.ok
   } catch (err) {
-    // Receipt already printed; a wait fault must not read as "send failed".
-    // Permanent poll errors (auth, closed window, not found) still surface, but
-    // always name the durable request and point at recovery.
+    // The send already succeeded durably; a wait fault must not read as "send
+    // failed". Permanent poll errors (auth, closed window, not found) still
+    // surface, but always name the durable request and point at recovery.
     if (err instanceof ApiCallError || err instanceof NetworkError) {
       log(deps).error('cli.error', {
         kind: err instanceof ApiCallError ? 'api' : 'network',
@@ -297,6 +316,9 @@ export async function sendCommand(
         `notifai: reply wait failed for ${receipt.request_id} (${err instanceof ApiCallError ? err.code : 'network'}: ${err.message}). ` +
           `Delivery and Companion Receipt are independent — check with \`notifai status ${receipt.request_id}\` and retry with \`notifai replies ${receipt.request_id}\`.`,
       )
+      // JSON callers still get their one object: the durable receipt, no
+      // replies, and `degraded: true` — "could not find out", not "no answer".
+      if (flags.json) deps.io.out(JSON.stringify(unansweredReplyResultJson(receipt, true)))
       if (err instanceof ApiCallError) {
         if (err.code === 'auth_required' || err.code === 'machine_revoked') return EXIT.auth
         return err.status >= 500 || err.status === 429 || err.status === 408
@@ -370,19 +392,52 @@ export async function repliesCommand(
     // Every delivered question in the session's queue, in registration order —
     // an agent may have several outstanding at once.
     const state = readSessionState(sessionId, deps.env)
-    requestIds = (Array.isArray(state.pending) ? state.pending : [])
+    const pending = Array.isArray(state.pending) ? state.pending : []
+    requestIds = pending
       .map((entry) => entry.request_id)
       .filter((id): id is string => id !== undefined)
+    const unsent = pending.filter((entry) => entry.request_id === undefined)
     if (requestIds.length === 0) {
       // `--json` is a promise about stdout, and an empty result is still a
       // result: a caller that asked for machine-readable output must not have
       // to parse an English sentence to learn there was nothing pending.
       if (flags.json === true) {
-        deps.io.out(JSON.stringify({ session_id: sessionId, pending: [], replies: [] }, null, 2))
+        deps.io.out(
+          JSON.stringify(
+            {
+              session_id: sessionId,
+              pending: unsent.map((entry) => ({
+                question: entry.question,
+                ...(entry.question_id === undefined ? {} : { question_id: entry.question_id }),
+              })),
+              replies: [],
+            },
+            null,
+            2,
+          ),
+        )
+      } else if (unsent.length > 0) {
+        for (const entry of unsent) {
+          deps.io.out(
+            entry.question_id === undefined
+              ? `unpushed question: ${entry.question}`
+              : `unpushed question ${entry.question_id}: ${entry.question}`,
+          )
+        }
+        deps.io.out('Retire one with `notifai close <question_id>` so a later Stop will not send it.')
       } else {
         deps.io.err(`Session ${sessionId} has no pushed question pending.`)
       }
-      return EXIT.noReply
+      return unsent.length > 0 ? EXIT.ok : EXIT.noReply
+    }
+    if (unsent.length > 0 && flags.json !== true) {
+      for (const entry of unsent) {
+        deps.io.out(
+          entry.question_id === undefined
+            ? `unpushed question: ${entry.question}`
+            : `unpushed question ${entry.question_id}: ${entry.question}`,
+        )
+      }
     }
   }
   if (requestIds.length === 0) {
@@ -477,9 +532,19 @@ function isNonNegativeInteger(value: number): boolean {
 }
 
 
-function replyResultJson(response: ListRepliesResponse, degraded: boolean): object {
+/**
+ * The one JSON object `send --reply --json` prints, whatever happens after the
+ * durable submit. Embedding the receipt keeps stdout a single parseable line;
+ * `replies` (from a wait) omits it because there is no submission to report.
+ */
+function replyResultJson(
+  response: ListRepliesResponse,
+  degraded: boolean,
+  receipt?: SubmissionReceipt,
+): object {
   return {
     type: 'reply_result',
+    ...(receipt !== undefined ? { receipt } : {}),
     request_id: response.request_id,
     reply_expires_at: response.reply_expires_at,
     replies: response.replies,
@@ -497,6 +562,25 @@ function replyResultJson(response: ListRepliesResponse, degraded: boolean): obje
   }
 }
 
+/**
+ * The reply_result for a reply send that has no answer to report — a receipt
+ * failure, or a wait that faulted. Same shape, same single line; `degraded`
+ * distinguishes "the wait could not find out" from "delivery already failed".
+ */
+function unansweredReplyResultJson(receipt: SubmissionReceipt, degraded: boolean): object {
+  return {
+    type: 'reply_result',
+    receipt,
+    request_id: receipt.request_id,
+    replies: [],
+    agent_acknowledgement_required: receipt.agent_acknowledgement_required,
+    agent_acknowledgement_text_required: receipt.agent_acknowledgement_text_required,
+    agent_acknowledgement: null,
+    acknowledgement_command: null,
+    degraded,
+  }
+}
+
 
 function recordReplies(deps: CommandDeps, requestId: string, replies: readonly ReplyView[]): void {
   const logger = log(deps)
@@ -505,8 +589,8 @@ function recordReplies(deps: CommandDeps, requestId: string, replies: readonly R
       request_id: requestId,
       sequence: reply.seq,
       device: reply.device_name,
-      text: reply.text,
-      answers: reply.answers,
+      text_chars: reply.text.length,
+      answers_count: reply.answers?.length ?? 0,
       source: reply.source,
     })
   }
@@ -565,11 +649,12 @@ export async function statusCommand(
   if (!authed) return EXIT.auth
   try {
     const snapshot = await authed.client.evidence(requestId)
+    recordObservedDeliveryProof(deps, snapshot, config.project.value)
     if (flags.json) {
       deps.io.out(JSON.stringify(snapshot, null, 2))
       return EXIT.ok
     }
-    deps.io.out(`request ${snapshot.request_id} (${snapshot.event ?? 'no event'}) — ${snapshot.overall}`)
+    deps.io.out(`request ${snapshot.request_id} — ${snapshot.overall}`)
     let anyReplyReceived = false
     for (const d of snapshot.deliveries) {
       deps.io.out(`  ${d.device_name}:`)

package/src/commands-setup-proof.ts

@@ -66,6 +66,40 @@ export function observedCompanionReceipt(
   deviceId: string,
 ): { delivery: EvidenceSnapshot['deliveries'][number]; observedAt: string } | null {
   const delivery = snapshot.deliveries.find((candidate) => candidate.device_id === deviceId)
-  const receipt = delivery?.events.find((event) => event.stage === 'companion_received')
-  return delivery && receipt ? { delivery, observedAt: receipt.occurred_at } : null
+  if (!delivery) return null
+  if (delivery.companion_receipt.state === 'observed' && delivery.companion_receipt.observed_at) {
+    return { delivery, observedAt: delivery.companion_receipt.observed_at }
+  }
+  const receipt = delivery.events.find((event) => event.stage === 'companion_received')
+  return receipt ? { delivery, observedAt: receipt.occurred_at } : null
+}
+
+/** Replace an unknown setup proof after this age; recent in-flight proofs stay. */
+export const SETUP_PROOF_STALE_MS = 24 * 60 * 60 * 1000
+
+export function setupProofIsStale(proof: SetupProofRecord, now: number): boolean {
+  const started = Date.parse(proof.started_at)
+  return Number.isFinite(started) && now - started > SETUP_PROOF_STALE_MS
+}
+
+/**
+ * Persist ordinary send/status Companion Receipts as the project's delivery
+ * proof so doctor does not demand a second verification request.
+ */
+export function recordObservedDeliveryProof(
+  deps: CommandDeps,
+  snapshot: EvidenceSnapshot,
+  project: string | null,
+): boolean {
+  for (const delivery of snapshot.deliveries) {
+    const observed = observedCompanionReceipt(snapshot, delivery.device_id)
+    if (observed === null) continue
+    return writeSetupProof(deps, {
+      request_id: snapshot.request_id,
+      device_id: delivery.device_id,
+      project,
+      started_at: observed.observedAt,
+    })
+  }
+  return false
 }

package/src/commands-skill.ts

@@ -1,4 +1,4 @@
-import type { NativeSkill, SkillScope } from './native-skills.js'
+import { SKILLS_INSTALLER_SPEC, type NativeSkill, type SkillScope } from './native-skills.js'
 import { type ReadinessState } from './readiness.js'
 import { skillsSource } from './release.js'
 import type { CommandDeps } from './commands-core.js'
@@ -18,6 +18,8 @@ export const SKILLS_SOURCE: string | null = skillsSource()
  */
 const SKILLS_SOURCE_LABEL = SKILLS_SOURCE ?? 'the public release tag matching this CLI'
 
+const SKILL_SCOPES: readonly SkillScope[] = ['project', 'global']
+
 function skillSourceParts(): { source: string; ref: string } | null {
   if (SKILLS_SOURCE === null) return null
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
@@ -35,13 +37,23 @@ function expectedSkill(skill: NativeSkill): boolean {
   )
 }
 
-export async function skillReadiness(
-  deps: CommandDeps,
-  selectedScope?: SkillScope,
-): Promise<ReadinessState> {
-  const scopes: SkillScope[] = selectedScope === undefined ? ['project', 'global'] : [selectedScope]
+function skillPin(skill: NativeSkill): string {
+  return skill.ref ?? 'unknown pin'
+}
+
+export interface ScopedNotifaiSkills {
+  installed: NativeSkill[]
+  errors: string[]
+}
+
+/**
+ * Installer-managed notifai skills in both scopes. Duplicate detection has to
+ * see the pair; a selected-scope filter would hide the copy the harness still
+ * lists.
+ */
+export async function listScopedNotifaiSkills(deps: CommandDeps): Promise<ScopedNotifaiSkills> {
   const results = await Promise.all(
-    scopes.map(async (scope) => {
+    SKILL_SCOPES.map(async (scope) => {
       if (deps.nativeSkills === undefined) return { scope, skills: [] as NativeSkill[] }
       try {
         return { scope, ...(await deps.nativeSkills.list(scope, deps.cwd, deps.env)) }
@@ -50,19 +62,70 @@ export async function skillReadiness(
       }
     }),
   )
-  const installed = results.flatMap(({ skills }) => skills).find(expectedSkill)
-  if (installed !== undefined) {
+  return {
+    installed: results.flatMap(({ skills }) => skills.filter((skill) => skill.name === 'notifai')),
+    errors: results
+      .filter((result) => result.error !== undefined)
+      .map((result) => `${result.scope}: ${result.error}`),
+  }
+}
+
+function duplicateSkillState(installed: NativeSkill[], selectedScope?: SkillScope): ReadinessState {
+  const project = installed.find((skill) => skill.scope === 'project')
+  const global = installed.find((skill) => skill.scope === 'global')
+  const projectPin = project === undefined ? 'not installed' : skillPin(project)
+  const globalPin = global === undefined ? 'not installed' : skillPin(global)
+  return {
+    id: 'skill',
+    title: 'Agent guidance skill',
+    status: 'gap',
+    detail:
+      `project (${projectPin}) and global (${globalPin}) are both installed, so the harness lists both. ` +
+      'Keep either project or global and uninstall the other.',
+    technical: {
+      project:
+        project === undefined
+          ? null
+          : { ref: project.ref, path: project.path, current: expectedSkill(project) },
+      global:
+        global === undefined
+          ? null
+          : { ref: global.ref, path: global.path, current: expectedSkill(global) },
+      resolution: 'both-listed',
+    },
+    remedy:
+      selectedScope === undefined
+        ? {
+            by: 'user-here',
+            summary:
+              'keep either the project or the machine-global skill and uninstall the other; add --global to remove the machine-global copy',
+            command: `npx -y ${SKILLS_INSTALLER_SPEC} remove notifai`,
+          }
+        : {
+            by: 'cli',
+            summary: `keep the ${selectedScope} skill and uninstall the other`,
+            command: `notifai init --skills --setup-scope ${selectedScope}`,
+          },
+  }
+}
+
+export async function skillReadiness(
+  deps: CommandDeps,
+  selectedScope?: SkillScope,
+): Promise<ReadinessState> {
+  const { installed, errors } = await listScopedNotifaiSkills(deps)
+  if (installed.length > 1) return duplicateSkillState(installed, selectedScope)
+
+  const current = installed.find(expectedSkill)
+  if (current !== undefined) {
     return {
       id: 'skill',
       title: 'Agent guidance skill',
       status: 'ready',
-      detail: `installed from ${SKILLS_SOURCE_LABEL} in the ${installed.scope} scope`,
+      detail: `installed from ${SKILLS_SOURCE_LABEL} in the ${current.scope} scope`,
     }
   }
 
-  const errors = results
-    .filter((result) => result.error !== undefined)
-    .map((result) => `${result.scope}: ${result.error}`)
   const scopeText = selectedScope === undefined ? 'project or machine-global scope' : `${selectedScope} scope`
   return {
     id: 'skill',
@@ -77,8 +140,8 @@ export async function skillReadiness(
       summary: 'install the skill agents follow when deciding to notify',
       command:
         selectedScope === undefined
-          ? 'notifai init --skills'
-          : `notifai init --skills --skills-scope ${selectedScope}`,
+          ? 'notifai init --skills --setup-scope project'
+          : `notifai init --skills --setup-scope ${selectedScope}`,
     },
   }
 }