@raidiant/notifai 10.1.1 → 10.1.2

package/src/commands-guidance.ts

@@ -1,181 +0,0 @@
-import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
-import path from 'node:path'
-import { EXIT, type CommandDeps } from './commands-core.js'
-import { GUIDANCE_TRUST_PREAMBLE, SHIPPED_GUIDANCE, shippedGuidanceTopic } from './guidance-content.js'
-import {
-  GUIDANCE_TOPIC_MAX_BYTES,
-  GUIDANCE_TOPIC_PATTERN,
-  findProjectGuidanceDir,
-  globalGuidanceDir,
-  personalProjectGuidanceDir,
-  resolveGuidance,
-} from './guidance.js'
-import { renderGuidance } from './guidance-render.js'
-
-// ---------------------------------------------------------------------------
-// guidance show / set / unset
-// ---------------------------------------------------------------------------
-
-/**
- * The whole effective guidance, ready to be followed as read.
- *
- * The trust preamble comes first and belongs to the CLI: it says who supplied
- * each topic and what no topic may ask for. Each topic then follows its own
- * marker, so a reader can tell the User's standing word from a repository's
- * house rules from the shipped default without the output stopping being
- * Markdown.
- */
-export function guidanceShowCommand(deps: CommandDeps, flags: { json?: boolean }): number {
-  const topics = resolveGuidance({ cwd: deps.cwd, env: deps.env })
-  if (flags.json) {
-    deps.io.out(
-      JSON.stringify(
-        {
-          trust: GUIDANCE_TRUST_PREAMBLE,
-          topics: topics.map((topic) => ({
-            name: topic.name,
-            source: topic.source,
-            authority: topic.authority,
-            summary: topic.summary,
-            content: topic.content,
-          })),
-        },
-        null,
-        2,
-      ),
-    )
-    return EXIT.ok
-  }
-  deps.io.out(renderGuidance(topics))
-  return EXIT.ok
-}
-
-type GuidanceMutationFlags = {
-  project?: boolean | undefined
-  local?: boolean | undefined
-  yes?: boolean | undefined
-}
-type GuidanceLayer = 'global' | 'project' | 'local'
-
-/**
- * Where a topic file for one layer lives. The project layer prefers an
- * existing `.notifai/guidance` up the tree and otherwise starts one at cwd,
- * the same anchoring `config set --project` uses for its file.
- */
-function guidanceLayerDir(deps: CommandDeps, layer: GuidanceLayer): string {
-  if (layer === 'local') return personalProjectGuidanceDir(deps.cwd, deps.env)
-  if (layer === 'project') {
-    return findProjectGuidanceDir(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'guidance')
-  }
-  return globalGuidanceDir(deps.env)
-}
-
-async function guidanceMutationTarget(
-  deps: CommandDeps,
-  topic: string,
-  flags: GuidanceMutationFlags,
-): Promise<{ path: string; layer: GuidanceLayer } | null> {
-  if (!GUIDANCE_TOPIC_PATTERN.test(topic)) {
-    deps.io.err(
-      `"${topic}" is not a topic name. Use lowercase letters, digits, "-" and "_", e.g. ${SHIPPED_GUIDANCE.map((t) => t.name).join(', ')}.`,
-    )
-    return null
-  }
-  let layer: GuidanceLayer = flags.local ? 'local' : flags.project ? 'project' : 'global'
-  if (
-    flags.local !== true &&
-    flags.project !== true &&
-    flags.yes !== true &&
-    deps.io.interactive === true &&
-    deps.io.select
-  ) {
-    const selected = await deps.io.select('Where should this guidance live?', [
-      { value: 'global', label: 'This machine', hint: 'your standing word, applies across projects' },
-      { value: 'project', label: 'This project (shared)', hint: '.notifai/guidance/ — committed, read as project policy' },
-      { value: 'local', label: 'This project (personal)', hint: 'your standing word here, stored outside the repo' },
-    ])
-    if (selected === null) {
-      deps.io.err('No guidance layer selected.')
-      return null
-    }
-    layer = selected as GuidanceLayer
-  }
-  return { path: path.join(guidanceLayerDir(deps, layer), `${topic}.md`), layer }
-}
-
-/**
- * Writes one topic at one layer, replacing the shipped topic of that name for
- * this scope. The confirmation gate is the same one `config set` holds: the
- * user owns their standing word, so an agent writes it only with their words
- * and their say-so.
- */
-export async function guidanceSetCommand(
-  deps: CommandDeps,
-  topic: string,
-  text: string,
-  flags: GuidanceMutationFlags,
-): Promise<number> {
-  if (text.trim() === '') {
-    deps.io.err('Guidance text is empty. Pass the text, or --file <path|-> to read it.')
-    return EXIT.usage
-  }
-  if (text.length > GUIDANCE_TOPIC_MAX_BYTES) {
-    deps.io.err(`Guidance for one topic is capped at ${GUIDANCE_TOPIC_MAX_BYTES} bytes.`)
-    return EXIT.usage
-  }
-  const target = await guidanceMutationTarget(deps, topic, flags)
-  if (target === null) return EXIT.usage
-
-  const shipped = shippedGuidanceTopic(topic)
-  if (!flags.yes) {
-    const replaces =
-      shipped === undefined
-        ? `Add guidance topic "${topic}"`
-        : `Replace the shipped "${topic}" guidance for this scope`
-    const confirmed = await deps.io.confirm(`${replaces} at ${target.path}?`)
-    if (!confirmed) {
-      deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.')
-      return EXIT.usage
-    }
-  }
-
-  mkdirSync(path.dirname(target.path), { recursive: true })
-  writeFileSync(target.path, text.endsWith('\n') ? text : `${text}\n`)
-  deps.io.out(`Wrote ${topic} to ${target.path}`)
-  if (shipped !== undefined) {
-    deps.io.out(`This file now replaces the shipped "${topic}" guidance wherever it applies.`)
-  }
-  // A shared file is committed and travels to everyone who clones this
-  // repository, where it is read as the project's policy rather than as
-  // anyone's personal standing word. Worth saying at the moment of writing:
-  // the same sentence means something different in the two locations.
-  if (target.layer === 'project') {
-    deps.io.out(
-      'This is shared project policy: it is committed, everyone working here reads it, and it is never read as the User\'s own standing word. Use --local for a personal preference.',
-    )
-  }
-  return EXIT.ok
-}
-
-export async function guidanceUnsetCommand(
-  deps: CommandDeps,
-  topic: string,
-  flags: GuidanceMutationFlags,
-): Promise<number> {
-  const target = await guidanceMutationTarget(deps, topic, flags)
-  if (target === null) return EXIT.usage
-  if (!existsSync(target.path)) {
-    deps.io.out(`${topic} is not set at ${target.path}`)
-    return EXIT.ok
-  }
-  if (!flags.yes) {
-    const confirmed = await deps.io.confirm(`Remove ${target.path}?`)
-    if (!confirmed) {
-      deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.')
-      return EXIT.usage
-    }
-  }
-  rmSync(target.path, { force: true })
-  deps.io.out(`Removed ${target.path}; the inherited guidance now applies.`)
-  return EXIT.ok
-}

