@raidiant/notifai 9.0.0 → 9.2.0

package/src/opencode-plugin.ts

@@ -1,7 +1,10 @@
 import path from 'node:path'
 import { hookHostPlatform, type HookHostPlatform } from './hook-adapter.js'
 import { configHome } from './install-hooks.js'
-import { SESSION_ACTIVATION_CONTEXT } from './session-activation.js'
+import {
+  MISSING_LIFECYCLE_GUIDANCE_CONTEXT,
+  WORKER_ACTIVATION_CONTEXT,
+} from './session-activation.js'
 
 /**
  * The OpenCode adapter.
@@ -32,7 +35,7 @@ export const OPENCODE_PLUGIN_MARKER = '// notifai managed opencode plugin'
 export const OPENCODE_PLUGIN_FILENAME = 'notifai.js'
 
 /** Bump when an installed generated file must be rewritten to remain functional. */
-const OPENCODE_ADAPTER_VERSION = 10
+const OPENCODE_ADAPTER_VERSION = 12
 
 export function opencodePluginDir(
   global: boolean,
@@ -104,7 +107,8 @@ import { spawn } from "node:child_process"
 ${nodeConstant}const ADAPTER = ${JSON.stringify(adapterPath)}
 const TIMEOUT_MS = ${timeoutSeconds * 1000}
 const ADAPTER_VERSION = ${OPENCODE_ADAPTER_VERSION}
-const SESSION_ACTIVATION_CONTEXT = ${JSON.stringify(SESSION_ACTIVATION_CONTEXT)}
+const MISSING_LIFECYCLE_GUIDANCE_CONTEXT = ${JSON.stringify(MISSING_LIFECYCLE_GUIDANCE_CONTEXT)}
+const WORKER_ACTIVATION_CONTEXT = ${JSON.stringify(WORKER_ACTIVATION_CONTEXT)}
 const PENDING_SESSION_TITLE =
   /^New session(?: *- *[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]+)?Z)?$/i
 
