@raidiant/notifai 10.0.0 → 10.1.1

package/dist/question-settlement-process.js

@@ -0,0 +1,35 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+/** Private handoff from the short prompt hook to its detached question owner. */
+export const QUESTION_SETTLEMENT_INPUT_ENV = 'NOTIFAI_INTERNAL_QUESTION_SETTLEMENT_INPUT';
+/**
+ * Launch the exact installed CLI build as a detached owner.
+ *
+ * UserPromptSubmit sits in front of the User's new turn, so it may only pay the
+ * process-spawn cost. The child owns submission and the complete answer window.
+ */
+export function spawnQuestionSettlement(launch) {
+    const child = spawn(process.execPath, [
+        fileURLToPath(new URL('./main.js', import.meta.url)),
+        'hook',
+        'question-settlement',
+        '--owner',
+        'notifai',
+        '--harness',
+        launch.harness,
+    ], {
+        cwd: launch.envelope.cwd ?? process.cwd(),
+        detached: true,
+        env: {
+            ...process.env,
+            [QUESTION_SETTLEMENT_INPUT_ENV]: JSON.stringify(launch.envelope),
+        },
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    // Spawn failures are diagnosed by the next ordinary lifecycle hook, which
+    // still owns the durable registration. Never turn one into a prompt delay.
+    child.once('error', () => undefined);
+    child.unref();
+}
+//# sourceMappingURL=question-settlement-process.js.map

package/dist/question-settlement-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-settlement-process.js","sourceRoot":"","sources":["../src/question-settlement-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAIxC,iFAAiF;AACjF,MAAM,CAAC,MAAM,6BAA6B,GAAG,4CAA4C,CAAA;AAOzF;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAgC;IACtE,MAAM,KAAK,GAAG,KAAK,CACjB,OAAO,CAAC,QAAQ,EAChB;QACE,aAAa,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpD,MAAM;QACN,qBAAqB;QACrB,SAAS;QACT,SAAS;QACT,WAAW;QACX,MAAM,CAAC,OAAO;KACf,EACD;QACE,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;QACzC,QAAQ,EAAE,IAAI;QACd,GAAG,EAAE;YACH,GAAG,OAAO,CAAC,GAAG;YACd,CAAC,6BAA6B,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC;SACjE;QACD,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,IAAI;KAClB,CACF,CAAA;IACD,0EAA0E;IAC1E,2EAA2E;IAC3E,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACpC,KAAK,CAAC,KAAK,EAAE,CAAA;AACf,CAAC"}

package/dist/readiness.d.ts

@@ -84,12 +84,36 @@ export interface Readiness {
 }
 /** The first thing standing in the way, or null when nothing is. */
 export declare function firstBlocker(readiness: Readiness): ReadinessState | null;
+/**
+ * Question Routing: what lets a question reach a phone when nobody is at the
+ * terminal. Hooks, their sub-states, and the setting that admits them.
+ *
+ * Separate from `isOptionalSetup` because these are also the states a human
+ * should not be handed as leftovers — "Optional, not set up" is a fair line
+ * about the agent skill and a confusing one about a session pointer.
+ */
+export declare function isOptionalAutomation(id: string): boolean;
+/**
+ * Automation layered on top of a product that already sends: Question Routing
+ * and the agent guidance skill.
+ *
+ * Real, and reported. `doctor` is the report and judges it strictly. Anything
+ * whose job is to get a first notification delivered treats it as a line to
+ * print, never a gate — a hook diagnostic or a duplicate skill install in
+ * front of the delivery proof means a setup that can already send never proves
+ * that it can. The one that fires most often, a turn that has not ended yet,
+ * cannot be closed by the agent standing inside that turn at all.
+ */
+export declare function isOptionalSetup(id: string): boolean;
+/** The first thing in the way that is not optional automation. */
+export declare function firstRequiredBlocker(readiness: Readiness): ReadinessState | null;
 /**
  * Ready enough to be useful, which is not the same as every box ticked.
  *
  * Hooks and the agent skill are genuinely optional — `send` works without
  * them — so an install that declined both is finished, not half-done. Saying
- * otherwise trains people to ignore the summary line.
+ * otherwise trains people to ignore the summary line, and it is the summary
+ * line an agent branches on.
  */
 export declare function isReady(readiness: Readiness): boolean;
 /** Baseline Notification Requests can be submitted in the final assessed state. */

package/dist/readiness.js

@@ -23,15 +23,45 @@
 export function firstBlocker(readiness) {
     return readiness.states.find((s) => s.status === 'gap') ?? null;
 }
+/**
+ * Question Routing: what lets a question reach a phone when nobody is at the
+ * terminal. Hooks, their sub-states, and the setting that admits them.
+ *
+ * Separate from `isOptionalSetup` because these are also the states a human
+ * should not be handed as leftovers — "Optional, not set up" is a fair line
+ * about the agent skill and a confusing one about a session pointer.
+ */
+export function isOptionalAutomation(id) {
+    return id === 'hooks' || id.startsWith('hooks-') || id === 'question-routing-settings';
+}
+/**
+ * Automation layered on top of a product that already sends: Question Routing
+ * and the agent guidance skill.
+ *
+ * Real, and reported. `doctor` is the report and judges it strictly. Anything
+ * whose job is to get a first notification delivered treats it as a line to
+ * print, never a gate — a hook diagnostic or a duplicate skill install in
+ * front of the delivery proof means a setup that can already send never proves
+ * that it can. The one that fires most often, a turn that has not ended yet,
+ * cannot be closed by the agent standing inside that turn at all.
+ */
+export function isOptionalSetup(id) {
+    return id === 'skill' || isOptionalAutomation(id);
+}
+/** The first thing in the way that is not optional automation. */
+export function firstRequiredBlocker(readiness) {
+    return readiness.states.find((s) => s.status === 'gap' && !isOptionalSetup(s.id)) ?? null;
+}
 /**
  * Ready enough to be useful, which is not the same as every box ticked.
  *
  * Hooks and the agent skill are genuinely optional — `send` works without
  * them — so an install that declined both is finished, not half-done. Saying
- * otherwise trains people to ignore the summary line.
+ * otherwise trains people to ignore the summary line, and it is the summary
+ * line an agent branches on.
  */
 export function isReady(readiness) {
-    return firstBlocker(readiness) === null;
+    return firstRequiredBlocker(readiness) === null;
 }
 const SEND_PREREQUISITES = new Set([
     'cli-bin',

package/dist/readiness.js.map

@@ -1 +1 @@
-{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"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"}

package/dist/session-activation.js

@@ -17,7 +17,7 @@ export function sessionActivationOutput(harness, hookEventName, cwd = process.cw
     const context = hookEventName === 'SubagentStart'
         ? WORKER_ACTIVATION_CONTEXT
         : rootActivationContext(cwd, env);
-    if (harness === 'opencode')
+    if (harness === 'opencode' || harness === 'openclaw')
         return context;
     if (harness === 'cursor') {
         return JSON.stringify({ additional_context: context });

package/dist/session-activation.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-activation.js","sourceRoot":"","sources":["../src/session-activation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAE3F,MAAM,cAAc,GAClB,sHAAsH;IACtH,iEAAiE,CAAA;AAEnE,MAAM,CAAC,MAAM,yBAAyB,GACpC,6WAA6W,CAAA;AAE/W,MAAM,CAAC,MAAM,kCAAkC,GAC7C,2JAA2J,CAAA;AAE7J,SAAS,qBAAqB,CAAC,GAAW,EAAE,GAAsB;IAChE,MAAM,QAAQ,GAAG,wBAAwB,CAAC;QACxC,GAAG;QACH,GAAG;QACH,QAAQ,EAAE,0BAA0B,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,cAAc,MAAM,EAAE,MAAM,CAAC;KAC1F,CAAC,CAAA;IACF,OAAO,GAAG,cAAc,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAA;AACrF,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,uBAAuB,CACrC,OAAgC,EAChC,aAA+C,EAC/C,MAAc,OAAO,CAAC,GAAG,EAAE,EAC3B,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,OAAO,GAAG,aAAa,KAAK,eAAe;QAC/C,CAAC,CAAC,yBAAyB;QAC3B,CAAC,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACnC,IAAI,OAAO,KAAK,UAAU;QAAE,OAAO,OAAO,CAAA;IAC1C,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAA;IACxD,CAAC;IACD,IAAI,OAAO,KAAK,aAAa,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACrD,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,kBAAkB,EAAE;gBAClB,aAAa;gBACb,iBAAiB,EAAE,OAAO;aAC3B;SACF,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAc,OAAO,CAAC,GAAG,EAAE,EAC3B,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,gBAAgB,EAAE,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC;KAClD,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"session-activation.js","sourceRoot":"","sources":["../src/session-activation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AAE3F,MAAM,cAAc,GAClB,sHAAsH;IACtH,iEAAiE,CAAA;AAEnE,MAAM,CAAC,MAAM,yBAAyB,GACpC,6WAA6W,CAAA;AAE/W,MAAM,CAAC,MAAM,kCAAkC,GAC7C,2JAA2J,CAAA;AAE7J,SAAS,qBAAqB,CAAC,GAAW,EAAE,GAAsB;IAChE,MAAM,QAAQ,GAAG,wBAAwB,CAAC;QACxC,GAAG;QACH,GAAG;QACH,QAAQ,EAAE,0BAA0B,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,cAAc,MAAM,EAAE,MAAM,CAAC;KAC1F,CAAC,CAAA;IACF,OAAO,GAAG,cAAc,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAA;AACrF,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,uBAAuB,CACrC,OAAgC,EAChC,aAA+C,EAC/C,MAAc,OAAO,CAAC,GAAG,EAAE,EAC3B,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,OAAO,GAAG,aAAa,KAAK,eAAe;QAC/C,CAAC,CAAC,yBAAyB;QAC3B,CAAC,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACnC,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,UAAU;QAAE,OAAO,OAAO,CAAA;IACpE,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAA;IACxD,CAAC;IACD,IAAI,OAAO,KAAK,aAAa,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACrD,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,kBAAkB,EAAE;gBAClB,aAAa;gBACb,iBAAiB,EAAE,OAAO;aAC3B;SACF,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAc,OAAO,CAAC,GAAG,EAAE,EAC3B,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,gBAAgB,EAAE,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC;KAClD,CAAC,CAAA;AACJ,CAAC"}

package/dist/setup-destinations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where a cross-surface setup errand is finished.
+ *
+ * Every handoff opens the destination for exactly one errand, carrying the
+ * platform when this terminal already asked for it. The omnibus help page is
+ * help: it covers access, two install routes, billing, refunds, deletion,
+ * privacy and terms, and its own next step is to go somewhere else. Sending
+ * someone there for a named gate makes them find it themselves.
+ *
+ * The server prints these same paths into `next_action`, which is the value
+ * this CLI prefers whenever it has one. These builders are the fallback for
+ * the paths where it does not, and they must stay spelled the same.
+ */
+/** The two platforms that can receive a notification. Mac is not one. */
+export declare const COMPANION_PLATFORMS: readonly ["iphone", "android"];
+export type CompanionPlatform = (typeof COMPANION_PLATFORMS)[number];
+export declare function companionPlatformLabel(platform: CompanionPlatform): string;
+/** Getting this Account access to Notifai, and nothing else. */
+export declare function setupAccessUrl(baseUrl: string, platform?: CompanionPlatform): string;
+/** Installing the Companion App on one named platform. */
+export declare function setupCompanionUrl(baseUrl: string, platform?: CompanionPlatform): string;
+/** General help: billing, policies, and everything setup is not. */
+export declare function supportPageUrl(baseUrl: string): string;

package/dist/setup-destinations.js

@@ -0,0 +1,44 @@
+/**
+ * Where a cross-surface setup errand is finished.
+ *
+ * Every handoff opens the destination for exactly one errand, carrying the
+ * platform when this terminal already asked for it. The omnibus help page is
+ * help: it covers access, two install routes, billing, refunds, deletion,
+ * privacy and terms, and its own next step is to go somewhere else. Sending
+ * someone there for a named gate makes them find it themselves.
+ *
+ * The server prints these same paths into `next_action`, which is the value
+ * this CLI prefers whenever it has one. These builders are the fallback for
+ * the paths where it does not, and they must stay spelled the same.
+ */
+/** The two platforms that can receive a notification. Mac is not one. */
+export const COMPANION_PLATFORMS = ['iphone', 'android'];
+export function companionPlatformLabel(platform) {
+    return platform === 'iphone' ? 'iPhone' : 'Android';
+}
+/**
+ * The dashboard a reader can sign in to, which is not always the API origin.
+ * Only the hosted deployment splits them; a self-host serves both from one.
+ */
+function dashboardOrigin(baseUrl) {
+    const normalized = baseUrl.replace(/\/+$/, '');
+    if (normalized === 'https://api.notifai.sh' || normalized === 'https://notifai.fly.dev') {
+        return 'https://app.notifai.sh';
+    }
+    return normalized;
+}
+/** Getting this Account access to Notifai, and nothing else. */
+export function setupAccessUrl(baseUrl, platform) {
+    const base = `${dashboardOrigin(baseUrl)}/setup/access`;
+    return platform === undefined ? base : `${base}?platform=${platform}`;
+}
+/** Installing the Companion App on one named platform. */
+export function setupCompanionUrl(baseUrl, platform) {
+    const base = `${dashboardOrigin(baseUrl)}/setup/companion`;
+    return platform === undefined ? base : `${base}?platform=${platform}`;
+}
+/** General help: billing, policies, and everything setup is not. */
+export function supportPageUrl(baseUrl) {
+    return `${dashboardOrigin(baseUrl)}/support`;
+}
+//# sourceMappingURL=setup-destinations.js.map

package/dist/setup-destinations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-destinations.js","sourceRoot":"","sources":["../src/setup-destinations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAU,CAAA;AAGjE,MAAM,UAAU,sBAAsB,CAAC,QAA2B;IAChE,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAA;AACrD,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,OAAe;IACtC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC9C,IAAI,UAAU,KAAK,wBAAwB,IAAI,UAAU,KAAK,yBAAyB,EAAE,CAAC;QACxF,OAAO,wBAAwB,CAAA;IACjC,CAAC;IACD,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,QAA4B;IAC1E,MAAM,IAAI,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,eAAe,CAAA;IACvD,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,aAAa,QAAQ,EAAE,CAAA;AACvE,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,QAA4B;IAC7E,MAAM,IAAI,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,kBAAkB,CAAA;IAC1D,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,aAAa,QAAQ,EAAE,CAAA;AACvE,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,UAAU,CAAA;AAC9C,CAAC"}

package/dist/ui/help.d.ts

@@ -1,8 +1,8 @@
 /**
  * Help that answers "what can I do here", not "what strings does argv accept".
  *
- * The old help listed seventeen commands in one flat column, with the two a new
- * user needs (`init`, `login`) sitting between a platform capability dump and
+ * The old help listed seventeen commands in one flat column, with the one a new
+ * user needs (`init`) sitting between a platform capability dump and
  * an entry point marked "Internal:". Everything was equally prominent, which is
  * the same as nothing being prominent.
  *
@@ -38,8 +38,7 @@ export declare const helpConfiguration: HelpConfiguration;
 /**
  * Footer for the root help.
  *
- * Its whole job is to make the interactive app discoverable, because someone
- * reading a wall of flags has already demonstrated they did not know it was
- * there.
+ * First-run is `notifai init`. The interactive app is what a human opens
+ * later, once setup is no longer the thing in the way.
  */
 export declare function rootHelpFooter(): string;

package/dist/ui/help.js

@@ -1,8 +1,8 @@
 /**
  * Help that answers "what can I do here", not "what strings does argv accept".
  *
- * The old help listed seventeen commands in one flat column, with the two a new
- * user needs (`init`, `login`) sitting between a platform capability dump and
+ * The old help listed seventeen commands in one flat column, with the one a new
+ * user needs (`init`) sitting between a platform capability dump and
  * an entry point marked "Internal:". Everything was equally prominent, which is
  * the same as nothing being prominent.
  *
@@ -84,16 +84,15 @@ export const helpConfiguration = {
 /**
  * Footer for the root help.
  *
- * Its whole job is to make the interactive app discoverable, because someone
- * reading a wall of flags has already demonstrated they did not know it was
- * there.
+ * First-run is `notifai init`. The interactive app is what a human opens
+ * later, once setup is no longer the thing in the way.
  */
 export function rootHelpFooter() {
     const lines = [
         '',
         style.heading('Start here'),
-        `  ${style.code('notifai')}              ${style.dim(`${glyph.arrow} the interactive app: status, settings, devices, test sends`)}`,
         `  ${style.code('notifai init')}         ${style.dim(`${glyph.arrow} set this project up, step by step`)}`,
+        `  ${style.code('notifai')}              ${style.dim(`${glyph.arrow} after setup: status, settings, devices, test sends`)}`,
         '',
         style.heading('First call, for an agent'),
         `  ${style.code('notifai send --kind done --title "All 42 tests passed" --body "Finished in 3m 10s. Next: review the release candidate."')}`,

package/dist/ui/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/ui/help.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/ui/help.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "10.0.0",
+  "version": "10.1.1",
   "type": "module",
   "description": "Send native device notifications from agents and local programs",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "6.0.0",
+    "@raidiant/notifai-protocol": "6.0.2",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"

package/src/cli-bin.test.ts

@@ -1,10 +1,60 @@
-import { chmodSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { cliBinReadiness, isExecutablePath, pathNotifaiEntries } from './cli-bin.js'
+import { cliUpdateRecoveryCommand } from './cli-update-contract.js'
 
 describe('PATH notifai diagnosis', () => {
+  function posixInstall(root: string, name: string, version: string) {
+    const prefix = path.join(root, name)
+    const artifact = path.join(
+      prefix,
+      'lib',
+      'node_modules',
+      '@raidiant',
+      'notifai',
+      'dist',
+      'main.js',
+    )
+    const command = path.join(prefix, 'bin', 'notifai')
+    mkdirSync(path.dirname(artifact), { recursive: true })
+    mkdirSync(path.dirname(command), { recursive: true })
+    writeFileSync(path.join(path.dirname(path.dirname(artifact)), 'package.json'), JSON.stringify({ version }))
+    writeFileSync(artifact, '#!/usr/bin/env node\n')
+    chmodSync(artifact, 0o755)
+    symlinkSync(path.relative(path.dirname(command), artifact), command)
+    return { prefix, artifact, command }
+  }
+
+  function windowsInstall(root: string, name: string, version: string) {
+    const prefix = path.join(root, name)
+    const artifact = path.join(
+      prefix,
+      'node_modules',
+      '@raidiant',
+      'notifai',
+      'dist',
+      'main.js',
+    )
+    const command = path.join(prefix, 'notifai.cmd')
+    mkdirSync(path.dirname(artifact), { recursive: true })
+    writeFileSync(path.join(path.dirname(path.dirname(artifact)), 'package.json'), JSON.stringify({ version }))
+    writeFileSync(artifact, '#!/usr/bin/env node\n')
+    writeFileSync(
+      command,
+      '@ECHO off\r\nnode "%dp0%node_modules\\@raidiant\\notifai\\dist\\main.js" %*\r\n',
+    )
+    return { prefix, artifact, command }
+  }
+
   it('reports a non-executable PATH binary as a gap', () => {
     if (process.platform === 'win32') return
     const directory = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-gap-'))
@@ -14,8 +64,10 @@ describe('PATH notifai diagnosis', () => {
     expect(isExecutablePath(file, 'darwin')).toBe(false)
     const state = cliBinReadiness({ PATH: directory }, 'darwin')
     expect(state.status).toBe('gap')
-    expect(state.detail).toContain(file)
-    expect(state.remedy?.command).toBe('npm install -g @raidiant/notifai')
+    expect(state.detail).not.toContain(file)
+    expect(state.technical).toMatchObject({ entries: [{ command_path: file, executable: false }] })
+    expect(state.remedy?.command).not.toBe('notifai update')
+    expect(state.remedy?.command).toMatch(/ update$/)
   })
 
   it('treats an executable PATH binary as ready', () => {
@@ -25,14 +77,100 @@ describe('PATH notifai diagnosis', () => {
     writeFileSync(file, '#!/usr/bin/env node\n')
     chmodSync(file, 0o755)
     expect(pathNotifaiEntries({ PATH: directory }, 'darwin')).toEqual([file])
-    expect(cliBinReadiness({ PATH: directory }, 'darwin').status).toBe('ready')
+    expect(
+      cliBinReadiness({ PATH: directory }, 'darwin', {
+        runningArtifactPath: file,
+        currentVersion: null,
+      }).status,
+    ).toBe('ready')
+  })
+
+  it('does not call an older executable PATH winner ready when this process is the current CLI', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-stale-winner-'))
+    const old = posixInstall(root, 'old', '3.0.1')
+    const current = posixInstall(root, 'current', '10.1.0')
+
+    const state = cliBinReadiness(
+      { PATH: `${path.dirname(old.command)}:${path.dirname(current.command)}` },
+      'darwin',
+      {
+        runningArtifactPath: current.artifact,
+        currentVersion: '10.1.0',
+      },
+    )
+
+    expect(state.status).toBe('gap')
+    expect(state.detail).not.toContain(old.command)
+    expect(state.remedy?.command).toBe(
+      cliUpdateRecoveryCommand(),
+    )
+    expect(state.remedy?.command).not.toContain(old.command)
+    expect(state.technical).toMatchObject({
+      current: { artifact_path: realpathSync(current.artifact), version: '10.1.0' },
+      effective: { command_path: old.command, artifact_path: realpathSync(old.artifact), version: '3.0.1' },
+    })
+  })
+
+  it('uses Windows Path order to reject an older executable winner', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-windows-winner-'))
+    const old = windowsInstall(root, 'old', '3.0.1')
+    const current = windowsInstall(root, 'current', '10.1.0')
+
+    const state = cliBinReadiness(
+      { Path: `${old.prefix};${current.prefix}` },
+      'win32',
+      {
+        runningArtifactPath: current.artifact,
+        currentVersion: '10.1.0',
+      },
+    )
+
+    expect(state.status).toBe('gap')
+    expect(state.remedy?.command).toBe(
+      cliUpdateRecoveryCommand(),
+    )
+    expect(state.technical).toMatchObject({
+      effective: {
+        command_path: old.command,
+        artifact_path: realpathSync(old.artifact),
+        version: '3.0.1',
+      },
+    })
+  })
+
+  it('keeps a healthy winner ready while reporting a later broken duplicate for cleanup', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-later-broken-'))
+    const current = posixInstall(root, 'current', '10.1.0')
+    const broken = posixInstall(root, 'broken', '3.0.1')
+    chmodSync(broken.artifact, 0o644)
+
+    const state = cliBinReadiness(
+      { PATH: `${path.dirname(current.command)}:${path.dirname(broken.command)}` },
+      'darwin',
+      { runningArtifactPath: current.artifact, currentVersion: '10.1.0' },
+    )
+
+    expect(state.status).toBe('optional-gap')
+    expect(state.detail).toContain('ready')
+    expect(state.detail).not.toContain(broken.command)
+    expect(state.technical).toMatchObject({
+      effective: { command_path: current.command, executable: true },
+      entries: [
+        { command_path: current.command, executable: true },
+        { command_path: broken.command, executable: false },
+      ],
+    })
   })
 
-  it('is ready when PATH has no notifai entry', () => {
+  it('does not call a PATH with no notifai entry ready', () => {
     const directory = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-empty-'))
     mkdirSync(directory, { recursive: true })
     const state = cliBinReadiness({ PATH: directory }, process.platform)
-    expect(state.status).toBe('ready')
-    expect(state.detail).toContain('no notifai binary was on PATH')
+    // The running process proves nothing about the command every printed next
+    // step names — but it is running, so this cannot stand in the way either.
+    expect(state.status).toBe('optional-gap')
+    expect(state.detail).toContain('will not be found')
+    expect(state.remedy?.command).not.toBe('notifai update')
+    expect(state.remedy?.command).toMatch(/ update$/)
   })
 })