@raidiant/notifai 7.0.2 → 8.0.0

package/src/commands-guidance.ts

@@ -0,0 +1,170 @@
+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_TOPIC_MAX_BYTES,
+  GUIDANCE_TOPIC_PATTERN,
+  findProjectGuidanceDir,
+  globalGuidanceDir,
+  personalProjectGuidanceDir,
+  resolveGuidance,
+} from './guidance.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.
+ */
+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,
+        })),
+        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'))
+  return EXIT.ok
+}
+
+type GuidanceMutationFlags = {
+  project?: boolean | undefined
+  local?: boolean | undefined
+  yes?: boolean | undefined
+}
+type GuidanceLayer = 'global' | 'project' | 'local'
+
+/**
+ * Where a topic file for one layer lives. The project layer prefers an
+ * existing `.notifai/guidance` up the tree and otherwise starts one at cwd,
+ * the same anchoring `config set --project` uses for its file.
+ */
+function guidanceLayerDir(deps: CommandDeps, layer: GuidanceLayer): string {
+  if (layer === 'local') return personalProjectGuidanceDir(deps.cwd, deps.env)
+  if (layer === 'project') {
+    return findProjectGuidanceDir(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'guidance')
+  }
+  return globalGuidanceDir(deps.env)
+}
+
+async function guidanceMutationTarget(
+  deps: CommandDeps,
+  topic: string,
+  flags: GuidanceMutationFlags,
+): Promise<string | 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(', ')}.`,
+    )
+    return null
+  }
+  let layer: GuidanceLayer = flags.local ? 'local' : flags.project ? 'project' : 'global'
+  if (
+    flags.local !== true &&
+    flags.project !== true &&
+    flags.yes !== true &&
+    deps.io.interactive === true &&
+    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' },
+    ])
+    if (selected === null) {
+      deps.io.err('No guidance layer selected.')
+      return null
+    }
+    layer = selected as GuidanceLayer
+  }
+  return path.join(guidanceLayerDir(deps, layer), `${topic}.md`)
+}
+
+/**
+ * Writes one topic at one layer, replacing the shipped topic of that name for
+ * this scope. The confirmation gate is the same one `config set` holds: the
+ * user owns their standing word, so an agent writes it only with their words
+ * and their say-so.
+ */
+export async function guidanceSetCommand(
+  deps: CommandDeps,
+  topic: string,
+  text: string,
+  flags: GuidanceMutationFlags,
+): Promise<number> {
+  if (text.trim() === '') {
+    deps.io.err('Guidance text is empty. Pass the text, or --file <path|-> to read it.')
+    return EXIT.usage
+  }
+  if (text.length > GUIDANCE_TOPIC_MAX_BYTES) {
+    deps.io.err(`Guidance for one topic is capped at ${GUIDANCE_TOPIC_MAX_BYTES} bytes.`)
+    return EXIT.usage
+  }
+  const target = await guidanceMutationTarget(deps, topic, flags)
+  if (target === null) return EXIT.usage
+
+  const shipped = shippedGuidanceTopic(topic)
+  if (!flags.yes) {
+    const replaces =
+      shipped === undefined
+        ? `Add guidance topic "${topic}"`
+        : `Replace the shipped "${topic}" guidance for this scope`
+    const confirmed = await deps.io.confirm(`${replaces} at ${target}?`)
+    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}`)
+  if (shipped !== undefined) {
+    deps.io.out(`This file now replaces the shipped "${topic}" guidance wherever it applies.`)
+  }
+  return EXIT.ok
+}
+
+export async function guidanceUnsetCommand(
+  deps: CommandDeps,
+  topic: string,
+  flags: GuidanceMutationFlags,
+): 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}`)
+    return EXIT.ok
+  }
+  if (!flags.yes) {
+    const confirmed = await deps.io.confirm(`Remove ${target}?`)
+    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.`)
+  return EXIT.ok
+}

package/src/commands-hooks.ts

