@raidiant/notifai 0.3.0 → 0.5.0

package/README.md

@@ -42,10 +42,9 @@ The agent registers the question, ends its turn, and your answer comes
 back on its next turn. On iPhone the choices are buttons on the banner
 itself.
 
-By default a question stays in your terminal while you are actually at
-the keyboard, and only reaches your devices once you have stepped away —
-a push you are sitting in front of is just noise. `require_idle = false`
-turns that off if you would rather always be notified.
+By default a question reaches your devices when the agent turn ends, whether or
+not you are at the keyboard (`ask_grace_seconds = 0`). Set a positive grace
+period for a terminal-only answer window first.
 
 For a harness that cannot resume an idle agent turn, `notifai send
 --reply` blocks and waits for the answer instead.
@@ -61,6 +60,22 @@ is what lets an agent's question reach your phone without the agent
 having to cooperate — no question detection, no state in a context window
 that compaction will eat.
 
+Every harness definition calls one stable user-level adapter at
+`~/.notifai/bin/hook-adapter`. Node, package manager, CLI version, checkout,
+XDG directories, and notification preferences are resolved behind it, so
+upgrades and configuration changes do not rewrite trusted hook definitions.
+The first migration may require one Codex `/hooks` approval; later repairs keep
+the same identity. Codex's Stop definition omits its timeout so the host default
+remains authoritative; prompt-submit and session-end retain fixed short limits.
+
+`notifai doctor` compares Codex trust on a best-effort basis against Codex's
+current persisted representation. Notifai never writes that trust store;
+Codex's `/hooks` review is authoritative if the diagnostic and UI disagree.
+
+Uninstall removes only the selected harness definition. It intentionally keeps
+the shared adapter because definitions for other harnesses or projects may
+still invoke it and cannot all be discovered from one working directory.
+
 ## Checking it works
 
 ```sh

package/dist/atomic-file.d.ts

@@ -1,6 +1,10 @@
 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;
 }
 /**
  * Replace one regular file without exposing a truncated intermediate state.

package/dist/atomic-file.js

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { chmodSync, closeSync, fsyncSync, lstatSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 /**
  * Replace one regular file without exposing a truncated intermediate state.
@@ -9,16 +9,21 @@ import path from 'node:path';
  * symlink target is refused instead of silently writing through it.
  */
 export function atomicWriteFileSync(file, contents, options = {}) {
-    mkdirSync(path.dirname(file), { recursive: true });
-    const mode = targetMode(file, options.mode ?? 0o600);
-    const temp = path.join(path.dirname(file), `.${path.basename(file)}.notifai-${process.pid}-${randomBytes(6).toString('hex')}.tmp`);
+    const directory = path.dirname(file);
+    mkdirSync(directory, { recursive: true });
+    const parent = safeDirectory(directory, options.requireCurrentUserOwner ?? false);
+    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;
     try {
-        handle = openSync(temp, 'wx', mode);
+        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);
     }
     catch (err) {
@@ -33,15 +38,15 @@ export function atomicWriteFileSync(file, contents, options = {}) {
         throw err;
     }
 }
-/** Mode to preserve, or the mode for a new file. Refuses a non-regular target. */
-function targetMode(file, fallback) {
+function targetMetadata(file, fallback, preserveMode, requireCurrentUserOwner) {
     let stat;
     try {
         stat = lstatSync(file);
     }
     catch (err) {
-        if (err.code === 'ENOENT')
-            return fallback;
+        if (err.code === 'ENOENT') {
+            return { mode: fallback, identity: null };
+        }
         throw err;
     }
     if (stat.isSymbolicLink()) {
@@ -50,6 +55,51 @@ function targetMode(file, fallback) {
     }
     if (!stat.isFile())
         throw new Error(`${file} is not a regular file; refusing to replace it.`);
-    return stat.mode & 0o777;
+    if (requireCurrentUserOwner)
+        assertCurrentUserOwns(file, stat.uid);
+    return {
+        mode: preserveMode ? stat.mode & 0o777 : fallback,
+        identity: { dev: stat.dev, ino: stat.ino },
+    };
+}
+function assertUnchangedTarget(file, target) {
+    let current;
+    try {
+        current = lstatSync(file);
+    }
+    catch (err) {
+        if (err.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, requireCurrentUserOwner) {
+    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, expected) {
+    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, owner) {
+    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.`);
+    }
 }
 //# sourceMappingURL=atomic-file.js.map