@@ -158,17 +162,43 @@ function runHook(event, envelope) {
 
 export const NotifAIPlugin = async ({ directory, client }) => {
   const cwd = typeof directory === "string" && directory.length > 0 ? directory : process.cwd()
+  const activated = new Set()
 
   return {
     /** Model-visible activation, independent of CLI setup and delivery state. */
     "experimental.chat.system.transform": async (input, output) => {
       const sessionID = input?.sessionID
       if (typeof sessionID !== "string" || sessionID.length === 0) return
+      if (activated.has(sessionID)) return
+      // OpenCode represents delegated work as child sessions. Missing or
+      // malformed relationship data must fail closed as worker context: it is
+      // safe to suppress a notification, never safe to let a child duplicate
+      // its parent's User-visible request.
+      let worker = true
+      try {
+        const response = await client.session.get({ path: { id: sessionID } })
+        const session = response?.data
+        if (session !== null && typeof session === "object") {
+          worker = typeof session.parentID === "string" && session.parentID.length > 0
+        }
+      } catch {
+        // Keep the safe worker classification.
+      }
+      const hookEventName = worker ? "SubagentStart" : "SessionStart"
+      const resolved = await runHook(worker ? "subagent-start" : "session-start", {
+        session_id: sessionID,
+        cwd,
+        hook_event_name: hookEventName,
+      })
+      const context = typeof resolved === "string" && resolved.trim().length > 0
+        ? resolved.trim()
+        : worker ? WORKER_ACTIVATION_CONTEXT : MISSING_LIFECYCLE_GUIDANCE_CONTEXT
       if (output.system.length === 0) {
-        output.system.push(SESSION_ACTIVATION_CONTEXT)
+        output.system.push(context)
       } else {
-        output.system[0] = output.system[0] + "\\n\\n" + SESSION_ACTIVATION_CONTEXT
+        output.system[0] = output.system[0] + "\\n\\n" + context
       }
+      activated.add(sessionID)
     },
 
     /** Exact active-harness identity and first-party title for agent shell commands. */

package/src/program.ts

@@ -25,6 +25,7 @@ import {
   logoutCommand,
   logsCommand,
   repliesCommand,
+  reportAskFailure,
   sendCommand,
   statusCommand,
   type CommandDeps,
@@ -216,6 +217,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
         '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('--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')
     .option(
@@ -228,6 +230,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .action(
       async (opts: {
         projectId?: string
+        json?: boolean
         skills?: boolean
         setupScope?: SkillScope
         skillsScope?: SkillScope
@@ -339,10 +342,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
     .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>', 'opaque exact-session override (env: NOTIFAI_SESSION_ID)')
+    .option('--session-id <id>', 'low-level automation override for an opaque exact session (env: NOTIFAI_SESSION_ID)')
     .option(
       '--session-label <text>',
-      'first human session name, frozen locally (env: NOTIFAI_SESSION_LABEL)',
+      'human 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')
@@ -373,6 +376,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--no-wait', 'return immediately after acceptance')
     .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[] = []) => [...all, v])
     .option('--idempotency-key <key>', 'safe-retry key (default: random)')
+    .option('--retry', 'explicitly retry one unresolved exact semantic send using its opaque saved attempt')
     .option(
       '--base-url <url>',
       'pairing override for the service origin; ignored when this machine is already paired (also NOTIFAI_BASE_URL)',
@@ -478,10 +482,9 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       (v: string, all: string[] = []) => [...all, v],
     )
     .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
-    .option('--session-id <id>', 'opaque exact-session override (env: NOTIFAI_SESSION_ID)')
     .option(
       '--session-label <text>',
-      'first human session name, frozen locally (env: NOTIFAI_SESSION_LABEL)',
+      'human session name; safe to repeat, with the first accepted name frozen (env: NOTIFAI_SESSION_LABEL)',
     )
     .action(async (question: string | undefined, opts: {
       choice?: string[]
@@ -494,20 +497,25 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       image?: string[]
       imageAlt?: string[]
       project?: string
-      sessionId?: string
       sessionLabel?: string
     }) => {
       let body = opts.body
       if (typeof opts.bodyFile === 'string') {
         if (body !== undefined) {
-          deps.io.err('Pass either --body or --body-file, not both.')
-          return exit(2)
+          return exit(reportAskFailure(deps, opts, {
+            code: 'invalid_input', check_id: 'body', exit_code: 2,
+            remedy: 'pass either --body or --body-file, then retry',
+            message: 'Pass either --body or --body-file, not both.',
+          }))
         }
         try {
           body = readFileSync(opts.bodyFile === '-' ? 0 : opts.bodyFile, 'utf8')
         } catch (err) {
-          deps.io.err(`Could not read ${opts.bodyFile}: ${String(err)}`)
-          return exit(2)
+          return exit(reportAskFailure(deps, opts, {
+            code: 'input_unreadable', check_id: 'body_file', exit_code: 2,
+            remedy: 'fix the body-file path or permissions, then retry',
+            message: `Could not read ${opts.bodyFile}: ${String(err)}`,
+          }))
         }
       }
       let form: string | undefined
@@ -515,8 +523,11 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
         try {
           form = readFileSync(opts.form === '-' ? 0 : opts.form, 'utf8')
         } catch (err) {
-          deps.io.err(`Could not read ${opts.form}: ${String(err)}`)
-          return exit(2)
+          return exit(reportAskFailure(deps, opts, {
+            code: 'input_unreadable', check_id: 'form_file', exit_code: 2,
+            remedy: 'fix the form-file path or permissions, then retry',
+            message: `Could not read ${opts.form}: ${String(err)}`,
+          }))
         }
       }
       // Commander collectors default to []; an empty list means "not passed".
@@ -528,7 +539,6 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
         ...(opts.image?.length ? { image: opts.image } : {}),
         ...(opts.imageAlt?.length ? { imageAlt: opts.imageAlt } : {}),
         ...(opts.project !== undefined ? { project: opts.project } : {}),
-        ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
         ...(opts.sessionLabel !== undefined ? { sessionLabel: opts.sessionLabel } : {}),
         ...(opts.json === true ? { json: true } : {}),
         ...(opts.literalBackslashN === true ? { literalBackslashN: true } : {}),

package/src/readiness.ts

@@ -84,6 +84,50 @@ export function isReady(readiness: Readiness): boolean {
   return firstBlocker(readiness) === null
 }
 
+const SEND_PREREQUISITES = new Set([
+  'cli-bin',
+  'credential',
+  'server',
+  'contract',
+  'auth',
+  'devices',
+])
+
+/** Baseline Notification Requests can be submitted in the final assessed state. */
+export function canSend(readiness: Readiness): boolean {
+  return [...SEND_PREREQUISITES].every((id) => {
+    const state = readiness.states.find((candidate) => candidate.id === id)
+    return state?.status === 'ready' || state?.status === 'optional-gap'
+  })
+}
+
+/** This exact invocation has a fully evidenced asynchronous question route. */
+export function questionRoutingReady(readiness: Readiness): boolean {
+  const relevant = readiness.states.filter(
+    (state) =>
+      state.id === 'question-routing-settings' ||
+      (state.id === 'hooks' || state.id.startsWith('hooks-')) && state.id !== 'hooks-detected',
+  )
+  return relevant.length > 0 && relevant.every((state) => state.status === 'ready')
+}
+
+/** Stable machine renderer shared by init and doctor. */
+export function readinessJson(readiness: Readiness): object {
+  return {
+    ready: isReady(readiness),
+    can_send: canSend(readiness),
+    question_routing_ready: questionRoutingReady(readiness),
+    states: readiness.states.map((state) => ({
+      id: state.id,
+      title: state.title,
+      status: state.status,
+      detail: state.detail,
+      technical: state.technical ?? null,
+      remedy: state.remedy ?? null,
+    })),
+  }
+}
+
 /** Everything that could still be done, blocking or not, in dependency order. */
 export function openItems(readiness: Readiness): ReadinessState[] {
   return readiness.states.filter((s) => s.status === 'gap' || s.status === 'optional-gap')

package/src/send-attempts.test.ts

@@ -0,0 +1,143 @@
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { NotificationDraftT } from '@raidiant/notifai-protocol'
+import type { MachineCredential } from './credentials.js'
+import {
+  SEND_ATTEMPT_TTL_MS,
+  beginSendAttempt,
+  semanticMediaIds,
+  sendDraftFingerprint,
+  settleSendAttempt,
+} from './send-attempts.js'
+
+const roots: string[] = []
+afterEach(() => {
+  while (roots.length > 0) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function fixture() {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-send-attempt-'))
+  roots.push(root)
+  const env = { XDG_STATE_HOME: path.join(root, 'state') }
+  const credential: MachineCredential = {
+    machineId: 'mac_attempt',
+    machineName: 'Attempt Machine',
+    baseUrl: 'https://app.notifai.test',
+    secret: 'private-machine-secret',
+  }
+  const draft = {
+    schema_version: 1,
+    kind: 'done',
+    project: 'private-project',
+    presentation: { title: 'Sensitive result', body: 'Private body text' },
+    targets: { mode: 'all' },
+  } as NotificationDraftT
+  return { root, env, credential, draft }
+}
+
+describe('opaque interrupted-send recovery', () => {
+  it('matches one exact semantic retry without storing notification content', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    const first = beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(first.ok).toBe(true)
+    if (!first.ok) return
+
+    const files = readdirSync(path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts'))
+    expect(files).toHaveLength(1)
+    const file = path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts', files[0]!)
+    const stored = readFileSync(file, 'utf8')
+    expect(stored).not.toContain('Sensitive result')
+    expect(stored).not.toContain('Private body text')
+    if (process.platform !== 'win32') expect(statSync(file).mode & 0o777).toBe(0o600)
+    if (process.platform !== 'win32') {
+      expect(statSync(path.dirname(file)).mode & 0o777).toBe(0o700)
+    }
+
+    const retry = beginSendAttempt({ env, credential, fingerprint, retry: true, now: 11 })
+    expect(retry).toMatchObject({
+      ok: true,
+      attemptId: first.attemptId,
+      idempotencyKey: first.idempotencyKey,
+      replay: true,
+    })
+    settleSendAttempt(env, first.attemptId)
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 12 })).toMatchObject({
+      ok: false,
+      code: 'retry_not_found',
+    })
+  })
+
+  it('does not follow a symlink presented as an attempt record', () => {
+    const { root, env, credential, draft } = fixture()
+    if (process.platform === 'win32') return
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    const first = beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(first.ok).toBe(true)
+    if (!first.ok) return
+    const directory = path.join(env.XDG_STATE_HOME, 'notifai', 'send-attempts')
+    const file = path.join(directory, `${first.attemptId}.json`)
+    const target = path.join(root, 'foreign.json')
+    writeFileSync(target, readFileSync(file, 'utf8'))
+    rmSync(file)
+    symlinkSync(target, file)
+
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 11 })).toMatchObject({
+      ok: false,
+      code: 'retry_not_found',
+    })
+    expect(readFileSync(target, 'utf8')).toContain(first.idempotencyKey)
+  })
+
+  it('refuses ambiguity instead of choosing between identical unresolved events', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 11 })
+    expect(beginSendAttempt({ env, credential, fingerprint, retry: true, now: 12 })).toMatchObject({
+      ok: false,
+      code: 'retry_ambiguous',
+    })
+  })
+
+  it('invalidates attempts after expiry or credential rotation', () => {
+    const { env, credential, draft } = fixture()
+    const fingerprint = sendDraftFingerprint(draft, credential)
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 10 })
+    expect(
+      beginSendAttempt({
+        env,
+        credential,
+        fingerprint,
+        retry: true,
+        now: 10 + SEND_ATTEMPT_TTL_MS + 1,
+      }),
+    ).toMatchObject({ ok: false, code: 'retry_not_found' })
+
+    beginSendAttempt({ env, credential, fingerprint, retry: false, now: 20 })
+    const rotated = { ...credential, secret: 'rotated-secret' }
+    expect(
+      beginSendAttempt({
+        env,
+        credential: rotated,
+        fingerprint: sendDraftFingerprint(draft, rotated),
+        retry: true,
+        now: 21,
+      }),
+    ).toMatchObject({ ok: false, code: 'retry_not_found' })
+  })
+
+  it('fingerprints local media bytes without retaining paths or bytes', () => {
+    const { root } = fixture()
+    const file = path.join(root, 'private.png')
+    writeFileSync(file, 'first bytes')
+    const first = semanticMediaIds([file], root)
+    writeFileSync(file, 'different bytes')
+    const second = semanticMediaIds([file], root)
+    expect(first).not.toEqual(second)
+    expect(first[0]).not.toContain(file)
+    expect(first[0]).not.toContain('first bytes')
+  })
+})