@@ -460,7 +460,13 @@ interface AskFormQuestion {
 
 export interface BuiltQuestions {
   questions: QuestionT[]
-  /** Canonical Markdown body: question block first, optional context second. */
+  /**
+   * Canonical Markdown body. The question already travels as the notification
+   * title and as structured questions, so the body carries only the context —
+   * repeating the question there put it on the lock screen and the reply
+   * screen twice. Only when there is no context does the question text stand
+   * in, because the wire requires a body.
+   */
   body: string
 }
 
@@ -524,14 +530,13 @@ export function buildQuestions(
       questions.push(built.question)
     }
     const context = flags.body ?? (record['body'] as string | undefined)
-    const questionBlock = questions.map((entry, index) => `${index + 1}. ${entry.text}`).join('\n')
     return {
       ok: true,
       questions,
       body:
         context !== undefined && context.trim() !== ''
-          ? `${questionBlock}\n\n${context}`
-          : questionBlock,
+          ? context
+          : questions.map((entry, index) => `${index + 1}. ${entry.text}`).join('\n'),
     }
   }
 
@@ -544,10 +549,7 @@ export function buildQuestions(
   return {
     ok: true,
     questions: [built.question],
-    body:
-      context !== undefined && context.trim() !== ''
-        ? `${built.question.text}\n\n${context}`
-        : built.question.text,
+    body: context !== undefined && context.trim() !== '' ? context : built.question.text,
   }
 }
 

package/src/commands-init.ts

@@ -23,7 +23,7 @@ import {
   reportError,
   type CommandDeps,
 } from './commands-core.js'
-import { readyIosDevices, supportPageUrl } from './commands-devices.js'
+import { readyCompanionDevices, supportPageUrl } from './commands-devices.js'
 import { assessReadiness, remedyLine } from './commands-doctor.js'
 import { hooksInstallCommand, pickHarnessesToInstall } from './commands-hooks.js'
 import { observedCompanionReceipt, readSetupProof, writeSetupProof } from './commands-setup-proof.js'
@@ -55,7 +55,7 @@ export interface InitFlags {
 }
 
 
-/** Long enough for a first TestFlight install; keep-waiting extends another budget. */
+/** Long enough for a first controlled Companion install; keep-waiting extends another budget. */
 const DEVICE_BRIDGE_TIMEOUT_MS = 10 * 60 * 1000
 const DEVICE_BRIDGE_POLL_MS = 2_000
 const PROOF_TIMEOUT_MS = 30_000
