@raidiant/notifai 8.0.0 → 9.1.0

package/dist/commands-hooks.js

@@ -9,28 +9,46 @@ 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, 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';
+import { resolveCommandSession } from './command-session.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 +81,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 +137,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', cwd, deps.env);
+        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, harness, cwd);
+            }
+            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, harness, cwd)) {
+                promptActivationStdout = sessionActivationOutput(harness, 'UserPromptSubmit', cwd, deps.env);
+                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(cwd, deps.env));
+        return EXIT.ok;
+    }
     let config = null;
     let configFailure;
     try {
@@ -127,6 +317,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 +365,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 +411,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 +454,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 +469,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.
  *
@@ -315,6 +511,26 @@ export function describeHookFailure(err) {
     }
     return lines;
 }
+/** One stable failure contract for every machine-readable ask refusal. */
+export function reportAskFailure(deps, flags, failure) {
+    if (flags.json === true) {
+        deps.io.out(JSON.stringify({ ok: false, registered: false, ...failure }, null, 2));
+    }
+    else {
+        deps.io.err(failure.message);
+        deps.io.err(`next: ${failure.remedy}`);
+    }
+    return failure.exit_code;
+}
+function askFailure(deps, flags, code, checkId, message, remedy, exitCode = EXIT.usage) {
+    return reportAskFailure(deps, flags, {
+        code,
+        check_id: checkId,
+        exit_code: exitCode,
+        remedy,
+        message,
+    });
+}
 /**
  * Turn ask input into questions plus their canonical body. Everything is
  * validated at registration because a later hook failure is easy to miss.
@@ -449,8 +665,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,
@@ -461,14 +678,14 @@ function recordRegisteredQuestion(deps, sessionId, built, draft, json = false) {
     }
     catch (err) {
         log(deps).error('ask.registered', { ok: false, session: sessionId, message: String(err) });
-        deps.io.err(`Could not register the question: ${err instanceof Error ? err.message : String(err)}`);
-        return EXIT.failed;
+        return askFailure(deps, { json }, 'registration_failed', 'question_registration', `Could not register the question: ${err instanceof Error ? err.message : String(err)}`, 'retire an older pending question if the limit was reached, then retry the same ask', EXIT.failed);
     }
     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,
     });
@@ -479,17 +696,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;
@@ -505,8 +725,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}, ` : '';
@@ -522,30 +742,31 @@ 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) {
     const authed = authedClient(deps, config);
-    if (!authed)
-        return EXIT.auth;
+    if (!authed) {
+        return askFailure(deps, flags, 'auth_required', 'credential', 'Question routing is not paired on this machine.', 'run `notifai init --json`', EXIT.auth);
+    }
     const mediaIds = [];
     for (const image of flags.image ?? []) {
         if (image.startsWith('med_')) {
             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);
-            return uploaded.exit;
+            return askFailure(deps, flags, 'media_upload_failed', 'media', uploaded.error ?? 'The image upload failed.', 'fix the reported image or network problem, then retry the same ask', uploaded.exit);
         }
         mediaIds.push(uploaded.mediaId);
     }
     const ready = buildAskDraft(config, built, flags, invocation, mediaIds);
     if (!ready.ok) {
-        deps.io.err(ready.error);
-        return EXIT.usage;
+        return askFailure(deps, flags, 'invalid_draft', 'draft', ready.error, 'fix the reported field and retry');
     }
     return recordRegisteredQuestion(deps, sessionId, built, ready.draft, flags.json === true);
 }
@@ -558,24 +779,20 @@ 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) {
+        return askFailure(deps, flags, 'invalid_input', 'body', escapedBody, 'fix the body and retry');
+    }
     const built = buildQuestions(flags, question);
     if (!built.ok) {
-        deps.io.err(built.error);
-        return EXIT.usage;
+        return askFailure(deps, flags, 'invalid_input', 'questions', built.error, 'fix the question input and retry');
     }
     const mediaInputError = validateMediaInputs(flags.image, flags.imageAlt);
     if (mediaInputError !== null) {
-        deps.io.err(mediaInputError);
-        return EXIT.usage;
-    }
-    const routingConfig = loadConfig({ cwd: deps.cwd, env: deps.env });
-    if (!routingConfig.ask_notifications.value) {
-        deps.io.err('Question routing is disabled by ask_notifications=false; enable it or use a blocking `notifai send --reply` question.');
-        return EXIT.usage;
+        return askFailure(deps, flags, 'invalid_input', 'media', mediaInputError, 'fix the media flags and retry');
     }
     if (deps.store.load() === null) {
-        deps.io.err('Question routing is not paired on this machine; run `notifai login` before registering an asynchronous question.');
-        return EXIT.usage;
+        return askFailure(deps, flags, 'auth_required', 'credential', 'Question routing is not paired on this machine.', 'run `notifai init --json`', EXIT.auth);
     }
     // An agent calling this gets no hook payload. Harness-native environment
     // markers identify the active owner, while UserPromptSubmit adds the hook's
@@ -584,66 +801,64 @@ export function askCommand(deps, question, flags) {
     const { active, contested } = resolveActiveHarness(deps.env, deps.cwd, now);
     let sessionId;
     if (active !== null) {
-        const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform);
+        if (contested.length > 1) {
+            return askFailure(deps, flags, 'session_identity_ambiguous', 'exact_session', `Several harness sessions could own this shell (${contested.map((candidate) => candidate.label).join(', ')}).`, 'run the ask from a shell with one exact active harness session');
+        }
+        const exactState = active.sessionId === undefined
+            ? null
+            : readSessionState(active.sessionId, deps.env);
+        const installationCwd = exactState?.activation_cwd ?? deps.cwd;
+        const installationDeps = installationCwd === deps.cwd ? deps : { ...deps, cwd: installationCwd };
+        const installations = findInstallations(installationCwd, deps.env, deps.hookAdapterHome, deps.hookPlatform);
         const activeInstalled = installations.some((installation) => installation.harness === active.harness);
         if (!activeInstalled) {
-            for (const line of diagnoseActiveHarnessSession(active, 'not-installed', installations, contested)) {
-                deps.io.err(line);
-            }
-            return EXIT.usage;
+            return askFailure(deps, flags, 'hooks_not_installed', 'hook_installation', `Notifai ${active.label} hooks are not installed for this project.`, `run \`notifai init --json\` from this ${active.label} session`);
         }
         if (active.sessionId === undefined) {
-            for (const problem of activeQuestionRouteProblems(deps, active, installations)) {
-                deps.io.err(`Question routing is not ready: ${problem}`);
-            }
-            return EXIT.usage;
+            return askFailure(deps, flags, 'session_identity_missing', 'exact_session', `The active ${active.label} shell does not expose an exact session id.`, 'use a blocking `notifai send --reply` question');
         }
-        const projectPointer = readMatchingProjectSessionPointer(deps.cwd, deps.env, now, active.sessionId, active.harness);
-        if (projectPointer === null) {
-            for (const line of diagnoseActiveHarnessSession(active, 'not-fired', installations, contested)) {
-                deps.io.err(line);
-            }
-            return EXIT.usage;
-        }
-        const routeProblems = activeQuestionRouteProblems(deps, active, installations);
+        const routeProblems = activeQuestionRouteProblems(installationDeps, active, installations);
         if (routeProblems.length > 0) {
-            for (const problem of routeProblems)
-                deps.io.err(`Question routing is not ready: ${problem}`);
-            return EXIT.usage;
+            return askFailure(deps, flags, 'question_routing_unavailable', 'hook_contract', `Question routing is not ready: ${routeProblems.join('; ')}`, 'run `notifai init --json` and follow its question-routing remedy');
         }
-        if (readSessionState(projectPointer.sessionId, deps.env).last_stop_at === undefined) {
-            deps.io.err(`Question routing is not ready: this ${active.label} session has fired UserPromptSubmit, but its Stop hook has not been observed. End one harmless turn, send a new prompt, then run \`notifai doctor\`.`);
-            return EXIT.usage;
+        const state = exactState ?? readSessionState(active.sessionId, deps.env);
+        if (state.harness !== active.harness || state.last_prompt_at === undefined) {
+            return askFailure(deps, flags, 'session_not_activated', 'user_prompt_submit', `This exact ${active.label} session has not fired UserPromptSubmit.`, `send one prompt in this ${active.label} session, then retry \`notifai ask --json\``);
         }
-        sessionId = projectPointer.sessionId;
+        if (state.last_stop_at === undefined) {
+            return askFailure(deps, flags, 'stop_not_observed', 'stop_hook', `This exact ${active.label} session has fired UserPromptSubmit, but its Stop hook has not been observed.`, `end one harmless turn, send a new prompt, then retry \`notifai ask --json\``);
+        }
+        sessionId = active.sessionId;
     }
     else {
-        for (const line of diagnoseMissingSession(deps))
-            deps.io.err(line);
-        deps.io.err('Could not prove which live harness session owns this command, so Notifai will not register a question that could be delivered to the wrong or already-ended agent. Run it from a supported harness with exact session identity, or use a blocking `notifai send --reply` question.');
-        return EXIT.usage;
+        return askFailure(deps, flags, 'session_identity_missing', 'exact_session', 'Could not prove which live harness session owns this command.', 'run it from a supported harness with exact session identity, or use a blocking `notifai send --reply` question');
     }
     if (!sessionId) {
-        for (const line of diagnoseMissingSession(deps))
-            deps.io.err(line);
-        return EXIT.usage;
+        return askFailure(deps, flags, 'session_identity_missing', 'exact_session', 'No exact active session is available.', 'use a blocking `notifai send --reply` question');
+    }
+    let routingConfig;
+    try {
+        routingConfig = loadConfig({ cwd: deps.cwd, env: deps.env, sessionId });
+    }
+    catch (err) {
+        return askFailure(deps, flags, 'config_invalid', 'configuration', `Question routing configuration is invalid: ${String(err)}`, 'fix the reported Notifai configuration and retry');
+    }
+    if (!routingConfig.ask_notifications.value) {
+        return askFailure(deps, flags, 'question_routing_disabled', 'ask_notifications', 'Question routing is disabled by ask_notifications=false.', 'enable question routing or use a blocking `notifai send --reply` question');
     }
     const source = resolveDraftInvocation(deps, flags, active);
     if (!source.ok) {
-        deps.io.err(source.error);
-        return EXIT.usage;
+        return askFailure(deps, flags, 'invalid_source', 'source_context', source.error, 'remove the conflicting source override and retry');
     }
     if (source.invocation.source?.session_id !== sessionId) {
-        deps.io.err(`Question routing is not ready: --session-id or NOTIFAI_SESSION_ID does not match the exact active ${active.label} session; refusing cross-session routing.`);
-        return EXIT.usage;
+        return askFailure(deps, flags, 'session_identity_mismatch', 'exact_session', `The inferred session does not match the exact active ${active.label} session.`, 'remove NOTIFAI_SESSION_ID and retry from the exact active session');
     }
     // Placeholders let every body, source, project, media, and payload limit fail
     // before an upload starts. The real ids replace them only after this passes.
     const placeholders = (flags.image ?? []).map((_, index) => `med_pending_${index + 1}`);
     const preflight = buildAskDraft(routingConfig, built, flags, source.invocation, placeholders);
     if (!preflight.ok) {
-        deps.io.err(preflight.error);
-        return EXIT.usage;
+        return askFailure(deps, flags, 'invalid_draft', 'draft', preflight.error, 'fix the reported field and retry');
     }
     if ((flags.image?.length ?? 0) > 0) {
         return uploadAskMedia(deps, routingConfig, sessionId, built, flags, source.invocation);
@@ -688,87 +903,24 @@ export function activeQuestionRouteProblems(deps, active, installations) {
     problems.push(...codexTrustProblems(matching, deps.env));
     return [...new Set(problems)];
 }
-function diagnoseActiveHarnessSession(active, problem, installations, contested = []) {
-    // Naming one harness confidently is wrong when the environment carries the
-    // markers of several and none of them has fired here: whichever one the
-    // agent is told to prompt may not be the one it is running in.
-    const ambiguity = contested.length > 1
-        ? [
-            `Several harness markers are present here (${contested.map((candidate) => candidate.label).join(', ')}) and none names a session that has fired in this directory, so ${active.label} is a guess from the environment. Send the prompt in the harness you are actually running.`,
-        ]
-        : [];
-    if (problem === 'not-installed') {
-        const others = installations.map((installation) => installation.harness);
-        return [
-            `Could not register the question for the active ${active.label} session: Notifai ${active.label} hooks are not installed for this project.`,
-            ...ambiguity,
-            ...(others.length === 0
-                ? []
-                : [
-                    `Hooks installed for ${[...new Set(others)].join(', ')} do not route an active ${active.label} session.`,
-                ]),
-            `Run \`notifai hooks install --harness ${active.harness}\`, then send one ${active.label} prompt and run \`notifai doctor\`.`,
-            `Retry \`notifai ask\` only after doctor reports that the ${active.label} hooks fired.`,
-        ];
-    }
-    if (problem === 'different-session') {
-        return [
-            `Could not register the question for the active ${active.label} session: the project pointer belongs to another ${active.label} session or harness.`,
-            ...ambiguity,
-            `Refusing to guess or cross-wire the question. Send one prompt in this ${active.label} session, then run \`notifai doctor\`.`,
-            `Retry \`notifai ask\` only after doctor reports that this active ${active.label} session fired the hooks.`,
-        ];
-    }
-    return [
-        `Could not register the question for the active ${active.label} session: Notifai hooks are installed, but this session has not published its pointer.`,
-        ...ambiguity,
-        `Send one ${active.label} prompt, then run \`notifai doctor\`.`,
-        `Retry \`notifai ask\` only after doctor reports that the active ${active.label} session fired the hooks.`,
-    ];
-}
-/**
- * Why `ask` cannot see a session, in terms of what to do about it.
- *
- * Only a UserPromptSubmit hook firing produces the pointer this reads, and the
- * old message answered every cause with "run `notifai hooks install` and send
- * one prompt". The useful next action depends on the harness: some reload
- * project hook files, OpenCode loads its plugin at startup, and Codex should be
- * checked after a prompt before assuming that a new session is required.
- */
-function diagnoseMissingSession(deps) {
-    const installations = findInstallations(deps.cwd, deps.env, deps.hookAdapterHome, deps.hookPlatform);
-    if (installations.length === 0) {
-        return [
-            'Could not tell which harness session this is: no Notifai hooks are installed for this project.',
-            'Run `notifai hooks install`, then follow the activation instruction it prints.',
-        ];
-    }
-    const where = installations.map((i) => `${i.harness} in ${i.file}`).join(', ');
-    return [
-        `Could not tell which harness session this is. Notifai hooks are installed (${where}),`,
-        'but no usable session pointer from the last 24 hours exists here.',
-        hookActivationAdvice(installations),
-        'Do not bypass this with a guessed session id; run from the exact active harness session or use a blocking `notifai send --reply` question.',
-    ];
-}
 /** The least disruptive verified way to make each installed adapter run once. */
 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');
