@raidiant/notifai 10.1.1 → 10.1.2

package/dist/skill-source/notifai/references/harness-setup.md

@@ -0,0 +1,220 @@
+# Harness setup and recovery
+
+The mechanics behind installing Notifai, routing questions to devices, and
+working out why either is not happening. Read it when you are installing,
+diagnosing, or recovering — not before.
+
+- [Signing this machine in](#signing-this-machine-in)
+- [Install deliberately](#install-deliberately)
+- [Activation by harness](#activation-by-harness)
+- [How the answer gets back to the agent](#how-the-answer-gets-back-to-the-agent)
+- [Bounded recovery](#bounded-recovery)
+- [Reading the record](#reading-the-record)
+- [Settings and environment](#settings-and-environment)
+
+## Signing this machine in
+
+Run `notifai login` yourself. It opens a browser page only the user can approve.
+
+In a headless or remote shell, `notifai login --no-open` prints the approval URL
+instead of trying to open a browser — hand the user that URL. `--name <name>`
+sets what the machine is called in their dashboard; the hostname is the default.
+
+`notifai auth status --json` says whether this machine is paired.
+`notifai auth access --json` says whether the account has access, including
+access already requested and waiting on a person — not something to ask them to
+do again. They fail differently and are worth separating before you report
+either as broken.
+`notifai logout` removes the stored credential.
+
+## Install deliberately
+
+Flagless `notifai init --json` needs no answer and closes everything before
+this point. Hooks place files, so this is where a question belongs: ask setup
+scope and whether they want questions routed, in the same structured question.
+If they do, let init install and assess the hooks in their chosen scope. Never
+tell the user to run setup commands themselves.
+
+```bash
+notifai init --hooks --setup-scope <project|global> --json
+```
+
+A machine-global Notifai skill is guidance, not routing evidence. The active
+harness needs its own installed hook and a current session pointer.
+
+Installed definitions call one stable user-level adapter at
+`~/.notifai/bin/hook-adapter`. `hooks install` atomically retargets that adapter
+to the current CLI while leaving definition bytes unchanged across Node/NVM,
+package-manager, CLI-version, checkout, XDG directory, and Notifai preference
+changes. Stop definitions differ by harness: Claude Code's runs asynchronously
+with an explicit timeout above the longest answer window (POSIX hosts only — on
+Windows it blocks like the others), and Codex declares the same full-window
+timeout; prompt-submit and session-end retain fixed short limits on both.
+Migrating an older Codex definition requires one unavoidable `/hooks` approval;
+later upgrades must not require another.
+
+`notifai ask --json` owns its admission check. On failure, branch on its stable
+`code`, `check_id`, `exit_code`, and `remedy`; do not run a routine doctor pass
+first. Historical UserPromptSubmit and Stop evidence remains part of that
+fail-closed check. Ask exposes no `--session-id` override and will not guess one.
+
+`hooks-wake-route` reports, without probing anything, whether an answer could
+start a turn in this exact Agent Session on its own. It never blocks: when it
+cannot, the answer is held and replayed at the Agent Session's next turn instead.
+
+Notifai never writes trust approvals. If its diagnosis and Codex disagree,
+`/hooks` is authoritative.
+
+The prepared User message for this human-only action is:
+
+> Open `/hooks` in Codex, approve or enable the Notifai handlers, then tell me
+> when it is done. I will finish setup and verify a fresh session.
+
+## Activation by harness
+
+- **Claude Code:** run the installer if needed, start one fresh Agent Session,
+  send one prompt, then run `notifai doctor`. An already-running Agent Session cannot
+  receive newly installed `SessionStart` context. If SessionStart is absent,
+  reinstall the current hooks and start a fresh Agent Session; UserPromptSubmit
+  records presence and question lifecycle only and never substitutes for
+  lifecycle activation. Claude's SubagentStart gives ordinary workers the
+  reporting-only context; explicit textual delegation makes a worker load the
+  skill and guidance as the new Notification Request owner.
+- **Codex:** run `notifai hooks install --harness codex`. If `hooks-trust`
+  fails, open `/hooks` in Codex and approve or enable the Notifai handlers.
+  Then start one fresh Agent Session, send one prompt, and run `notifai doctor`. If
+  SessionStart is absent, reinstall the current hooks and start a fresh Agent Session;
+  UserPromptSubmit does not activate it. Codex SubagentStart uses the same
+  reporting-only worker contract and explicit textual delegation rule as
+  Claude. Codex resolves project hooks from the main repository. In a
+  linked worktree, the installer writes the shared file to
+  the main checkout and creates the project-layer `.codex` directory in the
+  current worktree; run it once in each new worktree.
+- **Cursor:** start one fresh conversation, send one prompt, and let the first
+  completed or errored turn finish. Cursor's `SessionStart` context is currently
+  lossy, so one visible synthetic follow-up activates Notifai through its native
+  Stop contract; cancellation does not trigger it, and a live question
+  continuation takes priority. Then run `notifai doctor`. The agent shell does
+  not create a separately activated context for delegated work: it remains
+  under the parent Agent Session and its explicit Notification Request ownership. It
+  does not expose the exact conversation id needed to prove which concurrent Agent Session
+  invoked `notifai ask`, so asynchronous ask fails closed. Use blocking
+  `notifai send --reply` for questions.
+- **OpenCode:** restart after installation because plugins load at startup,
+  then start one fresh Agent Session, send one prompt, and run `notifai doctor`.
+  Notifai owns its generated plugin file and will not overwrite a foreign one.
+  The plugin treats a session with `parentID` as a worker. When relationship
+  lookup fails or returns unusable data it also fails safe as a non-sending
+  worker; only a proven parent Agent Session receives owner context. Explicit textual
+  delegation promotes that worker through the same skill-and-guidance rule.
+  OpenCode has no locally proven exactly-once continuation after `session.idle`,
+  so `notifai ask` fails closed instead of accepting an answer into a void.
+  Use a blocking `notifai send --reply` question when its answer must return to
+  the agent without another human prompt.
+- **OpenClaw:** restart the Gateway after installation because plugins load at
+  startup, then start one fresh Agent Session, send one prompt, and run
+  `notifai doctor`. Notifai owns its generated Gateway plugin and will not
+  overwrite a foreign one. Exact Agent Session identity is the OpenClaw
+  `sessionKey`; `sessionId` is a rotating generation and is never used as the
+  session id. A session key containing `:subagent:` or an ACP nested context
+  is a worker. Missing identity fails safe as a non-sending worker; only a
+  proven parent Agent Session receives owner context. Explicit textual
+  delegation promotes that worker through the same skill-and-guidance rule.
+  OpenClaw has no locally proven exactly-once continuation after `agent_end`,
+  so `notifai ask` fails closed instead of accepting an answer into a void.
+  Use a blocking `notifai send --reply` question when its answer must return to
+  the agent without another human prompt. Do not treat `/stop` as turn-end.
+- **Hermes:** classic CLI on the local terminal backend can send. Notifai reads
+  exact `HERMES_SESSION_ID` and derives git branch and worktree from the actual
+  invocation cwd. Do not run `notifai hooks install --harness hermes` — managed
+  setup, lifecycle activation, and Question Routing are unsupported. Use a
+  blocking `notifai send --reply` question. Install the Notifai skill through
+  `npx skills`; no Hermes plugin may vendor a copy. Nested inherited harness
+  markers fail closed. TUI, gateway, API, ACP, and remote backends are not
+  this baseline.
+
+Do not claim managed hook, activation, or Question Routing support for a
+harness that is absent from `notifai hooks install --help`. Classic Hermes CLI
+can send with Source Context without those.
+
+## How the answer gets back to the agent
+
+The session that registered a question owns the answer's return. The last
+meter differs per harness:
+
+- **Claude Code:** the Stop hook is asynchronous. It returns at once, so the
+  turn is never held and the terminal stays the user's, and the same process
+  keeps waiting out of band for the complete answer window. When the answer
+  arrives it is posted to that Agent Session's own inbox socket: an idle Agent
+  Session starts a new turn with it, and a busy one receives it when its current
+  turn ends. An Agent Session that is provably gone is cold-resumed instead —
+  never one whose liveness probe cannot rule it out.
+- **Codex:** the Stop hook is the waiter. It holds until the answer arrives or
+  the complete answer window ends, then continues the session by returning
+  `decision: block`.
+- **Crash recovery:** the answer journal protects an accepted answer if an
+  owner process or its route fails. It is not the normal last meter for an
+  unexpired question.
+
+An accepted answer is never dropped and never delivered twice, so a question
+that has not come back yet is still coming: do not re-ask it.
+
+At the `ask_grace_seconds` default of `0`, the question reaches devices as soon
+as the asking turn ends. A positive value keeps it in the terminal for that
+long first, so an answer typed there wins without a notification ever leaving.
+`reply_window_seconds` then controls how long the answer is accepted and how
+long Question Routing keeps an exact return path to this Agent Session. The
+grace window is skipped when a question from this Agent Session is already
+waiting on the user's devices: they have been interrupted already, and holding
+the second question back would only delay it.
+
+## Bounded recovery
+
+Follow the exact `notifai doctor` diagnostic. Common recovery is one repair,
+one fresh activation, and one new doctor check. Stop if the current pointer
+belongs to another active session or if the hook still has not fired; ask the
+user or coordinator instead of retrying indefinitely.
+
+If a companion device is missing, ask the user to open a supported companion
+build, sign in, and grant notification permission. Do not emulate that, and do
+not treat Provider Acceptance as Companion Receipt proof.
+
+To stop routing questions from this project, `notifai hooks uninstall`; add
+`--global` to remove a machine-wide install, and `--harness <name>` to name one
+when several are wired.
+
+## Reading the record
+
+`notifai logs` narrows several ways, and they compose:
+
+- `--request <id>` · `--run <id>` · `--session <id>` — one notification, one
+  invocation, one Agent Session
+- `--event <name>` (repeatable) · `--grep <text>` · `--level error`
+- `--since 10m|2h|1d|<ISO 8601>` · `-n <count>` · `--all` · `--project <id>` ·
+  `--all-projects`
+- `--json` for one record per line, `--path` for where the files are
+
+`--clear` deletes the user's local record. It is theirs, and nothing else keeps
+a copy — do not run it to tidy up.
+
+## Settings and environment
+
+`notifai config explain <key> [--json]` gives the full explanation of one
+setting; `notifai config show --explain` includes advanced keys and the file
+each value came from. Beyond the usual scopes, `--session <id>` writes a
+preference that lasts only for one Agent Session.
+
+`ask_notifications` is the setting that turns question routing off for a scope;
+`ask_grace_seconds` is the terminal-first window described above;
+`reply_window_seconds` is how long an answer is still accepted, a day by
+default and up to three.
+
+Those are three different controls and only the last one decides whether an
+answer is still wanted. Question Routing owns that complete window: Claude Code
+waits out of band and wakes the Agent Session, while Codex keeps the asking turn
+held. The journal is crash recovery, not the ordinary delivery path.
+
+`NOTIFAI_NO_INPUT=1` guarantees no command will ever prompt, which is what you
+want in CI or any shell with nobody at it. `NOTIFAI_CREDENTIALS=file` stores the
+machine credential in a plaintext file rather than the OS keychain — only when
+the user has asked for it, and never on a shared machine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "10.1.1",
+  "version": "10.1.2",
   "type": "module",
   "description": "Send native device notifications from agents and local programs",
   "bin": {
@@ -8,20 +8,11 @@
   },
   "files": [
     "dist",
-    "src",
-    "tsconfig.json",
     "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.json && node ../../scripts/chmod-cli-bin.mjs",
-    "pretest": "pnpm run build",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node ../../scripts/run-cli-tests.mjs",
-    "prepack": "pnpm run build"
-  },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "6.0.2",
+    "@raidiant/notifai-protocol": "6.0.3",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"
@@ -31,7 +22,7 @@
     "vitest": "^3.2.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=20.12.0"
   },
   "license": "Apache-2.0",
   "author": "Rafael Vidaurre",
@@ -58,5 +49,11 @@
     "ai",
     "claude",
     "codex"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.json && node ../../scripts/copy-shipped-skill.mjs && node ../../scripts/chmod-cli-bin.mjs",
+    "pretest": "pnpm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node ../../scripts/run-cli-tests.mjs"
+  }
+}

package/src/atomic-file.ts

@@ -1,198 +0,0 @@
-import { randomBytes } from 'node:crypto'
-import {
-  chmodSync,
-  closeSync,
-  fsyncSync,
-  lstatSync,
-  mkdirSync,
-  openSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs'
-import path from 'node:path'
-
-export interface AtomicWriteOptions {
-  /** Mode for a newly created file. Existing regular files keep their mode. */
-  mode?: number
-  /** False when a managed executable must keep the requested mode on repair. */
-  preserveMode?: boolean
-  /** Reject a target owned by another user instead of replacing it. */
-  requireCurrentUserOwner?: boolean
-  /**
-   * POSIX directory mode applied to the parent. Defaults to 0o700 when
-   * `requireCurrentUserOwner` is set so credential and config dirs match the
-   * hook-adapter and log directories.
-   */
-  directoryMode?: number
-}
-
-/**
- * Replace one regular file without exposing a truncated intermediate state.
- *
- * The temporary file is a unique sibling, so rename is atomic on every
- * supported filesystem. The contents are flushed before the rename, and a
- * symlink target is refused instead of silently writing through it.
- */
-export function atomicWriteFileSync(
-  file: string,
-  contents: string,
-  options: AtomicWriteOptions = {},
-): void {
-  const directory = path.dirname(file)
-  const requireCurrentUserOwner = options.requireCurrentUserOwner ?? false
-  const directoryMode = options.directoryMode ?? (requireCurrentUserOwner ? 0o700 : undefined)
-  const parent = ensureDirectory(directory, {
-    requireCurrentUserOwner,
-    ...(directoryMode === undefined ? {} : { mode: directoryMode }),
-  })
-  const target = targetMetadata(
-    file,
-    options.mode ?? 0o600,
-    options.preserveMode ?? true,
-    options.requireCurrentUserOwner ?? false,
-  )
-  const temp = path.join(
-    directory,
-    `.${path.basename(file)}.notifai-${process.pid}-${randomBytes(6).toString('hex')}.tmp`,
-  )
-  let handle: number | undefined
-  try {
-    handle = openSync(temp, 'wx', target.mode)
-    writeFileSync(handle, contents)
-    fsyncSync(handle)
-    closeSync(handle)
-    handle = undefined
-    chmodSync(temp, target.mode)
-    assertSameDirectory(directory, parent)
-    assertUnchangedTarget(file, target)
-    renameSync(temp, file)
-    syncDirectory(directory)
-  } catch (err) {
-    if (handle !== undefined) closeSync(handle)
-    try {
-      unlinkSync(temp)
-    } catch {
-      // Preserve the original error; the temp may not have been created.
-    }
-    throw err
-  }
-}
-
-/**
- * Create (or tighten) a directory that must not be world-readable.
- *
- * `mkdir` mode applies only to a newly created leaf, so an existing 0755
- * credential directory would otherwise stay world-listable. POSIX chmod of
- * the leaf is the matching repair; Windows has no equivalent mode bits.
- */
-export function ensurePrivateDirectory(directory: string): void {
-  ensureDirectory(directory, { mode: 0o700, requireCurrentUserOwner: false })
-}
-
-function ensureDirectory(
-  directory: string,
-  options: { mode?: number; requireCurrentUserOwner: boolean },
-): { dev: number; ino: number } {
-  if (options.mode === undefined) mkdirSync(directory, { recursive: true })
-  else mkdirSync(directory, { recursive: true, mode: options.mode })
-  const parent = safeDirectory(directory, options.requireCurrentUserOwner)
-  if (options.mode !== undefined && process.platform !== 'win32') {
-    chmodSync(directory, options.mode)
-  }
-  return parent
-}
-
-/** Persist the published directory entry where the host supports directory fsync. */
-function syncDirectory(directory: string): void {
-  if (process.platform === 'win32') return
-  const handle = openSync(directory, 'r')
-  try {
-    fsyncSync(handle)
-  } finally {
-    closeSync(handle)
-  }
-}
-
-/** Mode to preserve, or the mode for a new file. Refuses a non-regular target. */
-interface TargetMetadata {
-  mode: number
-  identity: { dev: number; ino: number } | null
-}
-
-function targetMetadata(
-  file: string,
-  fallback: number,
-  preserveMode: boolean,
-  requireCurrentUserOwner: boolean,
-): TargetMetadata {
-  let stat
-  try {
-    stat = lstatSync(file)
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
-      return { mode: fallback, identity: null }
-    }
-    throw err
-  }
-  if (stat.isSymbolicLink()) {
-    throw new Error(
-      `${file} is a symlink; refusing to write through it. Replace it with a regular file, ` +
-        'or use a different state directory.',
-    )
-  }
-  if (!stat.isFile()) throw new Error(`${file} is not a regular file; refusing to replace it.`)
-  if (requireCurrentUserOwner) assertCurrentUserOwns(file, stat.uid)
-  return {
-    mode: preserveMode ? stat.mode & 0o777 : fallback,
-    identity: { dev: stat.dev, ino: stat.ino },
-  }
-}
-
-function assertUnchangedTarget(file: string, target: TargetMetadata): void {
-  let current
-  try {
-    current = lstatSync(file)
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === 'ENOENT' && target.identity === null) return
-    throw new Error(`${file} changed during the atomic write; refusing to replace it.`)
-  }
-  if (
-    target.identity === null ||
-    current.dev !== target.identity.dev ||
-    current.ino !== target.identity.ino
-  ) {
-    throw new Error(`${file} changed during the atomic write; refusing to replace it.`)
-  }
-}
-
-function safeDirectory(
-  directory: string,
-  requireCurrentUserOwner: boolean,
-): { dev: number; ino: number } {
-  const stat = lstatSync(directory)
-  if (stat.isSymbolicLink() || !stat.isDirectory()) {
-    throw new Error(`${directory} is not a regular directory; refusing to write inside it.`)
-  }
-  if (requireCurrentUserOwner) assertCurrentUserOwns(directory, stat.uid)
-  return { dev: stat.dev, ino: stat.ino }
-}
-
-function assertSameDirectory(directory: string, expected: { dev: number; ino: number }): void {
-  const current = lstatSync(directory)
-  if (
-    current.isSymbolicLink() ||
-    !current.isDirectory() ||
-    current.dev !== expected.dev ||
-    current.ino !== expected.ino
-  ) {
-    throw new Error(`${directory} changed during the write; refusing to publish the file.`)
-  }
-}
-
-function assertCurrentUserOwns(file: string, owner: number): void {
-  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
-  if (uid !== undefined && owner !== uid) {
-    throw new Error(`${file} is owned by uid ${owner}, not the current user; refusing to replace it.`)
-  }
-}