@raidiant/notifai 7.0.2 → 9.0.0

package/dist/commands-hooks.js

@@ -9,28 +9,45 @@ import { loadConfig } from './config.js';
 import { withTargetFileLock } from './file-lock.js';
 import { HARNESS_CAPABILITIES, HARNESS_LABELS } from './harnesses.js';
 import { inspectHookAdapter, installHookAdapter, isNpxAdapterTarget, } from './hook-adapter.js';
-import { clearAcknowledgementObligation, handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readMatchingProjectSessionPointer, readProjectSession, readSessionState, registerQuestion, waiterCeilingSeconds, } from './hooks.js';
-import { BLOCKING_STOP_TIMEOUT_SECONDS, HARNESSES, applyPlan, buildCursorHookConfig, buildHookConfig, codexCoexistenceNotes, codexHomeNote, codexLayerDir, codexLayerPaths, codexRepresentationProblems, codexTrustProblems, detectHarness, detectedHarnesses, findInstallations, handlerEvent, hookDefinitionFiles, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, stopHandlerIsDetached, withCodexLayerTransaction, } from './install-hooks.js';
+import { clearAcknowledgementObligation, claimPromptActivation, claimCursorStopActivation, confirmCursorStopActivation, dropPendingQuestion, handleSessionEnd, handleStop, handleUserPromptSubmit, markSessionActivation, parkForRetirement, parseHookInput, pruneAbandonedSessions, readMatchingProjectSessionPointer, readProjectSession, readSessionState, resetCursorStopActivation, registerQuestion, waiterCeilingSeconds, withdrawUnpushedQuestions, } from './hooks.js';
+import { BLOCKING_STOP_TIMEOUT_SECONDS, HARNESSES, applyPlan, buildCursorHookConfig, buildHookConfig, cleanupEmptiedCodexLayer, codexCoexistenceNotes, codexHomeNote, codexLayerDir, codexLayerPaths, codexRepresentationProblems, codexTrustProblems, detectHarness, detectedHarnesses, findInstallations, handlerEvent, hookDefinitionFiles, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, stopHandlerIsDetached, withCodexLayerTransaction, } from './install-hooks.js';
 import { logConfigResolved, logSettingsFrom } from './logging.js';
 import { isOurOpencodePlugin, opencodePluginSource } from './opencode-plugin.js';
 import { packageVersion } from './release.js';
+import { rejectAccidentalEscapedNewlines } from './send.js';
+import { cursorStopActivationOutput, sessionActivationOutput, } from './session-activation.js';
 import { CHOICE_USAGE, buildDraft, parseChoices, slugify, validateMediaInputs, } from './send.js';
-import { EXIT, authedClient, loadLoggedConfig, log, makeClient, rejectedPaths, reportError, } from './commands-core.js';
+import { EXIT, authedClient, diagnoseIgnoredOriginOverride, loadLoggedConfig, log, makeClient, rejectedPaths, reportError, } from './commands-core.js';
 import { claudeSessionPid, resolveActiveHarness, } from './commands-harness-context.js';
 import { stopShapeProblems } from './commands-hook-shape.js';
 import { acknowledgementCommand, printAcknowledgementStatus, resolveDraftInvocation, uploadImage, waitForReply, } from './commands-send-support.js';
 // ---------------------------------------------------------------------------
 // hook / ask / close — harness integration
 // ---------------------------------------------------------------------------
