@raidiant/notifai 9.2.2 → 10.0.0

package/src/commands-hook-shape.ts

@@ -1,7 +1,7 @@
 import {
-  BLOCKING_STOP_TIMEOUT_SECONDS,
-  CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS,
+  NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
   handlerEvent,
+  QUESTION_STOP_TIMEOUT_SECONDS,
   stopHandlerIsDetached,
   type Installation,
 } from './install-hooks.js'
@@ -17,15 +17,15 @@ import {
  *     also declare a `timeout`, because the harness default is 600 s and the
  *     kill is silent — the backgrounded waiter vanishes and the answer the
  *     user already gave is never delivered.
- *   - Codex owns its Stop timeout. Declaring one changes the definition it
- *     hashes into `trusted_hash`, and an untrusted handler is simply not run.
- *   - Everything else blocks its turn and needs a ceiling above the wait.
+ *   - Codex must declare the same full-window timeout. That changes its trusted
+ *     definition and deliberately requires the User to approve it once.
+ *   - Everything else cannot own asynchronous Question Routing; it receives
+ *     only the shorter bounded cleanup/refusal timeout.
  */
 export function stopShapeProblems(
   installation: Installation,
   platform: NodeJS.Platform = process.platform,
 ): string[] {
-  if (installation.harness === 'codex') return []
   const problems: string[] = []
   for (const handler of installation.handlers.filter(
     (entry) => handlerEvent(entry.command) === 'stop',
@@ -36,16 +36,32 @@ export function stopShapeProblems(
           `${installation.file} declares a blocking Stop handler; the Claude Code wake route needs \`async: true\` so the turn ends while the waiter runs`,
         )
       }
-      if (handler.timeout === undefined || handler.timeout < CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS) {
+      if (handler.timeout === undefined || handler.timeout < QUESTION_STOP_TIMEOUT_SECONDS) {
         problems.push(
-          `${installation.file} gives Stop ${handler.timeout ?? 'no'} declared seconds; Claude Code then kills the backgrounded waiter at its 600s default without reporting anything, so it needs an explicit ${CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS}s`,
+          `${installation.file} gives Stop ${handler.timeout ?? 'no'} declared seconds; Claude Code then kills the backgrounded waiter silently before the complete answer window, so it needs an explicit ${QUESTION_STOP_TIMEOUT_SECONDS}s`,
         )
       }
       continue
     }
-    if (handler.timeout === undefined || handler.timeout < BLOCKING_STOP_TIMEOUT_SECONDS) {
+    if (installation.harness === 'codex' || installation.harness === 'claude-code') {
+      if (handler.async === true) {
+        problems.push(
+          `${installation.file} declares an asynchronous ${installation.harness} Stop handler, but this platform needs the blocking continuation so the harness consumes the answer output`,
+        )
+      }
+      if (handler.timeout === undefined || handler.timeout < QUESTION_STOP_TIMEOUT_SECONDS) {
+        problems.push(
+          `${installation.file} gives Stop ${handler.timeout ?? 'no'}s, but ${installation.harness} Question Routing requires ${QUESTION_STOP_TIMEOUT_SECONDS}s to own the complete answer window`,
+        )
+      }
+      continue
+    }
+    if (
+      handler.timeout === undefined ||
+      handler.timeout < NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS
+    ) {
       problems.push(
-        `${installation.file} gives Stop ${handler.timeout ?? 'no'}s, but the blocking answer owner requires ${BLOCKING_STOP_TIMEOUT_SECONDS}s`,
+        `${installation.file} gives Stop ${handler.timeout ?? 'no'}s, but the non-routing blocking handler requires ${NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS}s`,
       )
     }
   }

package/src/commands-hooks.ts

@@ -21,7 +21,14 @@ import { ApiCallError } from './client.js'
 import { codexWakeRoute } from './codex-wake.js'
 import { loadConfig, type CliConfig } from './config.js'
 import { withTargetFileLock } from './file-lock.js'
-import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js'
+import {
+  HARNESS_LABELS,
+  HERMES_QUESTION_ROUTING_UNAVAILABLE,
+  HOOK_INSTALLABLE_HARNESSES,
+  isHookInstallableHarness,
+  questionRoutingCapability,
+  type HookInstallableHarness,
+} from './harnesses.js'
 import {
   inspectHookAdapter,
   installHookAdapter,
@@ -43,7 +50,6 @@ import {
   readSessionState,
   resetCursorStopActivation,
   registerQuestion,
-  waiterCeilingSeconds,
   withdrawUnpushedQuestions,
   type EscalationDeliveryRoute,
   type HookContext,
@@ -51,8 +57,7 @@ import {
   type PendingQuestion,
 } from './hooks.js'
 import {
-  BLOCKING_STOP_TIMEOUT_SECONDS,
-  HARNESSES,
+  NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
   applyPlan,
   buildCursorHookConfig,
   buildHookConfig,
@@ -75,14 +80,15 @@ import {
   removeCursorHooks,
   removeHooks,
   settingsFile,
-  stopHandlerIsDetached,
   withCodexLayerTransaction,
-  type Harness,
   type Installation,
 } from './install-hooks.js'
+import { QUESTION_WAITER_CEILING_SECONDS } from './question-timing.js'
+import { inferInvocationContext } from './invocation-context.js'
 import { logConfigResolved, logSettingsFrom } from './logging.js'
 import { isOurOpencodePlugin, opencodePluginSource } from './opencode-plugin.js'
 import { packageVersion } from './release.js'
+import { enableProject, projectBinding, projectEnabled } from './project-enablement.js'
 import { rejectAccidentalEscapedNewlines } from './send.js'
 import {
   cursorStopActivationOutput,
@@ -137,7 +143,7 @@ export const HOOK_EVENTS = [
 export type HookEvent = (typeof HOOK_EVENTS)[number]
 
 /** Lifecycle handlers one installed harness must carry in this CLI build. */
-export function requiredHookEvents(harness: Harness): readonly HookEvent[] {
+export function requiredHookEvents(harness: HookInstallableHarness): readonly HookEvent[] {
   if (harness === 'opencode') return []
   return harness === 'cursor'
     ? ['session-start', 'activation-stop', 'user-prompt-submit', 'stop', 'session-end']
@@ -176,11 +182,10 @@ export async function hookRunCommand(
   // would grant slow setup a second budget and let the harness kill us before
   // an accepted answer is journaled or written to stdout.
   const now = deps.now ?? Date.now
-  // The waiter may spend a long wall clock exactly when no turn is held open
-  // for it, which is the same condition the installer used to declare
-  // `async: true`. One predicate decides it for both.
-  const detachedWaiter = stopHandlerIsDetached(harness, deps.hookPlatform ?? process.platform)
-  const processDeadlineAt = now() + waiterCeilingSeconds(detachedWaiter) * 1000
+  // One owner lifetime covers startup and the longest answer window. Claude
+  // runs it detached; Codex holds the turn. The delivery mechanism does not
+  // change how long the exact Agent Session remains reachable.
+  const processDeadlineAt = now() + QUESTION_WAITER_CEILING_SECONDS * 1000
 
   const logger = log(deps)
   logger.bind({ cmd: `hook ${event}` })
@@ -253,11 +258,29 @@ export async function hookRunCommand(
   const cwd = envelope.cwd ?? deps.cwd
   const sessionEnd = hookDefersDiagnosticsUntilAfterCleanup(event)
   logger.bind({ session: envelope.session_id ?? null })
-  // Session activation is local model context, not authenticated routing. It
-  // must survive the exact first-run states it exists to repair: no config,
-  // no credential, no Companion device, and no network.
+  const lifecycleEnabled = (): boolean => {
+    try {
+      const activationConfig = loadConfig({ cwd, env: deps.env, sessionId: envelope.session_id })
+      return projectEnabled(projectBinding(cwd, deps.env, activationConfig.project.value))
+    } catch (err) {
+      logger.error('hook.end', { hook: event, outcome: 'enablement-unavailable', ...failureData(err) })
+      return false
+    }
+  }
+  // Installation only makes lifecycle hooks available. Model-visible
+  // activation is a separate User-owned Project decision, checked anew on
+  // every run so disabling takes effect without reinstalling anything.
   if (event === 'session-start' || event === 'subagent-start') {
     start({ cwd, source: envelope.source ?? null })
+    if (!lifecycleEnabled()) {
+      logger.info('hook.end', {
+        hook: event,
+        outcome: 'ignored',
+        reason: 'project-disabled',
+        decided: false,
+      })
+      return EXIT.ok
+    }
     if (event === 'session-start' && harness === 'cursor' && envelope.session_id !== undefined) {
       try {
         resetCursorStopActivation(envelope.session_id, deps.env)
@@ -307,6 +330,15 @@ export async function hookRunCommand(
       logger.info('hook.end', { hook: event, outcome: 'unsupported-harness', decided: false })
       return EXIT.ok
     }
+    if (!lifecycleEnabled()) {
+      logger.info('hook.end', {
+        hook: event,
+        outcome: 'ignored',
+        reason: 'project-disabled',
+        decided: false,
+      })
+      return EXIT.ok
+    }
     if (envelope.status === 'aborted') {
       logger.info('hook.end', {
         hook: event,
@@ -507,7 +539,15 @@ export async function hookRunCommand(
       ...outcome.log,
     })
     for (const note of outcome.notes) deps.io.err(`notifai: ${note}`)
-    if (outcome.stdout !== undefined) deps.io.out(outcome.stdout)
+    if (outcome.stdout !== undefined) {
+      // No work, await, or diagnostic may sit between this cross-process
+      // SessionEnd fence and the irreversible harness stdout write.
+      if (outcome.commitStdout === undefined || outcome.commitStdout()) {
+        deps.io.out(outcome.stdout)
+      } else {
+        deps.io.err('notifai: the Agent Session ended before answer delivery; no continuation was written')
+      }
+    }
     return EXIT.ok
   } catch (err) {
     // SessionEnd defers its start record until after cleanup; if cleanup itself
@@ -537,7 +577,7 @@ export async function hookRunCommand(
  */
 function stopWakeRoute(
   deps: CommandDeps,
-  harness: Harness | undefined,
+  harness: HookInstallableHarness | undefined,
   sessionId: string | undefined,
   cwd: string,
 ): EscalationDeliveryRoute | undefined {
@@ -1028,6 +1068,17 @@ export function askCommand(
   if (mediaInputError !== null) {
     return askFailure(deps, flags, 'invalid_input', 'media', mediaInputError, 'fix the media flags and retry')
   }
+  let explicitUseConfig: CliConfig
+  try {
+    explicitUseConfig = loadConfig({ cwd: deps.cwd, env: deps.env })
+  } catch (err) {
+    return askFailure(deps, flags, 'config_invalid', 'configuration', `Question routing configuration is invalid: ${String(err)}`, 'fix the reported Notifai configuration and retry')
+  }
+  const explicitProject = flags.project ?? explicitUseConfig.project.value ?? inferInvocationContext(deps.cwd).project
+  if (explicitProject !== null) {
+    const binding = projectBinding(deps.cwd, deps.env, explicitProject)
+    if (binding !== null) enableProject(binding)
+  }
   if (deps.store.load() === null) {
     return askFailure(
       deps,
@@ -1056,6 +1107,17 @@ export function askCommand(
         'run the ask from a shell with one exact active harness session',
       )
     }
+    if (!isHookInstallableHarness(active.harness)) {
+      const capability = HERMES_QUESTION_ROUTING_UNAVAILABLE
+      return askFailure(
+        deps,
+        flags,
+        'question_routing_unavailable',
+        'hook_contract',
+        `${active.label}: ${capability.deliveryContract}`,
+        'use a blocking `notifai send --reply` question',
+      )
+    }
     const exactState = active.sessionId === undefined
       ? null
       : readSessionState(active.sessionId, deps.env)
@@ -1207,7 +1269,9 @@ export function activeQuestionRouteProblems(
       `the active ${active.label} shell does not expose an exact session id; a project-level last-writer pointer can cross-wire two sessions. Use a blocking \`notifai send --reply\` question`,
     )
   }
-  const capability = HARNESS_CAPABILITIES[active.harness]
+  const capability = isHookInstallableHarness(active.harness)
+    ? questionRoutingCapability(active.harness)
+    : HERMES_QUESTION_ROUTING_UNAVAILABLE
   if (capability.stopContinuation === 'unsupported') {
     problems.push(`${active.label}: ${capability.deliveryContract}`)
   }
@@ -1637,7 +1701,7 @@ function resolveHookAdapterTarget(deps: CommandDeps, flags: HooksInstallFlags):
   return { execPath, scriptPath }
 }
 
-function printHooksInstallClose(deps: CommandDeps, harness: Harness, file: string): void {
+function printHooksInstallClose(deps: CommandDeps, harness: HookInstallableHarness, file: string): void {
   const label = HARNESS_LABELS[harness]
   const activation =
     harness === 'codex'
@@ -1659,7 +1723,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   if (flags.harness === undefined) {
     const detected = detectedHarnesses(deps.cwd, deps.env)
     if (detected.length === 0) {
-      deps.io.err(`Could not tell which harness you mean — pass --harness <${HARNESSES.join('|')}>.`)
+      deps.io.err(`Could not tell which harness you mean — pass --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>.`)
       return EXIT.usage
     }
     let ok = true
@@ -1732,7 +1796,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
   if (harness === 'opencode') {
     return installOpencodePlugin(deps, settingsTarget, {
       adapterPath,
-      timeoutSeconds: BLOCKING_STOP_TIMEOUT_SECONDS,
+      timeoutSeconds: NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
       platform: hookPlatform,
       nodePath,
       ...(flags.narrate === undefined ? {} : { narrate: flags.narrate }),
@@ -2003,17 +2067,17 @@ function assertOwnedRegularFile(file: string): void {
   }
 }
 
-function resolveHarness(deps: CommandDeps, requested: string | undefined): Harness | null {
+function resolveHarness(deps: CommandDeps, requested: string | undefined): HookInstallableHarness | null {
   if (requested !== undefined) {
-    if ((HARNESSES as readonly string[]).includes(requested)) return requested as Harness
+    if ((HOOK_INSTALLABLE_HARNESSES as readonly string[]).includes(requested)) return requested as HookInstallableHarness
     deps.io.err(
-      `Unknown harness "${requested}". Supported: ${HARNESSES.join(', ')}.`,
+      `Unknown harness "${requested}". Supported: ${HOOK_INSTALLABLE_HARNESSES.join(', ')}.`,
     )
     return null
   }
   const detected = detectHarness(deps.cwd, deps.env)
   if (!detected) {
-    deps.io.err(`Could not tell which harness to install for — pass --harness <${HARNESSES.join('|')}>.`)
+    deps.io.err(`Could not tell which harness to install for — pass --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>.`)
     return null
   }
   return detected
@@ -2027,7 +2091,7 @@ function resolveHarness(deps: CommandDeps, requested: string | undefined): Harne
 export async function pickHarnessesToInstall(
   deps: CommandDeps,
   requested?: string,
-): Promise<Harness[] | null> {
+): Promise<HookInstallableHarness[] | null> {
   if (requested !== undefined) {
     const harness = resolveHarness(deps, requested)
     return harness === null ? null : [harness]
@@ -2037,7 +2101,7 @@ export async function pickHarnessesToInstall(
   if (deps.io.interactive === true && deps.io.multiselect) {
     const picked = await deps.io.multiselect(
       'Which agent harnesses should Notifai wire here?',
-      HARNESSES.map((name) => ({
+      HOOK_INSTALLABLE_HARNESSES.map((name) => ({
         value: name,
         label: HARNESS_LABELS[name],
         ...(detected.includes(name) ? { hint: 'detected on this machine' } : {}),
@@ -2045,16 +2109,16 @@ export async function pickHarnessesToInstall(
       detected,
     )
     if (picked === null) return null
-    const unknown = picked.filter((name) => !(HARNESSES as readonly string[]).includes(name))
+    const unknown = picked.filter((name) => !(HOOK_INSTALLABLE_HARNESSES as readonly string[]).includes(name))
     if (unknown.length > 0) {
-      deps.io.err(`Unknown harness "${unknown[0]}". Supported: ${HARNESSES.join(', ')}.`)
+      deps.io.err(`Unknown harness "${unknown[0]}". Supported: ${HOOK_INSTALLABLE_HARNESSES.join(', ')}.`)
       return null
     }
-    return picked as Harness[]
+    return picked as HookInstallableHarness[]
   }
   if (detected.length === 0) {
     deps.io.err(
-      `Could not tell which harness to wire. Run: notifai hooks install --harness <${HARNESSES.join('|')}>`,
+      `Could not tell which harness to wire. Run: notifai hooks install --harness <${HOOK_INSTALLABLE_HARNESSES.join('|')}>`,
     )
     return null
   }

package/src/commands-init.ts

@@ -43,6 +43,7 @@ import {
   writeSetupProof,
 } from './commands-setup-proof.js'
 import { listScopedNotifaiSkills, SKILLS_SOURCE } from './commands-skill.js'
+import { enableProject, projectBinding } from './project-enablement.js'
 
 // ---------------------------------------------------------------------------
 // init
@@ -139,6 +140,14 @@ async function closeGap(
     return 'closed'
   }
 
+  if (state.id === 'project-enablement') {
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+    const binding = projectBinding(deps.cwd, deps.env, config.project.value)
+    if (binding === null) return 'failed'
+    enableProject(binding)
+    return 'closed'
+  }
+
   if (state.id === 'hooks') {
     const harnesses = await pickHarnessesToInstall(deps)
     if (harnesses === null || harnesses.length === 0) return 'failed'
@@ -534,7 +543,7 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
 
 /** Closing a local gap cannot have changed the service, the keychain, or devices. */
 function refreshAfterClose(id: string): readonly ReadinessRefresh[] | undefined {
-  return id === 'project' || id === 'hooks' || id === 'skill' || id === 'question-routing-settings'
+  return id === 'project' || id === 'project-enablement' || id === 'hooks' || id === 'skill' || id === 'question-routing-settings'
     ? ['local']
     : undefined
 }
@@ -548,6 +557,7 @@ function wantsOptional(deps: CommandDeps, state: ReadinessState, flags: InitFlag
   // nothing, and is undone by editing one line — so it is done rather than
   // asked about, for a human and an agent alike.
   if (state.id === 'project') return Promise.resolve(true)
+  if (state.id === 'project-enablement') return Promise.resolve(true)
   const explicit = state.id === 'hooks' ? flags.hooks : state.id === 'skill' ? flags.skills : undefined
   if (explicit !== undefined) return Promise.resolve(explicit)
   // An agent is never asked, and never assumed into a change it did not

package/src/commands-project.ts

@@ -0,0 +1,47 @@
+import { loadLoggedConfig, EXIT, type CommandDeps } from './commands-core.js'
+import {
+  disableProject,
+  enableProject,
+  projectBinding,
+  projectEnabled,
+} from './project-enablement.js'
+
+function bindingFor(deps: CommandDeps) {
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  return projectBinding(deps.cwd, deps.env, config.project.value)
+}
+
+export function projectEnableCommand(deps: CommandDeps): number {
+  const binding = bindingFor(deps)
+  if (binding === null) {
+    deps.io.err('No Project can be inferred here. Run inside a Project or configure an explicit Project id.')
+    return EXIT.usage
+  }
+  enableProject(binding)
+  deps.io.out(`Notifai lifecycle behavior is enabled for Project "${binding.project}".`)
+  return EXIT.ok
+}
+
+export function projectDisableCommand(deps: CommandDeps): number {
+  const binding = bindingFor(deps)
+  if (binding === null) {
+    deps.io.err('No Project can be inferred here. Run inside a Project or configure an explicit Project id.')
+    return EXIT.usage
+  }
+  disableProject(binding)
+  deps.io.out(`Notifai lifecycle behavior is disabled for Project "${binding.project}".`)
+  return EXIT.ok
+}
+
+export function projectStatusCommand(deps: CommandDeps, json = false): number {
+  const binding = bindingFor(deps)
+  const enabled = projectEnabled(binding)
+  if (json) {
+    deps.io.out(JSON.stringify({ project: binding?.project ?? null, enabled }))
+  } else if (binding === null) {
+    deps.io.out('No Project can be inferred here; lifecycle behavior is disabled.')
+  } else {
+    deps.io.out(`Project "${binding.project}": lifecycle behavior ${enabled ? 'enabled' : 'disabled'}.`)
+  }
+  return EXIT.ok
+}

package/src/commands-send-support.ts

@@ -16,10 +16,6 @@ function managedSessionTitle(
   active: ActiveHarnessSession | null,
 ): string | undefined {
   if (active?.sessionLabel !== undefined) return active.sessionLabel
-  // The Orca worktree title names the workspace, not one harness: every
-  // Agent Session that Orca starts inside that worktree inherits the same
-  // environment selector, so any active session with an identity to label
-  // may use it. An explicit label still wins without paying for the lookup.
   if (
     active?.sessionId === undefined ||
     flags.sessionLabel !== undefined ||

package/src/commands-send.ts

@@ -9,6 +9,7 @@ import {
 import { ApiCallError, NetworkError } from './client.js'
 import type { FlagOverrides, loadConfig } from './config.js'
 import { MIN_REPLY_WINDOW_SECONDS, readSessionState } from './hooks.js'
+import { enableProject, projectBinding } from './project-enablement.js'
 import {
   buildDraft,
   formatReceipt,
@@ -26,7 +27,7 @@ import {
   reportError,
   type CommandDeps,
 } from './commands-core.js'
-import { activeHarnessSession } from './commands-harness-context.js'
+import { sourceContextHarnessSession } from './commands-harness-context.js'
 import { resolveCommandSession } from './command-session.js'
 import {
   beginSendAttempt,
@@ -142,15 +143,12 @@ export async function sendCommand(
   const source = resolveDraftInvocation(
     deps,
     flags,
-    activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)()),
+    sourceContextHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)()),
   )
   if (!source.ok) {
     deps.io.err(source.error)
     return EXIT.usage
   }
-  const authed = authedClient(deps, config)
-  if (!authed) return EXIT.auth
-  const credential = deps.store.load()!
   let semanticImages: string[]
   try {
     semanticImages = semanticMediaIds(flags.image ?? [], deps.cwd)
@@ -167,6 +165,13 @@ export async function sendCommand(
     deps.io.err(semanticBuild.error)
     return EXIT.usage
   }
+  if (semanticBuild.draft.project !== undefined) {
+    const binding = projectBinding(deps.cwd, deps.env, semanticBuild.draft.project)
+    if (binding !== null) enableProject(binding)
+  }
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  const credential = deps.store.load()!
   const attempt = beginSendAttempt({
     env: deps.env,
     credential,

package/src/commands-skill.test.ts

@@ -0,0 +1,44 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { CommandDeps } from './commands-core.js'
+import { skillReadiness, SKILLS_SOURCE } from './commands-skill.js'
+
+describe('development CLI skill parity', () => {
+  it('reports an exact gap instead of calling a stale released skill ready', async () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-dev-skill-'))
+    const installedPath = path.join(root, 'skills', 'notifai')
+    mkdirSync(installedPath, { recursive: true })
+    writeFileSync(path.join(installedPath, 'SKILL.md'), '# stale released skill\n')
+    const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE ?? '')
+    if (match === null) throw new Error('test build has no skill release pin')
+    const deps = {
+      cwd: root,
+      env: {},
+      io: { out() {}, err() {}, confirm: async () => false, openUrl() {} },
+      store: { load: () => null, save() {}, clear() {}, describe: () => 'test' },
+      nativeSkills: {
+        list: async (scope: 'project' | 'global') => ({
+          skills: scope === 'global'
+            ? [{ name: 'notifai', scope, path: installedPath, source: match[1]!, sourceType: 'github' as const, sourceUrl: `https://github.com/${match[1]}.git`, ref: match[2]! }]
+            : [],
+        }),
+        add: async () => 0,
+        remove: async () => 0,
+      },
+    } satisfies CommandDeps
+
+    const state = await skillReadiness(deps)
+    expect(state).toMatchObject({
+      status: 'gap',
+      technical: {
+        resolution: 'development-cli-skill-mismatch',
+        ref: match[2],
+        checkout_digest: expect.stringMatching(/^sha256:/),
+        installed_digest: expect.stringMatching(/^sha256:/),
+      },
+    })
+    expect(state.remedy).toBeUndefined()
+  })
+})

package/src/commands-skill.ts

@@ -1,4 +1,8 @@
 import { SKILLS_INSTALLER_SPEC, type NativeSkill, type SkillScope } from './native-skills.js'
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { type ReadinessState } from './readiness.js'
 import { skillsSource } from './release.js'
 import type { CommandDeps } from './commands-core.js'
@@ -20,6 +24,40 @@ const SKILLS_SOURCE_LABEL = SKILLS_SOURCE ?? 'the public release tag matching th
 
 const SKILL_SCOPES: readonly SkillScope[] = ['project', 'global']
 
+function markdownTreeDigest(root: string): string | null {
+  if (!existsSync(root)) return null
+  const files: string[] = []
+  const walk = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name)
+      if (entry.isDirectory()) walk(absolute)
+      else if (entry.isFile() && entry.name.endsWith('.md')) files.push(absolute)
+    }
+  }
+  try {
+    walk(root)
+    const hash = createHash('sha256')
+    for (const file of files.sort()) {
+      hash.update(path.relative(root, file))
+      hash.update('\0')
+      hash.update(readFileSync(file))
+      hash.update('\0')
+    }
+    return `sha256:${hash.digest('hex')}`
+  } catch {
+    return null
+  }
+}
+
+function developmentSkillMismatch(skill: NativeSkill): { checkout: string; installed: string } | null {
+  const checkoutRoot = fileURLToPath(new URL('../../../skills/notifai/', import.meta.url))
+  const checkout = markdownTreeDigest(checkoutRoot)
+  const installed = markdownTreeDigest(skill.path)
+  return checkout !== null && installed !== null && checkout !== installed
+    ? { checkout, installed }
+    : null
+}
+
 function skillSourceParts(): { source: string; ref: string } | null {
   if (SKILLS_SOURCE === null) return null
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
@@ -118,6 +156,25 @@ export async function skillReadiness(
 
   const current = installed.find(expectedSkill)
   if (current !== undefined) {
+    const mismatch = developmentSkillMismatch(current)
+    if (mismatch !== null) {
+      return {
+        id: 'skill',
+        title: 'Agent guidance skill',
+        status: 'gap',
+        detail:
+          `the active development CLI's shipped guidance differs from the installer-managed ${skillPin(current)} skill. ` +
+          'Released installs remain immutable; publish a new CLI/skill release before treating this combination as ready.',
+        technical: {
+          resolution: 'development-cli-skill-mismatch',
+          scope: current.scope,
+          ref: current.ref,
+          path: current.path,
+          checkout_digest: mismatch.checkout,
+          installed_digest: mismatch.installed,
+        },
+      }
+    }
     return {
       id: 'skill',
       title: 'Agent guidance skill',