@raidiant/notifai 9.2.1 → 9.3.0

package/src/install-hooks.test.ts

@@ -13,6 +13,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
 import { describe, expect, it } from 'vitest'
+import { REPLY_MAX_WINDOW_SECONDS } from '@raidiant/notifai-protocol'
 import { parseChoices } from './send.js'
 import {
   OPENCODE_PLUGIN_MARKER,
@@ -27,7 +28,7 @@ import {
 } from './session-activation.js'
 import { hookAdapterPath, installHookAdapter } from './hook-adapter.js'
 import {
-  BLOCKING_STOP_TIMEOUT_SECONDS,
+  QUESTION_STOP_TIMEOUT_SECONDS,
   HARNESSES,
   applyPlan,
   detectHarness,
@@ -152,18 +153,13 @@ describe('hook config', () => {
     ).toBe(true)
   })
 
-  it('lets Codex own Stop timeout while keeping short fixed lifecycle budgets', () => {
+  it('gives Codex a Stop timeout beyond the longest answer window', () => {
     const codex = buildHookConfig({ adapterPath: ADAPTER, harness: 'codex' })
 
     expect(codex['UserPromptSubmit']?.[0]?.hooks[0]?.timeout).toBe(15)
     expect(codex['SessionEnd']?.[0]?.hooks[0]?.timeout).toBe(3)
-    // Codex hashes the exact serialized definition into `trusted_hash`, so its
-    // Stop handler stays a bare blocking command: declaring a timeout would
-    // invalidate the user's approval and the handler would silently stop.
-    expect(codex['Stop']?.[0]?.hooks[0]).toEqual({
-      type: 'command',
-      command: hookCommand(ADAPTER, 'stop', 'codex'),
-    })
+    expect(codex['Stop']?.[0]?.hooks[0]?.timeout).toBe(QUESTION_STOP_TIMEOUT_SECONDS)
+    expect(QUESTION_STOP_TIMEOUT_SECONDS).toBeGreaterThan(REPLY_MAX_WINDOW_SECONDS)
   })
 
   it('gives Claude Code an asynchronous Stop with an explicit waiter budget on POSIX', () => {
@@ -176,7 +172,7 @@ describe('hook config', () => {
     expect(claude['Stop']?.[0]?.hooks[0]).toEqual({
       type: 'command',
       command: hookCommand(ADAPTER, 'stop', 'claude-code'),
-      timeout: 3600,
+      timeout: QUESTION_STOP_TIMEOUT_SECONDS,
       async: true,
     })
     expect(claude['UserPromptSubmit']?.[0]?.hooks[0]?.async).toBeUndefined()
@@ -195,7 +191,7 @@ describe('hook config', () => {
     expect(claude['Stop']?.[0]?.hooks[0]).toEqual({
       type: 'command',
       command: hookCommand(options.adapterPath, 'stop', 'claude-code', options),
-      timeout: BLOCKING_STOP_TIMEOUT_SECONDS,
+      timeout: QUESTION_STOP_TIMEOUT_SECONDS,
     })
   })
 
@@ -213,7 +209,7 @@ describe('hook config', () => {
       expect(groups.flatMap((group) => group.hooks)).toHaveLength(1)
     }
     expect(migrated.document.hooks?.['Stop']?.[0]?.hooks[0]).toMatchObject({
-      timeout: 3600,
+      timeout: QUESTION_STOP_TIMEOUT_SECONDS,
       async: true,
     })
     expect(migrated.replaced.sort()).toEqual([

package/src/install-hooks.ts

@@ -22,6 +22,10 @@ import {
 import { opencodePluginPath, opencodePluginTarget } from './opencode-plugin.js'
 import { HARNESSES, type Harness } from './harnesses.js'
 import { accountHome } from './platform.js'
+import {
+  NON_ROUTING_STOP_TIMEOUT_SECONDS,
+  QUESTION_STOP_TIMEOUT_SECONDS,
+} from './question-timing.js'
 
 export { HARNESSES, type Harness } from './harnesses.js'
 
@@ -177,40 +181,18 @@ export interface BuildOptions {
 }
 
 /**
- * Claude Code's Stop handler returns instantly and the same process lives on
- * out of band as the escalation waiter, so this `timeout` bounds a background
- * process rather than the user's turn.
- *
- * It is always declared, and declared far above the longest wait a waiter can
- * take. Claude's default is 600 s and the kill is **silent** — the backgrounded
- * process simply vanishes, no error is reported anywhere, and the answer the
- * user already gave is never delivered. Sitting anywhere near that boundary
- * turns a slow reply into a lost one, so this does not: an explicit value
- * raises the ceiling (verified against a 660 s wait under an hour-long
- * declaration), and an hour is several times the waiter's own ceiling.
+ * Harnesses without asynchronous Question Routing use this short Stop budget.
+ * Claude Code and Codex use `QUESTION_STOP_TIMEOUT_SECONDS` instead.
  */
-export const CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS = 3600
-
-/**
- * The declared process budget for a host that holds its turn while the waiter
- * runs: the waiter's own ceiling plus a minute of host headroom, as one plain
- * number rather than a budget carved into reserves.
- *
- * Codex is deliberately absent from this. It owns its Stop timeout today, and
- * declaring one would change the serialized definition Codex hashes into
- * `trusted_hash` — which silently stops every Notifai handler from running
- * until the user re-approves them in `/hooks`.
- */
-export const BLOCKING_STOP_TIMEOUT_SECONDS = 540
+export const NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS = NON_ROUTING_STOP_TIMEOUT_SECONDS
+export { QUESTION_STOP_TIMEOUT_SECONDS } from './question-timing.js'
 
 /**
  * Whether this harness's Stop handler runs detached from the turn.
  *
- * Three places decide this — the installer that declares `async: true`, the
- * hook runtime that picks the waiter's wall clock, and doctor's check that the
- * installed definition still has the right shape — and they must agree or the
- * waiter outlives a turn nobody left open. They were three separate spellings
- * of the same condition with nothing tying them together.
+ * The installer and doctor share this predicate so they agree whether Claude
+ * runs out of band. Owner lifetime is route-neutral and lives in
+ * `question-timing.ts`.
  */
 export function stopHandlerIsDetached(
   harness: Harness | undefined,
@@ -224,10 +206,10 @@ export function stopHandlerIsDetached(
  *
  * Claude Code takes the answer over its own inbox socket, so its Stop hook is
  * `async: true`: it returns immediately, the terminal is never held, and the
- * waiter finishes out of band. Every other host still delivers by printing a
- * continuation to this process's stdout, so its Stop hook blocks and needs a
- * declared ceiling above the wait — except Codex, which owns that number
- * itself and whose definition must stay byte-stable for its trust store.
+ * waiter finishes out of band. Codex and Claude on Windows block and print a
+ * continuation to stdout. Every Question Routing owner declares the same
+ * complete-window timeout; changing Codex's definition requires one explicit
+ * trust approval.
  */
 function stopHandler(
   adapterPath: string,
@@ -236,10 +218,12 @@ function stopHandler(
 ): HookHandler {
   const command = hookCommand(adapterPath, 'stop', harness, options)
   if (stopHandlerIsDetached(harness, options.platform)) {
-    return { type: 'command', command, timeout: CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS, async: true }
+    return { type: 'command', command, timeout: QUESTION_STOP_TIMEOUT_SECONDS, async: true }
+  }
+  if (harness === 'codex' || harness === 'claude-code') {
+    return { type: 'command', command, timeout: QUESTION_STOP_TIMEOUT_SECONDS }
   }
-  if (harness === 'codex') return { type: 'command', command }
-  return { type: 'command', command, timeout: BLOCKING_STOP_TIMEOUT_SECONDS }
+  return { type: 'command', command, timeout: NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS }
 }
 
 function commandOptionsFrom(options: BuildOptions): HookCommandOptions {
@@ -350,7 +334,7 @@ export function buildCursorHookConfig(options: BuildOptions): CursorHookConfig {
       },
       {
         command: hookCommand(options.adapterPath, 'stop', 'cursor', commandOptions),
-        timeout: BLOCKING_STOP_TIMEOUT_SECONDS,
+        timeout: NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
         // 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,

package/src/invocation-context.test.ts

@@ -346,7 +346,7 @@ describe('buildSourceContext', () => {
       }),
     ).toEqual({
       ok: false,
-      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact session id.',
+      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact Agent Session id.',
     })
   })
 })

package/src/invocation-context.ts

@@ -150,7 +150,7 @@ export type SourceContextBuild =
   | { ok: true; source?: SourceContextT }
   | { ok: false; error: string }
 
-/** Resolve per-field source precedence without fabricating session identity. */
+/** Resolve per-field Source Context precedence without fabricating Agent Session identity. */
 export function buildSourceContext(input: SourceContextInput): SourceContextBuild {
   const sessionId =
     input.sessionId ?? input.env['NOTIFAI_SESSION_ID'] ?? input.activeHarness?.sessionId
@@ -158,7 +158,7 @@ export function buildSourceContext(input: SourceContextInput): SourceContextBuil
   if (explicitLabel !== undefined && (sessionId === undefined || sessionId === '')) {
     return {
       ok: false,
-      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact session id.',
+      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact Agent Session id.',
     }
   }
   if (sessionId === '') {

package/src/program.test.ts

@@ -98,6 +98,24 @@ describe('program argv parsing', () => {
     })
   })
 
+  it('preserves deliberate Projectless send intent at the argv boundary', async () => {
+    let seen: Record<string, unknown> | undefined
+    await parse(
+      ['send', '--kind', 'done', '--title', 'T', '--body', 'B', '--projectless'],
+      { send: (async (_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['send'] },
+    )
+    expect(seen).toMatchObject({ projectless: true })
+  })
+
+  it('dispatches User-owned Project enablement commands', async () => {
+    let enabled = 0
+    const result = await parse(['project', 'enable'], {
+      projectEnable: ((_deps) => (enabled += 1, 0)) as ProgramRunners['projectEnable'],
+    })
+    expect(result.exitCode).toBe(0)
+    expect(enabled).toBe(1)
+  })
+
   it('drops empty collector defaults so "not passed" stays absent', async () => {
     let seen: Record<string, unknown> | undefined
     await parse(

package/src/program.ts

@@ -23,6 +23,9 @@ import {
   initCommand,
   loginCommand,
   logoutCommand,
+  projectDisableCommand,
+  projectEnableCommand,
+  projectStatusCommand,
   logsCommand,
   repliesCommand,
   reportAskFailure,
@@ -81,6 +84,9 @@ const defaultRunners = {
   accessStatus: accessStatusCommand,
   devices: devicesCommand,
   capabilities: capabilitiesCommand,
+  projectEnable: projectEnableCommand,
+  projectDisable: projectDisableCommand,
+  projectStatus: projectStatusCommand,
   send: sendCommand,
   replies: repliesCommand,
   acknowledge: acknowledgeCommand,
@@ -216,7 +222,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       '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('--project-id <id>', 'Project identifier slug (default: derived from the directory name)')
     .option('--json', 'machine-readable final readiness; never prompts')
     .option('--skills', 'install/update the agent skill from its pinned public release')
     .option('--no-skills', 'suppress the optional agent-skill status line')
@@ -250,6 +256,21 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       exit(await runners.doctor(deps, opts))
     })
 
+  const project = program
+    .command('project')
+    .helpGroup(GROUP.daily)
+    .summary('Control Notifai for this Project')
+    .description('Inspect or change this Project\'s User-owned lifecycle enablement')
+  project.command('enable').description('Enable lifecycle guidance for this Project').action(() => {
+    exit(runners.projectEnable(deps))
+  })
+  project.command('disable').description('Disable lifecycle guidance for this Project').action(() => {
+    exit(runners.projectDisable(deps))
+  })
+  project.command('status').description('Show lifecycle enablement for this Project').option('--json').action((opts: { json?: boolean }) => {
+    exit(runners.projectStatus(deps, opts.json === true))
+  })
+
   program
     .command('login')
     .helpGroup(GROUP.start)
@@ -339,13 +360,14 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     )
     .optionsGroup(SEND_GROUP.routing)
     .option('--kind <kind>', 'what this is (required): update | done | failed | blocked (no User reply would resume it) — question is set by --reply')
-    .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
+    .option('--project <id>', 'Project identifier override (otherwise configured or inferred)')
+    .option('--projectless', 'deliberately omit Project identity for this notification')
     .option('--device <id>', 'target a device id (repeatable)', (v: string, all: string[] = []) => [...all, v])
     .option('--all', 'target all routable devices (overrides configured devices)')
-    .option('--session-id <id>', 'low-level automation override for an opaque exact session (env: NOTIFAI_SESSION_ID)')
+    .option('--session-id <id>', 'low-level automation override for an opaque exact Agent Session (env: NOTIFAI_SESSION_ID)')
     .option(
       '--session-label <text>',
-      'human session name; safe to repeat, with the first accepted name frozen (env: NOTIFAI_SESSION_LABEL)',
+      'human Agent Session name; safe to repeat, with the first accepted name frozen (env: NOTIFAI_SESSION_LABEL)',
     )
     .optionsGroup(SEND_GROUP.presentation)
     .option('--collapse-key <key>', 'replace earlier notifications with the same key')
@@ -421,7 +443,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .helpGroup(GROUP.agent)
     .summary('Retrieve replies to a question')
     .description('Retrieve replies for a notification request')
-    .option('--pending', 'use the pushed question pending for this project session')
+    .option('--pending', 'use the pushed question pending for this Project and Agent 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')
@@ -481,10 +503,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       'alt text paired with --image occurrences by position (repeatable)',
       (v: string, all: string[] = []) => [...all, v],
     )
-    .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
+    .option('--project <id>', 'Project identifier override (otherwise configured or inferred)')
     .option(
       '--session-label <text>',
-      'human session name; safe to repeat, with the first accepted name frozen (env: NOTIFAI_SESSION_LABEL)',
+      'human Agent Session name; safe to repeat, with the first accepted name frozen (env: NOTIFAI_SESSION_LABEL)',
     )
     .action(async (question: string | undefined, opts: {
       choice?: string[]
@@ -551,9 +573,9 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .helpGroup(GROUP.agent)
     .summary('Retire a question so late answers are rejected')
     .description(
-      'Retire a question so late answers are rejected rather than lost. Pass --pending to withdraw this session\'s outstanding registrations, including ones the turn-end hook has not pushed yet.',
+      'Retire a question so late answers are rejected rather than lost. Pass --pending to withdraw this Agent Session\'s outstanding registrations, including ones the turn-end hook has not pushed yet.',
     )
-    .option('--pending', 'retire this session\'s outstanding questions, including ones not yet pushed')
+    .option('--pending', 'retire this Agent Session\'s outstanding questions, including ones not yet pushed')
     .option('--json', 'machine-readable output')
     .action(async (requestId: string | undefined, opts: { json?: boolean; pending?: boolean }) => {
       exit(await runners.close(deps, requestId, opts))
@@ -615,9 +637,9 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--event <name>', 'only this event; repeatable', (v: string, all: string[] = []) => [...all, v])
     .option('--run <id>', 'everything one command invocation did')
     .option('--request <id>', 'everything about one notification request')
-    .option('--session <id>', 'only this harness session')
-    .option('--project <id>', 'only this project')
-    .option('--all-projects', 'do not scope to the project in this directory')
+    .option('--session <id>', 'only this Agent Session')
+    .option('--project <id>', 'only this Project')
+    .option('--all-projects', 'do not scope to the Project in this directory')
     .option('--grep <text>', 'only records containing this text')
     .option('--json', 'one JSON record per line on stdout')
     .option('--path', 'print the log file paths instead of the records')
@@ -656,7 +678,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     )
     .option('--project', 'write to the shared .notifai/config.toml instead')
     .option('--local', 'write a personal project preference on this machine (not in the repo)')
-    .option('--session <id>', 'apply only to one session')
+    .option('--session <id>', 'apply only to one Agent Session')
     .option('--yes', 'skip the confirmation gate')
     .action(
       async (
@@ -674,7 +696,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     )
     .option('--project', 'remove from the shared .notifai/config.toml instead')
     .option('--local', 'remove a personal project preference stored on this machine')
-    .option('--session <id>', 'remove from one session')
+    .option('--session <id>', 'remove from one Agent Session')
     .option('--yes', 'skip the confirmation gate')
     .action(
       async (

package/src/project-enablement.test.ts

@@ -0,0 +1,55 @@
+import { execFileSync } from 'node:child_process'
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  disableProject,
+  enableProject,
+  projectBinding,
+  projectEnabled,
+} from './project-enablement.js'
+
+function git(cwd: string, ...args: string[]): void {
+  execFileSync('git', ['-C', cwd, ...args], { stdio: 'ignore' })
+}
+
+describe('Project enablement', () => {
+  it('is disabled by default and changes only through its User-owned marker', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-enablement-'))
+    const env = { XDG_CONFIG_HOME: path.join(root, 'config') }
+    const binding = projectBinding(root, env)
+    expect(binding).not.toBeNull()
+    expect(projectEnabled(binding)).toBe(false)
+
+    enableProject(binding!, new Date('2026-08-27T00:00:00.000Z'))
+    expect(projectEnabled(binding)).toBe(true)
+    disableProject(binding!)
+    expect(projectEnabled(binding)).toBe(false)
+  })
+
+  it('shares one decision across linked worktrees but not unrelated checkouts with the same name', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-enablement-git-'))
+    const repo = path.join(root, 'same-name')
+    const linked = path.join(root, 'linked')
+    const unrelatedParent = path.join(root, 'other')
+    const unrelated = path.join(unrelatedParent, 'same-name')
+    mkdirSync(repo, { recursive: true })
+    mkdirSync(unrelated, { recursive: true })
+    for (const cwd of [repo, unrelated]) {
+      git(cwd, 'init')
+      git(cwd, 'config', 'user.email', 'test@example.invalid')
+      git(cwd, 'config', 'user.name', 'Test')
+      writeFileSync(path.join(cwd, 'file'), 'x')
+      git(cwd, 'add', 'file')
+      git(cwd, 'commit', '-m', 'fixture')
+    }
+    git(repo, 'worktree', 'add', linked, '-b', 'linked')
+    const env = { XDG_CONFIG_HOME: path.join(root, 'config') }
+    const mainBinding = projectBinding(repo, env)
+    const linkedBinding = projectBinding(linked, env)
+    const unrelatedBinding = projectBinding(unrelated, env)
+    expect(linkedBinding?.markerPath).toBe(mainBinding?.markerPath)
+    expect(unrelatedBinding?.markerPath).not.toBe(mainBinding?.markerPath)
+  })
+})

package/src/project-enablement.ts

@@ -0,0 +1,99 @@
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, realpathSync, unlinkSync } from 'node:fs'
+import path from 'node:path'
+import { atomicWriteFileSync } from './atomic-file.js'
+import { globalConfigDir } from './config.js'
+import { inferInvocationContext } from './invocation-context.js'
+
+interface ProjectEnablementMarker {
+  version: 1
+  project: string
+  enabled: true
+  updated_at: string
+}
+
+export interface ProjectBinding {
+  project: string
+  markerPath: string
+}
+
+function gitCommonDirectory(cwd: string): string | null {
+  try {
+    const raw = execFileSync('git', ['-C', cwd, 'rev-parse', '--git-common-dir'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2_000,
+      windowsHide: true,
+    }).trim()
+    if (raw === '') return null
+    const resolved = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw)
+    try {
+      return realpathSync(resolved)
+    } catch {
+      return path.resolve(resolved)
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Resolve the User-owned enablement record for this exact local Project.
+ *
+ * The opaque key binds the semantic Project id to Git's shared common
+ * directory. Linked worktrees therefore share one decision, while another
+ * checkout cannot borrow it merely by committing the same Project id.
+ */
+export function projectBinding(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  explicitProject?: string | null,
+): ProjectBinding | null {
+  const project = explicitProject ?? inferInvocationContext(cwd).project
+  if (project === null) return null
+  const repository = gitCommonDirectory(cwd) ?? path.resolve(cwd)
+  const key = createHash('sha256')
+    .update('notifai-project-enablement-v1\0')
+    .update(repository)
+    .update('\0')
+    .update(project)
+    .digest('hex')
+  return {
+    project,
+    markerPath: path.join(globalConfigDir(env), 'project-enablement', `${key}.json`),
+  }
+}
+
+export function projectEnabled(binding: ProjectBinding | null): boolean {
+  if (binding === null || !existsSync(binding.markerPath)) return false
+  try {
+    const marker = JSON.parse(readFileSync(binding.markerPath, 'utf8')) as Partial<ProjectEnablementMarker>
+    return marker.version === 1 && marker.enabled === true && marker.project === binding.project
+  } catch {
+    return false
+  }
+}
+
+export function enableProject(binding: ProjectBinding, now: Date = new Date()): void {
+  const marker: ProjectEnablementMarker = {
+    version: 1,
+    project: binding.project,
+    enabled: true,
+    updated_at: now.toISOString(),
+  }
+  atomicWriteFileSync(binding.markerPath, `${JSON.stringify(marker, null, 2)}\n`, {
+    mode: 0o600,
+    preserveMode: false,
+    requireCurrentUserOwner: true,
+    directoryMode: 0o700,
+  })
+}
+
+export function disableProject(binding: ProjectBinding): void {
+  try {
+    unlinkSync(binding.markerPath)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+  }
+}

package/src/question-timing.ts

@@ -0,0 +1,56 @@
+import { REPLY_MAX_WINDOW_SECONDS } from '@raidiant/notifai-protocol'
+
+/**
+ * Time before reply-window admission that the Stop owner may spend reading its
+ * input, serving terminal-first grace, resolving devices, and submitting.
+ *
+ * Grace is capped at six minutes and every network operation is independently
+ * bounded. Twenty minutes lets setup spend up to ten while preserving the
+ * separate completion margin below; neither may borrow from the answer window
+ * the service actually commits.
+ */
+export const QUESTION_WAITER_STARTUP_HEADROOM_SECONDS = 20 * 60
+
+/**
+ * Minimum lifetime still available when a question is admitted.
+ *
+ * The server window starts during submission, not when the hook process
+ * started. Keeping ten minutes beyond the requested window covers the bounded
+ * submit, clock skew, close fence, and route handoff. If setup used more of the
+ * allowance, the frozen question remains local for a successor owner instead
+ * of publishing a window this process cannot observe completely.
+ */
+export const QUESTION_SUBMISSION_COMPLETION_HEADROOM_SECONDS = 10 * 60
+
+/**
+ * The longest one Stop owner may live from process start.
+ *
+ * The service can accept an answer for up to 72 hours. Starting this budget
+ * before submission is deliberate: the startup allowance above ensures that
+ * even the maximum reply window still ends before the owner does.
+ */
+export const QUESTION_WAITER_CEILING_SECONDS =
+  REPLY_MAX_WINDOW_SECONDS + QUESTION_WAITER_STARTUP_HEADROOM_SECONDS
+
+/** Time for final fencing, diagnostics, stdout handoff, and clean process exit. */
+export const QUESTION_STOP_TEARDOWN_HEADROOM_SECONDS = 60
+
+/**
+ * Declared harness timeout for every Stop handler that owns Question Routing.
+ * It must outlive the runtime owner; otherwise the harness silently kills the
+ * only process capable of continuing the exact Agent Session.
+ */
+export const QUESTION_STOP_TIMEOUT_SECONDS =
+  QUESTION_WAITER_CEILING_SECONDS + QUESTION_STOP_TEARDOWN_HEADROOM_SECONDS
+
+/**
+ * Short Stop budget for harnesses that cannot own asynchronous Question
+ * Routing. They retire/refuse promptly and never wait through an answer window.
+ */
+export const NON_ROUTING_STOP_TIMEOUT_SECONDS = 540
+
+/**
+ * Pre-PID claim files came only from the former eight-minute owner. Retain that
+ * recovery bound instead of making a corrupt legacy file block for 72 hours.
+ */
+export const LEGACY_QUESTION_CLAIM_TTL_SECONDS = 480

package/src/readiness.ts

@@ -34,7 +34,14 @@ export type Remedy =
    * the CLI's to launch but the human's to complete, so an agent must still
    * treat it as out of reach.
    */
-  | { by: 'user-here'; summary: string; command: string; interactive?: boolean }
+  | {
+      by: 'user-here'
+      summary: string
+      command: string
+      interactive?: boolean
+      /** Stable agent-facing description of an unavoidable harness-owned action. */
+      user_action?: { code: string; harness: string; action: string; message: string }
+    }
   /**
    * A human somewhere else entirely — phone in hand, app store, permission
    * dialog. The class the old init could only print a sentence about, and the

package/src/send.ts

@@ -34,9 +34,11 @@ export interface SendFlags {
   /** What this notification is; absent means update. */
   kind?: string
   project?: string
-  /** Opaque exact-session override. */
+  /** Deliberately omit Project identity even when config or cwd could supply one. */
+  projectless?: boolean
+  /** Opaque exact Agent Session override. */
   sessionId?: string
-  /** Human-readable session label override. */
+  /** Human-readable Agent Session label override. */
   sessionLabel?: string
   device?: string[]
   all?: boolean
@@ -287,7 +289,12 @@ export function buildDraft(
     }
   }
 
-  const project = flags.project ?? config.project.value ?? invocation.inferredProject
+  if (flags.projectless === true && flags.project !== undefined) {
+    return { ok: false, error: 'Choose either --project or --projectless, not both.' }
+  }
+  const project = flags.projectless === true
+    ? undefined
+    : flags.project ?? config.project.value ?? invocation.inferredProject
 
   // Ids are derived from labels so an agent writing a one-liner does not have
   // to invent them, but they stay the stable thing it branches on afterwards.

package/src/session-activation.ts

@@ -3,12 +3,11 @@ import { Buffer } from 'node:buffer'
 import { GUIDANCE_CONTEXT_MAX_BYTES, boundedEffectiveGuidance } from './guidance-render.js'
 
 const ROOT_OWNERSHIP =
-  'Notifai is active for this session. The effective, provenance-marked guidance below governs Notification Requests. ' +
-  'Missing CLI readiness is handled through `notifai init --json`. ' +
-  'The root agent owns User-visible Notification Requests unless it explicitly delegates that ownership; workers report Agent Events to the parent.'
+  'Notifai is enabled for this Project. The effective, provenance-marked guidance below governs Notification Requests. ' +
+  'Missing CLI readiness is handled through `notifai init --json`.'
 
 export const WORKER_ACTIVATION_CONTEXT =
-  'Notifai worker context: report Agent Events to the parent; do not send User-visible Notification Requests unless the parent explicitly delegated that ownership. If delegated, load the Notifai skill and run `notifai guidance` before composing one.'
+  'Notifai worker context: an Agent Event is a meaningful occurrence in your work; a Notification Request is a deliberate User-visible message about one. Report Agent Events to the parent and do not send Notification Requests unless the parent explicitly delegated that ownership. If delegated, load the Notifai skill and run `notifai guidance` before composing one.'
 
 export const MISSING_LIFECYCLE_GUIDANCE_CONTEXT =
   'Notifai is active, but lifecycle guidance could not be loaded. Run `notifai guidance` once before deciding whether or how to send a Notification Request.'

package/src/skill.test.ts

@@ -229,8 +229,8 @@ describe('Notifai agent skill', () => {
     const send = section('## Send')
     expect(send).toContain('--session-label')
     expect(send).toMatch(/2-6 words/i)
-    expect(send).toMatch(/when the current\s+environment exposes an exact session/i)
-    expect(send).toMatch(/without an exact session[\s\S]{0,160}usage\s+error/i)
+    expect(send).toMatch(/when the current environment exposes its exact\s+identifier/i)
+    expect(send).toMatch(/without an exact Agent Session[\s\S]{0,160}usage\s+error/i)
     expect(send).toMatch(/omit `--session-label`/i)
     expect(send).toMatch(/name the\s+environment supplies wins/i)
     expect(send).toMatch(/freezes one semantic name/i)

package/dist/orca-session-title.d.ts

@@ -1,10 +0,0 @@
-export type OrcaSessionTitleLookup = (env: NodeJS.ProcessEnv) => string | undefined;
-export type OrcaCommand = (executable: string, args: readonly string[]) => string | null;
-/**
- * Read the semantic display name assigned to this exact Orca worktree.
- *
- * The environment contributes only an opaque selector. Orca must return that
- * exact id and its matching path before its display name becomes trusted; no
- * path component or identifier is ever promoted into the User-visible label.
- */
-export declare function readOrcaSessionTitle(env: NodeJS.ProcessEnv, command?: OrcaCommand): string | undefined;