package/dist/atomic-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-file.js","sourceRoot":"","sources":["../src/atomic-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAA;AAChB,OAAO,IAAI,MAAM,WAAW,CAAA;AAO5B;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,QAAgB,EAChB,UAA8B,EAAE;IAEhC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAClD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC,CAAA;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CACpB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAClB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CACvF,CAAA;IACD,IAAI,MAA0B,CAAA;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;QACnC,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;QAC/B,SAAS,CAAC,MAAM,CAAC,CAAA;QACjB,SAAS,CAAC,MAAM,CAAC,CAAA;QACjB,MAAM,GAAG,SAAS,CAAA;QAClB,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS,CAAC,MAAM,CAAC,CAAA;QAC3C,IAAI,CAAC;YACH,UAAU,CAAC,IAAI,CAAC,CAAA;QAClB,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB;IAChD,IAAI,IAAI,CAAA;IACR,IAAI,CAAC;QACH,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAA;QACrE,MAAM,GAAG,CAAA;IACX,CAAC;IACD,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,+EAA+E;YACpF,qCAAqC,CACxC,CAAA;IACH,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,iDAAiD,CAAC,CAAA;IAC7F,OAAO,IAAI,CAAC,IAAI,GAAG,KAAK,CAAA;AAC1B,CAAC"}
+{"version":3,"file":"atomic-file.js","sourceRoot":"","sources":["../src/atomic-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAA;AAChB,OAAO,IAAI,MAAM,WAAW,CAAA;AAW5B;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,QAAgB,EAChB,UAA8B,EAAE;IAEhC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACpC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACzC,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,uBAAuB,IAAI,KAAK,CAAC,CAAA;IACjF,MAAM,MAAM,GAAG,cAAc,CAC3B,IAAI,EACJ,OAAO,CAAC,IAAI,IAAI,KAAK,EACrB,OAAO,CAAC,YAAY,IAAI,IAAI,EAC5B,OAAO,CAAC,uBAAuB,IAAI,KAAK,CACzC,CAAA;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CACpB,SAAS,EACT,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CACvF,CAAA;IACD,IAAI,MAA0B,CAAA;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;QAC1C,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;QAC/B,SAAS,CAAC,MAAM,CAAC,CAAA;QACjB,SAAS,CAAC,MAAM,CAAC,CAAA;QACjB,MAAM,GAAG,SAAS,CAAA;QAClB,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;QAC5B,mBAAmB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;QACtC,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACnC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS,CAAC,MAAM,CAAC,CAAA;QAC3C,IAAI,CAAC;YACH,UAAU,CAAC,IAAI,CAAC,CAAA;QAClB,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC;AAQD,SAAS,cAAc,CACrB,IAAY,EACZ,QAAgB,EAChB,YAAqB,EACrB,uBAAgC;IAEhC,IAAI,IAAI,CAAA;IACR,IAAI,CAAC;QACH,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;QAC3C,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IACD,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,+EAA+E;YACpF,qCAAqC,CACxC,CAAA;IACH,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,iDAAiD,CAAC,CAAA;IAC7F,IAAI,uBAAuB;QAAE,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IAClE,OAAO;QACL,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ;QACjD,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;KAC3C,CAAA;AACH,CAAC;AAED,SAAS,qBAAqB,CAAC,IAAY,EAAE,MAAsB;IACjE,IAAI,OAAO,CAAA;IACX,IAAI,CAAC;QACH,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI;YAAE,OAAM;QACxF,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,2DAA2D,CAAC,CAAA;IACrF,CAAC;IACD,IACE,MAAM,CAAC,QAAQ,KAAK,IAAI;QACxB,OAAO,CAAC,GAAG,KAAK,MAAM,CAAC,QAAQ,CAAC,GAAG;QACnC,OAAO,CAAC,GAAG,KAAK,MAAM,CAAC,QAAQ,CAAC,GAAG,EACnC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,2DAA2D,CAAC,CAAA;IACrF,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CACpB,SAAiB,EACjB,uBAAgC;IAEhC,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAA;IACjC,IAAI,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,GAAG,SAAS,2DAA2D,CAAC,CAAA;IAC1F,CAAC;IACD,IAAI,uBAAuB;QAAE,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACvE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAA;AACzC,CAAC;AAED,SAAS,mBAAmB,CAAC,SAAiB,EAAE,QAAsC;IACpF,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,CAAA;IACpC,IACE,OAAO,CAAC,cAAc,EAAE;QACxB,CAAC,OAAO,CAAC,WAAW,EAAE;QACtB,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG;QAC5B,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG,EAC5B,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,GAAG,SAAS,0DAA0D,CAAC,CAAA;IACzF,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAAC,IAAY,EAAE,KAAa;IACxD,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;IAC/E,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,oBAAoB,KAAK,iDAAiD,CAAC,CAAA;IACpG,CAAC;AACH,CAAC"}

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import type { AccountAccessResponse, BeginPairingResponse, CapabilityDocument, CreateMediaUploadRequestT, CreateMediaUploadResponse, EvidenceSnapshot, ListDevicesResponse, ListRepliesResponse, Platform, PollPairingResponse, SubmissionReceipt, SubmitNotificationRequestT } from '@raidiant/notifai-protocol';
+import type { Logger } from './logging.js';
 export declare class ApiCallError extends Error {
     status: number;
     code: string;
@@ -8,6 +9,13 @@ export declare class ApiCallError extends Error {
 }
 export declare class NetworkError extends Error {
 }
+/**
+ * Whether a replies-poll failure is temporary while the durable request stays
+ * live. Transport faults, throttling, request timeouts, and server failures
+ * can recover on a later poll; client errors cannot be repaired by retrying
+ * the same authenticated request.
+ */
+export declare function isRetryableReplyPollError(err: unknown): boolean;
 export interface ApiClient {
     beginPairing(body: {
         machine_name: string;
@@ -24,8 +32,8 @@ export interface ApiClient {
         waitSeconds: number;
         afterSeq: number;
     }): Promise<ListRepliesResponse>;
-    /** Retire a question so a late device answer is rejected rather than lost. */
-    closeReplies(requestId: string): Promise<void>;
+    /** Retire a question and return the replies committed before the close fence. */
+    closeReplies(requestId: string): Promise<ListRepliesResponse>;
     createMediaUpload(body: CreateMediaUploadRequestT): Promise<CreateMediaUploadResponse>;
     uploadMedia(grant: CreateMediaUploadResponse, bytes: Uint8Array): Promise<void>;
     health(): Promise<boolean>;
@@ -37,5 +45,20 @@ export interface ClientOptions {
      * whole network path stays inside the budget the harness allows them.
      */
     timeoutMs?: number;
+    /**
+     * Absolute wall-clock ceiling for the caller's whole operation. This is
+     * intentionally separate from `timeoutMs`: a late long poll must not get a
+     * fresh per-request allowance after its owning harness hook is nearly done.
+     */
+    deadlineAt?: number;
+    /** Test seam for `deadlineAt`; production uses the wall clock. */
+    now?: () => number;
+    /**
+     * Records each call locally. Worth having because the two failures that cost
+     * the most time — a server older than this CLI, and a network path that only
+     * fails inside a hook — both look identical from outside and are told apart
+     * instantly by a status code and a duration.
+     */
+    logger?: Pick<Logger, 'debug' | 'error'>;
 }
 export declare function createClient(baseUrl: string, bearer: string | null, options?: ClientOptions): ApiClient;

package/dist/client.js

@@ -13,6 +13,19 @@ export class ApiCallError extends Error {
 }
 export class NetworkError extends Error {
 }
+/**
+ * Whether a replies-poll failure is temporary while the durable request stays
+ * live. Transport faults, throttling, request timeouts, and server failures
+ * can recover on a later poll; client errors cannot be repaired by retrying
+ * the same authenticated request.
+ */
+export function isRetryableReplyPollError(err) {
+    if (err instanceof NetworkError)
+        return true;
+    if (!(err instanceof ApiCallError))
+        return false;
+    return err.status >= 500 || err.status === 429 || err.status === 408;
+}
 /**
  * A deadline that fired reads as an abort, which says nothing useful on its
  * own. Naming the timeout is what lets someone tell a hung server apart from a
@@ -30,14 +43,45 @@ const DEFAULT_TIMEOUT_MS = 20_000;
 export function createClient(baseUrl, bearer, options = {}) {
     const root = baseUrl.replace(/\/$/, '');
     const budgetMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    const logger = options.logger;
     async function call(method, apiPath, body, 
     /** Seconds the server was asked to hold the connection open. */
     serverWaitSeconds = 0) {
+        const startedAt = Date.now();
+        try {
+            const result = await callOnce(method, apiPath, body, serverWaitSeconds);
+            logger?.debug('http.call', {
+                method,
+                path: apiPath,
+                ok: true,
+                duration_ms: Date.now() - startedAt,
+            });
+            return result;
+        }
+        catch (err) {
+            logger?.error('http.call', {
+                method,
+                path: apiPath,
+                ok: false,
+                duration_ms: Date.now() - startedAt,
+                ...(err instanceof ApiCallError
+                    ? { status: err.status, code: err.code, message: err.message, details: err.details }
+                    : { message: String(err) }),
+            });
+            throw err;
+        }
+    }
+    async function callOnce(method, apiPath, body, serverWaitSeconds = 0) {
         // Without this, a server that accepts the connection and then never answers
         // hangs until the harness kills the whole hook — and the reply-poll deadline
         // cannot interrupt an individual fetch. The signal covers the
         // body read too, not just the response headers.
-        const limitMs = budgetMs + serverWaitSeconds * 1000;
+        const requestBudgetMs = budgetMs + serverWaitSeconds * 1000;
+        const remainingMs = options.deadlineAt === undefined
+            ? requestBudgetMs
+            : Math.max(1, options.deadlineAt - now());
+        const limitMs = Math.max(1, Math.min(requestBudgetMs, remainingMs));
         const signal = AbortSignal.timeout(limitMs);
         let response;
         try {

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAiBA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAE5B;IACA;IAEA;IACA;IALT,YACS,MAAc,EACd,IAAY,EACnB,OAAe,EACR,aAA4B,IAAI,EAChC,UAAmB,IAAI;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAA;QANP,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;QAEZ,eAAU,GAAV,UAAU,CAAsB;QAChC,YAAO,GAAP,OAAO,CAAgB;IAGhC,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,KAAK;CAAG;AAE1C;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAY;IACpD,IAAI,GAAG,YAAY,YAAY;QAAE,OAAO,IAAI,CAAA;IAC5C,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC;QAAE,OAAO,KAAK,CAAA;IAChD,OAAO,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,CAAA;AACtE,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,GAAY,EAAE,IAAY,EAAE,OAAe;IACjE,MAAM,IAAI,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IACjD,IAAI,IAAI,KAAK,cAAc,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QACrD,OAAO,IAAI,YAAY,CAAC,GAAG,IAAI,2BAA2B,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;IAC1F,CAAC;IACD,OAAO,IAAI,YAAY,CAAC,mBAAmB,IAAI,KAAK,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AACpE,CAAC;AAiDD,iFAAiF;AACjF,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAEjC,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,MAAqB,EACrB,UAAyB,EAAE;IAE3B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAA;IACxD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAA;IACnC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IAE7B,KAAK,UAAU,IAAI,CACjB,MAAc,EACd,OAAe,EACf,IAAc;IACd,gEAAgE;IAChE,iBAAiB,GAAG,CAAC;QAErB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAC5B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAI,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAA;YAC1E,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE;gBACzB,MAAM;gBACN,IAAI,EAAE,OAAO;gBACb,EAAE,EAAE,IAAI;gBACR,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACpC,CAAC,CAAA;YACF,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,EAAE,KAAK,CAAC,WAAW,EAAE;gBACzB,MAAM;gBACN,IAAI,EAAE,OAAO;gBACb,EAAE,EAAE,KAAK;gBACT,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBACnC,GAAG,CAAC,GAAG,YAAY,YAAY;oBAC7B,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE;oBACpF,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;aAC9B,CAAC,CAAA;YACF,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC;IAED,KAAK,UAAU,QAAQ,CACrB,MAAc,EACd,OAAe,EACf,IAAc,EACd,iBAAiB,GAAG,CAAC;QAErB,4EAA4E;QAC5E,6EAA6E;QAC7E,8DAA8D;QAC9D,gDAAgD;QAChD,MAAM,eAAe,GAAG,QAAQ,GAAG,iBAAiB,GAAG,IAAI,CAAA;QAC3D,MAAM,WAAW,GACf,OAAO,CAAC,UAAU,KAAK,SAAS;YAC9B,CAAC,CAAC,eAAe;YACjB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC,CAAA;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC,CAAA;QACnE,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC3C,IAAI,QAAkB,CAAA;QACtB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,EAAE,EAAE;gBAC1C,MAAM;gBACN,OAAO,EAAE;oBACP,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACrE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC7C;gBACD,MAAM;gBACN,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9D,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;QAC1C,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,IAAI,MAAM,GAAwB,IAAI,CAAA;YACtC,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAiB,CAAA;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,gBAAgB;YAClB,CAAC;YACD,MAAM,IAAI,YAAY,CACpB,QAAQ,CAAC,MAAM,EACf,MAAM,EAAE,KAAK,CAAC,IAAI,IAAI,gBAAgB,EACtC,MAAM,EAAE,KAAK,CAAC,OAAO,IAAI,8BAA8B,QAAQ,CAAC,MAAM,EAAE,EACxE,MAAM,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI,EACjC,MAAM,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI,CAC9B,CAAA;QACH,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,SAAc,CAAA;QAClD,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAA;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,uEAAuE;YACvE,wEAAwE;YACxE,MAAM,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;QAC1C,CAAC;IACH,CAAC;IAED,OAAO;QACL,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,kBAAkB,EAAE,IAAI,CAAC;QAC9D,WAAW,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,CACvC,IAAI,CAAC,MAAM,EAAE,oBAAoB,SAAS,OAAO,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;QACrF,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,wBAAwB,CAAC;QACzD,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,iBAAiB,CAAC;QACjD,YAAY,EAAE,CAAC,QAAQ,GAAG,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,wBAAwB,QAAQ,EAAE,CAAC;QACnF,MAAM,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,CAC5B,IAAI,CAAC,MAAM,EAAE,sCAAsC,WAAW,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC;QACtF,QAAQ,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,yBAAyB,SAAS,EAAE,CAAC;QAC1E,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CAChD,IAAI,CACF,KAAK,EACL,yBAAyB,kBAAkB,CAAC,SAAS,CAAC,yBAAyB,WAAW,cAAc,QAAQ,EAAE,EAClH,SAAS,EACT,WAAW,CACZ;QACH,YAAY,EAAE,CAAC,SAAS,EAAE,EAAE,CAC1B,IAAI,CACF,MAAM,EACN,yBAAyB,kBAAkB,CAAC,SAAS,CAAC,gBAAgB,CACvE;QACH,iBAAiB,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC;QAChE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAClC,IAAI,QAAkB,CAAA;YACtB,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE;oBACvC,MAAM,EAAE,KAAK;oBACb,OAAO,EAAE,KAAK,CAAC,cAAc;oBAC7B,IAAI,EAAE,KAAK;oBACX,qEAAqE;oBACrE,+CAA+C;oBAC/C,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;iBACxD,CAAC,CAAA;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,YAAY,CAAC,kBAAkB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YACzD,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,YAAY,CAAC,+BAA+B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;YAC1E,CAAC;QACH,CAAC;QACD,MAAM,EAAE,KAAK,IAAI,EAAE;YACjB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;gBAC7B,OAAO,IAAI,CAAA;YACb,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/commands.d.ts

@@ -4,6 +4,7 @@ import type { CredentialStore } from './credentials.js';
 import { type Readiness } from './readiness.js';
 import type { Tone } from './ui/theme.js';
 import { type HookHarness } from './hooks.js';
+import { type Logger } from './logging.js';
 import { type SendFlags } from './send.js';
 import type { NativeSkills, SkillScope } from './native-skills.js';
 export interface CommandIo {
@@ -47,6 +48,8 @@ export interface CommandDeps {
     store: CredentialStore;
     env: NodeJS.ProcessEnv;
     cwd: string;
+    /** Test seam; production fixes the hook adapter under os.homedir(). */
+    hookAdapterHome?: string;
     /** Test seam; production uses fetch against base_url. */
     clientFactory?: (baseUrl: string, bearer: string | null, options?: ClientOptions) => ApiClient;
     /** Test seam for bounded polling without wall-clock sleeps. */
@@ -57,7 +60,14 @@ export interface CommandDeps {
     idleSeconds?: () => number | null;
     /** Test seam and production adapter for the external native skills installer. */
     nativeSkills?: NativeSkills;
+    /**
+     * The local record of what this invocation did. Optional so a test fake need
+     * not carry one; `log(deps)` supplies a logger that records nothing.
+     */
+    logger?: Logger;
 }
+/** The invocation's logger, or one that discards everything. */
+export declare function log(deps: CommandDeps): Logger;
 export declare const EXIT: {
     readonly ok: 0;
     readonly failed: 1;
@@ -147,6 +157,8 @@ export declare function statusCommand(deps: CommandDeps, requestId: string, flag
 }): Promise<number>;
 export declare const HOOK_EVENTS: readonly ["user-prompt-submit", "stop", "session-end"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** SessionEnd cleanup must precede every diagnostic that can wait on a file lock. */
+export declare function hookDefersDiagnosticsUntilAfterCleanup(event: unknown): event is 'session-end';
 /**
  * Runs one harness hook. Contract with every harness: hook JSON arrives on
  * stdin, the decision (if any) goes to stdout, diagnostics go to stderr, and
@@ -197,9 +209,9 @@ export declare function buildQuestions(flags: AskFlags, question: string | undef
 };
 /**
  * Registers a question for turn-end routing under the user's presence config.
- * Returns immediately so the agent can ask in prose and end its turn. With the
- * default presence gate, recent keyboard or mouse activity keeps it local;
- * `require_idle = false` intentionally permits a push while the user is active.
+ * Returns immediately so the agent can ask in prose and end its turn. Presence
+ * does not block the shipped default; `require_idle = true` intentionally keeps
+ * the question local while the user is active.
  */
 export declare function askCommand(deps: CommandDeps, question: string | undefined, flags: AskFlags): number;
 /** Retire a question so a late answer is rejected rather than silently lost. */
@@ -221,9 +233,10 @@ export declare function configShowCommand(deps: CommandDeps, flags: {
 /**
  * One setting, explained in full.
  *
- * The gap this closes: `config show` prints `require_idle = true` and there was
- * nowhere to go from there. Every key already had a careful explanation — in a
- * TypeScript comment, read by everyone except the person who needed it.
+ * The gap this closes: `config show` prints a value and provenance but that is
+ * not enough to explain the setting's consequences. Every key already had a
+ * careful explanation — in a TypeScript comment, read by everyone except the
+ * person who needed it.
  */
 export declare function configExplainCommand(deps: CommandDeps, key: string, flags?: {
     json?: boolean;
@@ -234,12 +247,48 @@ export declare function configSetCommand(deps: CommandDeps, key: string, rawValu
     session?: string;
     yes?: boolean;
 }): Promise<number>;
+type ConfigMutationFlags = {
+    project?: boolean;
+    local?: boolean;
+    session?: string;
+    yes?: boolean;
+};
+export declare function configUnsetCommand(deps: CommandDeps, key: string, flags: ConfigMutationFlags): Promise<number>;
+export interface LogsFlags {
+    json?: boolean;
+    limit?: number;
+    all?: boolean;
+    since?: string;
+    level?: string;
+    event?: string[];
+    run?: string;
+    request?: string;
+    session?: string;
+    project?: string;
+    allProjects?: boolean;
+    grep?: string;
+    path?: boolean;
+    clear?: boolean;
+}
+/** `10m`, `2h`, `1d`, or an ISO 8601 instant. */
+export declare function parseSince(raw: string, now: number): number | null;
+/**
+ * What this machine recorded about itself.
+ *
+ * The retrieval half of the local log, and the half that decides whether the
+ * log is worth having. Three things make it usable by an agent rather than
+ * merely available to one: the default is bounded and scoped to this project,
+ * the filters match the questions actually asked ("that run", "that
+ * notification", "just the failures"), and `--json` gives the machine the
+ * records untouched on stdout while every word of explanation goes to stderr.
+ */
+export declare function logsCommand(deps: CommandDeps, flags: LogsFlags): number;
 /**
  * Where `npx skills add` fetches the optional agent skill from. In skills CLI
  * 1.5.x, `owner/repo@name` selects a skill; a Git ref belongs after `#`.
  * Keep this immutable and public because the command is printed to users.
  */
-export declare const SKILLS_SOURCE = "Raidiant-io/notifai#v0.3.0";
+export declare const SKILLS_SOURCE = "Raidiant-io/notifai#v0.4.0";
 /** Derive a contract-valid project slug from a directory name. */
 export declare function projectSlugFrom(name: string): string;
 export interface InitFlags {