@raidiant/notifai 9.2.1 → 9.3.0

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

@@ -21,8 +21,8 @@ import { normalizeOrigin } from './url-policy.js'
  * preference that evaporates mid-session is worse than none.
  *
  * `project-local` is a personal file under the user's config directory, keyed
- * by the project root so a checkout does not have to gitignore anything. Shared
- * `.notifai/config.toml` stays in the tree for committed project identity.
+ * by the Project root so a checkout does not have to gitignore anything. Shared
+ * `.notifai/config.toml` stays in the tree for committed Project identity.
  *
  * `config show --explain` surfaces the winning layer per key.
  */
@@ -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>
@@ -245,9 +245,9 @@ export function sanitizeSessionId(sessionId: string): string {
 }
 
 /**
- * Pointer from a project directory to the harness session currently working in
+ * Pointer from a Project directory to the Agent Session currently working in
  * it, written by the UserPromptSubmit hook. Without it `notifai ask` has no way
- * to learn its own session id: an ordinary agent shell command receives no hook
+ * to learn its own Agent Session id: an ordinary agent shell command receives no hook
  * payload, and no harness exports one into the environment.
  */
 export function projectSessionPointerPath(cwd: string, env: NodeJS.ProcessEnv = process.env): string {
@@ -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
@@ -420,7 +417,7 @@ export function loadConfig(options: {
   cwd?: string
   env?: NodeJS.ProcessEnv
   flags?: FlagOverrides
-  /** Harness session id; enables the session override layer when present. */
+  /** Agent Session id; enables the Agent Session override layer when present. */
   sessionId?: string | undefined
 }): CliConfig {
   const env = options.env ?? process.env

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),
       },
     })
   })