@raidiant/notifai 9.2.2 → 9.3.0

package/src/commands-send-support.ts

@@ -5,42 +5,16 @@ import path from 'node:path'
 import { isRetryableReplyPollError, type ApiClient } from './client.js'
 import { fetchMediaUrl } from './url-policy.js'
 import { buildSourceContext, inferInvocationContext } from './invocation-context.js'
-import { readOrcaSessionTitle } from './orca-session-title.js'
 import { type DraftInvocation, type SendFlags } from './send.js'
 import { EXIT, reportError, type CommandDeps } from './commands-core.js'
 import type { ActiveHarnessSession } from './commands-harness-context.js'
 
-function managedSessionTitle(
-  deps: CommandDeps,
-  flags: Pick<SendFlags, 'sessionLabel'>,
-  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 ||
-    deps.env['NOTIFAI_SESSION_LABEL'] !== undefined
-  ) {
-    return undefined
-  }
-  try {
-    return (deps.orcaSessionTitle ?? readOrcaSessionTitle)(deps.env)
-  } catch {
-    return undefined
-  }
-}
-
 export function resolveDraftInvocation(
   deps: CommandDeps,
   flags: Pick<SendFlags, 'sessionId' | 'sessionLabel'>,
   active: ActiveHarnessSession | null,
 ): { ok: true; invocation: DraftInvocation } | { ok: false; error: string } {
   const inferred = inferInvocationContext(deps.cwd)
-  const sessionTitle = managedSessionTitle(deps, flags, active)
   const source = buildSourceContext({
     env: deps.env,
     invocation: inferred,
@@ -52,7 +26,7 @@ export function resolveDraftInvocation(
           activeHarness: {
             harness: active.harness,
             ...(active.sessionId === undefined ? {} : { sessionId: active.sessionId }),
-            ...(sessionTitle === undefined ? {} : { sessionLabel: sessionTitle }),
+            ...(active.sessionLabel === undefined ? {} : { sessionLabel: active.sessionLabel }),
             ...(active.sessionLabelPending === true ? { sessionLabelPending: true } : {}),
           },
         }),

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,
@@ -148,9 +149,6 @@ export async function sendCommand(
     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',

package/src/commands.test.ts

@@ -68,6 +68,7 @@ import {
   codexTrustKey,
   findInstallations,
   handlerEvent,
+  QUESTION_STOP_TIMEOUT_SECONDS,
   settingsFile,
 } from './install-hooks.js'
 import { readSessionState, writeProjectSession, writeSessionState } from './hooks.js'
@@ -78,6 +79,7 @@ import { resetLatestPublishedCliVersionForTest } from './cli-release.js'
 import { activeLogPath, createLogger, logsDiskUsage, readLogRecords } from './logging.js'
 import { hookAdapterPath, inspectHookAdapter } from './hook-adapter.js'
 import type { Tone } from './ui/theme.js'
+import { projectBinding, projectEnabled } from './project-enablement.js'
 
 afterEach(() => {
   resetLatestPublishedCliVersionForTest()
@@ -416,6 +418,31 @@ function replyResponse(
 }
 
 describe('command contracts', () => {
+  it('durably enables a valid in-Project send before missing authentication stops it', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-explicit-enable-'))
+    const io = new CapturedIo()
+    const env = isolatedEnv(cwd)
+    const deps = {
+      ...makeDeps(io, {} as ApiClient),
+      cwd,
+      env,
+      store: { load: () => null, save: () => {}, clear: () => {}, describe: () => 'empty store' },
+    }
+    expect(await sendCommand(deps, { title: 'Ready', body: 'Ready.', kind: 'done' })).toBe(EXIT.auth)
+    expect(projectEnabled(projectBinding(cwd, env))).toBe(true)
+  })
+
+  it('sends deliberately Projectless without enabling the inferred Project', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-projectless-'))
+    const io = new CapturedIo()
+    const env = isolatedEnv(cwd)
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = { submit: async (body: SubmitNotificationRequestT) => ((submitted = body), receipt) } as unknown as ApiClient
+    const deps = { ...makeDeps(io, client), cwd, env }
+    expect(await sendCommand(deps, { title: 'Ready', body: 'Ready.', kind: 'done', projectless: true })).toBe(EXIT.ok)
+    expect(submitted?.draft.project).toBeUndefined()
+    expect(projectEnabled(projectBinding(cwd, env))).toBe(false)
+  })
   it('shows an actionable no-plan access state', async () => {
     const io = new CapturedIo()
     const client = {
@@ -829,7 +856,7 @@ describe('command contracts', () => {
     expect(io.errLines.join('\n')).not.toContain('opaque-claude-session-42')
   })
 
-  it('uses the exact Orca worktree title for an active Claude session send', async () => {
+  it('never promotes an Orca worktree title into an Agent Session label', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-orca-claude-title-'))
     const io = new CapturedIo()
     let submitted: SubmitNotificationRequestT | undefined
@@ -852,10 +879,6 @@ describe('command contracts', () => {
       ...makeDeps(io, client),
       cwd,
       env,
-      orcaSessionTitle: (lookupEnv: NodeJS.ProcessEnv) => {
-        expect(lookupEnv['ORCA_WORKTREE_ID']).toBe(worktreeId)
-        return 'Worker - semantic session implementation'
-      },
     }
 
     expect(
@@ -868,12 +891,13 @@ describe('command contracts', () => {
 
     expect(submitted?.draft.source).toMatchObject({
       session_id: 'orca-claude-session',
-      session_label: 'Worker - semantic session implementation',
       harness: 'claude-code',
     })
+    expect(submitted?.draft.source?.session_label).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
+    expect(submitted?.draft.source?.session_label).not.toBe('Worker - semantic session implementation')
   })
 
-  it('uses the exact Orca worktree title for an active Codex session send', async () => {
+  it('never treats an Orca worktree title as a Codex Agent Session label', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-orca-codex-title-'))
     const io = new CapturedIo()
     let submitted: SubmitNotificationRequestT | undefined
@@ -894,10 +918,6 @@ describe('command contracts', () => {
         TERM_PROGRAM: 'Orca',
         ORCA_WORKTREE_ID: worktreeId,
       },
-      orcaSessionTitle: (lookupEnv: NodeJS.ProcessEnv) => {
-        expect(lookupEnv['ORCA_WORKTREE_ID']).toBe(worktreeId)
-        return 'Worker - semantic session implementation'
-      },
     }
 
     expect(
@@ -910,9 +930,9 @@ describe('command contracts', () => {
 
     expect(submitted?.draft.source).toMatchObject({
       session_id: 'orca-codex-thread',
-      session_label: 'Worker - semantic session implementation',
       harness: 'codex',
     })
+    expect(submitted?.draft.source?.session_label).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
   })
 
   it('falls back safely when Orca returns a private path as its title', async () => {
@@ -936,7 +956,6 @@ describe('command contracts', () => {
         TERM_PROGRAM: 'Orca',
         ORCA_WORKTREE_ID: `repo-123::${cwd}`,
       },
-      orcaSessionTitle: () => '/private/untrusted/worktree',
     }
 
     expect(
@@ -6093,7 +6112,7 @@ describe('asking before the hooks have ever run', () => {
     expect(readSessionState('codex-orchestrator', env).pending).toBeUndefined()
   })
 
-  it('registers an Orca-managed Claude question under the semantic worktree title', () => {
+  it('registers an Orca-managed Claude question without borrowing the worktree title', () => {
     const cwd = scratchDir('notifai-orca-claude-ask-')
     const io = new CapturedIo()
     const env = {
@@ -6108,7 +6127,6 @@ describe('asking before the hooks have ever run', () => {
       cwd,
       env,
       now: () => 42,
-      orcaSessionTitle: () => 'Worker - semantic session implementation',
     }
 
     expect(hooksInstallCommand(deps, { harness: 'claude-code', execPath, scriptPath })).toBe(
@@ -6121,9 +6139,10 @@ describe('asking before the hooks have ever run', () => {
     expect(askCommand(deps, 'Ship the semantic resolver?', {})).toBe(EXIT.ok)
     expect(readSessionState('orca-claude-question', env).pending?.[0]?.source).toMatchObject({
       session_id: 'orca-claude-question',
-      session_label: 'Worker - semantic session implementation',
       harness: 'claude-code',
     })
+    expect(readSessionState('orca-claude-question', env).pending?.[0]?.source?.session_label)
+      .toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
   })
 
   it('judges the fired check against the active harness, not a global installation of another', async () => {
@@ -6276,6 +6295,16 @@ describe('asking before the hooks have ever run', () => {
     await doctorCommand(deps, {})
     expect(io.outLines.join('\n')).toMatch(/FAIL\s+Codex hook trust.*Stop/is)
     expect(io.outLines.join('\n')).toMatch(/best-effort.*never writes.*\/hooks/is)
+    const readiness = await assessReadiness(deps)
+    expect(readiness.states.find((state) => state.id === 'hooks-trust')?.remedy).toMatchObject({
+      command: '/hooks',
+      user_action: {
+        code: 'codex_hook_approval_required',
+        harness: 'codex',
+        action: 'approve_or_enable_notifai_hooks',
+        message: expect.stringContaining('Open `/hooks` in Codex'),
+      },
+    })
   })
 
   it('gives doctor the same active-Codex diagnosis as ask', async () => {
@@ -6650,7 +6679,8 @@ describe('asking before the hooks have ever run', () => {
     const out = io.outLines.join('\n')
     expect(out).toMatch(/FAIL\s+Turn\-end hook shape/)
     expect(out).toContain('needs `async: true`')
-    expect(out).toContain('kills the backgrounded waiter at its 600s default')
+    expect(out).toContain('kills the backgrounded waiter silently before the complete answer window')
+    expect(out).toContain(`needs an explicit ${QUESTION_STOP_TIMEOUT_SECONDS}s`)
   })
 
   /** A configured Claude Code project with one live session claiming `pid`. */

package/src/commands.ts

@@ -62,4 +62,9 @@ export {
   type SetupScope,
 } from './commands-init.js'
 export { assessReadiness, doctorCommand } from './commands-doctor.js'
+export {
+  projectDisableCommand,
+  projectEnableCommand,
+  projectStatusCommand,
+} from './commands-project.js'
 export { realIo } from './commands-io.js'

package/src/config-schema.ts

@@ -100,7 +100,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     unit: 's',
     summary: 'Optional delay before a question may reach your devices',
     detail:
-      'Zero (the default) sends the question to your devices as soon as the agent turn ends. Set a positive duration to offer the terminal an exclusive answer window first; the timer is measured from the moment the agent asked.\n\nA timer and nothing more. Whether you happen to be at this keyboard does not change it: waiting no longer holds your terminal, so there is nothing your being here would protect you from.',
+      'Zero (the default) sends the question to your devices as soon as the agent turn ends. Set a positive duration to offer the terminal an exclusive answer window first; the timer is measured from the moment the agent asked.\n\nThis controls when the question reaches devices, not how the harness keeps the Agent Session available afterward. Claude Code waits out of band; Codex holds the asking turn.',
     example: '0',
   },
 
@@ -111,7 +111,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     unit: 's',
     summary: 'How long the service keeps accepting your answer to a question',
     detail:
-      'A question stays answerable for this long after it is asked. The default is a day, so a question that arrives while you are away is still yours to answer when you come back.\n\nThis is not how long anything waits on you. The agent ends its turn immediately; if it is still running when you answer, the answer reaches it directly, and otherwise it is delivered at that session\'s next turn. Shortening this only makes an answer arrive too late to be accepted.',
+      'A question stays answerable for this long after it reaches the service. The default is a day, so a question that arrives while you are away is still yours to answer when you come back.\n\nQuestion Routing keeps the exact Agent Session available for this complete window. Claude Code waits out of band and wakes the Agent Session; Codex keeps its turn held. This is separate from `--reply-timeout`, which controls how long a direct `send --reply` command blocks.',
     example: '86400',
   },
 

package/src/config.test.ts

@@ -141,10 +141,9 @@ describe('harness config layers', () => {
     expect(config.ask_grace_seconds).toEqual({ value: 0, source: 'default' })
   })
 
-  it('bounds the terminal-first window so a reply window always survives it', () => {
+  it('bounds the terminal-first window to the supported preference', () => {
     // Config is readable from a repository, so an unbounded grace is hostile
-    // input: it would eat the waiter's whole ceiling and leave no window the
-    // server would accept an answer into.
+    // input rather than permission to hold question delivery arbitrarily.
     const { env, cwd } = setup({ globalToml: 'ask_grace_seconds = 100000\n' })
     expect(loadConfig({ cwd, env }).ask_grace_seconds.value).toBe(360)
   })

package/src/config.ts

@@ -70,8 +70,8 @@ export interface CliConfig {
    * elapses does the question reach companion devices.
    *
    * A timer, and only a timer. Whether the user happens to be at this keyboard
-   * decides nothing — the waiter no longer holds their terminal, so there is
-   * nothing for their presence to protect them from.
+   * decides nothing; the harness-specific owner continues waiting either in
+   * the held turn or out of band.
    */
   ask_grace_seconds: ResolvedValue<number>
   /**
@@ -90,7 +90,7 @@ export interface CliConfig {
    * usefulness.
    */
   log_max_bytes: ResolvedValue<number>
-  /** How long the server keeps accepting an answer to a question. */
+  /** How long the server accepts an answer and Question Routing owns its return path. */
   reply_window_seconds: ResolvedValue<number>
   /** Log files kept in total, the active one included. */
   log_max_files: ResolvedValue<number>
@@ -330,17 +330,14 @@ export function findProjectLocalConfigPath(
 
 /**
  * Ranges every layer is clamped to. Config is readable from a repository, so an
- * out-of-range value is attacker input, not a typo: an unbounded grace window
- * would consume the waiter's whole ceiling and silently leave no time at all in
- * which the user's answer could still be accepted.
+ * out-of-range value is attacker input, not a typo.
  */
 const NUMERIC_BOUNDS: Partial<Record<ConfigKey, { min: number; max: number }>> = {
   wait_seconds: { min: 0, max: 300 },
   ttl_seconds: { min: 0, max: 7 * 24 * 3600 },
-  // A plain number, no longer derived from a hook budget's leftovers. Six
-  // minutes leaves two clear minutes of the waiter's 480s ceiling, so the
-  // longest window a user can choose still leaves an answer window the server
-  // will accept — with room to spare for a timer that wakes late.
+  // Six minutes is the supported terminal-first preference bound. The Stop
+  // owner carries separate startup headroom, so this never shortens the answer
+  // window that begins after submission.
   ask_grace_seconds: { min: 0, max: 360 },
   // The floor is the shortest window the wire contract accepts; the ceiling is
   // the point past which a question would outlive the retained content it

package/src/guidance-content.ts

@@ -24,6 +24,28 @@ export interface GuidanceTopic {
   content: string
 }
 
+/** Canonical lifecycle vocabulary, always emitted from trusted CLI source. */
+export const AGENT_TERMS_PREAMBLE = `# Notifai terms
+
+An **Agent Event** is something that happened in the agent's work: completion,
+failure, a blocker, a question that needs the User, or another meaningful
+change. It stays inside the agent team until the Notification Request owner
+decides it should reach the User.
+
+A **Notification Request** is the deliberate User-visible message or question
+submitted through Notifai about an Agent Event. It is not every event and it
+is not an internal worker report.
+
+The root agent owns Notification Requests by default. Ordinary workers report
+Agent Events to their parent and do not notify the User themselves. Explicit
+delegation transfers that ownership for the delegated work.`
+
+export const AGENT_TERMS_FALLBACK = `# Notifai terms
+
+An **Agent Event** is a meaningful occurrence in agent work. A **Notification
+Request** is a deliberate User-visible message about one. Root owns requests;
+workers report events unless ownership is explicitly delegated.`
+
 const WHEN_TO_NOTIFY = `# When to notify
 
 Notify when something changed for the user:

package/src/guidance-render.ts

@@ -1,6 +1,6 @@
 import { Buffer } from 'node:buffer'
 import { describeSource } from './config-schema.js'
-import { GUIDANCE_TRUST_PREAMBLE } from './guidance-content.js'
+import { AGENT_TERMS_FALLBACK, AGENT_TERMS_PREAMBLE, GUIDANCE_TRUST_PREAMBLE } from './guidance-content.js'
 import { resolveGuidance, type GuidanceAuthority, type ResolvedGuidanceTopic } from './guidance.js'
 
 const AUTHORITY_LABEL: Record<GuidanceAuthority, string> = {
@@ -24,7 +24,7 @@ export function renderGuidance(topics: readonly ResolvedGuidanceTopic[]): string
       `${filePath === null ? '' : ` file=${encodeURIComponent(filePath)}`} -->`
     return `${marker}\n${markerSafe(topic.content).trimEnd()}`
   })
-  return [GUIDANCE_TRUST_PREAMBLE, ...blocks].join('\n\n')
+  return [GUIDANCE_TRUST_PREAMBLE, AGENT_TERMS_PREAMBLE, ...blocks].join('\n\n')
 }
 
 /** Hard ceiling for model-visible lifecycle context, including repository topics. */
@@ -48,7 +48,7 @@ export function boundedEffectiveGuidance(options: {
     bytes,
     max_bytes: maxBytes,
     fallback:
-      `${GUIDANCE_TRUST_PREAMBLE}\n\n` +
+      `${GUIDANCE_TRUST_PREAMBLE}\n\n${AGENT_TERMS_FALLBACK}\n\n` +
       `Notifai guidance is ${bytes} bytes, above the ${maxBytes}-byte lifecycle limit. ` +
       'Before deciding whether or how to notify, run `notifai guidance` once in this session. ' +
       'Do not infer or partially follow the omitted topics.',

package/src/harnesses.ts

@@ -38,13 +38,13 @@ export const HARNESS_CAPABILITIES: Record<Harness, HarnessCapability> = {
     stopContinuation: 'decision-block',
     deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
     deliveryContract:
-      'the Stop hook returns at once and waits out of band, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
+      'the Stop hook returns at once and waits out of band through the complete answer window, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
   },
   codex: {
     stopContinuation: 'decision-block',
     deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
     deliveryContract:
-      'live Stop continuation while the turn is held; once it returns, a stopped thread is resumed behind its writer lock and anything else waits for the next turn',
+      'live Stop continuation while the turn is held through the complete answer window; crash recovery may resume only a stopped thread behind its writer lock',
   },
   cursor: {
     stopContinuation: 'unsupported',

package/src/hook-adapter.test.ts

@@ -21,6 +21,7 @@ import {
   isNpxAdapterTarget,
 } from './hook-adapter.js'
 import { buildHookConfig, codexHookIdentityHash, type InstalledHandler } from './install-hooks.js'
+import { enableProject, projectBinding } from './project-enablement.js'
 
 function isolated(): { root: string; homeDir: string } {
   const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-hook-adapter-'))
@@ -28,22 +29,40 @@ function isolated(): { root: string; homeDir: string } {
 }
 
 describe('stable hook adapter', () => {
-  it('delivers session activation through the installed adapter before setup exists', () => {
+  it('keeps the installed adapter silent until the Project is enabled', () => {
     const { root, homeDir } = isolated()
+    const env = {
+      ...process.env,
+      HOME: homeDir,
+      XDG_CONFIG_HOME: path.join(root, 'config'),
+      XDG_STATE_HOME: path.join(root, 'state'),
+    }
     const scriptPath = fileURLToPath(new URL('../dist/main.js', import.meta.url))
     const installed = installHookAdapter({ execPath: process.execPath, scriptPath }, homeDir)
+    const disabled = spawnSync(
+      installed.path,
+      ['hook', 'session-start', '--owner', 'notifai', '--harness', 'codex'],
+      {
+        encoding: 'utf8',
+        input: JSON.stringify({ session_id: 'adapter-session', cwd: root, source: 'startup' }),
+        env,
+      },
+    )
+
+    expect(disabled.status).toBe(0)
+    expect(disabled.stderr).toBe('')
+    expect(disabled.stdout).toBe('')
+
+    const binding = projectBinding(root, env)
+    if (binding === null) throw new Error('test Project binding unavailable')
+    enableProject(binding)
     const run = spawnSync(
       installed.path,
       ['hook', 'session-start', '--owner', 'notifai', '--harness', 'codex'],
       {
         encoding: 'utf8',
         input: JSON.stringify({ session_id: 'adapter-session', cwd: root, source: 'startup' }),
-        env: {
-          ...process.env,
-          HOME: homeDir,
-          XDG_CONFIG_HOME: path.join(root, 'config'),
-          XDG_STATE_HOME: path.join(root, 'state'),
-        },
+        env,
       },
     )
 
@@ -52,7 +71,7 @@ describe('stable hook adapter', () => {
     expect(JSON.parse(run.stdout)).toMatchObject({
       hookSpecificOutput: {
         hookEventName: 'SessionStart',
-        additionalContext: expect.stringMatching(/Notifai.*session/i),
+        additionalContext: expect.stringMatching(/Notifai.*enabled.*Project/i),
       },
     })
   })