package/src/send-attempts.ts

@@ -0,0 +1,188 @@
+import { createHash, createHmac, randomBytes } from 'node:crypto'
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+} from 'node:fs'
+import path from 'node:path'
+import type { NotificationDraftT } from '@raidiant/notifai-protocol'
+import { atomicWriteFileSync } from './atomic-file.js'
+import { stateDir } from './config.js'
+import type { MachineCredential } from './credentials.js'
+
+interface SendAttemptRecord {
+  version: 1
+  attempt_id: string
+  fingerprint: string
+  idempotency_key: string
+  credential_tag: string
+  machine_id: string
+  service: string
+  created_at: string
+  expires_at: string
+}
+
+export const SEND_ATTEMPT_TTL_MS = 24 * 60 * 60 * 1000
+
+/** Stable pre-upload media identities used only inside the keyed draft digest. */
+export function semanticMediaIds(images: readonly string[], cwd: string): string[] {
+  return images.map((image) => {
+    if (image.startsWith('med_')) return image
+    const digest = createHash('sha256')
+    if (/^https?:\/\//i.test(image)) digest.update(`url\0${image}`)
+    else digest.update('file\0').update(readFileSync(path.resolve(cwd, image)))
+    return `med_retry_${digest.digest('base64url')}`
+  })
+}
+
+function directory(env: NodeJS.ProcessEnv): string {
+  return path.join(stateDir(env), 'send-attempts')
+}
+
+function credentialTag(credential: MachineCredential): string {
+  return createHmac('sha256', credential.secret)
+    .update('notifai-send-attempt-credential-v1')
+    .digest('base64url')
+}
+
+/** A keyed digest proves equality without persisting notification content. */
+export function sendDraftFingerprint(
+  draft: NotificationDraftT,
+  credential: MachineCredential,
+): string {
+  return createHmac('sha256', credential.secret)
+    .update('notifai-send-draft-v1\0')
+    .update(JSON.stringify(draft))
+    .digest('base64url')
+}
+
+function parseRecord(file: string): SendAttemptRecord | null {
+  let descriptor: number | undefined
+  try {
+    const before = lstatSync(file)
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+    if (before.isSymbolicLink() || !before.isFile() || (uid !== undefined && before.uid !== uid)) {
+      return null
+    }
+    const flags = constants.O_RDONLY | (process.platform === 'win32' ? 0 : constants.O_NOFOLLOW)
+    descriptor = openSync(file, flags)
+    const opened = fstatSync(descriptor)
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) return null
+    const value = JSON.parse(readFileSync(descriptor, 'utf8')) as Partial<SendAttemptRecord>
+    return value.version === 1 &&
+      typeof value.attempt_id === 'string' &&
+      typeof value.fingerprint === 'string' &&
+      typeof value.idempotency_key === 'string' &&
+      typeof value.credential_tag === 'string' &&
+      typeof value.machine_id === 'string' &&
+      typeof value.service === 'string' &&
+      typeof value.created_at === 'string' &&
+      typeof value.expires_at === 'string'
+      ? value as SendAttemptRecord
+      : null
+  } catch {
+    return null
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor)
+  }
+}
+
+function liveRecords(
+  env: NodeJS.ProcessEnv,
+  credential: MachineCredential,
+  now: number,
+): SendAttemptRecord[] {
+  const dir = directory(env)
+  if (!existsSync(dir)) return []
+  const directoryStat = lstatSync(dir)
+  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+  if (
+    directoryStat.isSymbolicLink() ||
+    !directoryStat.isDirectory() ||
+    (uid !== undefined && directoryStat.uid !== uid)
+  ) return []
+  const tag = credentialTag(credential)
+  const records: SendAttemptRecord[] = []
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue
+    const file = path.join(dir, name)
+    const record = parseRecord(file)
+    const expired = record === null || Date.parse(record.expires_at) <= now
+    const rotated = record !== null && (
+      record.machine_id !== credential.machineId ||
+      record.service !== credential.baseUrl ||
+      record.credential_tag !== tag
+    )
+    if (expired || rotated) {
+      rmSync(file, { force: true })
+      continue
+    }
+    records.push(record)
+  }
+  return records
+}
+
+export type BeginAttempt =
+  | { ok: true; attemptId: string; idempotencyKey: string; replay: boolean }
+  | { ok: false; code: 'retry_not_found' | 'retry_ambiguous'; message: string }
+
+export function beginSendAttempt(options: {
+  env: NodeJS.ProcessEnv
+  credential: MachineCredential
+  fingerprint: string
+  retry: boolean
+  idempotencyKey?: string
+  now?: number
+}): BeginAttempt {
+  const now = options.now ?? Date.now()
+  const live = liveRecords(options.env, options.credential, now)
+  if (options.retry) {
+    const matches = live.filter((record) => record.fingerprint === options.fingerprint)
+    if (matches.length === 0) {
+      return {
+        ok: false,
+        code: 'retry_not_found',
+        message: 'No unresolved opaque attempt matches this exact send on the current Approved Machine.',
+      }
+    }
+    if (matches.length > 1) {
+      return {
+        ok: false,
+        code: 'retry_ambiguous',
+        message: 'More than one unresolved opaque attempt matches this exact send; refusing to guess or create another notification.',
+      }
+    }
+    const match = matches[0]!
+    return { ok: true, attemptId: match.attempt_id, idempotencyKey: match.idempotency_key, replay: true }
+  }
+
+  const attemptId = `sat_${randomBytes(12).toString('base64url')}`
+  const idempotencyKey = options.idempotencyKey ?? `cli-${randomBytes(12).toString('base64url')}`
+  const record: SendAttemptRecord = {
+    version: 1,
+    attempt_id: attemptId,
+    fingerprint: options.fingerprint,
+    idempotency_key: idempotencyKey,
+    credential_tag: credentialTag(options.credential),
+    machine_id: options.credential.machineId,
+    service: options.credential.baseUrl,
+    created_at: new Date(now).toISOString(),
+    expires_at: new Date(now + SEND_ATTEMPT_TTL_MS).toISOString(),
+  }
+  atomicWriteFileSync(
+    path.join(directory(options.env), `${attemptId}.json`),
+    `${JSON.stringify(record)}\n`,
+    { mode: 0o600, directoryMode: 0o700, requireCurrentUserOwner: true },
+  )
+  return { ok: true, attemptId, idempotencyKey, replay: false }
+}
+
+export function settleSendAttempt(env: NodeJS.ProcessEnv, attemptId: string): void {
+  rmSync(path.join(directory(env), `${attemptId}.json`), { force: true })
+}