package/src/commands-harness-context.ts

@@ -1,207 +0,0 @@
-import {
-  hermesClassicCliLocalInstance,
-  isHookInstallableHarness,
-  type HermesClassicCliLocalInstance,
-  type SourceContextHarness,
-} from './harnesses.js'
-import { readLiveProjectSessionPointers, readSessionState } from './hooks.js'
-
-/**
- * Exact evidence that this shell command is running inside one supported
- * harness. Configuration-directory variables are deliberately absent: they
- * describe where a tool stores files, not which tool owns the current shell.
- * OpenCode's generated plugin supplies the Notifai-owned marker because its
- * plugin API exposes Agent Session identity but the ordinary environment does not.
- *
- * Hermes contributes `HERMES_SESSION_ID` only — the durable Agent Session id
- * bridged into tool subprocesses. `HERMES_SESSION_KEY` is a gateway routing
- * key and must never be treated as Agent Session identity.
- */
-export interface ActiveHarnessSession {
-  harness: SourceContextHarness
-  label: string
-  sessionId?: string
-  /** Exact surface/backend cell proven for this marker envelope. */
-  integrationInstance?: HermesClassicCliLocalInstance
-  /** Trusted human title published by this harness's managed adapter. */
-  sessionLabel?: string
-  /** The harness has only a temporary placeholder title so far. */
-  sessionLabelPending?: boolean
-}
-
-/**
- * Every harness marker present in this environment, in declared order.
- *
- * Order here is a last resort, not an answer. A harness exports its markers
- * into every process it starts, so a nested harness inherits its parent's
- * markers alongside its own and the environment alone cannot say which of them
- * owns this shell; `resolveActiveHarness` settles that with live evidence.
- */
-function harnessEnvCandidates(env: NodeJS.ProcessEnv): ActiveHarnessSession[] {
-  const candidates: ActiveHarnessSession[] = []
-  if (env['NOTIFAI_ACTIVE_HARNESS'] === 'opencode') {
-    const sessionId = env['NOTIFAI_ACTIVE_SESSION_ID']
-    const sessionLabel = env['NOTIFAI_ACTIVE_SESSION_LABEL']
-    const sessionLabelPending = env['NOTIFAI_ACTIVE_SESSION_LABEL_PENDING'] === '1'
-    candidates.push({
-      harness: 'opencode',
-      label: 'OpenCode',
-      ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
-      ...(sessionLabel === undefined || sessionLabel === '' ? {} : { sessionLabel }),
-      ...(sessionLabelPending ? { sessionLabelPending: true } : {}),
-    })
-  }
-  if (env['NOTIFAI_ACTIVE_HARNESS'] === 'openclaw') {
-    const sessionId = env['NOTIFAI_ACTIVE_SESSION_ID']
-    candidates.push({
-      harness: 'openclaw',
-      label: 'OpenClaw',
-      ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
-    })
-  }
-  if (env['CLAUDECODE'] === '1') {
-    const sessionId = env['CLAUDE_CODE_SESSION_ID']
-    candidates.push({
-      harness: 'claude-code',
-      label: 'Claude Code',
-      ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
-    })
-  }
-  const codexSession = env['CODEX_THREAD_ID']
-  if (codexSession !== undefined && codexSession !== '') {
-    candidates.push({ harness: 'codex', label: 'Codex', sessionId: codexSession })
-  }
-  if ((env['CURSOR_AGENT'] ?? '') !== '') candidates.push({ harness: 'cursor', label: 'Cursor' })
-  const hermesSession = env['HERMES_SESSION_ID']
-  if (hermesSession !== undefined && hermesSession !== '') {
-    const integrationInstance = hermesClassicCliLocalInstance(env)
-    candidates.push({
-      harness: 'hermes',
-      label: 'Hermes',
-      sessionId: hermesSession,
-      ...(integrationInstance === null ? {} : { integrationInstance }),
-    })
-  }
-  return candidates
-}
-
-interface ActiveHarnessResolution {
-  active: ActiveHarnessSession | null
-  /**
-   * Markers of harnesses that could equally own this shell, present only when
-   * nothing here has fired yet and declared order had to pick. Whatever is
-   * reported then has to hold for every one of them.
-   */
-  contested: ActiveHarnessSession[]
-}
-
-/**
- * Which Agent Session owns this shell, when several claim to.
- *
- * Nesting is ordinary: an orchestrator running inside Claude Code starts a
- * Codex session, and that Codex process inherits `CLAUDECODE` and
- * `CLAUDE_CODE_SESSION_ID` on top of its own `CODEX_THREAD_ID`. The mirror is
- * just as ordinary, so no fixed precedence between two markers can be right —
- * whichever one it favours is wrong in the opposite nesting, and the cost is
- * silent: `ask` looks up a session that is not this one, and every remedy the
- * agent is told to try addresses a harness that is not running here.
- *
- * The general rule is to prefer the most specific *live* signal over inherited
- * environment. An inherited marker is a claim about some ancestor process; a
- * session id that names an entry in this directory's live pointer index is
- * evidence that that exact session fired a hook here and its state still
- * exists. Live evidence therefore wins over declared order, and the most
- * recently active pointer wins between two live candidates: the harness whose
- * turn is running is the one that fired last, while its parent sits blocked on
- * the child it started. Declared order decides only when nothing here has
- * fired yet, and it says so — every route fails closed there anyway.
- */
-export function resolveActiveHarness(
-  env: NodeJS.ProcessEnv,
-  cwd: string,
-  now: number,
-): ActiveHarnessResolution {
-  const candidates = harnessEnvCandidates(env)
-  const first = candidates[0]
-  if (first === undefined) return { active: null, contested: [] }
-  if (candidates.length === 1) return { active: first, contested: [] }
-
-  // A send-only harness has no hook evidence, so live pointer/state of a
-  // hook-installable parent cannot prove which nested process owns this
-  // shell. Mixing Hermes with another marker therefore stays contested.
-  const mixedWithSendOnly = candidates.some((candidate) => !isHookInstallableHarness(candidate.harness))
-  if (mixedWithSendOnly) return { active: first, contested: candidates }
-
-  // Exact lifecycle state is machine-global and survives a command moving to
-  // another linked checkout. Prefer it before the checkout-local
-  // pointer. A unique newest hook event proves which nested harness owns this
-  // shell; ties and missing evidence remain contested and fail closed.
-  const evidenced = candidates.flatMap((candidate) => {
-    if (candidate.sessionId === undefined) return []
-    const state = readSessionState(candidate.sessionId, env)
-    if (state.harness !== candidate.harness) return []
-    const activity = Math.max(state.last_prompt_at ?? 0, state.last_stop_at ?? 0)
-    return activity > 0 ? [{ candidate, activity }] : []
-  })
-  if (evidenced.length > 0) {
-    evidenced.sort((left, right) => right.activity - left.activity)
-    if (evidenced.length === 1 || evidenced[0]!.activity > evidenced[1]!.activity) {
-      return { active: evidenced[0]!.candidate, contested: [] }
-    }
-    return { active: first, contested: candidates }
-  }
-  for (const pointer of readLiveProjectSessionPointers(cwd, env, now)) {
-    const owner = candidates.find(
-      (candidate) =>
-        candidate.harness === pointer.harness && candidate.sessionId === pointer.sessionId,
-    )
-    if (owner !== undefined) return { active: owner, contested: [] }
-  }
-  return { active: first, contested: candidates }
-}
-
-export function activeHarnessSession(
-  env: NodeJS.ProcessEnv,
-  cwd: string,
-  now: number,
-): ActiveHarnessSession | null {
-  return resolveActiveHarness(env, cwd, now).active
-}
-
-/**
- * Source Context attribution. Hook-installable nesting still uses declared
- * order when nothing has fired — that existing send behavior is preserved.
- * A contested mix that includes a send-only harness (Hermes) fails closed:
- * the wrong Agent Session would otherwise be named as the owner.
- */
-export function sourceContextHarnessSession(
-  env: NodeJS.ProcessEnv,
-  cwd: string,
-  now: number,
-): ActiveHarnessSession | null {
-  const { active, contested } = resolveActiveHarness(env, cwd, now)
-  if (contested.some((candidate) => !isHookInstallableHarness(candidate.harness))) {
-    return null
-  }
-  if (active?.harness === 'hermes' && active.integrationInstance === undefined) return null
-  return active
-}
-
-/**
- * The pid of the Claude Code session this hook belongs to.
- *
- * Claude exports `CLAUDE_PID` to its hooks, and that is the authoritative
- * answer. `process.ppid` agrees with it today — the hook command runs through
- * a shell, but the shell `exec`s, so this process's parent *is* the session
- * (probed against a live 2.1.228 session) — and it remains the fallback for a
- * harness build that stops exporting the variable.
- *
- * Preferring the explicit value costs a line and removes a silent failure: if
- * this ever resolved to a shell instead, no session descriptor would match, the
- * route could not prove own-child ownership, and every answer would degrade to
- * hold-for-next-turn with nothing reported as wrong.
- */
-export function claudeSessionPid(env: NodeJS.ProcessEnv): number {
-  const declared = Number(env['CLAUDE_PID'])
-  return Number.isInteger(declared) && declared > 0 ? declared : process.ppid
-}