@@ -159,20 +159,21 @@ async function closeGap(
 
 function deviceBridgeMessage(devices: readonly RoutableDevice[]): string {
   if (devices.length === 0) {
-    return 'Waiting for the iPhone app to sign in and register…'
+    return 'Waiting for a Companion App to sign in and register…'
   }
   const denied = devices.find((device) => device.permission_status === 'denied')
   if (denied) return `Waiting for notifications to be allowed on ${denied.display_name}…`
   const undecided = devices.find((device) => device.permission_status === 'not_determined')
   if (undecided) return `Waiting for ${undecided.display_name} to allow the notification prompt…`
-  return 'Waiting for an iPhone to become ready…'
+  return 'Waiting for a Companion device to become ready…'
 }
 
 /**
  * Observe the supported Device Installation path while the user finishes the
- * app-side work. The live bridge is the dashboard `/support` page (TestFlight
- * steps). Interactive runs offer to open it so the user never types the URL;
- * non-interactive/agent paths only print plain text and never wait on a prompt.
+ * app-side work. The live bridge is the dashboard `/support` page (controlled
+ * Companion installation steps). Interactive runs offer to open it so the user
+ * never types the URL; non-interactive/agent paths only print plain text and
+ * never wait on a prompt.
  *
  * The wait budget is stated up front. On expiry we say the *timer* expired —
  * not the setup — and offer another budget when a human is present. Agents
@@ -197,9 +198,9 @@ async function waitForReadyDevice(deps: CommandDeps, state: ReadinessState): Pro
       state.detail,
       remedy.summary,
       `Install steps (no typing): ${supportUrl}`,
-      `I will wait up to ${budgetLabel} for your iPhone to become ready.`,
+      `I will wait up to ${budgetLabel} for a Companion device to become ready.`,
     ].join('\n'),
-    'Finish setup on your iPhone',
+    'Finish setup on your Companion device',
   )
 
   // Open the real support page so the user never has to type the URL. Decline
@@ -219,7 +220,9 @@ async function waitForReadyDevice(deps: CommandDeps, state: ReadinessState): Pro
   const sleep =
     deps.sleep ??
     ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)))
-  const spinner = await deps.io.spinner?.(`Waiting up to ${budgetLabel} for your iPhone…`)
+  const spinner = await deps.io.spinner?.(
+    `Waiting up to ${budgetLabel} for a Companion device…`,
+  )
   let lastDevices: RoutableDevice[] = []
   let deadline = now() + DEVICE_BRIDGE_TIMEOUT_MS
 
@@ -227,14 +230,16 @@ async function waitForReadyDevice(deps: CommandDeps, state: ReadinessState): Pro
     while (now() < deadline) {
       try {
         const response = await authed.client.listDevices()
-        const iphoneDevices = response.devices.filter((device) => device.platform === 'ios')
-        lastDevices = iphoneDevices
-        const ready = readyIosDevices(iphoneDevices)[0]
+        const companionDevices = response.devices.filter(
+          (device) => device.platform === 'ios' || device.platform === 'android',
+        )
+        lastDevices = companionDevices
+        const ready = readyCompanionDevices(companionDevices)[0]
         if (ready) {
           spinner?.stop(`${ready.display_name} is ready to receive`)
           return 'closed'
         }
-        spinner?.message(deviceBridgeMessage(iphoneDevices))
+        spinner?.message(deviceBridgeMessage(companionDevices))
       } catch (err) {
         if (!(err instanceof NetworkError)) {
           spinner?.error('Could not check companion readiness')
@@ -263,10 +268,12 @@ async function waitForReadyDevice(deps: CommandDeps, state: ReadinessState): Pro
       false,
     )
     if (!keepWaiting) {
-      deps.io.out('Stopping the wait. iPhone setup can continue; re-run `notifai init` when ready.')
+      deps.io.out(
+        'Stopping the wait. Companion setup can continue; re-run `notifai init` when ready.',
+      )
       return 'pending'
     }
-    spinner?.message(`Waiting another ${budgetLabel} for your iPhone…`)
+    spinner?.message(`Waiting another ${budgetLabel} for a Companion device…`)
     deadline = now() + DEVICE_BRIDGE_TIMEOUT_MS
   }
 }
@@ -284,10 +291,12 @@ function setupProofDraft(
         : `This real notification completed setup verification for ${project}.`,
     event: 'setup_verified',
     kind: 'update',
-    platform: 'ios',
+    platform: device.platform,
     device: [device.device_id],
     sound: 'none',
-    level: 'passive',
+    // Android has no caller-selected interruption level. Explicit null keeps an
+    // Apple preference in config from leaking into this Android-only proof.
+    level: device.platform === 'ios' ? 'passive' : null,
     collapseKey: 'notifai-setup-verification',
   })
 }
@@ -331,8 +340,8 @@ async function submitSetupProof(
 
 /**
  * Send or resume one real setup probe, then wait for a Companion Receipt.
- * Provider Acceptance is intentionally insufficient: it proves APNs accepted
- * the push, not that a companion process received it.
+ * Provider Acceptance is intentionally insufficient: it proves a push provider
+ * accepted the request, not that a companion process received it.
  */
 async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
@@ -346,7 +355,7 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
     reportError(deps, err)
     return 'failed'
   }
-  const candidates = readyIosDevices(devices)
+  const candidates = readyCompanionDevices(devices)
   const existing = readSetupProof(deps)
   const target =
     candidates.find(
@@ -354,7 +363,7 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
         device.device_id === existing?.device_id && existing.project === config.project.value,
     ) ?? candidates[0]
   if (!target) {
-    deps.io.err('Setup proof needs a receipt-capable iPhone.')
+    deps.io.err('Setup proof needs a receipt-capable iPhone or Android Companion App.')
     return 'pending'
   }
 

package/src/commands-send-support.ts

@@ -15,10 +15,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
   ) {

package/src/commands-send.ts

@@ -46,14 +46,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
@@ -75,9 +74,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 +90,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.',
     )
@@ -165,13 +161,16 @@ 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
@@ -220,23 +219,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 +243,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 +272,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 +287,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
@@ -477,9 +470,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 +500,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)