package/src/session-activation.ts

@@ -1,29 +1,46 @@
 import type { HookHarness } from './hooks.js'
+import { Buffer } from 'node:buffer'
+import { GUIDANCE_CONTEXT_MAX_BYTES, boundedEffectiveGuidance } from './guidance-render.js'
 
-/**
- * Model-visible session bootstrap. It names the installed capability and its
- * authoritative sources without restating any notification policy that the
- * user may have overridden.
- */
-export const SESSION_ACTIVATION_CONTEXT =
-  'Notifai is active for this session, even when the user did not mention it. ' +
-  'Before beginning task work, use the Notifai skill and run `notifai guidance`; its resolved guidance governs notification decisions for Agent Events. ' +
-  'Missing skill or CLI readiness is handled through `notifai init` and its diagnosis. ' +
-  'For delegated work, the parent owns User-visible Notification Requests unless it explicitly delegates that ownership; workers report Agent Events to the parent and do not send independently.'
+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.'
+
+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.'
+
+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.'
+
+function rootActivationContext(cwd: string, env: NodeJS.ProcessEnv): string {
+  const guidance = boundedEffectiveGuidance({
+    cwd,
+    env,
+    maxBytes: GUIDANCE_CONTEXT_MAX_BYTES - Buffer.byteLength(`${ROOT_OWNERSHIP}\n\n`, 'utf8'),
+  })
+  return `${ROOT_OWNERSHIP}\n\n${guidance.ok ? guidance.content : guidance.fallback}`
+}
 
 /** One lifecycle meaning, encoded for each harness output contract. */
 export function sessionActivationOutput(
   harness: HookHarness | undefined,
-  hookEventName: 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit',
+  hookEventName: 'SessionStart' | 'SubagentStart',
+  cwd: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
 ): string | undefined {
+  const context = hookEventName === 'SubagentStart'
+    ? WORKER_ACTIVATION_CONTEXT
+    : rootActivationContext(cwd, env)
+  if (harness === 'opencode') return context
   if (harness === 'cursor') {
-    return JSON.stringify({ additional_context: SESSION_ACTIVATION_CONTEXT })
+    return JSON.stringify({ additional_context: context })
   }
   if (harness === 'claude-code' || harness === 'codex') {
     return JSON.stringify({
       hookSpecificOutput: {
         hookEventName,
-        additionalContext: SESSION_ACTIVATION_CONTEXT,
+        additionalContext: context,
       },
     })
   }
@@ -35,11 +52,11 @@ export function sessionActivationOutput(
  * to the model. Its native post-Stop follow-up is the narrow fallback and is
  * claimed once per conversation by the hook-state layer.
  */
-export function cursorStopActivationOutput(): string {
+export function cursorStopActivationOutput(
+  cwd: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
+): string {
   return JSON.stringify({
-    followup_message: SESSION_ACTIVATION_CONTEXT.replace(
-      'Before beginning task work,',
-      'Before finalizing the Agent Event from the turn that just ended,',
-    ),
+    followup_message: rootActivationContext(cwd, env),
   })
 }