@raidiant/notifai 0.1.7 → 0.1.8

package/dist/commands.js

@@ -9,7 +9,7 @@ import { sha256Hex } from '@raidiant/notifai-protocol/node';
 import { ApiCallError, NetworkError, createClient, } from './client.js';
 import { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS, NUMERIC_CONFIG_KEYS, configBounds, findProjectConfigPath, findProjectLocalConfigPath, globalConfigPath, loadConfig, sessionConfigPath, } from './config.js';
 import { firstBlocker, openItems } from './readiness.js';
-import { handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readProjectSession, registerQuestion, } from './hooks.js';
+import { handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readProjectSession, readProjectSessionPointer, readSessionState, registerQuestion, } from './hooks.js';
 import { readIdleSeconds } from './idle.js';
 import { HARNESSES, applyPlan, blockingHookTimeoutSeconds, buildCursorHookConfig, buildHookConfig, codexLayerDir, codexProjectRoot, detectHarness, findInstallations, handlerEvent, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, } from './install-hooks.js';
 import { isOurOpencodePlugin, opencodePluginSource, } from './opencode-plugin.js';
@@ -79,7 +79,7 @@ export async function loginCommand(deps, flags) {
     }
     const interactive = deps.io.interactive === true;
     if (interactive) {
-        await deps.io.intro?.('NotifAI sign in');
+        await deps.io.intro?.('Notifai sign in');
         await deps.io.note?.(`Code: ${begin.code}\n${begin.approve_url}`, 'Approve this machine');
     }
     else {
@@ -93,7 +93,14 @@ export async function loginCommand(deps, flags) {
     const intervalMs = Math.max(begin.poll_interval_seconds, 1) * 1000;
     const now = deps.now ?? Date.now;
     const sleep = deps.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
-    const spinner = interactive ? await deps.io.spinner?.('Waiting for approval…') : null;
+    const approvalWaitMessage = () => {
+        const remainingSec = Math.max(0, Math.ceil((expiresAt - now()) / 1000));
+        const minutes = Math.floor(remainingSec / 60);
+        const seconds = remainingSec % 60;
+        const remaining = minutes > 0 ? `${minutes}m ${seconds.toString().padStart(2, '0')}s` : `${seconds}s`;
+        return `Waiting for approval… code ${begin.code} · ${remaining} left`;
+    };
+    const spinner = interactive ? await deps.io.spinner?.(approvalWaitMessage()) : null;
     while (now() < expiresAt) {
         await sleep(intervalMs);
         let poll;
@@ -102,7 +109,7 @@ export async function loginCommand(deps, flags) {
         }
         catch (err) {
             if (err instanceof NetworkError) {
-                spinner?.message('Connection lost — retrying…');
+                spinner?.message(`Connection lost — retrying… code ${begin.code}`);
                 continue;
             }
             spinner?.error('Pairing failed');
@@ -124,9 +131,18 @@ export async function loginCommand(deps, flags) {
             deps.io.err('Pairing was denied from the dashboard.');
             return EXIT.auth;
         }
+        if (poll.status === 'no_active_plan') {
+            const next = poll.next_action ??
+                `Open ${baseUrl.replace(/\/$/, '')}/support to request Alpha access, then retry.`;
+            spinner?.error('Account has no Alpha access');
+            deps.io.err('This account has no active plan or temporary Alpha access.');
+            deps.io.err(`next: ${next}`);
+            deps.io.err('After access is granted, run `notifai login` again.');
+            return EXIT.auth;
+        }
         if (poll.status === 'expired')
             break;
-        spinner?.message('Waiting for approval…');
+        spinner?.message(approvalWaitMessage());
     }
     spinner?.error('Pairing expired');
     deps.io.err('Pairing expired before it was approved. Run `notifai login` again.');
@@ -160,6 +176,32 @@ export function authStatusCommand(deps, flags) {
     deps.io.out(`Credential store: ${deps.store.describe()}`);
     return EXIT.ok;
 }
+/** Show the server's account access decision without attempting a product mutation. */
+export async function accessStatusCommand(deps, flags) {
+    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const authed = authedClient(deps, config);
+    if (!authed)
+        return EXIT.auth;
+    try {
+        const access = await authed.client.accessStatus();
+        if (flags.json) {
+            deps.io.out(JSON.stringify(access, null, 2));
+            return access.status === 'active' ? EXIT.ok : EXIT.failed;
+        }
+        if (access.status === 'no_active_plan') {
+            const supportUrl = `${authed.baseUrl.replace(/\/$/, '')}/support`;
+            deps.io.out('No active plan or temporary Alpha access for this account.');
+            deps.io.out(`next: Open ${supportUrl} to request Alpha access, then retry.`);
+            return EXIT.failed;
+        }
+        const expiry = access.expires_at ? ` until ${access.expires_at}` : '';
+        deps.io.out(`Access active (${access.reason})${expiry}`);
+        return EXIT.ok;
+    }
+    catch (err) {
+        return reportError(deps, err);
+    }
+}
 // ---------------------------------------------------------------------------
 // devices / capabilities
 // ---------------------------------------------------------------------------
@@ -175,7 +217,15 @@ export async function devicesCommand(deps, flags) {
             return EXIT.ok;
         }
         if (result.devices.length === 0) {
-            deps.io.out('No devices. Install a NotifAI companion app on a device and sign in.');
+            const supportUrl = supportPageUrl(authed.baseUrl);
+            let email = null;
+            try {
+                email = (await authed.client.accessStatus()).email;
+            }
+            catch {
+                // Best-effort: the empty-state copy still points at /support without it.
+            }
+            deps.io.out(`No devices yet. Install Notifai from ${supportUrl}, ${sameAccountSignInLine(email)}, and allow notifications.`);
             return EXIT.ok;
         }
         for (const d of result.devices) {
@@ -215,6 +265,10 @@ export async function sendCommand(deps, flags) {
     const hasReplyChoice = Array.isArray(flags.replyChoice)
         ? flags.replyChoice.length > 0
         : flags.replyChoice !== undefined;
+    if (flags.reply && flags.kind === 'done') {
+        deps.io.err('--kind done cannot be combined with --reply; a reply request is a question.');
+        return EXIT.usage;
+    }
     if (!flags.reply &&
         (flags.replyTimeout !== undefined || flags.replyWindow !== undefined || flags.noBlock || hasReplyChoice)) {
         deps.io.err('Use --reply with --reply-timeout, --reply-window, --reply-choice, or --no-block.');
@@ -281,6 +335,7 @@ export async function sendCommand(deps, flags) {
             deps.io.err(`${issue.path}: ${issue.message}`);
         return EXIT.usage;
     }
+    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.');
@@ -292,10 +347,19 @@ export async function sendCommand(deps, flags) {
         const receiptExit = receiptExitCode(receipt);
         if (!flags.json)
             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(JSON.stringify(flags.reply ? { receipt, replies: [] } : receipt, null, 2));
+                deps.io.out(flags.reply
+                    ? JSON.stringify({
+                        type: 'reply_result',
+                        request_id: receipt.request_id,
+                        replies: [],
+                        degraded: false,
+                    })
+                    : JSON.stringify(receipt, null, 2));
             }
             return receiptExit;
         }
@@ -306,7 +370,12 @@ export async function sendCommand(deps, flags) {
             sleep: deps.sleep,
         });
         if (flags.json) {
-            deps.io.out(JSON.stringify({ receipt, replies: result.response.replies, degraded: result.degraded }, null, 2));
+            deps.io.out(JSON.stringify({
+                type: 'reply_result',
+                request_id: receipt.request_id,
+                replies: result.response.replies,
+                degraded: result.degraded,
+            }));
         }
         else if (result.response.replies.length > 0)
             printReplies(deps, result.response.replies);
@@ -316,13 +385,40 @@ export async function sendCommand(deps, flags) {
             deps.io.err(DEGRADED_WAIT_WARNING);
             return EXIT.network;
         }
+        if (result.timedOut) {
+            deps.io.err(`No reply yet. Retrieve it with \`notifai replies ${receipt.request_id}\` or retire the question with ` +
+                `\`notifai close ${receipt.request_id}\`.`);
+        }
         return result.timedOut ? EXIT.noReply : EXIT.ok;
     }
     catch (err) {
         return reportError(deps, err);
     }
 }
-export async function repliesCommand(deps, requestId, flags) {
+function emitSendWarnings(deps, flags, config) {
+    if (flags.title.length > 40) {
+        deps.io.err(`Heads up: this title is ${flags.title.length} characters; notification titles work best around 40 characters or fewer.`);
+    }
+    if (looksLikeMarkdown(flags.body)) {
+        deps.io.err('Heads up: --body looks like Markdown, but banners show plain text. Put long-form Markdown in --detail or --detail-file.');
+    }
+    const effectiveKind = flags.reply ? 'question' : (flags.kind ?? 'update');
+    if (effectiveKind === 'update' && /^(done|failed)\b/i.test(flags.title.trim())) {
+        deps.io.err(`Heads up: this title announces completion but the notification kind is update. Use --kind done for finished work.`);
+    }
+    if (flags.collapseKey === undefined &&
+        config.collapse_key.value !== null &&
+        config.collapse_key.source.startsWith('global:')) {
+        deps.io.err('Heads up: collapse_key comes from machine-global config, so unrelated notifications may replace each other. Prefer a project or command-specific --collapse-key.');
+    }
+    if (flags.ttl !== undefined && flags.ttl > 259_200) {
+        deps.io.err('Heads up: this explicit --ttl is longer than 72 hours; stale notifications may arrive after they are useful.');
+    }
+}
+function looksLikeMarkdown(value) {
+    return /(?:^|\n)\s{0,3}(?:#{1,6}\s|[-+*]\s|>\s|\d+\.\s|```)|(?:\*\*|__|~~|`)[^\n]+(?:\*\*|__|~~|`)|\[[^\]]+\]\([^)]+\)/m.test(value);
+}
+export async function repliesCommand(deps, requestedId, flags) {
     const waitSeconds = flags.wait ?? 0;
     const afterSeq = flags.after ?? 0;
     if (!isNonNegativeInteger(waitSeconds)) {
@@ -333,6 +429,27 @@ export async function repliesCommand(deps, requestId, flags) {
         deps.io.err('--after must be a non-negative integer sequence number.');
         return EXIT.usage;
     }
+    if (flags.pending === true && requestedId !== undefined) {
+        deps.io.err('Pass a request id or --pending, not both.');
+        return EXIT.usage;
+    }
+    let requestId = requestedId;
+    if (flags.pending === true) {
+        const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)());
+        if (sessionId === null) {
+            deps.io.err('No active session pointer is available in this directory.');
+            return EXIT.noReply;
+        }
+        requestId = readSessionState(sessionId, deps.env).pending?.request_id;
+        if (requestId === undefined) {
+            deps.io.err(`Session ${sessionId} has no pushed question pending.`);
+            return EXIT.noReply;
+        }
+    }
+    if (requestId === undefined) {
+        deps.io.err('Pass a request id or --pending.');
+        return EXIT.usage;
+    }
     const config = loadConfig({ cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed)
@@ -347,8 +464,11 @@ export async function repliesCommand(deps, requestId, flags) {
         if (flags.json) {
             deps.io.out(JSON.stringify({ ...result.response, degraded: result.degraded }, null, 2));
         }
-        else if (result.response.replies.length > 0)
+        else if (result.response.replies.length > 0) {
+            if (flags.pending === true)
+                deps.io.out(`pending request ${requestId}`);
             printReplies(deps, result.response.replies);
+        }
         else
             printNoReply(deps, requestId, result.response.reply_expires_at);
         if (result.degraded) {
@@ -481,11 +601,11 @@ export async function statusCommand(deps, requestId, flags) {
             deps.io.out(`    Provider Acceptance: ${d.state === 'provider_accepted' ? 'accepted' : 'not recorded'}`);
             if (d.companion_receipt.state === 'observed') {
                 const latency = d.companion_receipt.latency_ms;
-                deps.io.out(`    Companion Receipt: observed at ${d.companion_receipt.observed_at}` +
+                deps.io.out(`    Companion Receipt (the app's delivery confirmation): observed at ${d.companion_receipt.observed_at}` +
                     (latency === null ? '' : ` (${formatElapsed(latency)} after Provider Acceptance)`));
             }
             else {
-                deps.io.out('    Companion Receipt: unknown — not observed; this is not a failure or proof of non-receipt');
+                deps.io.out("    Companion Receipt (the app's delivery confirmation): unknown — not observed; this is not a failure or proof of non-receipt");
             }
             for (const e of d.events) {
                 deps.io.out(`      ${e.occurred_at}  ${e.stage}${e.reason ? ` (${e.reason})` : ''}`);
@@ -569,7 +689,19 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
     }
     let envelope;
     try {
-        envelope = parseHookInput(await readStdin());
+        const raw = await readStdin();
+        if (raw.trim() !== '') {
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed !== 'object' || parsed === null)
+                    throw new Error('not an object');
+            }
+            catch {
+                deps.io.err('notifai: ignored malformed or truncated hook input; no routing action was taken');
+                return EXIT.ok;
+            }
+        }
+        envelope = parseHookInput(raw);
         if (harness === 'cursor') {
             const sessionId = envelope.session_id ?? envelope.conversation_id;
             const cwd = envelope.cwd ?? envelope.workspace_roots?.[0];
@@ -602,8 +734,10 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         const cwd = envelope.cwd ?? deps.cwd;
         const config = loadConfig({ cwd, env: deps.env, sessionId: envelope.session_id });
         const credential = deps.store.load();
-        if (!credential)
+        if (!credential) {
+            deps.io.err('notifai: hook skipped: this machine is not paired; run `notifai login`');
             return EXIT.ok;
+        }
         // Pin authenticated traffic to the origin the credential was issued for. A
         // repository can commit `.notifai/config.toml`, and honouring a base_url
         // from it would hand this machine's bearer token to whatever host it names.
@@ -636,6 +770,7 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
                     degraded: result.degraded,
                 };
             },
+            ...(harness === undefined ? {} : { harness }),
         };
         // Real clock, deliberately, not `deps.now`. This compares against file
         // mtimes, which are wall-clock facts — handing it a virtual or skewed clock
@@ -713,17 +848,48 @@ function rejectedPaths(details) {
  * `require_idle = false` intentionally permits a push while the user is active.
  */
 export function askCommand(deps, question, flags) {
-    // An agent calling this gets no hook payload and no harness exports its
-    // session id, so the UserPromptSubmit hook leaves a pointer keyed on the
-    // project directory and we read it back here. The pointer outranks the
+    // An agent calling this gets no hook payload. Harness-native environment
+    // markers identify the active owner, while the UserPromptSubmit hook leaves
+    // a pointer keyed on the project directory with the hook's canonical id.
+    // The pointer outranks the
     // NOTIFAI_SESSION fallback deliberately: the exported id is often a chosen
     // label rather than the harness's own id, and the hooks key state by the
     // latter — the env var is only trusted when no hook has spoken.
     const now = (deps.now ?? Date.now)();
-    const sessionId = flags.session ??
-        readProjectSession(deps.cwd, deps.env, now) ??
-        deps.env['NOTIFAI_SESSION'] ??
-        undefined;
+    const projectPointer = readProjectSessionPointer(deps.cwd, deps.env, now);
+    const pointer = projectPointer?.sessionId ?? null;
+    const active = activeHarnessSession(deps.env);
+    let sessionId;
+    if (flags.session !== undefined) {
+        sessionId = flags.session;
+    }
+    else if (active !== null) {
+        const installations = findInstallations(deps.cwd, deps.env);
+        const activeInstalled = installations.some((installation) => installation.harness === active.harness);
+        if (!activeInstalled) {
+            for (const line of diagnoseActiveHarnessSession(active, 'not-installed', installations)) {
+                deps.io.err(line);
+            }
+            return EXIT.usage;
+        }
+        if (projectPointer === null) {
+            for (const line of diagnoseActiveHarnessSession(active, 'not-fired', installations)) {
+                deps.io.err(line);
+            }
+            return EXIT.usage;
+        }
+        if (projectPointer.harness !== active.harness ||
+            (active.sessionId !== undefined && projectPointer.sessionId !== active.sessionId)) {
+            for (const line of diagnoseActiveHarnessSession(active, 'different-session', installations)) {
+                deps.io.err(line);
+            }
+            return EXIT.usage;
+        }
+        sessionId = projectPointer.sessionId;
+    }
+    else {
+        sessionId = pointer ?? deps.env['NOTIFAI_SESSION'] ?? undefined;
+    }
     if (!sessionId) {
         for (const line of diagnoseMissingSession(deps))
             deps.io.err(line);
@@ -762,6 +928,59 @@ export function askCommand(deps, question, flags) {
     deps.io.out('Question registered. Ask it in the conversation as usual and end your turn.');
     return EXIT.ok;
 }
+function activeHarnessSession(env) {
+    const explicit = env['NOTIFAI_ACTIVE_HARNESS'];
+    if (explicit === 'opencode') {
+        const sessionId = env['NOTIFAI_ACTIVE_SESSION_ID'];
+        return {
+            harness: 'opencode',
+            label: 'OpenCode',
+            ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
+        };
+    }
+    if (env['CLAUDECODE'] === '1') {
+        const sessionId = env['CLAUDE_CODE_SESSION_ID'];
+        return {
+            harness: 'claude-code',
+            label: 'Claude Code',
+            ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
+        };
+    }
+    const codexSession = env['CODEX_THREAD_ID'];
+    if (codexSession !== undefined && codexSession !== '') {
+        return { harness: 'codex', label: 'Codex', sessionId: codexSession };
+    }
+    if ((env['CURSOR_AGENT'] ?? '') !== '')
+        return { harness: 'cursor', label: 'Cursor' };
+    return null;
+}
+function diagnoseActiveHarnessSession(active, problem, installations) {
+    if (problem === 'not-installed') {
+        const others = installations.map((installation) => installation.harness);
+        return [
+            `Could not register the question for the active ${active.label} session: Notifai ${active.label} hooks are not installed for this project.`,
+            ...(others.length === 0
+                ? []
+                : [
+                    `Hooks installed for ${[...new Set(others)].join(', ')} do not route an active ${active.label} session.`,
+                ]),
+            `Run \`notifai hooks install --harness ${active.harness}\`, then send one ${active.label} prompt and run \`notifai doctor\`.`,
+            `Retry \`notifai ask\` only after doctor reports that the ${active.label} hooks fired.`,
+        ];
+    }
+    if (problem === 'different-session') {
+        return [
+            `Could not register the question for the active ${active.label} session: the project pointer belongs to another ${active.label} session or harness.`,
+            `Refusing to guess or cross-wire the question. Send one prompt in this ${active.label} session, then run \`notifai doctor\`.`,
+            `Retry \`notifai ask\` only after doctor reports that this active ${active.label} session fired the hooks.`,
+        ];
+    }
+    return [
+        `Could not register the question for the active ${active.label} session: Notifai hooks are installed, but this session has not published its pointer.`,
+        `Send one ${active.label} prompt, then run \`notifai doctor\`.`,
+        `Retry \`notifai ask\` only after doctor reports that the active ${active.label} session fired the hooks.`,
+    ];
+}
 /**
  * Why `ask` cannot see a session, in terms of what to do about it.
  *
@@ -775,13 +994,13 @@ function diagnoseMissingSession(deps) {
     const installations = findInstallations(deps.cwd, deps.env);
     if (installations.length === 0) {
         return [
-            'Could not tell which harness session this is: no NotifAI hooks are installed for this project.',
+            'Could not tell which harness session this is: no Notifai hooks are installed for this project.',
             'Run `notifai hooks install`, then follow the activation instruction it prints.',
         ];
     }
     const where = installations.map((i) => `${i.harness} in ${i.file}`).join(', ');
     return [
-        `Could not tell which harness session this is. NotifAI hooks are installed (${where}),`,
+        `Could not tell which harness session this is. Notifai hooks are installed (${where}),`,
         'but no usable session pointer from the last 24 hours exists here.',
         hookActivationAdvice(installations),
         'To ask from this session anyway, pass --session <id>.',
@@ -807,7 +1026,7 @@ function hookActivationAdvice(installations) {
         advice.push('Codex: send one prompt, then run `notifai doctor`; start a new session only if it still has not fired');
     }
     if (harnesses.has('opencode')) {
-        advice.push('OpenCode: restart it, then send one prompt; plugins load at startup');
+        advice.push('OpenCode: restart it, then send one prompt; plugins load at startup, and a device answer is delivered on the next prompt');
     }
     return `${advice.join('. ')}.`;
 }
@@ -857,6 +1076,7 @@ export function hooksInstallCommand(deps, flags) {
             scriptPath,
             replyTimeoutSeconds: config.hook_reply_timeout_seconds.value,
             graceSeconds: config.ask_grace_seconds.value,
+            harness: 'cursor',
         }), scriptPath);
         try {
             applyPlan(file, merged.document);
@@ -878,8 +1098,8 @@ export function hooksInstallCommand(deps, flags) {
             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('A companion-device answer is submitted as one');
-        deps.io.out('follow-up user message; loop_limit = 1 prevents repeated answer turns.');
+        deps.io.out('A companion-device answer is submitted as one follow-up user message.');
+        deps.io.out('loop_limit = 3 permits bounded chained questions without an unbounded loop.');
         return EXIT.ok;
     }
     let document;
@@ -895,6 +1115,7 @@ export function hooksInstallCommand(deps, flags) {
         scriptPath,
         replyTimeoutSeconds: config.hook_reply_timeout_seconds.value,
         graceSeconds: config.ask_grace_seconds.value,
+        harness,
     }), scriptPath);
     try {
         applyPlan(file, merged.document);
@@ -917,11 +1138,11 @@ export function hooksInstallCommand(deps, flags) {
             `nothing is pushed. A question registered with \`notifai ask\` stays in the terminal ` +
             `until its ${config.ask_grace_seconds.value}s grace window, counted from registration, ` +
             `has elapsed; it goes to your devices only while the machine also meets the idle threshold. ` +
-            `Set \`require_idle = false\` to be notified even while you are working.`
+            `Run \`notifai config set require_idle false\` to be notified even while you are working.`
         : `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 ` +
-            `(\`require_idle = false\`).`);
+            `(\`notifai config set require_idle false\` is already in effect).`);
     if (config.require_idle.value) {
         deps.io.out('If this OS exposes no keyboard/mouse idle signal, the hook falls back to prompt silence and skips the blocking grace once it decides you are away.');
     }
@@ -957,7 +1178,7 @@ export function hooksInstallCommand(deps, flags) {
     return EXIT.ok;
 }
 /**
- * Writes the OpenCode plugin, replacing any NotifAI plugin already there —
+ * Writes the OpenCode plugin, replacing any Notifai plugin already there —
  * including one a different checkout wrote, matched on the managed marker for
  * the same reason command hooks are.
  */
@@ -965,7 +1186,7 @@ function installOpencodePlugin(deps, file, options) {
     if (existsSync(file)) {
         const existing = readFileSync(file, 'utf8');
         if (!isOurOpencodePlugin(existing)) {
-            deps.io.err(`${file} exists and was not written by NotifAI; move it aside first.`);
+            deps.io.err(`${file} exists and was not written by Notifai; move it aside first.`);
             return EXIT.failed;
         }
     }
@@ -982,8 +1203,9 @@ function installOpencodePlugin(deps, file, options) {
     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 cannot reliably resume an idle agent turn with a device answer; use');
-    deps.io.out('`notifai send --reply` when the answer must return to the agent.');
+    deps.io.out('OpenCode pushes without holding its idle event open; the next user prompt');
+    deps.io.out('collects a device answer and adds it to the agent context. Use `notifai');
+    deps.io.out('send --reply` only when the answer must return before another prompt.');
     deps.io.out('');
     deps.io.out('Restart OpenCode: it loads plugins once at start.');
     return EXIT.ok;
@@ -1001,11 +1223,11 @@ export function hooksUninstallCommand(deps, flags) {
     if (harness === 'opencode') {
         // We own the whole file, but only if we wrote it.
         if (!isOurOpencodePlugin(readFileSync(file, 'utf8'))) {
-            deps.io.out(`Left ${file} alone: NotifAI did not write it.`);
+            deps.io.out(`Left ${file} alone: Notifai did not write it.`);
             return EXIT.ok;
         }
         rmSync(file, { force: true });
-        deps.io.out(`Removed the NotifAI OpenCode plugin at ${file}`);
+        deps.io.out(`Removed the Notifai OpenCode plugin at ${file}`);
         return EXIT.ok;
     }
     if (harness === 'cursor') {
@@ -1026,8 +1248,8 @@ export function hooksUninstallCommand(deps, flags) {
             return EXIT.failed;
         }
         deps.io.out(stripped.replaced.length > 0
-            ? `Removed NotifAI hooks (${stripped.replaced.join(', ')}) from ${file}`
-            : `No NotifAI hooks found in ${file}`);
+            ? `Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${file}`
+            : `No Notifai hooks found in ${file}`);
         return EXIT.ok;
     }
     let document;
@@ -1047,8 +1269,8 @@ export function hooksUninstallCommand(deps, flags) {
         return EXIT.failed;
     }
     deps.io.out(stripped.replaced.length > 0
-        ? `Removed NotifAI hooks (${stripped.replaced.join(', ')}) from ${file}`
-        : `No NotifAI hooks found in ${file}`);
+        ? `Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${file}`
+        : `No Notifai hooks found in ${file}`);
     return EXIT.ok;
 }
 function resolveHarness(deps, requested) {
@@ -1159,27 +1381,59 @@ export async function configSetCommand(deps, key, rawValue, flags) {
  * 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.
  */
-export const SKILLS_SOURCE = 'RafaelVidaurre/notifai#v0.1.7';
-function pinnedSkillInstalled(cwd) {
+export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.1.8';
+function skillSourceParts() {
     const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE);
-    if (!match)
-        return false;
-    const lockPath = path.join(cwd, 'skills-lock.json');
-    const installedPath = path.join(cwd, '.agents', 'skills', 'notifai', 'SKILL.md');
-    if (!existsSync(lockPath) || !existsSync(installedPath))
-        return false;
-    try {
-        const parsed = JSON.parse(readFileSync(lockPath, 'utf8'));
-        const skill = parsed.skills?.notifai;
-        if (!skill)
-            return false;
-        return (skill.source === match[1] &&
-            skill.ref === match[2] &&
-            skill.skillPath === 'skills/notifai/SKILL.md');
-    }
-    catch {
-        return false;
+    return match === null ? null : { source: match[1], ref: match[2] };
+}
+function expectedSkill(skill) {
+    const expected = skillSourceParts();
+    return (expected !== null &&
+        skill.name === 'notifai' &&
+        skill.source === expected.source &&
+        skill.sourceType === 'github' &&
+        skill.ref === expected.ref);
+}
+async function skillReadiness(deps, selectedScope) {
+    const scopes = selectedScope === undefined ? ['project', 'global'] : [selectedScope];
+    const results = await Promise.all(scopes.map(async (scope) => {
+        if (deps.nativeSkills === undefined)
+            return { scope, skills: [] };
+        try {
+            return { scope, ...(await deps.nativeSkills.list(scope, deps.cwd, deps.env)) };
+        }
+        catch (err) {
+            return { scope, skills: [], error: String(err) };
+        }
+    }));
+    const installed = results.flatMap(({ skills }) => skills).find(expectedSkill);
+    if (installed !== undefined) {
+        return {
+            id: 'skill',
+            title: 'Agent guidance skill',
+            status: 'ready',
+            detail: `installed from ${SKILLS_SOURCE} in the ${installed.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',
+        title: 'Agent guidance skill',
+        status: 'optional-gap',
+        detail: errors.length > 0
+            ? `could not verify installer-managed state in ${scopeText} (${errors.join('; ')})`
+            : `not installed from ${SKILLS_SOURCE} in ${scopeText}`,
+        remedy: {
+            by: 'cli',
+            summary: 'install the skill agents follow when deciding to notify',
+            command: selectedScope === undefined
+                ? 'notifai init --skills'
+                : `notifai init --skills --skills-scope ${selectedScope}`,
+        },
+    };
 }
 /** Derive a contract-valid project slug from a directory name. */
 export function projectSlugFrom(name) {
@@ -1190,10 +1444,36 @@ export function projectSlugFrom(name) {
         .slice(0, 64);
     return slug.length > 0 && /^[a-z0-9]/.test(slug) ? slug : 'project';
 }
-const DEVICE_BRIDGE_TIMEOUT_MS = 5 * 60 * 1000;
+/** Long enough for a first TestFlight 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;
 const PROOF_POLL_MS = 1_000;
+function supportPageUrl(baseUrl) {
+    return `${baseUrl.replace(/\/$/, '')}/support`;
+}
+function formatWaitBudget(milliseconds) {
+    const minutes = Math.round(milliseconds / 60_000);
+    return minutes === 1 ? '1 minute' : `${minutes} minutes`;
+}
+/** Same-account line for the device hop; prefers the real email when known. */
+function sameAccountSignInLine(email) {
+    return email
+        ? `sign in with the same email as this account (${email})`
+        : 'sign in with the same email as this account';
+}
+function deviceInstallRemedy(options) {
+    const support = supportPageUrl(options.baseUrl);
+    const sameEmail = sameAccountSignInLine(options.email);
+    if (options.devices.length === 0) {
+        return (`open the install steps at ${support} on that device (or your phone’s browser), ` +
+            `install Notifai, ${sameEmail}, and allow notifications`);
+    }
+    if (options.devices.some((d) => d.permission_status === 'denied')) {
+        return 'allow notifications for Notifai in that device’s system settings';
+    }
+    return 'open Notifai on that device and allow its notification prompt';
+}
 function setupProofPath(deps) {
     let projectDir = path.resolve(deps.cwd);
     try {
@@ -1268,18 +1548,23 @@ async function closeGap(deps, state, flags) {
         return hooksInstallCommand(deps, { harness }) === EXIT.ok ? 'closed' : 'failed';
     }
     if (state.id === 'skill') {
-        deps.io.out(`Installing the notifai agent skill (npx skills add ${SKILLS_SOURCE})...`);
-        const code = await new Promise((resolve) => {
-            const child = spawn('npx', ['-y', 'skills', 'add', SKILLS_SOURCE, '--skill', 'notifai'], {
-                cwd: deps.cwd,
-                stdio: 'inherit',
-            });
-            child.on('error', () => resolve(1));
-            child.on('exit', (exitCode) => resolve(exitCode ?? 1));
-        });
+        if (deps.nativeSkills === undefined) {
+            deps.io.err('Skill installation failed — the native `npx skills` flow is unavailable.');
+            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 = {
+            source: SKILLS_SOURCE,
+            skill: 'notifai',
+            cwd: deps.cwd,
+            env: deps.env,
+            ...(flags.skillsScope === undefined ? {} : { scope: flags.skillsScope }),
+        };
+        const code = await deps.nativeSkills.add(addOptions);
         if (code !== 0) {
             deps.io.err('Skill installation failed — run it manually with:');
-            deps.io.err(`  npx skills add ${SKILLS_SOURCE} --skill notifai`);
+            deps.io.err(`  npx skills add ${SKILLS_SOURCE} --skill notifai${flags.skillsScope === 'global' ? ' --global' : ''}${flags.skillsScope === undefined ? '' : ' --yes'}`);
         }
         return code === 0 ? 'closed' : 'failed';
     }
@@ -1308,56 +1593,90 @@ function deviceBridgeMessage(devices) {
 }
 /**
  * Observe the supported Device Installation path while the user finishes the
- * app-side work. There is deliberately no invented QR or download URL here:
- * this release exposes neither an App Store/TestFlight URL nor a device-pairing
- * endpoint, and a placeholder bridge is worse than an explicit boundary.
+ * 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.
+ *
+ * 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
+ * never hang: this whole path is gated on `io.interactive`, and keep-waiting
+ * uses `confirm` which resolves the safe default when not interactive.
  */
 async function waitForReadyDevice(deps, state) {
     const remedy = state.remedy;
     if (deps.io.interactive !== true || remedy?.by !== 'user-elsewhere')
         return 'pending';
-    await deps.io.note?.(`${state.detail}\n${remedy.summary}`, 'Finish setup on your companion device');
-    if (!(await deps.io.confirm('Wait here while you finish that on your device?', true))) {
-        return 'pending';
-    }
     const config = loadConfig({ cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
-    if (!authed)
+    if (!authed) {
+        deps.io.err('Could not start the companion-device wait: this machine is not signed in.');
         return 'failed';
+    }
+    const budgetLabel = formatWaitBudget(DEVICE_BRIDGE_TIMEOUT_MS);
+    const supportUrl = supportPageUrl(authed.baseUrl);
+    await deps.io.note?.([
+        state.detail,
+        remedy.summary,
+        `Install steps (no typing): ${supportUrl}`,
+        `I will wait up to ${budgetLabel} for a companion device to become ready.`,
+    ].join('\n'), 'Finish setup on your companion device');
+    // Open the real support page so the user never has to type the URL. Decline
+    // is fine — the URL remains in the note and in the Next: line if they leave.
+    if (await deps.io.confirm('Open install instructions in your browser?', true)) {
+        deps.io.openUrl(supportUrl);
+    }
+    if (!(await deps.io.confirm('Wait here while you finish that on your device?', true))) {
+        deps.io.out(`OK — finish device setup when you can (install steps: ${supportUrl}), then re-run \`notifai init\`.`);
+        return 'pending';
+    }
     const now = deps.now ?? Date.now;
-    const sleep = deps.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
-    const deadline = now() + DEVICE_BRIDGE_TIMEOUT_MS;
-    const spinner = await deps.io.spinner?.('Waiting for a companion device…');
+    const sleep = deps.sleep ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const spinner = await deps.io.spinner?.(`Waiting up to ${budgetLabel} for a companion device…`);
     let lastDevices = [];
-    while (now() < deadline) {
-        try {
-            const response = await authed.client.listDevices();
-            lastDevices = response.devices;
-            const ready = response.devices.find(deviceCanReceive);
-            if (ready) {
-                spinner?.stop(`${ready.display_name} is ready to receive`);
-                return 'closed';
+    let deadline = now() + DEVICE_BRIDGE_TIMEOUT_MS;
+    for (;;) {
+        while (now() < deadline) {
+            try {
+                const response = await authed.client.listDevices();
+                lastDevices = response.devices;
+                const ready = response.devices.find(deviceCanReceive);
+                if (ready) {
+                    spinner?.stop(`${ready.display_name} is ready to receive`);
+                    return 'closed';
+                }
+                spinner?.message(deviceBridgeMessage(response.devices));
             }
-            spinner?.message(deviceBridgeMessage(response.devices));
-        }
-        catch (err) {
-            if (!(err instanceof NetworkError)) {
-                spinner?.error('Could not check companion readiness');
-                reportError(deps, err);
-                return 'failed';
+            catch (err) {
+                if (!(err instanceof NetworkError)) {
+                    spinner?.error('Could not check companion readiness');
+                    reportError(deps, err);
+                    return 'failed';
+                }
+                spinner?.message('Connection lost — still watching…');
             }
-            spinner?.message('Connection lost — still watching…');
+            await sleep(Math.min(DEVICE_BRIDGE_POLL_MS, Math.max(0, deadline - now())));
         }
-        await sleep(Math.min(DEVICE_BRIDGE_POLL_MS, Math.max(0, deadline - now())));
+        // Timer expired — setup did not. Offer another budget only when a human
+        // can answer; confirm() already returns the fallback for agents, so this
+        // never hangs unattended even if interactive were mis-set.
+        spinner?.error(`The ${budgetLabel} wait timer expired`);
+        deps.io.err(`The ${budgetLabel} wait timer expired — setup is not finished, only this wait.`);
+        deps.io.err(deviceBridgeMessage(lastDevices).replace(/…$/, '.'));
+        deps.io.err(`Re-run \`notifai init\` later and it will pick up from here (install steps: ${supportUrl}).`);
+        const keepWaiting = await deps.io.confirm(`Keep waiting for another ${budgetLabel}?`, false);
+        if (!keepWaiting) {
+            deps.io.out('Stopping the wait. Device setup can continue; re-run `notifai init` when ready.');
+            return 'pending';
+        }
+        spinner?.message(`Waiting another ${budgetLabel} for a companion device…`);
+        deadline = now() + DEVICE_BRIDGE_TIMEOUT_MS;
     }
-    spinner?.error('No companion device became ready');
-    deps.io.err(deviceBridgeMessage(lastDevices).replace(/…$/, '.'));
-    return 'pending';
 }
 function setupProofDraft(config, device) {
     const project = config.project.value;
     return buildDraft(config, {
-        title: 'NotifAI is ready',
+        title: 'Notifai is ready',
         body: project === null
             ? 'This real notification completed setup verification.'
             : `This real notification completed setup verification for ${project}.`,
@@ -1421,7 +1740,7 @@ async function runSetupProof(deps) {
     const existing = readSetupProof(deps);
     const target = candidates.find((device) => 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. The current macOS notification path does not emit Companion Receipts.');
+        deps.io.err("Setup proof needs a receipt-capable iPhone. The current macOS notification path does not emit Companion Receipts (the app's delivery confirmation).");
         return 'pending';
     }
     let proof = existing?.device_id === target.device_id && existing.project === config.project.value
@@ -1452,7 +1771,7 @@ async function runSetupProof(deps) {
     const sleep = deps.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
     const deadline = now() + PROOF_TIMEOUT_MS;
     const spinner = deps.io.interactive === true
-        ? await deps.io.spinner?.('Waiting for a Companion Receipt…')
+        ? await deps.io.spinner?.("Waiting for a Companion Receipt (the app's delivery confirmation)…")
         : null;
     let lastError = null;
     let replacedMissingProof = false;
@@ -1502,11 +1821,11 @@ async function runSetupProof(deps) {
             break;
         await sleep(Math.min(PROOF_POLL_MS, Math.max(0, deadline - now())));
     }
-    spinner?.error('Companion Receipt not observed yet');
+    spinner?.stop('Delivery confirmation not observed yet');
     if (lastError instanceof NetworkError)
         deps.io.err(lastError.message);
-    deps.io.err(`No Companion Receipt was observed for ${proof.request_id} within ${PROOF_TIMEOUT_MS / 1000}s. ` +
-        'That is not proof of non-receipt; re-run `notifai init` to check this same notification again.');
+    deps.io.out(`Provider accepted the notification; Companion Receipt (the app's delivery confirmation) for ${proof.request_id} was not observed within ${PROOF_TIMEOUT_MS / 1000}s. ` +
+        'Proof may still arrive — re-run `notifai init` and it will re-check this same notification.');
     return 'pending';
 }
 /** Whether an optional gap should be closed, given flags and who is watching. */
@@ -1525,7 +1844,7 @@ function wantsOptional(deps, state, flags) {
         return Promise.resolve(false);
     const question = state.id === 'hooks'
         ? 'Install harness hooks, so questions reach your devices when you are away?'
-        : 'Install/update the agent guidance skill in this repo?';
+        : 'Install/update the agent guidance skill through the native npx skills flow?';
     return deps.io.confirm(question, true);
 }
 /**
@@ -1545,8 +1864,25 @@ function wantsOptional(deps, state, flags) {
  * states rather than four branches to enumerate.
  */
 export async function initCommand(deps, flags) {
-    await deps.io.intro?.('NotifAI setup');
-    let readiness = await assessReadiness(deps);
+    if (flags.skillsScope !== undefined &&
+        flags.skillsScope !== 'project' &&
+        flags.skillsScope !== 'global') {
+        deps.io.err('Invalid skill scope. Choose `project` or `global`.');
+        return EXIT.usage;
+    }
+    if (flags.skillsScope !== undefined && flags.skills !== true) {
+        deps.io.err('`--skills-scope` requires `--skills`. Choose project or global in the native installer.');
+        return EXIT.usage;
+    }
+    if (flags.skills === true &&
+        deps.io.interactive !== true &&
+        flags.skillsScope === undefined) {
+        deps.io.err('Unattended skill setup requires an explicit scope: `notifai init --skills --skills-scope project` or `... global`.');
+        return EXIT.usage;
+    }
+    await deps.io.intro?.('Notifai setup');
+    const reassess = () => assessReadiness(deps, flags.skillsScope === undefined ? {} : { skillScope: flags.skillsScope });
+    let readiness = await reassess();
     let failed = false;
     const attempted = new Set();
     // Re-assess after every successful action. This is how a browser approval or
@@ -1577,11 +1913,16 @@ export async function initCommand(deps, flags) {
                 const result = await closeGap(deps, state, flags);
                 if (result === 'failed')
                     failed = true;
+                if (result === 'failed' && state.status === 'optional-gap') {
+                    readiness = await reassess();
+                    advanced = true;
+                    break;
+                }
                 if (result !== 'closed') {
                     stop = true;
                     break;
                 }
-                readiness = await assessReadiness(deps);
+                readiness = await reassess();
                 advanced = true;
                 break;
             }
@@ -1594,27 +1935,23 @@ export async function initCommand(deps, flags) {
                     stop = true;
                     break;
                 }
-                readiness = await assessReadiness(deps);
+                readiness = await reassess();
                 advanced = true;
                 break;
             }
-            // Its to launch, theirs to complete. Offering to start the sign-in is
-            // useful only when someone is demonstrably watching; an agent never
-            // reaches this prompt or opens a browser.
+            // Its to launch, theirs to complete. Running `init` is the consent; announce
+            // and open rather than re-asking. An agent never reaches this path.
             if (remedy.by === 'user-here' &&
                 remedy.interactive === true &&
                 deps.io.interactive === true) {
                 attempted.add(state.id);
-                if (!(await deps.io.confirm('Sign in now? (opens your browser)', true))) {
-                    stop = true;
-                    break;
-                }
+                deps.io.out('Opening your browser to approve this machine — Ctrl-C to stop.');
                 if ((await loginCommand(deps, {})) !== EXIT.ok) {
                     failed = true;
                     stop = true;
                     break;
                 }
-                readiness = await assessReadiness(deps);
+                readiness = await reassess();
                 advanced = true;
                 break;
             }
@@ -1629,7 +1966,7 @@ export async function initCommand(deps, flags) {
                     stop = true;
                     break;
                 }
-                readiness = await assessReadiness(deps);
+                readiness = await reassess();
                 advanced = true;
                 break;
             }
@@ -1640,13 +1977,13 @@ export async function initCommand(deps, flags) {
         if (stop || !advanced)
             break;
     }
-    readiness = await assessReadiness(deps);
+    readiness = await reassess();
     for (const state of readiness.states.filter((s) => s.status === 'ready')) {
         deps.io.out(`${state.title}: ${state.detail}`);
     }
     const blocker = firstBlocker(readiness);
     if (blocker === null) {
-        const skipped = openItems(readiness);
+        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)}`);
         deps.io.out('All set. Agents in this project can notify you and ask questions.');
@@ -1659,7 +1996,9 @@ export async function initCommand(deps, flags) {
     deps.io.out('');
     deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`);
     deps.io.out(`  ${remedyLine(blocker)}`);
-    if (blocker.remedy?.by === 'user-elsewhere') {
+    // 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)');
@@ -1696,9 +2035,8 @@ async function contractCheck(client) {
             name: 'contract',
             ok: false,
             detail: local !== undefined && remote < local
-                ? `server speaks schema v${remote}, this CLI speaks v${local} — the server needs deploying, ` +
-                    'until then sends carrying newer fields are rejected'
-                : `server speaks schema v${remote}, this CLI speaks v${local} — update the CLI`,
+                ? `server speaks schema v${remote}, this CLI speaks v${local} — the service is being updated; try again later`
+                : `server speaks schema v${remote}, this CLI speaks v${local} — update the CLI: npm install -g @raidiant/notifai`,
         };
     }
     catch (err) {
@@ -1718,7 +2056,7 @@ async function contractCheck(client) {
  * `unknown`, which is the honest answer and keeps a network outage from
  * looking like a broken install.
  */
-export async function assessReadiness(deps) {
+export async function assessReadiness(deps, options = {}) {
     const config = loadConfig({ cwd: deps.cwd, env: deps.env });
     const states = [];
     let accountClient = null;
@@ -1815,56 +2153,37 @@ export async function assessReadiness(deps) {
                 },
             });
     }
+    let accountEmail = null;
+    let accountLookupFailed = false;
     if (!credential || !reachable) {
         const why = !credential ? 'this machine is not paired' : 'the server is unreachable';
         states.push({ id: 'auth', title: 'Account', status: 'unknown', detail: `not checked — ${why}` });
-        states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: `not checked — ${why}` });
     }
     else {
         const client = makeClient(deps, baseUrl, `Bearer nfm_${credential.machineId}.${credential.secret}`);
         accountClient = client;
         try {
-            const { devices } = await client.listDevices();
+            const [{ devices }, email] = await Promise.all([
+                client.listDevices(),
+                Promise.resolve()
+                    .then(async () => (await client.accessStatus()).email)
+                    .catch(() => null),
+            ]);
             accountDevices = devices;
-            const ready = devices.filter(deviceCanReceive);
+            accountEmail = email;
             states.push({
                 id: 'auth',
                 title: 'Account',
                 status: 'ready',
-                detail: `machine ${credential.machineId} accepted`,
+                detail: accountEmail
+                    ? `machine ${credential.machineId} accepted (${accountEmail})`
+                    : `machine ${credential.machineId} accepted`,
             });
-            states.push(ready.length > 0
-                ? {
-                    id: 'devices',
-                    title: 'Your devices',
-                    status: 'ready',
-                    detail: `${ready.map((d) => d.display_name).join(', ')} ready to receive`,
-                }
-                : {
-                    id: 'devices',
-                    title: 'Your devices',
-                    status: 'gap',
-                    // The one gap that cannot be closed from this terminal, and the
-                    // likeliest place a first setup is abandoned. Naming which of
-                    // the three sub-states it is matters: "install the app" is
-                    // useless advice to someone who installed it and denied the
-                    // permission prompt.
-                    detail: devices.length === 0
-                        ? 'nothing registered yet; this release has no supported App Store/TestFlight URL for the CLI to open'
-                        : `${devices.map((d) => `${d.display_name} (${d.permission_status})`).join(', ')} — registered but not able to receive`,
-                    remedy: {
-                        by: 'user-elsewhere',
-                        summary: devices.length === 0
-                            ? 'install NotifAI through a supported distribution you already have, open it, sign in with the same account, and allow notifications'
-                            : devices.some((d) => d.permission_status === 'denied')
-                                ? 'allow notifications for NotifAI in that device’s system settings'
-                                : 'open NotifAI on that device and allow its notification prompt',
-                    },
-                });
         }
         catch (err) {
             // A credential the server rejects is revocation, not absence, and the
             // remedy is the same sign-in either way.
+            accountLookupFailed = true;
             states.push({
                 id: 'auth',
                 title: 'Account',
@@ -1876,28 +2195,53 @@ export async function assessReadiness(deps) {
                     command: 'notifai login',
                 },
             });
-            states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: 'not checked — sign-in failed' });
         }
     }
+    // Optional setup that works without a companion device must appear before the
+    // device gap: init stops at the first user-elsewhere blocker, and hooks/skill
+    // are reachable without a phone.
     states.push(...hookStates(deps));
-    states.push(pinnedSkillInstalled(deps.cwd)
-        ? {
-            id: 'skill',
-            title: 'Agent guidance skill',
-            status: 'ready',
-            detail: `installed from ${SKILLS_SOURCE} in this project`,
-        }
-        : {
-            id: 'skill',
-            title: 'Agent guidance skill',
-            status: 'optional-gap',
-            detail: `not installed from ${SKILLS_SOURCE} in this project`,
-            remedy: {
-                by: 'cli',
-                summary: 'install the skill agents follow when deciding to notify',
-                command: 'notifai init --skills',
-            },
-        });
+    states.push(await skillReadiness(deps, options.skillScope));
+    if (!credential || !reachable) {
+        const why = !credential ? 'this machine is not paired' : 'the server is unreachable';
+        states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: `not checked — ${why}` });
+    }
+    else if (accountLookupFailed || accountDevices === null) {
+        states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: 'not checked — sign-in failed' });
+    }
+    else {
+        const devices = accountDevices;
+        const ready = devices.filter(deviceCanReceive);
+        states.push(ready.length > 0
+            ? {
+                id: 'devices',
+                title: 'Your devices',
+                status: 'ready',
+                detail: `${ready.map((d) => d.display_name).join(', ')} ready to receive`,
+            }
+            : {
+                id: 'devices',
+                title: 'Your devices',
+                status: 'gap',
+                // The one gap that cannot be closed from this terminal, and the
+                // likeliest place a first setup is abandoned. Naming which of
+                // the three sub-states it is matters: "install the app" is
+                // useless advice to someone who installed it and denied the
+                // permission prompt. The live bridge is /support on the
+                // dashboard origin — not a placeholder, and not typed by hand.
+                detail: devices.length === 0
+                    ? `nothing registered yet; install Notifai on iPhone or Mac via ${supportPageUrl(baseUrl)}`
+                    : `${devices.map((d) => `${d.display_name} (${d.permission_status})`).join(', ')} — registered but not able to receive`,
+                remedy: {
+                    by: 'user-elsewhere',
+                    summary: deviceInstallRemedy({
+                        baseUrl,
+                        email: accountEmail,
+                        devices,
+                    }),
+                },
+            });
+    }
     states.push(await setupProofState(deps, config, accountClient, accountDevices));
     return { states };
 }
@@ -1921,14 +2265,17 @@ async function setupProofState(deps, config, client, devices) {
     }
     const ios = readyIosDevices(devices);
     if (ios.length === 0) {
+        // Honest non-blocking caveat: notifications can reach the Mac; only the
+        // receipt proof path is unavailable in this release. Never emit a Next:
+        // step the user cannot satisfy, and never claim unobserved proof.
         return {
             id: 'proof',
             title: 'Delivery proof',
-            status: 'gap',
-            detail: 'blocked — the current macOS notification path does not emit Companion Receipts, so this CLI cannot prove receipt on a macOS-only setup',
+            status: 'optional-gap',
+            detail: "unprovable in this release — notifications can reach your Mac, but the macOS path does not emit Companion Receipts (the app's delivery confirmation); receipt proof needs an iPhone",
             remedy: {
                 by: 'user-elsewhere',
-                summary: 'pair a receipt-capable iPhone build; no supported macOS receipt bridge is available in this release',
+                summary: 'receipt proof needs an iPhone in this release (notifications still reach this Mac)',
             },
         };
     }
@@ -1939,10 +2286,10 @@ async function setupProofState(deps, config, client, devices) {
             id: 'proof',
             title: 'Delivery proof',
             status: 'gap',
-            detail: 'no Companion Receipt has proven this project on this machine yet',
+            detail: "no Companion Receipt (the app's delivery confirmation) has proven this project on this machine yet",
             remedy: {
                 by: 'cli',
-                summary: 'send one real verification notification and wait for its Companion Receipt',
+                summary: "send one real verification notification and wait for its Companion Receipt (the app's delivery confirmation)",
                 command: 'notifai init',
             },
         };
@@ -1955,14 +2302,14 @@ async function setupProofState(deps, config, client, devices) {
                 id: 'proof',
                 title: 'Delivery proof',
                 status: 'ready',
-                detail: `Companion Receipt observed from ${observed.delivery.device_name} at ${observed.observedAt} (${proof.request_id})`,
+                detail: `Companion Receipt (the app's delivery confirmation) observed from ${observed.delivery.device_name} at ${observed.observedAt} (${proof.request_id})`,
             };
         }
         return {
             id: 'proof',
             title: 'Delivery proof',
             status: 'gap',
-            detail: `${proof.request_id} was sent, but its Companion Receipt is still unknown`,
+            detail: `${proof.request_id} was sent, but its Companion Receipt (the app's delivery confirmation) is still unknown`,
             remedy: {
                 by: 'cli',
                 summary: 'check the same verification notification again',
@@ -1989,7 +2336,7 @@ export async function doctorCommand(deps, flags) {
     const blocker = firstBlocker(readiness);
     const ok = blocker === null;
     if (flags.json) {
-        deps.io.out(JSON.stringify({ ok, states: readiness.states }, null, 2));
+        deps.io.out(JSON.stringify({ ok, exit_code: ok ? EXIT.ok : EXIT.failed, states: readiness.states }, null, 2));
         return ok ? EXIT.ok : EXIT.failed;
     }
     const line = (s) => `${s.title}: ${s.detail}`;
@@ -1998,14 +2345,20 @@ export async function doctorCommand(deps, flags) {
     // problems in dependency order has an obvious first move and saying so
     // costs nothing.
     if (deps.io.interactive === true && deps.io.check) {
-        await deps.io.intro?.('NotifAI doctor');
+        await deps.io.intro?.('Notifai doctor');
         for (const s of readiness.states)
             await deps.io.check(s.status !== 'gap', line(s));
         await deps.io.outro?.(ok ? 'Everything looks good' : `Start with: ${remedyLine(blocker)}`);
     }
     else {
         for (const s of readiness.states) {
-            const mark = s.status === 'gap' ? 'FAIL' : s.status === 'unknown' ? '  ? ' : 'ok  ';
+            const mark = s.status === 'gap'
+                ? 'FAIL'
+                : s.status === 'unknown'
+                    ? '  ? '
+                    : s.status === 'optional-gap'
+                        ? '  --'
+                        : 'ok  ';
             deps.io.out(`${mark}  ${line(s)}`);
         }
         if (!ok)
@@ -2049,38 +2402,64 @@ function remedyLine(state) {
  */
 function hookStates(deps) {
     const installations = findInstallations(deps.cwd, deps.env);
+    const active = activeHarnessSession(deps.env);
+    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const settings = {
+        id: 'question-routing-settings',
+        title: 'Question routing settings',
+        status: 'ready',
+        detail: [
+            `ask_notifications=${config.ask_notifications.value} (${config.ask_notifications.source})`,
+            `require_idle=${config.require_idle.value} (${config.require_idle.source})`,
+            `away_after_seconds=${config.away_after_seconds.value} (${config.away_after_seconds.source})`,
+            `ask_grace_seconds=${config.ask_grace_seconds.value} (${config.ask_grace_seconds.source})`,
+            `hook_reply_timeout_seconds=${config.hook_reply_timeout_seconds.value} (${config.hook_reply_timeout_seconds.source})`,
+        ].join(', '),
+    };
     if (installations.length === 0) {
         return [
             {
                 id: 'hooks',
                 title: 'Question routing',
-                status: 'optional-gap',
-                detail: 'hooks not installed, so questions stay in the terminal',
+                status: active === null ? 'optional-gap' : 'gap',
+                detail: active === null
+                    ? 'hooks not installed, so questions stay in the terminal'
+                    : `active ${active.label} session detected, but ${active.label} hooks are not installed; \`notifai ask\` cannot route this session`,
                 remedy: {
                     by: 'cli',
                     summary: 'install harness hooks so questions reach your devices when you are away',
-                    command: 'notifai hooks install',
+                    command: active === null
+                        ? 'notifai hooks install'
+                        : `notifai hooks install --harness ${active.harness}`,
                 },
             },
+            settings,
         ];
     }
     /** Real but not in the way; see the note above. */
-    const informational = new Set(['hooks (fired)', 'hooks (opencode continuation)']);
-    return hookChecks(deps).map((check) => ({
-        id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
-        title: check.name === 'hooks' ? 'Question routing' : check.name,
-        status: check.ok ? 'ready' : informational.has(check.name) ? 'optional-gap' : 'gap',
-        detail: check.detail,
-        ...(check.ok
-            ? {}
-            : {
-                remedy: {
-                    by: 'user-here',
-                    summary: 'the detail above names what to change',
-                    command: 'notifai hooks install',
-                },
-            }),
-    }));
+    const informational = new Set(['hooks (opencode continuation)']);
+    if (active === null)
+        informational.add('hooks (fired)');
+    return [
+        ...hookChecks(deps).map((check) => ({
+            id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
+            title: check.name === 'hooks' || check.name.startsWith('hooks (active')
+                ? 'Question routing'
+                : check.name,
+            status: check.ok ? 'ready' : informational.has(check.name) ? 'optional-gap' : 'gap',
+            detail: check.detail,
+            ...(check.ok
+                ? {}
+                : {
+                    remedy: {
+                        by: 'user-here',
+                        summary: 'the detail above names what to change',
+                        command: 'notifai hooks install',
+                    },
+                }),
+        })),
+        settings,
+    ];
 }
 function hookChecks(deps) {
     const checks = [];
@@ -2102,6 +2481,34 @@ function hookChecks(deps) {
             .map((i) => `${i.harness} ${i.global ? 'global' : 'project'} (${i.file})`)
             .join(', '),
     });
+    const active = activeHarnessSession(deps.env);
+    const activeInstallations = active === null
+        ? []
+        : installations.filter((installation) => installation.harness === active.harness);
+    if (active !== null) {
+        checks.push({
+            name: 'hooks (active harness)',
+            ok: activeInstallations.length > 0,
+            detail: activeInstallations.length > 0
+                ? `active ${active.label} session has a matching hook installation`
+                : `active ${active.label} session has no matching hook installation — run \`notifai hooks install --harness ${active.harness}\``,
+        });
+        if (activeInstallations.length > 0) {
+            const pointer = readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)());
+            const matches = pointer !== null &&
+                pointer.harness === active.harness &&
+                (active.sessionId === undefined || pointer.sessionId === active.sessionId);
+            checks.push({
+                name: 'hooks (active session)',
+                ok: matches,
+                detail: pointer === null
+                    ? `active ${active.label} session has not published a live pointer — send one ${active.label} prompt, then check again`
+                    : matches
+                        ? `the project pointer belongs to the active ${active.label} session`
+                        : `the project pointer belongs to another ${active.label} session or harness; refusing cross-session routing`,
+            });
+        }
+    }
     // A handler naming an event this build dropped exits 2 every time the harness
     // fires it, which the harness reports as a hook failure.
     const stale = installations.flatMap((i) => i.handlers
@@ -2125,6 +2532,19 @@ function hookChecks(deps) {
             detail: adapterProblems.join('; '),
         });
     }
+    const config = loadConfig({ cwd: deps.cwd, env: deps.env });
+    const requiredTimeout = blockingHookTimeoutSeconds(config.ask_grace_seconds.value, config.hook_reply_timeout_seconds.value);
+    const shortTimeouts = installations.flatMap((installation) => installation.handlers
+        .filter((handler) => handlerEvent(handler.command) === 'stop')
+        .filter((handler) => handler.timeout === undefined || handler.timeout < requiredTimeout)
+        .map((handler) => `${installation.harness} declares ${handler.timeout ?? 'no'}s, needs ${requiredTimeout}s — run \`notifai hooks install --harness ${installation.harness}${installation.global ? ' --global' : ''}\``));
+    checks.push({
+        name: 'hooks (timeout)',
+        ok: shortTimeouts.length === 0,
+        detail: shortTimeouts.length === 0
+            ? `installed Stop timeouts cover the current ${requiredTimeout}s grace/reply budget`
+            : shortTimeouts.join('; '),
+    });
     // Two checkouts each installing hooks means both fire for the same event, and
     // the user gets every question twice.
     //
@@ -2144,23 +2564,25 @@ function hookChecks(deps) {
             name: 'hooks (duplicates)',
             ok: false,
             detail: duplicated
-                .map((entry) => `${entry.harness}: ${entry.scripts.size} different NotifAI builds are installed, so each event will fire all of them. Uninstall the ones you do not want: ${[...entry.scripts].join(', ')}`)
+                .map((entry) => `${entry.harness}: ${entry.scripts.size} different Notifai builds are installed, so each event will fire all of them. Uninstall the ones you do not want: ${[...entry.scripts].join(', ')}`)
                 .join('; '),
         });
     }
-    const fired = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)()) !== null;
+    const firedPointer = readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)());
+    const fired = firedPointer !== null;
+    const activationInstallations = active !== null && activeInstallations.length > 0 ? activeInstallations : installations;
     checks.push({
         name: 'hooks (fired)',
         ok: fired,
         detail: fired
             ? 'a session in this directory has run them'
-            : `no session pointer from the last 24 hours — ${hookActivationAdvice(installations)}`,
+            : `no session pointer from the last 24 hours — ${hookActivationAdvice(activationInstallations)}`,
     });
     if (installations.some((installation) => installation.harness === 'opencode')) {
         checks.push({
             name: 'hooks (opencode continuation)',
             ok: false,
-            detail: 'question routing is installed, but OpenCode cannot reliably resume an idle agent turn with the answer; use `notifai send --reply` for decisions',
+            detail: 'question routing is installed; OpenCode cannot resume an idle turn automatically, but its next user prompt collects the answer',
         });
     }
     const stray = codexStrayWorktreeCheck(deps);
@@ -2285,9 +2707,18 @@ export function realIo(env = process.env) {
                 log.error(message);
         },
         openUrl: (url) => {
-            const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
             try {
-                spawn(command, [url], { stdio: 'ignore', detached: true }).unref();
+                if (process.platform === 'darwin') {
+                    spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+                }
+                else if (process.platform === 'win32') {
+                    // `start` is a cmd builtin; spawn('start', …) cannot work on Windows.
+                    // Empty title argument keeps URLs with special characters intact.
+                    spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
+                }
+                else {
+                    spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+                }
             }
             catch {
                 // Browser opening is best-effort; the URL is printed anyway.