-export const HOOK_EVENTS = ['user-prompt-submit', 'stop', 'session-end'];
+export const HOOK_EVENTS = [
+    'session-start',
+    'subagent-start',
+    'activation-stop',
+    'user-prompt-submit',
+    'stop',
+    'session-end',
+];
+/** Lifecycle handlers one installed harness must carry in this CLI build. */
+export function requiredHookEvents(harness) {
+    if (harness === 'opencode')
+        return [];
+    return harness === 'cursor'
+        ? ['session-start', 'activation-stop', 'user-prompt-submit', 'stop', 'session-end']
+        : ['session-start', 'subagent-start', 'user-prompt-submit', 'stop', 'session-end'];
+}
 /** SessionEnd cleanup must precede every diagnostic that can wait on a file lock. */
 export function hookDefersDiagnosticsUntilAfterCleanup(event) {
     return event === '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
- * exit 0 with no stdout means "no decision — carry on as normal".
+ * stdin, harness output (if any) goes to stdout, diagnostics go to stderr, and
+ * exit 0 with no stdout means "no decision or added context — carry on as normal".
  *
  * Every failure path in here must reach that no-decision state. A hook that
  * throws, or that blocks past the harness's timeout, degrades the agent for a
@@ -63,6 +80,20 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
     const failureData = (err) => err instanceof ApiCallError
         ? { status: err.status, code: err.code, message: err.message, details: err.details }
         : { message: err instanceof Error ? err.message : String(err) };
+    // Cursor may load ~/.claude/settings.json in addition to its own native
+    // hooks. Cursor guarantees CURSOR_PROJECT_DIR to hook processes, so a Claude
+    // compatibility copy becomes a no-op and the native Cursor definition is
+    // the single owner. Real Claude hooks do not receive that hook-only marker.
+    if (harness === 'claude-code' && deps.env['CURSOR_PROJECT_DIR']) {
+        start({ outcome: 'cursor-compatibility-copy-skipped' });
+        logger.info('hook.end', {
+            hook: event,
+            outcome: 'ignored',
+            reason: 'cursor-native-handler-owns-event',
+            decided: false,
+        });
+        return EXIT.ok;
+    }
     let raw;
     try {
         raw = await readStdin();
@@ -105,6 +136,164 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
     const cwd = envelope.cwd ?? deps.cwd;
     const sessionEnd = hookDefersDiagnosticsUntilAfterCleanup(event);
     logger.bind({ session: envelope.session_id ?? null });
+    const declaredSourcePid = declaredHookSourcePid(deps);
+    const activationOwnerPid = harness === 'claude-code'
+        ? (deps.claudeSourcePid ?? declaredSourcePid ?? claudeSessionPid(deps.env))
+        : harness === 'codex'
+            ? (deps.codexSourcePid ?? declaredSourcePid ?? process.ppid)
+            : undefined;
+    // Session activation is local model context, not authenticated routing. It
+    // must survive the exact first-run states it exists to repair: no config,
+    // no credential, no Companion device, and no network.
+    if (event === 'session-start' || event === 'subagent-start') {
+        start({ cwd, source: envelope.source ?? null });
+        if (event === 'session-start' && harness === 'cursor' && envelope.session_id !== undefined) {
+            try {
+                resetCursorStopActivation(envelope.session_id, deps.env);
+            }
+            catch (err) {
+                logger.error('hook.end', {
+                    hook: event,
+                    outcome: 'reset-failed',
+                    ...failureData(err),
+                });
+            }
+        }
+        const stdout = sessionActivationOutput(harness, event === 'session-start' ? 'SessionStart' : 'SubagentStart');
+        if (stdout !== undefined)
+            deps.io.out(stdout);
+        if (stdout !== undefined &&
+            event === 'session-start' &&
+            activationOwnerPid !== undefined &&
+            envelope.session_id !== undefined) {
+            try {
+                // Write stdout first. If the process dies between these operations a
+                // later prompt may duplicate context, but it cannot suppress context
+                // that the host never received.
+                markSessionActivation(envelope.session_id, deps.env, now(), activationOwnerPid);
+            }
+            catch (err) {
+                logger.error('hook.end', {
+                    hook: event,
+                    outcome: 'mark-failed',
+                    reason: 'activation-state-failed',
+                    ...failureData(err),
+                });
+            }
+        }
+        logger.info('hook.end', {
+            hook: event,
+            outcome: stdout === undefined ? 'unsupported-harness' : 'context-added',
+            decided: false,
+        });
+        return EXIT.ok;
+    }
+    // SessionStart is the preferred model-visible activation seam. A few
+    // managed hosts regenerate older hook definitions that retain
+    // UserPromptSubmit but omit newer lifecycle events. Claim the first prompt
+    // once per exact session as a compatibility fallback, before config/auth/
+    // device/network work, and stay silent when SessionStart already ran.
+    let promptActivationStdout;
+    if (event === 'user-prompt-submit' &&
+        (harness === 'claude-code' || harness === 'codex') &&
+        activationOwnerPid !== undefined &&
+        envelope.session_id !== undefined) {
+        try {
+            if (claimPromptActivation(envelope.session_id, deps.env, now(), activationOwnerPid)) {
+                promptActivationStdout = sessionActivationOutput(harness, 'UserPromptSubmit');
+                if (promptActivationStdout !== undefined)
+                    deps.io.out(promptActivationStdout);
+            }
+        }
+        catch (err) {
+            logger.error('hook.end', {
+                hook: event,
+                outcome: 'claim-failed',
+                reason: 'activation-state-failed',
+                ...failureData(err),
+            });
+        }
+    }
+    // Cursor has a confirmed host bug in which sessionStart.additional_context
+    // is accepted but never reaches the model. A native Stop follow-up is the
+    // host's guaranteed model-visible channel. Claim it once per conversation,
+    // before config/auth/network, and leave the ordinary Stop handler separate
+    // so question delivery is never displaced by activation.
+    if (event === 'activation-stop') {
+        start({ cwd, stop_hook_active: envelope.stop_hook_active ?? null });
+        if (harness !== 'cursor') {
+            logger.info('hook.end', { hook: event, outcome: 'unsupported-harness', decided: false });
+            return EXIT.ok;
+        }
+        if (envelope.status === 'aborted') {
+            logger.info('hook.end', {
+                hook: event,
+                outcome: 'ignored',
+                reason: `turn-${envelope.status}`,
+                decided: false,
+            });
+            return EXIT.ok;
+        }
+        if (envelope.session_id === undefined) {
+            logger.info('hook.end', {
+                hook: event,
+                outcome: 'ignored',
+                reason: 'missing-conversation-id',
+                decided: false,
+            });
+            return EXIT.ok;
+        }
+        if (envelope.session_id !== undefined &&
+            typeof envelope.loop_count === 'number' &&
+            envelope.loop_count > 0) {
+            let activationOwned = false;
+            try {
+                activationOwned = confirmCursorStopActivation(envelope.session_id, deps.env, now());
+            }
+            catch (err) {
+                logger.error('hook.end', {
+                    hook: event,
+                    outcome: 'confirm-failed',
+                    ...failureData(err),
+                });
+            }
+            if (activationOwned) {
+                logger.info('hook.end', { hook: event, outcome: 'confirmed', decided: false });
+                return EXIT.ok;
+            }
+        }
+        const cursorState = readSessionState(envelope.session_id, deps.env);
+        if ((cursorState.pending?.length ?? 0) > 0 ||
+            cursorState.accepted !== undefined ||
+            (cursorState.acknowledgement_due?.length ?? 0) > 0) {
+            logger.info('hook.end', {
+                hook: event,
+                outcome: 'deferred',
+                reason: 'question-continuation-owns-stop',
+                decided: false,
+            });
+            return EXIT.ok;
+        }
+        let claimed = false;
+        try {
+            claimed = claimCursorStopActivation(envelope.session_id, deps.env, now());
+        }
+        catch (err) {
+            logger.error('hook.end', {
+                hook: event,
+                outcome: 'claim-failed',
+                ...failureData(err),
+            });
+        }
+        logger.info('hook.end', {
+            hook: event,
+            outcome: claimed ? 'followup-added' : 'already-activated',
+            decided: claimed,
+        });
+        if (claimed)
+            deps.io.out(cursorStopActivationOutput());
+        return EXIT.ok;
+    }
     let config = null;
     let configFailure;
     try {
@@ -127,6 +316,7 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
                 hook: event,
                 outcome: 'failed',
                 reason: 'config-failed',
+                ...(promptActivationStdout === undefined ? {} : { activation: 'context-added' }),
                 ...failureData(err),
             });
             for (const line of describeHookFailure(err))
@@ -174,9 +364,7 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         // repository can commit `.notifai/config.toml`, and honouring a base_url
         // from it would hand this machine's bearer token to whatever host it names.
         const baseUrl = credential.baseUrl;
-        if (resolved.base_url.source !== 'default' && resolved.base_url.value !== baseUrl) {
-            deps.io.err(`notifai: ignoring base_url from ${resolved.base_url.source}; hooks only talk to ${baseUrl}`);
-        }
+        diagnoseIgnoredOriginOverride(deps.io, resolved, credential);
         // UserPromptSubmit runs in front of the user's own prompt under a 15s
         // harness ceiling and can make two calls, so each gets a small slice of it;
         // Stop is allowed to block and keeps the ordinary budget.
@@ -222,9 +410,10 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
         const notes = outcome.notes.filter((note) => !/^(?:late )?answer from /.test(note));
         logger.info('hook.end', {
             hook: event,
-            // A hook that returns stdout has taken over the turn; one that does not
-            // has handed the terminal back. That distinction is the whole contract.
-            decided: outcome.stdout !== undefined,
+            // Stop stdout takes over the turn. UserPromptSubmit stdout may instead
+            // add context to the user's own turn, which is explicitly non-decisive.
+            decided: outcome.decided ?? outcome.stdout !== undefined,
+            ...(promptActivationStdout === undefined ? {} : { activation: 'context-added' }),
             ...(notes.length === 0 ? {} : { notes }),
             ...outcome.log,
         });
@@ -264,13 +453,14 @@ export async function hookRunCommand(deps, event, readStdin, harness) {
 function stopWakeRoute(deps, harness, sessionId, cwd) {
     if (sessionId === undefined)
         return undefined;
+    const declaredSourcePid = declaredHookSourcePid(deps);
     if (harness === 'claude-code') {
         if ((deps.hookPlatform ?? process.platform) === 'win32')
             return undefined;
         return claudeWakeRoute({
             sessionId,
             cwd,
-            sourcePid: deps.claudeSourcePid ?? claudeSessionPid(deps.env),
+            sourcePid: deps.claudeSourcePid ?? declaredSourcePid ?? claudeSessionPid(deps.env),
             ...(deps.claudeWake === undefined ? {} : { adapters: deps.claudeWake }),
         });
     }
@@ -278,13 +468,18 @@ function stopWakeRoute(deps, harness, sessionId, cwd) {
         return codexWakeRoute({
             threadId: sessionId,
             cwd,
-            sourcePid: deps.codexSourcePid ?? process.ppid,
+            sourcePid: deps.codexSourcePid ?? declaredSourcePid ?? process.ppid,
             env: deps.env,
             ...(deps.codexWake === undefined ? {} : { adapters: deps.codexWake }),
         });
     }
     return undefined;
 }
+/** Stable harness parent propagated by the managed adapter across child tools. */
+function declaredHookSourcePid(deps) {
+    const value = Number(deps.env['NOTIFAI_HOOK_SOURCE_PID']);
+    return Number.isInteger(value) && value > 0 ? value : undefined;
+}
 /**
  * What went wrong, in terms of what to do about it.
  *
@@ -374,13 +569,12 @@ export function buildQuestions(flags, question) {
             questions.push(built.question);
         }
         const context = flags.body ?? record['body'];
-        const questionBlock = questions.map((entry, index) => `${index + 1}. ${entry.text}`).join('\n');
         return {
             ok: true,
             questions,
             body: context !== undefined && context.trim() !== ''
-                ? `${questionBlock}\n\n${context}`
-                : questionBlock,
+                ? context
+                : questions.map((entry, index) => `${index + 1}. ${entry.text}`).join('\n'),
         };
     }
     if (question === undefined || question.trim() === '') {
@@ -393,9 +587,7 @@ export function buildQuestions(flags, question) {
     return {
         ok: true,
         questions: [built.question],
-        body: context !== undefined && context.trim() !== ''
-            ? `${built.question.text}\n\n${context}`
-            : built.question.text,
+        body: context !== undefined && context.trim() !== '' ? context : built.question.text,
     };
 }
 function buildOneQuestion(text, choiceLabels, multi, index, usedIds) {
@@ -452,8 +644,9 @@ function buildAskDraft(config, built, flags, invocation, mediaIds) {
     return { ok: true, draft: result.draft };
 }
 function recordRegisteredQuestion(deps, sessionId, built, draft, json = false) {
+    let questionId;
     try {
-        registerQuestion(sessionId, deps.env, {
+        questionId = registerQuestion(sessionId, deps.env, {
             question: built.questions[0].text,
             questions: built.questions,
             body: draft.presentation.body,
@@ -470,8 +663,9 @@ function recordRegisteredQuestion(deps, sessionId, built, draft, json = false) {
     log(deps).info('ask.registered', {
         ok: true,
         session: sessionId,
+        question_id: questionId,
         questions: built.questions.length,
-        text: built.questions[0].text,
+        text_chars: built.questions[0].text.length,
         choices: built.questions[0].choices?.length ?? 0,
         media: draft.presentation.media?.length ?? 0,
     });
@@ -482,17 +676,20 @@ function recordRegisteredQuestion(deps, sessionId, built, draft, json = false) {
     if (json) {
         deps.io.out(JSON.stringify({
             registered: true,
+            question_id: questionId,
             questions: built.questions.map((entry) => ({
                 id: entry.id,
                 text: entry.text,
                 ...(entry.choices === undefined ? {} : { choices: entry.choices }),
                 ...(entry.multi === true ? { multi: true } : {}),
             })),
+            close: `notifai close ${questionId}`,
             next: {
                 end_turn: true,
                 in_this_turn: 'Ask the question in the conversation and say what concrete work each possible answer will make you resume, then end the turn.',
                 route_neutral: 'Never say where the answer must arrive; it returns by whatever route the harness supports.',
                 on_answer: 'Acknowledge it, then resume the committed work without asking the user to confirm again.',
+                answered_outside_notifai: `If they answer in the conversation instead, run \`notifai close ${questionId}\` before ending the turn so a later Stop will not send this question.`,
             },
         }, null, 2));
         return EXIT.ok;
@@ -508,8 +705,8 @@ function recordRegisteredQuestion(deps, sessionId, built, draft, json = false) {
         }
     }
     deps.io.out(built.questions.length > 1
-        ? `${built.questions.length} questions registered as one form. Ask them in the conversation, state the concrete work you will resume for their answers, then end your turn.`
-        : 'Question registered. Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.');
+        ? `${built.questions.length} questions registered as one form (${questionId}). Ask them in the conversation, state the concrete work you will resume for their answers, then end your turn.`
+        : `Question registered (${questionId}). Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.`);
     deps.io.out('Before ending this turn, pre-commit in your own words to the work you will resume:');
     for (const [index, entry] of built.questions.entries()) {
         const questionPrefix = built.questions.length > 1 ? `Question ${index + 1}, ` : '';
@@ -525,6 +722,7 @@ function recordRegisteredQuestion(deps, sessionId, built, draft, json = false) {
     }
     deps.io.out('When the answer arrives, resume the matching work without asking the user to confirm again. Frame this as work you will resume, not as approval you receive.');
     deps.io.out('A Notifai answer cannot answer a harness permission prompt or interactive picker; leave those to the harness and user.');
+    deps.io.out(`If they answer in this conversation instead, retire it with \`notifai close ${questionId}\` so a later Stop will not send it.`);
     return EXIT.ok;
 }
 async function uploadAskMedia(deps, config, sessionId, built, flags, invocation) {
@@ -537,7 +735,7 @@ async function uploadAskMedia(deps, config, sessionId, built, flags, invocation)
             mediaIds.push(image);
             continue;
         }
-        const uploaded = await uploadImage(deps, authed.client, image);
+        const uploaded = await uploadImage(deps, authed.client, image, config.media_origins.value);
         if (!uploaded.ok) {
             if (uploaded.error !== null)
                 deps.io.err(uploaded.error);
@@ -561,6 +759,11 @@ export function askCommand(deps, question, flags) {
     // Validate before route discovery. A malformed question belongs to the
     // caller and should not be hidden behind whichever harness setup issue
     // happens to exist on this machine.
+    const escapedBody = rejectAccidentalEscapedNewlines(flags.body, flags.literalBackslashN);
+    if (escapedBody !== null) {
+        deps.io.err(escapedBody);
+        return EXIT.usage;
+    }
     const built = buildQuestions(flags, question);
     if (!built.ok) {
         deps.io.err(built.error);
@@ -759,19 +962,19 @@ export function hookActivationAdvice(installations) {
     const harnesses = new Set(installations.map((installation) => installation.harness));
     const advice = [];
     if (installations.some((installation) => installation.harness === 'claude-code' && !installation.global)) {
-        advice.push('Claude Code: send one new prompt; project hook files reload without a restart');
+        advice.push('Claude Code: start one fresh session, send one prompt, then run `notifai doctor`');
     }
     if (installations.some((installation) => installation.harness === 'claude-code' && installation.global)) {
-        advice.push('Claude Code global hooks: send one prompt; start a new session only if it does not fire');
+        advice.push('Claude Code global hooks: start one fresh session, send one prompt, then run `notifai doctor`');
     }
     if (installations.some((installation) => installation.harness === 'cursor' && !installation.global)) {
-        advice.push('Cursor: send one prompt, then run `notifai doctor`; start a new session only if it still has not fired');
+        advice.push('Cursor: start one fresh conversation, send one prompt, finish its first turn, then run `notifai doctor`');
     }
     if (installations.some((installation) => installation.harness === 'cursor' && installation.global)) {
-        advice.push('Cursor global hooks: send one prompt; start a new session only if it does not fire');
+        advice.push('Cursor global hooks: start one fresh conversation, send one prompt, finish its first turn, then run `notifai doctor`');
     }
     if (harnesses.has('codex')) {
-        advice.push('Codex: send one prompt, then run `notifai doctor`; start a new session only if it still has not fired');
+        advice.push('Codex: approve the Notifai handlers in `/hooks` if asked, start one fresh session, send one prompt, then run `notifai doctor`');
     }
     if (harnesses.has('opencode')) {
         advice.push('OpenCode: restart it, then send one prompt; plugins load at startup, but non-blocking question continuation is intentionally unsupported');
@@ -800,7 +1003,6 @@ export async function acknowledgeCommand(deps, requestId, flags) {
     const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     logger.info('acknowledgement.attempted', {
         request_id: requestId,
-        text,
         characters: text.length,
     });
     const authed = authedClient(deps, config);
@@ -817,7 +1019,7 @@ export async function acknowledgeCommand(deps, requestId, flags) {
         logger.info('acknowledgement.outcome', {
             request_id: requestId,
             outcome: result.status,
-            text: result.agent_acknowledgement.text,
+            text_chars: result.agent_acknowledgement.text.length,
             created_at: result.agent_acknowledgement.created_at,
             agent_acknowledgement_required: true,
         });
@@ -838,12 +1040,27 @@ export async function acknowledgeCommand(deps, requestId, flags) {
 }
 /** Retire a question so a late answer is rejected rather than silently lost. */
 export async function closeCommand(deps, requestId, flags = {}) {
+    if (flags.pending === true && requestId !== undefined) {
+        deps.io.err('Pass a request id or --pending, not both.');
+        return EXIT.usage;
+    }
+    if (flags.pending !== true && requestId === undefined) {
+        deps.io.err('Pass a request id or --pending.');
+        return EXIT.usage;
+    }
+    if (flags.pending === true) {
+        return closePendingQuestions(deps, flags.json === true);
+    }
+    const local = await closeLocalQuestion(deps, requestId, flags.json === true);
+    if (local !== null)
+        return local;
     const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
     const authed = authedClient(deps, config);
     if (!authed)
         return EXIT.auth;
     try {
         const response = await authed.client.closeReplies(requestId);
+        forgetClosedQuestion(deps, requestId);
         if (flags.json) {
             deps.io.out(JSON.stringify({
                 ...response,
@@ -861,6 +1078,148 @@ export async function closeCommand(deps, requestId, flags = {}) {
         return reportError(deps, err);
     }
 }
+/**
+ * Retire this session's outstanding questions, including registrations the
+ * Stop hook has not pushed yet. Unpushed entries only exist locally: dropping
+ * them is the whole retirement. Live ones still need their reply window closed.
+ */
+async function closePendingQuestions(deps, json) {
+    const now = (deps.now ?? Date.now)();
+    const sessionId = readProjectSession(deps.cwd, deps.env, now);
+    if (sessionId === null) {
+        deps.io.err('No active session pointer is available in this directory.');
+        return EXIT.noReply;
+    }
+    const pending = readSessionState(sessionId, deps.env).pending ?? [];
+    if (pending.length === 0) {
+        if (json) {
+            deps.io.out(JSON.stringify({ session_id: sessionId, withdrawn: [], closed: [] }, null, 2));
+        }
+        else {
+            deps.io.err(`Session ${sessionId} has no registered question pending.`);
+        }
+        return EXIT.noReply;
+    }
+    const withdrawn = withdrawUnpushedQuestions(sessionId, deps.env);
+    const live = (readSessionState(sessionId, deps.env).pending ?? []).filter((entry) => entry.request_id !== undefined);
+    const closed = [];
+    if (live.length > 0) {
+        const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
+        const authed = authedClient(deps, config);
+        if (!authed)
+            return EXIT.auth;
+        for (const entry of live) {
+            try {
+                await authed.client.closeReplies(entry.request_id);
+                parkClosedQuestion(sessionId, deps.env, entry);
+                dropPendingQuestion(sessionId, deps.env, entry);
+                closed.push(entry.request_id);
+            }
+            catch (err) {
+                return reportError(deps, err, { operation: 'close', request_id: entry.request_id });
+            }
+        }
+    }
+    const output = {
+        session_id: sessionId,
+        withdrawn: withdrawn.map((entry) => ({
+            question: entry.question,
+            ...(entry.question_id === undefined ? {} : { question_id: entry.question_id }),
+        })),
+        closed,
+    };
+    if (json)
+        deps.io.out(JSON.stringify(output, null, 2));
+    else {
+        if (withdrawn.length > 0) {
+            deps.io.out(withdrawn.length === 1
+                ? 'Withdrew 1 unpushed question so a later Stop will not send it.'
+                : `Withdrew ${withdrawn.length} unpushed questions so a later Stop will not send them.`);
+        }
+        for (const requestId of closed) {
+            deps.io.out(`Closed the reply window for ${requestId}.`);
+        }
+    }
+    return EXIT.ok;
+}
+/**
+ * Close one outstanding question by the stable id `notifai ask` returned, or
+ * by a request id already on a device. Unpushed entries only exist locally.
+ * Returns null when this directory's session has no matching registration, so
+ * the caller can still close a live request id against the service.
+ */
+async function closeLocalQuestion(deps, id, json) {
+    const now = (deps.now ?? Date.now)();
+    const sessionId = readProjectSession(deps.cwd, deps.env, now);
+    if (sessionId === null)
+        return null;
+    const entry = (readSessionState(sessionId, deps.env).pending ?? []).find((candidate) => candidate.question_id === id || candidate.request_id === id);
+    if (entry === undefined)
+        return null;
+    if (entry.request_id === undefined) {
+        dropPendingQuestion(sessionId, deps.env, entry);
+        const output = {
+            session_id: sessionId,
+            withdrawn: [
+                {
+                    question: entry.question,
+                    ...(entry.question_id === undefined ? {} : { question_id: entry.question_id }),
+                },
+            ],
+            closed: [],
+        };
+        if (json)
+            deps.io.out(JSON.stringify(output, null, 2));
+        else {
+            deps.io.out(`Withdrew unpushed question ${entry.question_id ?? id} so a later Stop will not send it.`);
+        }
+        return EXIT.ok;
+    }
+    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
+    const authed = authedClient(deps, config);
+    if (!authed)
+        return EXIT.auth;
+    try {
+        const response = await authed.client.closeReplies(entry.request_id);
+        parkClosedQuestion(sessionId, deps.env, entry);
+        dropPendingQuestion(sessionId, deps.env, entry);
+        if (json) {
+            deps.io.out(JSON.stringify({
+                ...response,
+                question_id: entry.question_id,
+                acknowledgement_command: acknowledgementCommand(response.request_id, response.agent_acknowledgement_required, response.agent_acknowledgement_text_required, response.agent_acknowledgement, response.replies.length > 0),
+            }, null, 2));
+        }
+        else {
+            deps.io.out(`Closed the reply window for ${entry.request_id}.`);
+            if (response.replies.length > 0)
+                printAcknowledgementStatus(deps, response);
+        }
+        return EXIT.ok;
+    }
+    catch (err) {
+        return reportError(deps, err, { operation: 'close', request_id: entry.request_id });
+    }
+}
+function forgetClosedQuestion(deps, requestId) {
+    const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)());
+    if (sessionId === null)
+        return;
+    const entry = (readSessionState(sessionId, deps.env).pending ?? []).find((candidate) => candidate.request_id === requestId);
+    if (entry === undefined)
+        return;
+    parkClosedQuestion(sessionId, deps.env, entry);
+    dropPendingQuestion(sessionId, deps.env, entry);
+}
+function parkClosedQuestion(sessionId, env, entry) {
+    try {
+        parkForRetirement(sessionId, env, entry, 'expired');
+    }
+    catch {
+        // Incomplete identifiers cannot be retired on a device; dropping the
+        // local record is still the right way to stop a later Stop from waiting.
+    }
+}
 /** True when this process is `npx` / `npm exec`, not a global or linked install. */
 export function runningViaNpx(env, scriptPath) {
     if (env['npm_command'] === 'exec')
@@ -894,12 +1253,19 @@ function resolveHookAdapterTarget(deps, flags) {
 }
 function printHooksInstallClose(deps, harness, file) {
     const label = HARNESS_LABELS[harness];
+    const activation = harness === 'codex'
+        ? 'Approve the Notifai handlers in `/hooks` if Codex asks, then start one fresh Codex session, send one prompt, and run `notifai doctor`.'
+        : harness === 'cursor'
+            ? 'Start one fresh Cursor conversation, send one prompt, finish its first turn, then run `notifai doctor`.'
+            : harness === 'opencode'
+                ? 'Restart OpenCode, start one fresh session, send one prompt, then run `notifai doctor`.'
+                : `Start one fresh ${label} session, send one prompt, then run \`notifai doctor\`.`;
     if (deps.io.interactive === true && deps.io.note) {
-        void deps.io.note(`${file}\nSend one ${label} prompt, then run \`notifai doctor\`.`, `${label} hooks installed`);
+        void deps.io.note(`${file}\n${activation}`, `${label} hooks installed`);
         return;
     }
     deps.io.out(`Installed ${harness} hooks in ${file}`);
-    deps.io.out(`Send one ${label} prompt, then check \`notifai doctor\`.`);
+    deps.io.out(activation);
 }
 export function hooksInstallCommand(deps, flags) {
     if (flags.harness === undefined) {
@@ -934,7 +1300,18 @@ export function hooksInstallCommand(deps, flags) {
     const existing = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform).filter((installation) => installation.harness === harness);
     const otherScope = existing.filter((installation) => installation.global !== wantGlobal);
     if (!wantGlobal && otherScope.some((installation) => installation.global)) {
-        const globalFile = otherScope.find((installation) => installation.global)?.file;
+        const globalInstallations = otherScope.filter((installation) => installation.global);
+        const globalInstallation = globalInstallations[0];
+        const installedEvents = new Set(globalInstallation?.handlers
+            .map((handler) => handlerEvent(handler.command))
+            .filter((event) => event !== null && HOOK_EVENTS.includes(event)) ?? []);
+        if (globalInstallations.length !== 1 ||
+            globalInstallations.some((installation) => (installation.problems?.length ?? 0) > 0) ||
+            globalInstallations.some((installation) => stopShapeProblems(installation, deps.hookPlatform).length > 0) ||
+            !requiredHookEvents(harness).every((event) => installedEvents.has(event))) {
+            return hooksInstallCommand(deps, { ...flags, global: true, harness });
+        }
+        const globalFile = globalInstallation?.file;
         deps.io.out(`${HARNESS_LABELS[harness]} hooks already cover this machine (${globalFile}). This project does not need its own copy. To wire only this project: notifai hooks uninstall --harness ${harness} --global && notifai hooks install --harness ${harness}`);
         return EXIT.ok;
     }
@@ -995,7 +1372,21 @@ export function hooksInstallCommand(deps, flags) {
         installed =
             codexPaths === null
                 ? withTargetFileLock(settingsTarget, () => installInto(settingsTarget))
-                : withCodexLayerTransaction(codexPaths, (inspection) => installInto(inspection.writeTarget));
+                : withCodexLayerTransaction(codexPaths, (inspection) => {
+                    const staleTarget = inspection.writeTarget === inspection.paths.hooksJson
+                        ? inspection.paths.configToml
+                        : inspection.paths.hooksJson;
+                    const staleEvents = staleTarget === inspection.paths.hooksJson
+                        ? inspection.ourJsonEvents
+                        : inspection.ourTomlEvents;
+                    if (staleEvents.length > 0) {
+                        const staleDocument = loadSettings(staleTarget);
+                        const stripped = removeHooks(staleDocument, scriptPath);
+                        if (stripped.replaced.length > 0)
+                            applyPlan(staleTarget, stripped.document);
+                    }
+                    return installInto(inspection.writeTarget);
+                });
     }
     catch (err) {
         deps.io.err(String(err));
@@ -1031,7 +1422,7 @@ function foreignStopHandlers(document) {
         return [];
     return groups
         .flatMap((group) => group.hooks ?? [])
-        .filter((handler) => !/ hook (user-prompt-submit|stop|session-end)\b/.test(handler.command));
+        .filter((handler) => !/ hook (session-start|subagent-start|activation-stop|user-prompt-submit|stop|session-end)\b/.test(handler.command));
 }
 /**
  * Writes the OpenCode plugin, replacing any Notifai plugin already there —
@@ -1149,7 +1540,11 @@ export function hooksUninstallCommand(deps, flags) {
         result =
             codexPaths === null
                 ? removeInstalledHooks()
-                : withCodexLayerTransaction(codexPaths, removeInstalledHooks);
+                : withCodexLayerTransaction(codexPaths, (inspection) => {
+                    const stripped = removeInstalledHooks();
+                    cleanupEmptiedCodexLayer(inspection.paths);
+                    return stripped;
+                });
     }
     catch (err) {
         deps.io.err(String(err));