@raidiant/notifai 0.1.6 → 0.1.8

package/src/install-hooks.test.ts

@@ -97,6 +97,22 @@ describe('hook config', () => {
     expect(config['UserPromptSubmit']?.[0]?.hooks[0]?.timeout).toBe(15)
     expect(config['SessionEnd']?.[0]?.hooks[0]?.timeout).toBe(3)
   })
+
+  it('stamps the exact harness on every generated command', () => {
+    const config = buildHookConfig({
+      execPath: EXEC,
+      scriptPath: SCRIPT,
+      replyTimeoutSeconds: 240,
+      graceSeconds: 0,
+      harness: 'claude-code',
+    })
+    expect(
+      Object.values(config)
+        .flatMap((groups) => groups)
+        .flatMap((group) => group.hooks)
+        .every((handler) => handler.command.includes('--harness claude-code')),
+    ).toBe(true)
+  })
 })
 
 describe('merging into existing settings', () => {
@@ -450,6 +466,7 @@ describe('the OpenCode adapter', () => {
   it('shells out to the same hook commands the other harnesses run', () => {
     // The whole point: presence, escalation and retirement stay in the CLI.
     expect(source).toContain('"hook", event')
+    expect(source).toContain('"--harness", "opencode"')
     expect(source).toContain(JSON.stringify(SCRIPT))
     expect(source).toContain(JSON.stringify(EXEC))
   })
@@ -464,6 +481,18 @@ describe('the OpenCode adapter', () => {
     expect(source).not.toContain('"permission.ask"')
   })
 
+  it('injects collected late answers into the next OpenCode user message', () => {
+    expect(source).toContain('hookSpecificOutput?.additionalContext')
+    expect(source).toContain('synthetic: true')
+  })
+
+  it('injects an exact active-harness and session marker into OpenCode shells', () => {
+    expect(source).toContain('"shell.env"')
+    expect(source).toContain('NOTIFAI_ACTIVE_HARNESS')
+    expect(source).toContain('NOTIFAI_ACTIVE_SESSION_ID')
+    expect(source).toContain('input.sessionID')
+  })
+
   it('carries the ownership marker so a second checkout replaces it', () => {
     expect(source).toContain(OPENCODE_PLUGIN_MARKER)
     expect(isOurOpencodePlugin(source)).toBe(true)
@@ -487,11 +516,17 @@ describe('the OpenCode adapter', () => {
     // rather than a command line, so answering with the plugin's own path made
     // an ordinary OpenCode install look like a second checkout and turned the
     // duplicate check red on a healthy machine.
-    expect(opencodePluginTarget(source)).toEqual({ exec: EXEC, script: SCRIPT, current: true })
+    expect(opencodePluginTarget(source)).toEqual({
+      exec: EXEC,
+      script: SCRIPT,
+      current: true,
+      timeoutSeconds: 240,
+    })
     expect(opencodePluginTarget(source.replace(/^const ADAPTER_VERSION = .*\n/m, ''))).toEqual({
       exec: EXEC,
       script: SCRIPT,
       current: false,
+      timeoutSeconds: 240,
     })
     expect(opencodePluginTarget('export const SomeoneElse = () => ({})')).toBeNull()
     // Ours, but with the constants edited beyond recognition: no answer beats

package/src/install-hooks.ts

@@ -1,18 +1,11 @@
 import {
-  closeSync,
   existsSync,
-  fsyncSync,
-  lstatSync,
-  mkdirSync,
-  openSync,
   readFileSync,
   statSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync,
 } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { atomicWriteFileSync } from './atomic-file.js'
 import { opencodePluginPath, opencodePluginTarget } from './opencode-plugin.js'
 
 /**
@@ -73,22 +66,22 @@ export function hookCommand(
   execPath: string,
   scriptPath: string,
   event: string,
-  harness?: 'cursor',
+  harness?: Harness,
 ): string {
   return (
     `${quote(execPath)} ${quote(scriptPath)} hook ${event} ${OWNER_MARKER}` +
-    (harness === 'cursor' ? ' --harness cursor' : '')
+    (harness === undefined ? '' : ` --harness ${harness}`)
   )
 }
 
 /**
- * Says "NotifAI installed this" without saying which checkout did.
+ * Says "Notifai installed this" without saying which checkout did.
  *
  * Ownership used to be matched on the absolute script path, so installing from
  * a second checkout did not recognise the first one's handlers as ours. Both
  * stayed, the harness ran both, and one question produced two notifications;
  * uninstalling the second silently left the first running. A marker that every
- * NotifAI build writes and no build's path appears in fixes that by making
+ * Notifai build writes and no build's path appears in fixes that by making
  * ownership a property of the handler rather than of the machine it was
  * installed from.
  *
@@ -114,6 +107,8 @@ export interface BuildOptions {
   replyTimeoutSeconds: number
   /** Seconds the question waits in the terminal before it is pushed at all. */
   graceSeconds: number
+  /** The installed adapter stamps its exact harness into project pointers. */
+  harness?: Harness
 }
 
 /** Command-hook harnesses kill at 600s; generated adapters use the same safe ceiling. */
@@ -139,7 +134,7 @@ export function buildHookConfig(options: BuildOptions): HookConfig {
         hooks: [
           {
             type: 'command',
-            command: hookCommand(execPath, scriptPath, 'user-prompt-submit'),
+            command: hookCommand(execPath, scriptPath, 'user-prompt-submit', options.harness),
             // Claude Code caps UserPromptSubmit at 30s; stay well inside it so
             // a slow network can never delay the user's own prompt.
             timeout: 15,
@@ -152,7 +147,7 @@ export function buildHookConfig(options: BuildOptions): HookConfig {
         hooks: [
           {
             type: 'command',
-            command: hookCommand(execPath, scriptPath, 'stop'),
+            command: hookCommand(execPath, scriptPath, 'stop', options.harness),
             timeout: blockingTimeout,
           },
         ],
@@ -163,7 +158,7 @@ export function buildHookConfig(options: BuildOptions): HookConfig {
         hooks: [
           {
             type: 'command',
-            command: hookCommand(execPath, scriptPath, 'session-end'),
+            command: hookCommand(execPath, scriptPath, 'session-end', options.harness),
             // Both harnesses give SessionEnd a ~1-3s budget, so this handler
             // only touches local state.
             timeout: 3,
@@ -205,9 +200,9 @@ export function buildCursorHookConfig(options: BuildOptions): CursorHookConfig {
       {
         command: hookCommand(options.execPath, options.scriptPath, 'stop', 'cursor'),
         timeout: blockingTimeout,
-        // One companion-device answer produces one automatic follow-up turn. There is no
-        // useful reason for Cursor to repeat it, even if state cleanup fails.
-        loop_limit: 1,
+        // A continuation may register a real follow-up question. Match the
+        // session-state cap so those chains are useful but never unbounded.
+        loop_limit: 3,
       },
     ],
     sessionEnd: [
@@ -568,49 +563,7 @@ export function removeHooks(existing: SettingsDocument, scriptPath: string): Mer
  * support.
  */
 export function applyPlan(file: string, document: SettingsDocument | CursorSettingsDocument): void {
-  mkdirSync(path.dirname(file), { recursive: true })
-  const mode = targetMode(file)
-  const temp = path.join(path.dirname(file), `.${path.basename(file)}.notifai-${process.pid}.tmp`)
-
-  const handle = openSync(temp, 'w', mode)
-  try {
-    writeFileSync(handle, `${JSON.stringify(document, null, 2)}\n`)
-    fsyncSync(handle)
-  } finally {
-    closeSync(handle)
-  }
-  try {
-    renameSync(temp, file)
-  } catch (err) {
-    // Leaving the temp behind would be a second, quieter mess on top of the
-    // failure the caller is about to hear about.
-    try {
-      unlinkSync(temp)
-    } catch {
-      // Nothing useful to do; the rename error is the one that matters.
-    }
-    throw err
-  }
-}
-
-/** Mode to preserve, or the mode for a new file. Refuses a non-regular target. */
-function targetMode(file: string): number {
-  let stat
-  try {
-    stat = lstatSync(file)
-  } catch (err) {
-    // A settings file can carry tokens, so a file we create is ours alone.
-    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return 0o600
-    throw err
-  }
-  if (stat.isSymbolicLink()) {
-    throw new Error(
-      `${file} is a symlink; refusing to write through it. Replace it with a regular file, ` +
-        'or install to a different location.',
-    )
-  }
-  if (!stat.isFile()) throw new Error(`${file} is not a regular file; refusing to replace it.`)
-  return stat.mode & 0o777
+  atomicWriteFileSync(file, `${JSON.stringify(document, null, 2)}\n`)
 }
 
 export function loadSettings(file: string): SettingsDocument {
@@ -633,6 +586,8 @@ export interface InstalledHandler {
   /** Index of the handler within its group. */
   handlerIndex: number
   command: string
+  /** Declared process lifetime, used to detect config/install drift. */
+  timeout?: number
 }
 
 export interface Installation {
@@ -645,9 +600,9 @@ export interface Installation {
 }
 
 /**
- * Any NotifAI handler, whatever checkout wrote it.
+ * Any Notifai handler, whatever checkout wrote it.
  *
- * Deliberately looser than `isOurHandler`: this answers "has NotifAI been set
+ * Deliberately looser than `isOurHandler`: this answers "has Notifai been set
  * up here at all", and a handler installed from a second checkout is still
  * evidence that it has (and is itself worth reporting).
  */
@@ -659,7 +614,7 @@ function isNotifaiHandler(handler: HookHandler): boolean {
   return isNotifaiCommand(handler.command)
 }
 
-/** Every place either harness would read a NotifAI handler from. */
+/** Every place either harness would read a Notifai handler from. */
 export function findInstallations(cwd: string, env: NodeJS.ProcessEnv = process.env): Installation[] {
   const found: Installation[] = []
   for (const harness of HARNESSES) {
@@ -687,6 +642,7 @@ export function findInstallations(cwd: string, env: NodeJS.ProcessEnv = process.
             groupIndex: 0,
             handlerIndex: 0,
             command: hookCommand(target.exec, target.script, hookEvent),
+            ...(target.timeoutSeconds === undefined ? {} : { timeout: target.timeoutSeconds }),
           })),
         })
         continue
@@ -699,7 +655,10 @@ export function findInstallations(cwd: string, env: NodeJS.ProcessEnv = process.
           continue
         }
         const handlers = locateCursorHandlers(document)
-        if (handlers.length > 0) found.push({ harness, file, global, handlers })
+        if (handlers.length > 0) {
+          const problems = harnessMarkerProblems(harness, handlers)
+          found.push({ harness, file, global, handlers, ...(problems.length > 0 ? { problems } : {}) })
+        }
         continue
       }
       let document: SettingsDocument
@@ -709,18 +668,35 @@ export function findInstallations(cwd: string, env: NodeJS.ProcessEnv = process.
         continue
       }
       const handlers = locateHandlers(document)
-      if (handlers.length > 0) found.push({ harness, file, global, handlers })
+      if (handlers.length > 0) {
+        const problems = harnessMarkerProblems(harness, handlers)
+        found.push({ harness, file, global, handlers, ...(problems.length > 0 ? { problems } : {}) })
+      }
     }
   }
   return found
 }
 
+function harnessMarkerProblems(harness: Harness, handlers: InstalledHandler[]): string[] {
+  return handlers.every((handler) => handler.command.includes(`--harness ${harness}`))
+    ? []
+    : [
+        `installed commands do not stamp the ${harness} routing identity; rerun \`notifai hooks install --harness ${harness}\``,
+      ]
+}
+
 function locateCursorHandlers(document: CursorSettingsDocument): InstalledHandler[] {
   const handlers: InstalledHandler[] = []
   for (const [event, eventHandlers] of Object.entries(document.hooks ?? {})) {
     eventHandlers.forEach((handler, handlerIndex) => {
       if (isNotifaiCommand(handler.command)) {
-        handlers.push({ event, groupIndex: 0, handlerIndex, command: handler.command })
+        handlers.push({
+          event,
+          groupIndex: 0,
+          handlerIndex,
+          command: handler.command,
+          ...(handler.timeout === undefined ? {} : { timeout: handler.timeout }),
+        })
       }
     })
   }
@@ -733,7 +709,13 @@ function locateHandlers(document: SettingsDocument): InstalledHandler[] {
     groups.forEach((group, groupIndex) => {
       group.hooks?.forEach((handler, handlerIndex) => {
         if (isNotifaiHandler(handler)) {
-          handlers.push({ event, groupIndex, handlerIndex, command: handler.command })
+          handlers.push({
+            event,
+            groupIndex,
+            handlerIndex,
+            command: handler.command,
+            ...(handler.timeout === undefined ? {} : { timeout: handler.timeout }),
+          })
         }
       })
     })

package/src/main.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { Command } from 'commander'
 import {
   askCommand,
+  accessStatusCommand,
   authStatusCommand,
   capabilitiesCommand,
   closeCommand,
@@ -25,13 +26,16 @@ import {
   type CommandDeps,
 } from './commands.js'
 import { defaultCredentialStore } from './credentials.js'
+import { HARNESSES } from './install-hooks.js'
 import type { Platform } from '@raidiant/notifai-protocol'
+import { nativeSkills, type SkillScope } from './native-skills.js'
 
 const deps: CommandDeps = {
   io: realIo(),
   store: defaultCredentialStore(),
   env: process.env,
   cwd: process.cwd(),
+  nativeSkills,
 }
 
 /**
@@ -89,11 +93,36 @@ const program = new Command('notifai')
   .description('Send native device notifications from agents and local programs')
   .version(version())
 
+// Setup leads: `init` is the single entry command for first-run friendliness.
+program
+  .command('init')
+  .description(
+    'Set up Notifai here, idempotently: sign-in, project id, hooks, device readiness, live receipt proof. ' +
+      'Interactive at a human terminal; never prompts otherwise (agents: pass flags)',
+  )
+  .option('--project-id <id>', 'project identifier slug (default: derived from the directory name)')
+  .option('--skills', 'install/update the agent skill from its pinned public release')
+  .option('--no-skills', 'suppress the optional agent-skill status line')
+  .option('--skills-scope <scope>', 'unattended skill scope: project or global')
+  .option('--hooks', 'install harness hooks for registered-question routing')
+  .option('--no-hooks', 'skip the hooks without being asked')
+  .action(async (opts: { projectId?: string; skills?: boolean; skillsScope?: SkillScope; hooks?: boolean }) => {
+    process.exit(await initCommand(deps, opts))
+  })
+
+program
+  .command('doctor')
+  .description('Audit config, credential, server, contract, device, hook, and saved receipt proof; exits nonzero when any line is FAIL (no live send)')
+  .option('--json', 'machine-readable output')
+  .action(async (opts: { json?: boolean }) => {
+    process.exit(await doctorCommand(deps, opts))
+  })
+
 program
   .command('login')
-  .description('Pair this machine with your NotifAI account via browser approval')
+  .description('Pair this machine with your Notifai account via browser approval')
   .option('--name <name>', 'machine name shown in the dashboard (default: hostname)')
-  .option('--base-url <url>', 'NotifAI server URL')
+  .option('--base-url <url>', 'Notifai server URL')
   .option('--no-open', 'do not open the approval page in a browser')
   .action(async (opts: { name?: string; baseUrl?: string; open?: boolean }) => {
     process.exit(await loginCommand(deps, opts))
@@ -114,6 +143,13 @@ auth
   .action((opts: { json?: boolean }) => {
     process.exit(authStatusCommand(deps, opts))
   })
+auth
+  .command('access')
+  .description('Show the account plan and access decision')
+  .option('--json', 'machine-readable output')
+  .action(async (opts: { json?: boolean }) => {
+    process.exit(await accessStatusCommand(deps, opts))
+  })
 
 program
   .command('devices')
@@ -132,7 +168,7 @@ program
     process.exit(await capabilitiesCommand(deps, opts))
   })
 
-program
+const send = program
   .command('send')
   .description('Send a notification')
   .requiredOption('--title <title>', 'notification title')
@@ -148,18 +184,15 @@ program
   .option('--all', 'target all routable devices (overrides configured devices)')
   .option('--ttl <seconds>', 'delivery window in seconds', (v: string) => Number(v))
   .option('--collapse-key <key>', 'replace earlier notifications with the same key')
-  .option('--platform <platform>', 'platform whose optional fields to include (default: ios)')
+  .option('--platform <platform>', 'limit optional fields to ios or macos (default: both)')
   .option('--sound <sound>', 'default | done | attention | alert | none')
-  .option('--badge <n>', 'app badge count', (v: string) => Number(v))
   .option('--thread-id <id>', 'group related notifications')
   .option('--level <level>', 'interruption level: passive | active | time_sensitive')
-  .option('--relevance <score>', '0..1 relevance score', (v: string) => Number(v))
-  .option('--target-content-id <id>')
   .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[]) => [...all, v], [])
   .option('--image <path|url|media_id>', 'upload or attach an image')
   .option('--reply', 'enable the inline reply action and block for the answer')
   .option('--reply-timeout <seconds>', 'how long to wait for a reply (default: 900)', (v: string) => Number(v))
-  .option('--reply-window <seconds>', 'how long the server accepts a reply (default: 86400)', (v: string) => Number(v))
+  .option('--reply-window <seconds>', 'how long the server accepts a reply (default: 3600)', (v: string) => Number(v))
   .option(
     '--reply-choice <label>',
     'with --reply, ask a closed question (2-6 answers); one value splits on commas, or repeat the flag',
@@ -171,7 +204,7 @@ program
   .option('--wait <seconds>', 'how long to wait for provider outcomes', (v: string) => Number(v))
   .option('--no-wait', 'return immediately after acceptance')
   .option('--idempotency-key <key>', 'safe-retry key (default: random)')
-  .option('--base-url <url>', 'NotifAI server URL')
+  .option('--base-url <url>', 'Notifai server URL')
   .option('--json', 'print the full submission receipt as JSON')
   .action(async (opts: Record<string, unknown>) => {
     // commander maps --no-wait onto the same "wait" flag; disentangle.
@@ -206,13 +239,19 @@ program
     process.exit(await sendCommand(deps, flags))
   })
 
+send.addHelpText(
+  'after',
+  `\nKind profiles (used unless --sound, --level, or saved user config overrides them):\n  update    sound none       level passive\n  done      sound done       level passive\n  question  sound attention  level active (--reply)\n`,
+)
+
 program
-  .command('replies <request_id>')
+  .command('replies [request_id]')
   .description('Retrieve replies for a notification request')
+  .option('--pending', 'use the pushed question pending for this project session')
   .option('--wait <seconds>', 'how long to wait for a reply', (v: string) => Number(v))
   .option('--after <seq>', 'return replies after this sequence number', (v: string) => Number(v))
   .option('--json', 'machine-readable output')
-  .action(async (requestId: string, opts: { wait?: number; after?: number; json?: boolean }) => {
+  .action(async (requestId: string | undefined, opts: { wait?: number; after?: number; json?: boolean; pending?: boolean }) => {
     process.exit(await repliesCommand(deps, requestId, opts))
   })
 
@@ -253,13 +292,14 @@ program
   .command('hook <event>')
   .description('Internal: run a harness hook (reads hook JSON on stdin)')
   // Inert, and the point of it is that it is inert: the installed command line
-  // carries a marker that says "NotifAI wrote this" independently of which
+  // carries a marker that says "Notifai wrote this" independently of which
   // checkout wrote it.
   .option('--owner <name>', 'internal ownership marker')
   .option('--harness <name>', 'internal harness output adapter')
   .action(async (event: string, opts: { harness?: string }) => {
+    const harness = HARNESSES.find((candidate) => candidate === opts.harness)
     process.exit(
-      await hookRunCommand(deps, event, readStdin, opts.harness === 'cursor' ? 'cursor' : undefined),
+      await hookRunCommand(deps, event, readStdin, harness),
     )
   })
 
@@ -269,7 +309,7 @@ hooks
   .description('Wire this harness to route registered questions to your devices')
   .option(
     '--harness <name>',
-    'claude-code | codex | cursor | opencode (default: detected; OpenCode cannot resume an idle turn from an answer)',
+    'claude-code | codex | cursor | opencode (default: detected; OpenCode delivers answers on the next prompt)',
   )
   .option('--global', 'install for every project instead of just this one')
   .action((opts: { harness?: string; global?: boolean }) => {
@@ -312,27 +352,4 @@ config
     },
   )
 
-program
-  .command('init')
-  .description(
-    'Set up NotifAI here, idempotently: sign-in, project id, hooks, device readiness, live receipt proof. ' +
-      'Interactive at a human terminal; never prompts otherwise (agents: pass flags)',
-  )
-  .option('--project-id <id>', 'project identifier slug (default: derived from the directory name)')
-  .option('--skills', 'install/update the agent skill from its pinned public release')
-  .option('--no-skills', 'suppress the optional agent-skill status line')
-  .option('--hooks', 'install harness hooks for registered-question routing')
-  .option('--no-hooks', 'skip the hooks without being asked')
-  .action(async (opts: { projectId?: string; skills?: boolean; hooks?: boolean }) => {
-    process.exit(await initCommand(deps, opts))
-  })
-
-program
-  .command('doctor')
-  .description('Audit config, credential, server, contract, device, hook, and saved receipt proof (no live send)')
-  .option('--json', 'machine-readable output')
-  .action(async (opts: { json?: boolean }) => {
-    process.exit(await doctorCommand(deps, opts))
-  })
-
 await program.parseAsync(process.argv)

package/src/native-skills.ts

@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/** The two scopes offered by the skills installer. */
+export type SkillScope = 'project' | 'global'
+
+/** The installer-managed evidence needed by Notifai readiness. */
+export interface NativeSkill {
+  name: string
+  scope: SkillScope
+  path: string
+  source: string | null
+  sourceType: string | null
+  sourceUrl: string | null
+  ref: string | null
+}
+
+export interface SkillsListResult {
+  skills: NativeSkill[]
+  error?: string
+}
+
+export interface SkillsAddOptions {
+  source: string
+  skill: string
+  scope?: SkillScope
+  cwd: string
+  env: NodeJS.ProcessEnv
+}
+
+export interface NativeSkills {
+  /** Launch the native interactive `npx skills add` flow. */
+  add(options: SkillsAddOptions): Promise<number>
+  /** Ask the native installer for its managed install inventory. */
+  list(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): Promise<SkillsListResult>
+}
+
+interface JsonSkill {
+  name?: unknown
+  path?: unknown
+  scope?: unknown
+  source?: unknown
+  sourceType?: unknown
+  sourceUrl?: unknown
+}
+
+interface LockEntry {
+  source?: unknown
+  sourceType?: unknown
+  sourceUrl?: unknown
+  ref?: unknown
+}
+
+interface LockFile {
+  skills?: Record<string, LockEntry>
+}
+
+function skillLockPath(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): string {
+  if (scope === 'project') return path.join(cwd, 'skills-lock.json')
+  const stateHome = env['XDG_STATE_HOME']
+  const home = env['HOME'] ?? env['USERPROFILE'] ?? os.homedir()
+  return stateHome !== undefined && stateHome !== ''
+    ? path.join(stateHome, 'skills', '.skill-lock.json')
+    : path.join(home, '.agents', '.skill-lock.json')
+}
+
+function readLock(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): LockFile {
+  const file = skillLockPath(scope, cwd, env)
+  if (!existsSync(file)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as LockFile
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function lockEntryFor(lock: LockFile, name: string): LockEntry | undefined {
+  const direct = lock.skills?.[name]
+  if (direct) return direct
+  const normalized = name.toLowerCase().replace(/[\s_]+/g, '-')
+  const key = Object.keys(lock.skills ?? {}).find(
+    (candidate) => candidate.toLowerCase().replace(/[\s_]+/g, '-') === normalized,
+  )
+  return key === undefined ? undefined : lock.skills?.[key]
+}
+
+function jsonArray(stdout: string): unknown[] | null {
+  const start = stdout.indexOf('[')
+  const end = stdout.lastIndexOf(']')
+  if (start < 0 || end < start) return null
+  try {
+    const parsed: unknown = JSON.parse(stdout.slice(start, end + 1))
+    return Array.isArray(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+function managedSkills(stdout: string, scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): NativeSkill[] | null {
+  const entries = jsonArray(stdout)
+  if (entries === null) return null
+  const lock = readLock(scope, cwd, env)
+  return entries.flatMap((entry): NativeSkill[] => {
+    if (entry === null || typeof entry !== 'object') return []
+    const value = entry as JsonSkill
+    if (
+      typeof value.name !== 'string' ||
+      typeof value.path !== 'string' ||
+      value.scope !== scope
+    ) {
+      return []
+    }
+    const lockEntry = lockEntryFor(lock, value.name)
+    return [
+      {
+        name: value.name,
+        scope,
+        path: value.path,
+        source: typeof value.source === 'string' ? value.source : null,
+        sourceType: typeof value.sourceType === 'string' ? value.sourceType : null,
+        sourceUrl: typeof value.sourceUrl === 'string' ? value.sourceUrl : null,
+        ref: typeof lockEntry?.ref === 'string' ? lockEntry.ref : null,
+      },
+    ]
+  })
+}
+
+function run(
+  args: string[],
+  options: { cwd: string; env: NodeJS.ProcessEnv; stdio: 'inherit' | 'capture' },
+): Promise<{ code: number; stdout: string }> {
+  return new Promise((resolve) => {
+    const child = spawn('npx', args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: options.stdio === 'inherit' ? 'inherit' : ['ignore', 'pipe', 'ignore'],
+    })
+    if (options.stdio === 'capture') {
+      let stdout = ''
+      child.stdout?.on('data', (chunk: Buffer | string) => {
+        stdout += chunk.toString()
+      })
+      child.on('error', () => resolve({ code: 1, stdout }))
+      child.on('exit', (code) => resolve({ code: code ?? 1, stdout }))
+      return
+    }
+    child.on('error', () => resolve({ code: 1, stdout: '' }))
+    child.on('exit', (code) => resolve({ code: code ?? 1, stdout: '' }))
+  })
+}
+
+/** The only process/filesystem adapter Notifai needs for the external installer. */
+export const nativeSkills: NativeSkills = {
+  async add(options) {
+    const args = ['-y', 'skills', 'add', options.source, '--skill', options.skill]
+    if (options.scope === 'global') args.push('--global')
+    // An explicit scope is the unattended contract. Native `--yes` keeps all
+    // remaining installer prompts non-interactive after the scope is chosen.
+    if (options.scope !== undefined) args.push('--yes')
+    return (await run(args, { cwd: options.cwd, env: options.env, stdio: 'inherit' })).code
+  },
+
+  async list(scope, cwd, env) {
+    const result = await run(
+      ['-y', 'skills', 'list', '--json', ...(scope === 'global' ? ['--global'] : [])],
+      { cwd, env, stdio: 'capture' },
+    )
+    if (result.code !== 0) return { skills: [], error: `npx skills list exited with code ${result.code}` }
+    const skills = managedSkills(result.stdout, scope, cwd, env)
+    return skills === null
+      ? { skills: [], error: 'npx skills list returned invalid JSON' }
+      : { skills }
+  },
+}