@@ -794,10 +946,14 @@ export async function acknowledgeCommand(deps, requestId, flags) {
         return EXIT.usage;
     }
     const logger = log(deps);
-    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
+    const lifecycleSession = resolveCommandSession(deps, requestId);
+    const config = loadLoggedConfig(deps, {
+        cwd: deps.cwd,
+        env: deps.env,
+        ...(lifecycleSession === null ? {} : { sessionId: lifecycleSession.sessionId }),
+    });
     logger.info('acknowledgement.attempted', {
         request_id: requestId,
-        text,
         characters: text.length,
     });
     const authed = authedClient(deps, config);
@@ -814,13 +970,12 @@ 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,
         });
-        const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)());
-        if (sessionId !== null) {
-            clearAcknowledgementObligation(sessionId, deps.env, requestId);
+        if (lifecycleSession !== null) {
+            clearAcknowledgementObligation(lifecycleSession.sessionId, deps.env, requestId);
         }
         if (flags.json)
             deps.io.out(JSON.stringify(output, null, 2));
@@ -835,12 +990,32 @@ 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 = {}) {
-    const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env });
+    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 lifecycleSession = resolveCommandSession(deps, requestId);
+    const config = loadLoggedConfig(deps, {
+        cwd: deps.cwd,
+        env: deps.env,
+        ...(lifecycleSession === null ? {} : { sessionId: lifecycleSession.sessionId }),
+    });
     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,
@@ -858,6 +1033,149 @@ 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 lifecycleSession = resolveCommandSession(deps);
+    if (lifecycleSession === null) {
+        deps.io.err('No active session pointer is available in this directory.');
+        return EXIT.noReply;
+    }
+    const sessionId = lifecycleSession.sessionId;
+    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, sessionId });
+        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 lifecycleSession = resolveCommandSession(deps, id);
+    if (lifecycleSession === null)
+        return null;
+    const sessionId = lifecycleSession.sessionId;
+    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, sessionId });
+    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 lifecycleSession = resolveCommandSession(deps, requestId);
+    if (lifecycleSession === null)
+        return;
+    const sessionId = lifecycleSession.sessionId;
+    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')
@@ -891,12 +1209,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) {
@@ -931,7 +1256,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;
     }
@@ -992,7 +1328,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));
@@ -1028,7 +1378,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 —
@@ -1146,7 +1496,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));