claude-dev-env 7.1.0 → 7.2.1

package/.agents/skills/everything-search/SKILL.md

@@ -15,7 +15,11 @@ Search files instantly on Windows using the Everything command-line interface (e
 
 Every search carries a scope: a project path or registry token, an `ext:` filter, a `dm:` date filter, a `size:` filter, or a name pattern. A bare whole-drive scan or a network-share sweep is out of bounds. Narrow the search to what you need.
 
-When `es.exe` fails or returns nothing, self-heal first: fall back to the `Glob` tool (name and path patterns) or `Grep` (file contents), and report the outage so the reader knows the index was unavailable. When self-healing also fails, ask the user through `AskUserQuestion` with a short analysis and next-step options.
+When `es.exe` returns Error 8, the Everything IPC client window is missing. Retry the same search twice with a short pause. Do not report that Everything is not running, not loaded, or that the index is unavailable from that first miss. After those retries fail, report that the Everything IPC client did not answer and that the service state was not probed, then fall back to the `Glob` tool (name and path patterns) or `Grep` (file contents) with the same scope.
+
+When `es.exe` is missing, or a later search returns no hits, fall back to `Glob` or `Grep`. A failed search is not proof the index is down. When those fallbacks also fail, ask the user through `AskUserQuestion` with a short analysis and next-step options.
+
+Direct `es.exe` calls use the same Error 8 retry. The wrapper in `scripts/everything_search.py` already retries Error 8 twice.
 
 ## Registry tokens
 
@@ -139,7 +143,8 @@ Run separate searches for each extension type:
 
 ## Best Practices
 
-- Everything must be running (system tray) for es.exe to work
+- `es.exe` talks to the Everything tray client IPC window. The Everything service can be running while Error 8 still fires.
+- On Error 8, retry the same search twice before treating the search as failed.
 - Run one extension per search for cleaner results
 - Use `dm:` to filter recent files by the index timestamp
 - Combine with path to narrow scope
@@ -165,5 +170,5 @@ Everything indexes REAL paths only, not junctions or mapped drives.
 
 ## Files
 
-- `scripts/everything_search.py` runs one Everything search without a shell.
-- `scripts/test_everything_search.py` verifies registry expansion and command failures.
+- `scripts/everything_search.py` runs one Everything search without a shell, retries Error 8 twice, and reports that the IPC client did not answer and that the service state was not probed when those retries fail.
+- `scripts/test_everything_search.py` verifies registry expansion, command failures, Error 8 retry, and the IPC-client miss message.

package/.agents/skills/everything-search/scripts/everything_search.py

@@ -4,6 +4,7 @@ import json
 import shutil
 import subprocess
 import sys
+import time
 from collections.abc import Mapping, Sequence
 from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import TextIO
@@ -14,6 +15,10 @@ from everything_search_command_constants.config.constants import (
     EXECUTION_ERROR_EXIT_CODE,
     INFORMATIONAL_ARGUMENT,
     INVALID_INPUT_EXIT_CODE,
+    IPC_CLIENT_DID_NOT_ANSWER_MESSAGE,
+    IPC_WINDOW_NOT_FOUND_EXIT_CODE,
+    IPC_WINDOW_RETRY_COUNT,
+    IPC_WINDOW_RETRY_DELAY_SECONDS,
     PROJECT_PATHS_FILE_NAME,
     REGISTRY_META_KEY,
     SEARCH_SCOPE_REQUIRED_MESSAGE,
@@ -115,21 +120,32 @@ def _run_search(
     search_stdout: TextIO,
     search_stderr: TextIO,
 ) -> int:
-    try:
-        search_run = subprocess.run(
-            [executable_path, *all_search_arguments],
-            capture_output=True,
-            check=False,
-            encoding=UTF8_ENCODING,
-            shell=False,
-            text=True,
-        )
-    except OSError as error:
-        search_stderr.write(f"{error}\n")
-        return EXECUTION_ERROR_EXIT_CODE
-    search_stdout.write(search_run.stdout)
-    search_stderr.write(search_run.stderr)
-    return search_run.returncode
+    ipc_client_did_not_answer_message = IPC_CLIENT_DID_NOT_ANSWER_MESSAGE
+    ipc_window_not_found_exit_code = IPC_WINDOW_NOT_FOUND_EXIT_CODE
+    ipc_window_retry_count = IPC_WINDOW_RETRY_COUNT
+    ipc_window_retry_delay_seconds = IPC_WINDOW_RETRY_DELAY_SECONDS
+    last_search_run = None
+    for each_attempt_index in range(ipc_window_retry_count + 1):
+        try:
+            last_search_run = subprocess.run(
+                [executable_path, *all_search_arguments],
+                capture_output=True,
+                check=False,
+                encoding=UTF8_ENCODING,
+                shell=False,
+                text=True,
+            )
+        except OSError as error:
+            search_stderr.write(f"{error}\n")
+            return EXECUTION_ERROR_EXIT_CODE
+        if last_search_run.returncode != ipc_window_not_found_exit_code:
+            search_stdout.write(last_search_run.stdout)
+            search_stderr.write(last_search_run.stderr)
+            return last_search_run.returncode
+        if each_attempt_index < ipc_window_retry_count:
+            time.sleep(ipc_window_retry_delay_seconds)
+    search_stderr.write(ipc_client_did_not_answer_message)
+    return ipc_window_not_found_exit_code
 
 
 def _run_registered_search(

package/.agents/skills/everything-search/scripts/everything_search_command_constants/config/constants.py

@@ -5,6 +5,12 @@ EXECUTABLE_NAME = "es.exe"
 EXECUTION_ERROR_EXIT_CODE = 1
 INFORMATIONAL_ARGUMENT = "-version"
 INVALID_INPUT_EXIT_CODE = 2
+IPC_CLIENT_DID_NOT_ANSWER_MESSAGE = (
+    "Everything IPC client did not answer. Everything service state was not probed.\n"
+)
+IPC_WINDOW_NOT_FOUND_EXIT_CODE = 8
+IPC_WINDOW_RETRY_COUNT = 2
+IPC_WINDOW_RETRY_DELAY_SECONDS = 0.5
 PROJECT_PATHS_FILE_NAME = "project-paths.json"
 REGISTRY_META_KEY = "_meta"
 SEARCH_SCOPE_REQUIRED_MESSAGE = "The first search argument must define a path, project, name, extension, date, or size scope.\n"

package/.agents/skills/everything-search/scripts/test_everything_search.py

@@ -113,12 +113,79 @@ def test_main_passes_through_child_exit_status() -> None:
     with (
         patch.object(search, "load_registry", return_value={}),
         patch.object(search.shutil, "which", return_value="es.exe"),
-        patch.object(search.subprocess, "run", return_value=completed_process),
+        patch.object(
+            search.subprocess, "run", return_value=completed_process
+        ) as run_process,
         patch.object(search.sys, "stderr", captured_stderr),
     ):
         exit_code = search.main(["config.py"])
     assert exit_code == 7
     assert captured_stderr.getvalue() == "failed\n"
+    run_process.assert_called_once()
+
+
+def _ipc_window_error_process() -> search.subprocess.CompletedProcess:
+    return search.subprocess.CompletedProcess(
+        args=["es.exe", "config.py"],
+        returncode=8,
+        stdout="",
+        stderr=(
+            "Error 8: Everything IPC window not found. "
+            "Please make sure Everything is running.\n"
+        ),
+    )
+
+
+def test_main_retries_ipc_window_error_then_returns_search_hits() -> None:
+    successful_process = search.subprocess.CompletedProcess(
+        args=["es.exe", "config.py"],
+        returncode=0,
+        stdout="found path\n",
+        stderr="",
+    )
+    captured_stdout = io.StringIO()
+    captured_stderr = io.StringIO()
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value="es.exe"),
+        patch.object(
+            search.subprocess,
+            "run",
+            side_effect=[_ipc_window_error_process(), successful_process],
+        ) as run_process,
+        patch.object(search.sys, "stdout", captured_stdout),
+        patch.object(search.sys, "stderr", captured_stderr),
+        patch("time.sleep"),
+    ):
+        exit_code = search.main(["config.py"])
+    assert exit_code == 0
+    assert captured_stdout.getvalue() == "found path\n"
+    assert "not loaded" not in captured_stderr.getvalue().casefold()
+    assert "not running" not in captured_stderr.getvalue().casefold()
+    assert run_process.call_count == 2
+
+
+def test_main_reports_ipc_client_miss_after_ipc_window_retries_exhaust() -> None:
+    captured_stderr = io.StringIO()
+    with (
+        patch.object(search, "load_registry", return_value={}),
+        patch.object(search.shutil, "which", return_value="es.exe"),
+        patch.object(
+            search.subprocess,
+            "run",
+            return_value=_ipc_window_error_process(),
+        ) as run_process,
+        patch.object(search.sys, "stderr", captured_stderr),
+        patch("time.sleep"),
+    ):
+        exit_code = search.main(["config.py"])
+    assert exit_code == 8
+    stderr_text = captured_stderr.getvalue()
+    assert "Everything IPC client did not answer" in stderr_text
+    assert "service state was not probed" in stderr_text.casefold()
+    assert "Please make sure Everything is running" not in stderr_text
+    assert "not loaded" not in stderr_text.casefold()
+    assert run_process.call_count == 3
 
 
 def test_main_reports_missing_executable() -> None:

package/.agents/skills/session-continuity/README.md

@@ -1,9 +1,12 @@
 # Session continuity companion
 
-Status: draft implementation. Claude and Codex adapters have repository-level
-contract tests. Installed-host activation, reload, and agent compliance remain
-unverified. Cursor automatic activation is unsupported by this implementation.
-All three hosts remain part of the requested outcome.
+Status: draft implementation. Claude, Codex, and Cursor adapters have
+repository-level contract tests. Installed-host activation, reload, and agent
+compliance remain unverified.
+
+Every supported host activates Poteto Mode automatically when a session starts
+and when the host resumes the conversation after compaction. An explicit
+invocation still works and still records the user's own scope.
 
 ## The persistence failure
 
@@ -12,6 +15,10 @@ lose its duration, later corrections, or the instruction to reload it. This
 companion saves user-scoped requirements under a stable host-session key and
 returns the current skill contents during supported recovery callbacks.
 
+Automatic activation removes the first half of that failure. A session that
+never carried an explicit invocation still starts with Poteto Mode loaded, so
+the mode does not depend on the user retyping it after each restart.
+
 ## Ownership and setup
 
 Pstack owns `Poteto Mode`, directory `poteto-mode`. Its source description names
@@ -33,7 +40,8 @@ The existing selective `--only core` list does not include the companion in this
 draft. Use the full install above. Plugin-only installations need the same
 canonical installed skill before this setup can run.
 
-The setup defaults to `claude codex`. Pass either host name to configure it alone.
+The setup defaults to `claude codex cursor`. Pass one or more host names to
+configure that subset alone.
 It uses `bin/resolve-install-root.mjs`, including `CLAUDE_CONFIG_DIR` and
 `CODEX_HOME`. It merges only its own hook groups into Claude `settings.json` and
 Codex `hooks.json`, preserves other settings, writes a one-time backup before
@@ -51,10 +59,13 @@ that has not been tested. Use builds exposing the documented events below.
 
 | Host | Adapter input | Forms recognized by the companion |
 | --- | --- | --- |
+| Claude Code | `SessionStart` with source `startup`, `resume`, `compact`, `clear`, or `fork` | Automatic session-scope activation, no user text needed |
 | Claude Code | `UserPromptExpansion`, `expansion_type=slash_command` | Existing `poteto-mode` and `pstack:poteto-mode` command names |
 | Claude Code | `UserPromptSubmit` | A leading `/poteto-mode` or `/pstack:poteto-mode`; exact natural forms below |
+| Codex | `SessionStart` with source `startup`, `resume`, `compact`, or `clear` | Automatic session-scope activation, no user text needed |
 | Codex | `UserPromptSubmit` | A leading `$poteto-mode`, `$pstack:poteto-mode`, or `[$pstack:poteto-mode](path)` skill reference; exact natural forms below |
-| Cursor | No automatic adapter installed | The inspected prompt and lifecycle hooks do not establish the required timing |
+| Cursor | `sessionStart` | Automatic session-scope activation, returned as `additional_context` |
+| Cursor | `beforeSubmitPrompt` | The same leading command and natural forms; the prompt is never blocked |
 
 Natural forms include bare `poteto`, `Use Poteto Mode`, `Activate Poteto Mode`,
 `Invoke Poteto Mode`, and `Poteto Mode applies for this entire session`. Exact
@@ -65,6 +76,12 @@ Free-form style requests and host UI forms that omit the skill token from the
 prompt remain unverified. The adapter's recognition is not proof that every host
 resolves every form as a native skill invocation.
 
+Automatic activation records one session-scope skill requirement carrying the
+`automatic` flag. A later explicit invocation writes the entry again with the
+user's own evidence quote and scope. An explicit deactivation stops automatic
+recovery for the same host session; a Claude or Codex `clear` starts a fresh
+automatic set under the reused session id.
+
 The companion does not define a `/potato-mode` alias or rename `poteto-mode`.
 Quotations, fenced examples, indented code, discussion, imported transcripts, and
 tool-result callbacks do not independently activate the companion. Subsequent
@@ -111,12 +128,14 @@ messages and source comparison snapshots and stay outside the repository.
 
 | Situation | Discovery and restoration |
 | --- | --- |
-| First recognized invocation | Hook creates the record, returns its exact path and read-back, and includes the complete companion instructions |
+| Session start with no record | Hook creates an active record holding a session-scope Poteto Mode requirement and returns its path, read-back, and current source |
+| First recognized invocation | Hook creates or updates the record, returns its exact path and read-back, and includes the complete companion instructions |
 | Later user prompt | Same session key; pending evidence is saved and the companion directs the agent to reconcile it before dependent work |
 | Claude/Codex startup or resume | `SessionStart` with the same id finds the active record and reads current active skill sources |
 | Claude/Codex compaction | `SessionStart` with source `compact` reloads the same record and sources |
-| New unrelated conversation | A new id has no record and inherits nothing |
-| Clear | The same-id record is deactivated; a new id starts empty |
+| Cursor compaction | `preCompact` marks the record for reload; the next `postToolUse` returns the record and sources as `additional_context` |
+| New unrelated conversation | A new id starts a fresh automatic set and inherits no task, rule, or pending message |
+| Clear | The same-id record holds a fresh automatic set |
 | Explicit handoff | The source command binds a snapshot to a known destination host/id; its next supported start callback discovers that record |
 | Explicit deactivation | An inactive tombstone suppresses recovery until another explicit invocation creates a fresh active set |
 
@@ -136,15 +155,20 @@ host-truncated source in full before dependent work. Missing sources produce an
 explicit unavailable message. Changed sources include current contents and a
 bounded before/after comparison. Stored snapshots are for comparison only.
 
-Cursor's `beforeSubmitPrompt` returns `continue` and a blocked-user message, not
-agent context. Its `preToolUse` can send agent context by denying a pending tool,
-and `postToolUse` can inject context after a tool runs. That does not cover a
-reply-only invocation before dependent work. `sessionStart` is fire-and-forget
-when a composer conversation is created; `preCompact` cannot block or modify
-compaction. Startup reminders, first-tool-only gates, or stop-hook follow-ups
-would weaken the requested contract. This draft installs none of those as a
-substitute. Shared storage accepts a `cursor` namespace for explicit operations;
-that is not automatic Cursor support.
+Cursor's documented `sessionStart` output carries `additional_context`, so the
+Cursor adapter loads the record and the current sources when a composer
+conversation is created. Cursor has no post-compaction event that returns agent
+context: `preCompact` runs before compaction and returns only a user message.
+The adapter therefore marks the record during `preCompact` and returns the
+record and sources through the next `postToolUse`, whose documented output
+includes `additional_context`. On Cursor the reload lands with the agent's first
+tool result after compaction rather than before it, which is the earliest
+documented delivery point.
+
+Cursor's `beforeSubmitPrompt` output carries `continue` and a user message, not
+agent context. The adapter uses it to save pending user evidence and to mark an
+explicit invocation for the next reload. It always returns `continue: true`, so
+a companion failure never blocks the user's prompt.
 
 Automatic prompt capture and source emission are code paths. Selecting actual
 user rules, checkpointing, loading shortened sources, and following instructions
@@ -153,7 +177,7 @@ compliance merely because a callback ran.
 
 ## Validation and remaining installed-host proof
 
-Run the repository contract tests:
+Run the repository contract tests, which cover all three host adapters:
 
 ```sh
 node --test packages/claude-dev-env/.agents/skills/session-continuity/continuity.test.mjs \
@@ -177,10 +201,10 @@ real compaction and a same-conversation restart, supply no record path, and
 capture discovery plus source reload before dependent work. Repeat with a later
 correction, a new skill, changed/missing sources, simultaneous sessions,
 quoted-only mentions, explicit handoff, deactivation, and reactivation. Keep
-Poteto's source hash unchanged throughout. Cursor needs a supported pre-work
-loading mechanism before equivalent installed-host acceptance can be run.
+Poteto's source hash unchanged throughout. On Cursor, also capture the tool call
+whose `postToolUse` result carries the reload after a compaction.
 
-## Primary references checked on 2026-09-06
+## Primary references checked on 2026-09-07
 
 - [Pstack Poteto Mode source](https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md)
 - [Claude Code hooks](https://code.claude.com/docs/en/hooks)

package/.agents/skills/session-continuity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: session-continuity
-description: Preserve user-scoped task requirements and named skills in a host-session record. Loaded by the separate Poteto companion hook or explicitly invoked as session-continuity. triggers with poteto-mode, poteto, /poteto-mode, /poteto.
+description: Preserve user-scoped task requirements and named skills in a host-session record, and activate Poteto Mode automatically at session start and after compaction. Loaded by the separate Poteto companion hook or explicitly invoked as session-continuity. triggers with poteto-mode, poteto, /poteto-mode, /poteto.
 ---
 
 # Session continuity
@@ -11,6 +11,16 @@ Preserve the user's instructions at their actual scope. Restore the saved record
 and the current skill sources before work that depends on them. Keep Poteto Mode
 and its invocation unchanged.
 
+## Automatic activation
+
+Each supported host runs this companion when a session starts and when it
+resumes after compaction. With no saved record, the hook writes one holding a
+session-scope `pstack:poteto-mode` requirement marked `automatic`, then returns
+the current Poteto Mode source. Treat that source as the mode the user asked for
+at session scope. A later explicit invocation writes the entry again with
+the user's own quote and scope. An explicit deactivation stops the automatic
+recovery for that host session.
+
 ## On activation or recovery
 
 1. Immediately report the exact absolute record path printed by the hook.
@@ -102,13 +112,14 @@ authoritative location is restored or the user changes the requirement.
 `/session-continuity off` or `Deactivate session continuity.` deactivates the
 companion record. This does not change Poteto Mode. A later explicit Poteto or
 companion invocation starts a new active set in the same record location.
-Deactivated requirements stay out of recovery.
+Deactivated requirements stay out of recovery, and automatic activation stays
+off for that host session until an explicit invocation or a `clear` arrives.
 
 ## Verification limits
 
-Read `README.md` for setup and supported trigger forms. Claude and Codex have
-repository-tested hook adapters. Installed-host delivery, source loading, and
-agent compliance require separate live evidence. Cursor automatic activation
-and recovery are not implemented because the inspected prompt and lifecycle
-hooks do not establish the required pre-work delivery contract. A manual storage
-command is not evidence of automatic activation in any host.
+Read `README.md` for setup and supported trigger forms. Claude, Codex, and
+Cursor have repository-tested hook adapters. Installed-host delivery, source
+loading, and agent compliance require separate live evidence. On Cursor the
+post-compaction reload arrives with the first tool result after compaction,
+because Cursor documents no post-compaction event that returns agent context.
+A manual storage command is not evidence of automatic activation in any host.

package/.agents/skills/session-continuity/continuity.mjs

@@ -7,6 +7,9 @@ const skillDirectory = dirname(fileURLToPath(import.meta.url));
 const hosts = new Set(['claude', 'codex', 'cursor']);
 const potetoNames = new Set(['poteto-mode', 'pstack:poteto-mode']);
 const companionNames = new Set(['session-continuity', 'claude-dev-env:session-continuity']);
+const cursorEvents = new Set(['sessionStart', 'beforeSubmitPrompt', 'preCompact', 'postToolUse']);
+const automaticQuote = 'Automatic activation configured in the installed host hook';
+const automaticDuration = 'This host session, including its resumes and compactions';
 const digest = value => createHash('sha256').update(value).digest('hex');
 const encode = value => JSON.stringify(value, null, 2);
 const stateRoot = () => resolve(process.env.CDE_CONTINUITY_ROOT || join(skillDirectory, '..', '..', 'state', 'session-continuity'));
@@ -116,16 +119,31 @@ function sourceSnapshot(source) {
 
 function promptEvidence(payload) {
     const text = requireText(payload.prompt, 'user prompt');
-    return { id: digest(`${payload.turn_id || ''}\0${text}`), text, authority: 'user-message-evidence' };
+    return { id: digest(`${payload.turn_id || payload.generation_id || ''}\0${text}`), text, authority: 'user-message-evidence' };
 }
 
-function activate(previous, host, session, payload, trigger) {
-    const record = previous?.status === 'active' ? previous : {
+function emptyRecord(host, session, payload) {
+    return {
         schema: 1, host, session_id: session, status: 'active', revision: 0,
-        workspace: payload.cwd || '',
+        workspace: payload.cwd || (payload.workspace_roots || [])[0] || '',
         task: { id: randomUUID(), goal: '', boundaries: [], constraints: [], completion: [], completed: false },
         requirements: [], pending: [], checkpoint: { completed: [], remaining: [] },
     };
+}
+
+function automaticRecord(host, session, payload) {
+    const record = emptyRecord(host, session, payload);
+    record.requirements.push({
+        id: 'skill:pstack:poteto-mode', kind: 'skill', name: 'pstack:poteto-mode', active: true,
+        scope: 'session', task_id: null, duration: automaticDuration, automatic: true,
+        evidence: { prompt_id: null, quote: automaticQuote },
+        ...sourceSnapshot(potetoSource()),
+    });
+    return record;
+}
+
+function activate(previous, host, session, payload, trigger) {
+    const record = previous?.status === 'active' ? previous : emptyRecord(host, session, payload);
     if (record.task.completed) {
         record.requirements.forEach(requirement => { if (requirement.scope === 'task') requirement.active = false; });
         record.task = { id: randomUUID(), goal: '', boundaries: [], constraints: [], completion: [], completed: false };
@@ -141,7 +159,7 @@ function activate(previous, host, session, payload, trigger) {
             ? { source: current.source, sha256: current.sha256, comparison_text: current.comparison_text }
             : sourceSnapshot(selectedSource);
         const entry = {
-            id, kind: 'skill', name: 'pstack:poteto-mode', active: true,
+            id, kind: 'skill', name: 'pstack:poteto-mode', active: true, automatic: false,
             scope, task_id: scope === 'task' ? record.task.id : null,
             duration: trigger.scope ? trigger.text : current?.duration || 'Current task, until completed or explicitly changed by the user',
             evidence: { prompt_id: evidence.id, quote: trigger.text },
@@ -200,8 +218,61 @@ function render(record, path, loadSources) {
     return sections.join('\n\n');
 }
 
+const deactivationRequest = prompt => /^(?:[/$](?:claude-dev-env:)?session-continuity off|deactivate session continuity)[.!]?\s*$/i.test(prompt || '');
+
+function sessionOpening(host, session, path, previous, payload, reset) {
+    if (!reset && previous) {
+        if (previous.status !== 'active') return {};
+        return { context: render(previous, path, true) };
+    }
+    try {
+        const saved = transact(host, session, () => automaticRecord(host, session, payload));
+        return { message: `Activated Poteto Mode for this session and read the record back: ${saved.path}`,
+            context: render(saved.record, saved.path, true) };
+    } catch (error) {
+        return { message: `Session continuity did not activate Poteto Mode automatically: ${error.message}` };
+    }
+}
+
+function cursorHook(payload) {
+    const event = payload.hook_event_name;
+    if (!cursorEvents.has(event) || payload.agent_id) return {};
+    const session = requireText(payload.conversation_id || payload.session_id, 'host session id');
+    const path = recordPath('cursor', session);
+    const previous = readRecord(path, 'cursor', session);
+    if (event === 'sessionStart') {
+        const opening = sessionOpening('cursor', session, path, previous, payload, false);
+        return { ...(opening.context ? { additional_context: opening.context } : {}), ...(opening.message ? { user_message: opening.message } : {}) };
+    }
+    if (event === 'preCompact') {
+        if (previous?.status !== 'active') return {};
+        transact('cursor', session, record => ({ ...record, reload_pending: true }));
+        return { user_message: 'Poteto Mode and the saved session record reload on the next tool result after this compaction.' };
+    }
+    if (event === 'postToolUse') {
+        if (previous?.status !== 'active' || !previous.reload_pending) return {};
+        const saved = transact('cursor', session, record => ({ ...record, reload_pending: false }));
+        return { additional_context: render(saved.record, saved.path, true) };
+    }
+    if (deactivationRequest(payload.prompt)) {
+        if (previous?.status !== 'active') return { continue: true };
+        const saved = transact('cursor', session, record => ({ ...record, status: 'inactive', reload_pending: false, pending: [] }));
+        return { continue: true, user_message: `Session continuity deactivated at ${saved.path}. Poteto Mode is unchanged.` };
+    }
+    const trigger = invocation(payload.prompt);
+    if (!trigger && previous?.status !== 'active') return { continue: true };
+    const saved = transact('cursor', session, record => {
+        if (trigger) return { ...activate(record, 'cursor', session, payload, trigger), reload_pending: true };
+        if (record?.status !== 'active') throw new Error('Record deactivated during prompt processing; retry');
+        const evidence = promptEvidence(payload);
+        if (!record.pending.some(requirement => requirement.id === evidence.id)) record.pending.push(evidence);
+        return record;
+    });
+    return { continue: true, user_message: `Session continuity recorded this message at ${saved.path}. Revision ${saved.record.revision}.` };
+}
+
 function hook(host, payload) {
-    if (host === 'cursor') throw new Error('Cursor automatic activation is unsupported. beforeSubmitPrompt cannot inject agent context; sessionStart is fire-and-forget and preCompact is observational. No automatic hooks installed.');
+    if (host === 'cursor') return cursorHook(payload);
     const event = payload.hook_event_name;
     if (payload.agent_id || (payload.role && payload.role !== 'user')) return {};
     const accepted = ['SessionStart', 'UserPromptSubmit'];
@@ -211,16 +282,13 @@ function hook(host, payload) {
     const path = recordPath(host, session);
     const previous = readRecord(path, host, session);
     if (event === 'SessionStart') {
-        if (payload.source === 'clear' && previous?.status === 'active') {
-            transact(host, session, record => ({ ...record, status: 'inactive', pending: [] }));
-            return { systemMessage: `Session continuity ended by clear: ${path}` };
-        }
         const sources = host === 'claude' ? ['startup', 'resume', 'compact', 'clear', 'fork'] : ['startup', 'resume', 'compact', 'clear'];
         if (!sources.includes(payload.source)) return {};
-        if (!previous || previous.status !== 'active') return {};
-        return { hookSpecificOutput: { hookEventName: event, additionalContext: render(previous, path, true) } };
+        const opening = sessionOpening(host, session, path, previous, payload, payload.source === 'clear');
+        return { ...(opening.message ? { systemMessage: opening.message } : {}),
+            ...(opening.context ? { hookSpecificOutput: { hookEventName: event, additionalContext: opening.context } } : {}) };
     }
-    if (/^(?:[/$](?:claude-dev-env:)?session-continuity off|deactivate session continuity)[.!]?\s*$/i.test(payload.prompt || '')) {
+    if (deactivationRequest(payload.prompt)) {
         if (!previous || previous.status !== 'active') return {};
         const saved = transact(host, session, record => ({ ...record, status: 'inactive', pending: [] }));
         return { systemMessage: `Session continuity deactivated at ${saved.path}. Poteto Mode is unchanged.`,
@@ -364,12 +432,16 @@ try {
 } catch (error) {
     if (command === 'hook') {
         const message = `Session continuity failed: ${error.message}`;
-        console.log(encode({
-            ...(['UserPromptSubmit', 'UserPromptExpansion'].includes(hookEvent) ? { decision: 'block', reason: message } : {}),
-            systemMessage: message,
-            ...(['SessionStart', 'UserPromptSubmit', 'UserPromptExpansion'].includes(hookEvent)
-                ? { hookSpecificOutput: { hookEventName: hookEvent, additionalContext: `${message}. Stop dependent work until recovery succeeds.` } } : {}),
-        }));
+        const guidance = `${message}. Stop dependent work until recovery succeeds.`;
+        console.log(encode(cursorEvents.has(hookEvent)
+            ? { ...(hookEvent === 'beforeSubmitPrompt' ? { continue: true } : {}), user_message: message,
+                ...(['sessionStart', 'postToolUse'].includes(hookEvent) ? { additional_context: guidance } : {}) }
+            : {
+                ...(['UserPromptSubmit', 'UserPromptExpansion'].includes(hookEvent) ? { decision: 'block', reason: message } : {}),
+                systemMessage: message,
+                ...(['SessionStart', 'UserPromptSubmit', 'UserPromptExpansion'].includes(hookEvent)
+                    ? { hookSpecificOutput: { hookEventName: hookEvent, additionalContext: guidance } } : {}),
+            }));
     } else console.error(error.message);
     process.exitCode = command === 'hook' ? 0 : 1;
 }

package/.agents/skills/session-continuity/continuity.test.mjs

@@ -26,7 +26,7 @@ function fixture(t, host) {
     writeFileSync(second, secondText);
     const script = join(skill, 'continuity.mjs');
     const configPath = join(root, host === 'claude' ? 'settings.json' : 'hooks.json');
-    writeFileSync(configPath, JSON.stringify({ hooks: continuityHookConfiguration(host, script) }));
+    writeFileSync(configPath, JSON.stringify({ ...(host === 'cursor' ? { version: 1 } : {}), hooks: continuityHookConfiguration(host, script) }));
     const env = { ...process.env };
     delete env.CDE_CONTINUITY_ROOT;
     delete env.CDE_POTETO_SOURCE;
@@ -37,11 +37,11 @@ function fixture(t, host) {
         return expectedStatus ? result.stderr : JSON.parse(result.stdout);
     };
     const fire = (event, session, fields = {}) => {
-        const payload = { hook_event_name: event, session_id: session, cwd: root, ...fields };
+        const payload = { hook_event_name: event, cwd: root, ...(host === 'cursor' ? { conversation_id: session } : { session_id: session }), ...fields };
         const config = JSON.parse(readFileSync(configPath, 'utf8'));
         const groups = config.hooks[event] || [];
         const matching = groups.filter(group => !group.matcher || new RegExp(group.matcher).test(event === 'SessionStart' ? fields.source : fields.command_name));
-        return matching.flatMap(group => group.hooks.map(handler => {
+        return matching.flatMap(group => (group.hooks || [group]).map(handler => {
             const result = spawnSync(handler.command, { shell: true, input: JSON.stringify(payload), encoding: 'utf8', env });
             assert.equal(result.status, 0, result.stderr);
             return JSON.parse(result.stdout);
@@ -55,7 +55,6 @@ function fixture(t, host) {
 for (const host of ['claude', 'codex']) {
     test(`${host}: configured invocation emits complete instructions, writes and reads back, restores without a path`, t => {
         const f = fixture(t, host);
-        assert.deepEqual(f.fire('SessionStart', 'session-a', { source: 'startup' }), [{}]);
         assert.equal(existsSync(f.pathFor('session-a')), false);
         const prefix = host === 'codex' ? '$pstack:poteto-mode' : '/pstack:poteto-mode';
         const prompt = `${prefix} for this entire session\nFinish the sample task. Keep changes local. Use second-skill for this task.`;
@@ -86,7 +85,9 @@ for (const host of ['claude', 'codex']) {
         assert.equal(readFileSync(f.poteto, 'utf8'), potetoText);
         record = f.read('session-a');
         assert.equal(record.pending.length, 0);
-        assert.deepEqual(f.fire('SessionStart', 'unrelated-session', { source: 'startup' }), [{}]);
+        const unrelated = f.fire('SessionStart', 'unrelated-session', { source: 'startup' })[0].hookSpecificOutput.additionalContext;
+        assert.equal(unrelated.includes('build sample'), false);
+        assert.equal(unrelated.includes(secondText), false);
     });
 
     test(`${host}: quoting, discussion, tool output and subagent input do not activate`, t => {
@@ -247,12 +248,81 @@ test('a busy record blocks prompt processing, preserves state, and supports a sa
     assert.equal(f.read('busy').pending.length, 2);
 });
 
-test('clear deactivates a reused host id rather than inheriting an unrelated task', t => {
+test('clear drops a reused host id rather than inheriting an unrelated task', t => {
     const f = fixture(t, 'claude');
-    f.submit('clear', '/poteto-mode for this entire session');
+    f.submit('clear', '/poteto-mode for this entire session\nKeep the sample local.');
+    const before = f.read('clear');
     f.fire('SessionStart', 'clear', { source: 'clear' });
-    assert.equal(f.read('clear').status, 'inactive');
-    assert.deepEqual(f.fire('SessionStart', 'clear', { source: 'startup' }), [{}]);
+    const record = f.read('clear');
+    assert.equal(record.status, 'active');
+    assert.notEqual(record.task.id, before.task.id);
+    assert.deepEqual(record.pending, []);
+    assert.deepEqual(record.requirements.map(entry => entry.id), ['skill:pstack:poteto-mode']);
+    assert.equal(record.requirements[0].automatic, true);
+});
+
+for (const host of ['claude', 'codex']) {
+    test(`${host}: session start and compaction activate Poteto Mode with no explicit invocation`, t => {
+        const f = fixture(t, host);
+        const started = f.fire('SessionStart', 'auto', { source: 'startup' })[0];
+        assert.ok(started.systemMessage.includes(f.pathFor('auto')));
+        assert.ok(started.hookSpecificOutput.additionalContext.includes(potetoText));
+        const record = f.read('auto');
+        assert.equal(record.requirements.length, 1);
+        assert.equal(record.requirements[0].scope, 'session');
+        assert.equal(record.requirements[0].automatic, true);
+        assert.equal(record.requirements[0].source, f.poteto);
+        assert.deepEqual(record.pending, []);
+        for (const source of ['compact', 'resume']) {
+            const later = f.fire('SessionStart', 'auto', { source })[0].hookSpecificOutput.additionalContext;
+            assert.ok(later.includes(potetoText));
+        }
+        assert.equal(f.read('auto').revision, record.revision);
+        f.submit('auto', '/session-continuity off');
+        assert.deepEqual(f.fire('SessionStart', 'auto', { source: 'compact' }), [{}]);
+        assert.deepEqual(f.fire('SessionStart', 'auto', { source: 'startup' }), [{}]);
+    });
+
+    test(`${host}: an unavailable Poteto source stops automatic activation without writing a record`, t => {
+        const f = fixture(t, host);
+        writeFileSync(f.poteto, '---\nname: Something Else\n---\n');
+        const started = f.fire('SessionStart', 'broken', { source: 'startup' })[0];
+        assert.match(started.systemMessage, /did not activate Poteto Mode/);
+        assert.equal(existsSync(f.pathFor('broken')), false);
+    });
+}
+
+test('cursor: session start injects Poteto Mode and compaction reloads it on the next tool result', t => {
+    const f = fixture(t, 'cursor');
+    const started = f.fire('sessionStart', 'cursor-a', { session_id: 'composer-1', composer_mode: 'agent' })[0];
+    assert.ok(started.additional_context.includes(potetoText));
+    assert.equal(f.read('cursor-a').requirements[0].automatic, true);
+    assert.deepEqual(f.fire('postToolUse', 'cursor-a', { tool_name: 'Shell' }), [{}]);
+    const compacting = f.fire('preCompact', 'cursor-a', { trigger: 'auto' })[0];
+    assert.ok(compacting.user_message.includes('Poteto Mode'));
+    assert.equal(f.read('cursor-a').reload_pending, true);
+    const reloaded = f.fire('postToolUse', 'cursor-a', { tool_name: 'Shell' })[0];
+    assert.ok(reloaded.additional_context.includes(potetoText));
+    assert.ok(reloaded.additional_context.includes(f.pathFor('cursor-a')));
+    assert.equal(f.read('cursor-a').reload_pending, false);
+    assert.deepEqual(f.fire('postToolUse', 'cursor-a', { tool_name: 'Shell' }), [{}]);
+});
+
+test('cursor: a prompt records evidence, never blocks submission, and reloads named skills after a tool result', t => {
+    const f = fixture(t, 'cursor');
+    f.fire('sessionStart', 'cursor-b', { session_id: 'composer-2' });
+    const submitted = f.fire('beforeSubmitPrompt', 'cursor-b', { prompt: 'Finish the sample task.', generation_id: 'gen-1' })[0];
+    assert.equal(submitted.continue, true);
+    assert.equal(f.read('cursor-b').pending.length, 1);
+    const invoked = f.fire('beforeSubmitPrompt', 'cursor-b', { prompt: '/poteto-mode for this entire session', generation_id: 'gen-2' })[0];
+    assert.equal(invoked.continue, true);
+    assert.equal(f.read('cursor-b').reload_pending, true);
+    assert.ok(f.fire('postToolUse', 'cursor-b', { tool_name: 'Read' })[0].additional_context.includes(potetoText));
+    const off = f.fire('beforeSubmitPrompt', 'cursor-b', { prompt: '/session-continuity off', generation_id: 'gen-3' })[0];
+    assert.equal(off.continue, true);
+    assert.equal(f.read('cursor-b').status, 'inactive');
+    assert.deepEqual(f.fire('sessionStart', 'cursor-b', { session_id: 'composer-2' }), [{}]);
+    assert.deepEqual(f.fire('preCompact', 'cursor-b', { trigger: 'manual' }), [{}]);
 });
 
 test('missing host identity and corrupt records produce visible recovery failures', t => {

package/bin/install-session-continuity.mjs

@@ -2,13 +2,15 @@ import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } fro
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const supportedHosts = ['claude', 'codex', 'cursor'];
+
 export function continuityHookConfiguration(host, script) {
-    if (host === 'cursor') {
-        throw new Error('Cursor automatic activation is unsupported: beforeSubmitPrompt has no agent-context output, sessionStart is fire-and-forget, and preCompact is observational. No Cursor settings changed.');
-    }
-    if (!['claude', 'codex'].includes(host)) throw new Error(`Unsupported host ${host}`);
+    if (!supportedHosts.includes(host)) throw new Error(`Unsupported host ${host}`);
     if (/[\r\n"`$%]/.test(script)) throw new Error('Hook script path contains shell expansion characters');
     const command = `node "${script.replace(/\\/g, '/')}" hook ${host}`;