package/src/commands-hook-shape.ts

@@ -1,69 +0,0 @@
-import {
-  NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS,
-  handlerEvent,
-  QUESTION_STOP_TIMEOUT_SECONDS,
-  stopHandlerIsDetached,
-  type Installation,
-} from './install-hooks.js'
-
-/**
- * Whether an installed Stop handler declares the shape its harness needs.
- *
- * The three answers differ, and getting one wrong fails silently in a
- * different way each time:
- *
- *   - Claude Code's handler must be `async: true`, or the waiter holds the
- *     user's turn for its whole wait instead of returning at once. It must
- *     also declare a `timeout`, because the harness default is 600 s and the
- *     kill is silent — the backgrounded waiter vanishes and the answer the
- *     user already gave is never delivered.
- *   - Codex must declare the same full-window timeout. That changes its trusted
- *     definition and deliberately requires the User to approve it once.
- *   - Everything else cannot own asynchronous Question Routing; it receives
- *     only the shorter bounded cleanup/refusal timeout.
- */
-export function stopShapeProblems(
-  installation: Installation,
-  platform: NodeJS.Platform = process.platform,
-): string[] {
-  const problems: string[] = []
-  for (const handler of installation.handlers.filter(
-    (entry) => handlerEvent(entry.command) === 'stop',
-  )) {
-    if (stopHandlerIsDetached(installation.harness, platform)) {
-      if (handler.async !== true) {
-        problems.push(
-          `${installation.file} declares a blocking Stop handler; the Claude Code wake route needs \`async: true\` so the turn ends while the waiter runs`,
-        )
-      }
-      if (handler.timeout === undefined || handler.timeout < QUESTION_STOP_TIMEOUT_SECONDS) {
-        problems.push(
-          `${installation.file} gives Stop ${handler.timeout ?? 'no'} declared seconds; Claude Code then kills the backgrounded waiter silently before the complete answer window, so it needs an explicit ${QUESTION_STOP_TIMEOUT_SECONDS}s`,
-        )
-      }
-      continue
-    }
-    if (installation.harness === 'codex' || installation.harness === 'claude-code') {
-      if (handler.async === true) {
-        problems.push(
-          `${installation.file} declares an asynchronous ${installation.harness} Stop handler, but this platform needs the blocking continuation so the harness consumes the answer output`,
-        )
-      }
-      if (handler.timeout === undefined || handler.timeout < QUESTION_STOP_TIMEOUT_SECONDS) {
-        problems.push(
-          `${installation.file} gives Stop ${handler.timeout ?? 'no'}s, but ${installation.harness} Question Routing requires ${QUESTION_STOP_TIMEOUT_SECONDS}s to own the complete answer window`,
-        )
-      }
-      continue
-    }
-    if (
-      handler.timeout === undefined ||
-      handler.timeout < NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS
-    ) {
-      problems.push(
-        `${installation.file} gives Stop ${handler.timeout ?? 'no'}s, but the non-routing blocking handler requires ${NON_ROUTING_BLOCKING_STOP_TIMEOUT_SECONDS}s`,
-      )
-    }
-  }
-  return problems
-}