+    if (host === 'cursor') {
+        return Object.fromEntries(['sessionStart', 'beforeSubmitPrompt', 'preCompact', 'postToolUse'].map(event => [event, [{ command }]]));
+    }
     const events = host === 'claude' ? ['UserPromptSubmit', 'UserPromptExpansion', 'SessionStart'] : ['UserPromptSubmit', 'SessionStart'];
     return Object.fromEntries(events.map(event => [event, [{
         ...(event === 'SessionStart' ? { matcher: host === 'claude' ? 'startup|resume|compact|clear|fork' : 'startup|resume|compact|clear' } : {}),
@@ -20,19 +22,22 @@ export function continuityHookConfiguration(host, script) {
 export function mergeContinuityHooks(existing, host, script) {
     const additions = continuityHookConfiguration(host, script);
     const mergedConfiguration = structuredClone(existing);
+    if (host === 'cursor') mergedConfiguration.version = 1;
     mergedConfiguration.hooks ||= {};
     for (const [event, groups] of Object.entries(additions)) {
         const current = mergedConfiguration.hooks[event] || [];
-        for (const group of current) {
-            for (const hook of group.hooks || []) {
-                if (hook.command?.includes('/session-continuity/continuity.mjs') && hook.command !== groups[0].hooks[0].command) {
+        const command = host === 'cursor' ? groups[0].command : groups[0].hooks[0].command;
+        for (const entry of current) {
+            for (const hook of entry.hooks || [entry]) {
+                if (hook.command?.includes('/session-continuity/continuity.mjs') && hook.command !== command) {
                     throw new Error('Another continuity installation owns this host config. Select its profile or remove that installation explicitly.');
                 }
             }
         }
-        const kept = current.flatMap(group => {
-            const hooks = (group.hooks || []).filter(hook => hook.command !== groups[0].hooks[0].command);
-            return hooks.length ? [{ ...group, hooks }] : [];
+        const kept = current.flatMap(entry => {
+            if (host === 'cursor') return entry.command === command ? [] : [entry];
+            const hooks = (entry.hooks || []).filter(hook => hook.command !== command);
+            return hooks.length ? [{ ...entry, hooks }] : [];
         });
         mergedConfiguration.hooks[event] = kept.concat(groups);
     }
@@ -41,15 +46,20 @@ export function mergeContinuityHooks(existing, host, script) {
 
 async function main() {
     const requested = process.argv.slice(2);
-    const selected = requested.length ? requested : ['claude', 'codex'];
-    if (selected.some(host => !['claude', 'codex'].includes(host))) continuityHookConfiguration(selected.find(host => !['claude', 'codex'].includes(host)), '');
+    const selected = requested.length ? requested : supportedHosts;
+    const unsupported = selected.find(host => !supportedHosts.includes(host));
+    if (unsupported) throw new Error(`Unsupported host ${unsupported}`);
     const { resolveInstallRoot } = await import('./resolve-install-root.mjs');
     const roots = resolveInstallRoot();
     const script = join(roots.skillsInstallDirectory, 'session-continuity', 'continuity.mjs');
     if (!existsSync(script) || !existsSync(join(dirname(script), 'SKILL.md'))) {
         throw new Error('Run the full claude-dev-env installer from this checkout first so the companion is in the canonical agents home.');
     }
-    const paths = { claude: join(roots.managedRoot, 'settings.json'), codex: join(dirname(roots.codexRulesInstallDirectory), 'hooks.json') };
+    const paths = {
+        claude: join(roots.managedRoot, 'settings.json'),
+        codex: join(dirname(roots.codexRulesInstallDirectory), 'hooks.json'),
+        cursor: join(roots.cursorInstallDirectory, 'hooks.json'),
+    };
     const plans = selected.map(host => {
         const path = paths[host];
         if (!existsSync(dirname(path))) throw new Error(`Host config directory is absent: ${dirname(path)}`);
@@ -70,7 +80,7 @@ async function main() {
         if (readFileSync(plan.path, 'utf8') !== plan.content) throw new Error(`Config read-back mismatch: ${plan.path}`);
         console.log(`Configured and read back: ${plan.path}`);
     }
-    console.log('Review and trust the new hooks in each host. Cursor remains unsupported; no Cursor settings changed.');
+    console.log('Review and trust the new hooks in each host.');
 }
 
 if (process.argv[1] && resolve(realpathSync(process.argv[1])) === fileURLToPath(import.meta.url)) {

package/bin/install-session-continuity.test.mjs

@@ -14,11 +14,24 @@ test('setup preserves other hooks and settings, is idempotent, and rejects compe
     assert.throws(() => continuityHookConfiguration('claude', '/path/with$expansion/continuity.mjs'), /expansion/);
 });
 
-test('Cursor setup refuses an unsupported automatic activation claim without changing config', () => {
-    const existing = { version: 1, hooks: { beforeSubmitPrompt: [{ command: 'existing' }] } };
-    const before = JSON.stringify(existing);
-    assert.throws(() => mergeContinuityHooks(existing, 'cursor', '/skill/continuity.mjs'), /beforeSubmitPrompt has no agent-context output/);
-    assert.equal(JSON.stringify(existing), before);
+test('Cursor setup keeps other hooks, sets the file version, and stays idempotent', () => {
+    const existing = { hooks: { beforeShellExecution: [{ command: 'existing' }] } };
+    const script = '/home/jon/.agents/skills/session-continuity/continuity.mjs';
+    const first = mergeContinuityHooks(existing, 'cursor', script);
+    assert.equal(first.version, 1);
+    assert.equal(first.hooks.beforeShellExecution[0].command, 'existing');
+    assert.deepEqual(mergeContinuityHooks(first, 'cursor', script), first);
+    assert.equal(existing.hooks.beforeShellExecution.length, 1);
+    assert.throws(() => mergeContinuityHooks(first, 'cursor', '/other/session-continuity/continuity.mjs'), /Another continuity installation/);
+});
+
+test('Cursor setup registers only documented context-carrying events', () => {
+    const configuration = continuityHookConfiguration('cursor', '/home/jon/.agents/skills/session-continuity/continuity.mjs');
+    assert.deepEqual(Object.keys(configuration), ['sessionStart', 'beforeSubmitPrompt', 'preCompact', 'postToolUse']);
+    for (const entries of Object.values(configuration)) {
+        assert.equal(entries.length, 1);
+        assert.equal(entries[0].command, 'node "/home/jon/.agents/skills/session-continuity/continuity.mjs" hook cursor');
+    }
 });
 
 for (const host of ['claude', 'codex']) {

package/bin/install.test.mjs

@@ -1353,6 +1353,23 @@ test('mergeHooksIntoSettings is idempotent when run twice against an already-upd
 });
 
 
+test('shipped SessionEnd hook timeouts stay within the Codex runtime limit', () => {
+    const shippedHooksConfig = JSON.parse(
+        readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8')
+    );
+    const allSessionEndHooks = (shippedHooksConfig.hooks.SessionEnd || [])
+        .flatMap(eachMatcherGroup => eachMatcherGroup.hooks);
+
+    assert.ok(allSessionEndHooks.length > 0, 'shipped hooks.json must register SessionEnd hooks');
+    for (const eachSessionEndHook of allSessionEndHooks) {
+        assert.ok(
+            eachSessionEndHook.timeout <= 3,
+            `${eachSessionEndHook.command} exceeds the Codex SessionEnd runtime limit`,
+        );
+    }
+});
+
+
 test('shipped hooks.json keeps only nonblocking policy handlers and lifecycle hooks', () => {
     const shippedHooksConfig = JSON.parse(
         readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8')

package/hooks/blocking/content_search_to_zoekt_redirector.py

@@ -0,0 +1 @@
+"""Retired search hook entrypoint kept inert for stale command references."""

package/hooks/blocking/test_content_search_to_zoekt_redirector.py

@@ -0,0 +1,46 @@
+"""Regression tests for the inert retired search hook entrypoint."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+_BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+_ENTRYPOINT_PATH = _BLOCKING_DIRECTORY / "content_search_to_zoekt_redirector.py"
+_HOOKS_MANIFEST_PATH = _BLOCKING_DIRECTORY.parent / "hooks.json"
+
+
+def test_retired_entrypoint_allows_valid_search_events_silently() -> None:
+    all_search_events = (
+        {"tool_name": "Bash", "tool_input": {"command": "rg --files packages"}},
+        {
+            "tool_name": "Grep",
+            "tool_input": {"pattern": "zoekt", "path": "packages"},
+        },
+        {
+            "tool_name": "Search",
+            "tool_input": {"pattern": "zoekt", "path": "packages"},
+        },
+    )
+
+    for each_search_event in all_search_events:
+        completed_process = subprocess.run(
+            [sys.executable, str(_ENTRYPOINT_PATH)],
+            check=False,
+            input=json.dumps(each_search_event),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+        )
+        assert completed_process.returncode == 0
+        assert completed_process.stdout == ""
+        assert completed_process.stderr == ""
+
+
+def test_shipped_hook_manifest_omits_retired_entrypoint() -> None:
+    hooks_manifest_text = _HOOKS_MANIFEST_PATH.read_text(encoding="utf-8")
+
+    assert _ENTRYPOINT_PATH.name not in hooks_manifest_text

package/hooks/hooks.json

@@ -84,12 +84,12 @@
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/session_end_cleanup.py",
-            "timeout": 15
+            "timeout": 3
           },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/session_edit_tracker_cleanup.py",
-            "timeout": 10
+            "timeout": 3
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "7.1.0",
+    "version": "7.2.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/filesystem-search.md

@@ -19,7 +19,7 @@ Three tools are equally sanctioned; pick by what you know:
 | A name or path pattern | The harness `Glob` tool |
 | Text inside files | The harness `Grep` tool |
 
-When `es.exe` fails or returns nothing, fall back to `Glob` or `Grep` without pausing, and report the outage so the reader knows the index was unavailable. Ask the user only after all three tools fail.
+When `es.exe` returns Error 8, retry the same search twice before any fallback. Error 8 is a missing IPC client window, not proof the index is down. After those retries fail, report that the Everything IPC client did not answer and that the service state was not probed, then fall back to `Glob` or `Grep` with the same scope. When `es.exe` is missing, or a later search returns no hits, fall back to `Glob` or `Grep`. Ask the user only after all three tools fail.
 
 `skills/everything-search/SKILL.md` holds the full `es.exe` operator reference: `ext:`, `dm:`, `size:`, wildcards, OR/AND/NOT, output flags, and the junction and drive-mapping note.