claude-dev-env 7.2.0 → 7.3.0

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/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/bin/pstack-codex-discovery.test.mjs

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import test from 'node:test';
+import { verifyInstallation } from './pstack.mjs';
+
+const executable = process.env.CDE_CODEX_EXECUTABLE;
+const project = process.env.CDE_PSTACK_PROOF_PROJECT;
+
+test('native Codex discovers every installed pstack skill and its real entry path', {
+    skip: !executable || !project ? 'Set CDE_CODEX_EXECUTABLE and CDE_PSTACK_PROOF_PROJECT for native discovery' : false,
+    timeout: 60000,
+}, async t => {
+    const installation = verifyInstallation({ project });
+    const release = join(resolve(project), '.claude', 'pstack', 'releases', installation.release);
+    const manifest = JSON.parse(readFileSync(join(release, 'release.json'), 'utf8'));
+    const home = mkdtempSync(join(tmpdir(), 'pstack codex home '));
+    const codexHome = join(home, '.codex');
+    mkdirSync(codexHome);
+    const env = { PATH: process.env.PATH, HOME: home, CODEX_HOME: codexHome };
+    const version = spawnSync(executable, ['--version'], { env, encoding: 'utf8', timeout: 15000 });
+    assert.equal(version.status, 0, version.stderr || version.error?.message);
+    const child = spawn(executable, ['app-server'], { cwd: project, env, stdio: ['pipe', 'pipe', 'pipe'] });
+    const lines = createInterface({ input: child.stdout });
+    let stderr = '';
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.stdin.on('error', () => {});
+    t.after(async () => {
+        lines.close();
+        const stopped = child.exitCode !== null || child.signalCode !== null
+            ? Promise.resolve() : new Promise(accept => child.once('close', accept));
+        child.kill();
+        await stopped;
+        rmSync(home, { recursive: true, force: true });
+    });
+    const transcript = [];
+    const send = message => child.stdin.write(JSON.stringify(message) + '\n');
+    const request = (id, method, params) => new Promise((accept, reject) => {
+        const timer = setTimeout(() => finish(new Error(`Codex ${method} timed out: ${stderr}`)), 15000);
+        const failed = error => finish(error);
+        const closed = code => finish(new Error(`Codex exited ${code}: ${stderr}`));
+        const receive = line => {
+            let message;
+            try { message = JSON.parse(line); } catch (error) { finish(error); return; }
+            transcript.push(message);
+            if (message.id === id) finish(message.error ? new Error(JSON.stringify(message.error)) : null, message.result);
+        };
+        const finish = (error, response) => {
+            clearTimeout(timer);
+            child.off('error', failed);
+            child.off('close', closed);
+            lines.off('line', receive);
+            if (error) reject(error); else accept(response);
+        };
+        child.once('error', failed);
+        child.once('close', closed);
+        lines.on('line', receive);
+        send({ id, method, params });
+    });
+    await request(0, 'initialize', { clientInfo: { name: 'skillcheck', version: '1.0.0' } });
+    send({ method: 'initialized', params: {} });
+    const discovered = await request(1, 'skills/list', { cwds: [resolve(project)], forceReload: true });
+    const evidence = { verification: 'native-codex-skill-discovery', codexVersion: version.stdout.trim(),
+        upstreamCommit: installation.commit, adapterDigest: installation.adapterDigest, transcript };
+    if (process.env.CDE_PSTACK_DISCOVERY_REPORT) writeFileSync(process.env.CDE_PSTACK_DISCOVERY_REPORT, JSON.stringify(evidence, null, 2) + '\n');
+    const workspace = discovered.data.find(entry => resolve(entry.cwd) === resolve(project));
+    assert.ok(workspace, 'Codex returned the requested workspace');
+    assert.deepEqual(workspace.errors, []);
+    for (const expected of manifest.skills) {
+        const found = workspace.skills.filter(skill => skill.name === expected.name);
+        assert.equal(found.length, 1, `Codex discovers ${expected.name} once`);
+        assert.equal(found[0].enabled, true, expected.name);
+        assert.equal(realpathSync(found[0].path), realpathSync(join(release, expected.path, 'SKILL.md')));
+    }
+    t.diagnostic(`${version.stdout.trim()}: ${manifest.skills.length} installed skills discovered through Codex`);
+});

package/bin/pstack.mjs

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const bundledLockPath = join(packageRoot, 'scripts', 'pstack.lock.json');
+const hosts = ['claude', 'codex', 'cursor'];
+const digest = value => createHash('sha256').update(value).digest('hex');
+const readJson = path => JSON.parse(readFileSync(path, 'utf8'));
+const json = value => JSON.stringify(value, null, 2) + '\n';
+const entryExists = path => { try { lstatSync(path); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; } };
+
+export function validateLock(lock) {
+    if (lock?.schemaVersion !== 1 || lock?.adapterVersion !== 1
+        || lock.repository !== 'https://github.com/cursor/plugins.git'
+        || !/^[0-9a-f]{40}$/.test(lock.commit ?? '')
+        || JSON.stringify(lock.components) !== JSON.stringify(['pstack', 'cursor-team-kit'])) {
+        throw new Error('Unsupported pstack lock. Update claude-dev-env for a newer adapter.');
+    }
+    const required = { pstack: ['poteto-mode'], 'cursor-team-kit': ['deslop', 'control-cli', 'control-ui'] };
+    for (const [component, names] of Object.entries(required)) {
+        const declared = lock.requiredSkills?.[component];
+        if (!Array.isArray(declared) || declared.some(name => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
+            || names.some(name => !declared.includes(name))) throw new Error(`Invalid ${component} dependencies`);
+    }
+    return lock;
+}
+
+function filesUnder(root) {
+    return readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap(entry => {
+        const path = join(root, entry.name);
+        if (entry.isSymbolicLink()) throw new Error(`Upstream symlinks require review: ${path}`);
+        if (entry.isDirectory()) return filesUnder(path);
+        if (!entry.isFile()) throw new Error(`Unsupported upstream file: ${path}`);
+        return [path];
+    });
+}
+
+function runGit(args, cwd) {
+    return execFileSync('git', args, {
+        cwd, encoding: 'utf8', timeout: 40000, maxBuffer: 16 * 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+}
+
+export function fetchUpstream(lock, destination) {
+    mkdirSync(destination, { recursive: true });
+    runGit(['init', '--quiet'], destination);
+    runGit(['config', 'core.autocrlf', 'false'], destination);
+    runGit(['config', 'core.hooksPath', join(destination, '.disabled-hooks')], destination);
+    runGit(['remote', 'add', 'origin', lock.repository], destination);
+    runGit(['config', 'core.sparseCheckout', 'true'], destination);
+    writeFileSync(join(destination, '.git', 'info', 'sparse-checkout'), '/pstack/\n/cursor-team-kit/\n/LICENSE\n');
+    runGit(['fetch', '--quiet', '--depth=1', '--filter=blob:none', 'origin', lock.commit], destination);
+    if (runGit(['rev-parse', 'FETCH_HEAD'], destination) !== lock.commit) throw new Error('Upstream commit mismatch');
+    runGit(['checkout', '--quiet', '--detach', 'FETCH_HEAD'], destination);
+}
+
+function adapterFiles(root) {
+    const adapters = join(root, 'scripts', 'pstack-adapters');
+    return Object.fromEntries([
+        ...['common.md', ...hosts.map(host => `host-${host}.md`), 'create-skill.md'].map(name => [name, join(adapters, name)]),
+        ...['pstack-host-mapping.md', 'pstack-models.md'].map(name => [name, join(root, 'rules', name)]),
+        ['select_pstack_models.mjs', join(root, 'scripts', 'select_pstack_models.mjs')],
+    ].map(([name, path]) => [name, readFileSync(path, 'utf8')]));
+}
+
+function adaptSkill(text, name, releaseRoot, skillRoot) {
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
+    if (!match || !/^description:\s*\S/m.test(match[1])) throw new Error(`Missing skill metadata: ${name}`);
+    const frontmatter = match[1].replace(/^name:.*$/m, `name: ${name}`);
+    if (!/^name:/m.test(frontmatter)) throw new Error(`Missing skill name: ${name}`);
+    const safeFrontmatter = frontmatter.replace(/^(?:context|agent|model):.*\r?\n?/gm, '');
+    const fork = /^context:\s*fork\s*$/m.test(frontmatter)
+        ? 'The upstream entry requests a fork. Delegate through the native host after reading the compatibility mapping.\n' : '';
+    return `---\n${safeFrontmatter}\n---\n\n## Host compatibility\n\n`
+        + `Read ${JSON.stringify(join(releaseRoot, 'compat', 'common.md'))} and the matching host file before following this workflow.\n`
+        + `Resolve this skill's relative paths from ${JSON.stringify(skillRoot)}. Read ${JSON.stringify(join(releaseRoot, 'release.json'))} for skill and agent paths.\n`
+        + fork + '\n' + match[2].trimStart();
+}
+
+export function prepareRelease(checkout, stage, finalRoot, lock, adapters) {
+    const skills = [];
+    const agents = [];
+    mkdirSync(join(stage, 'compat'), { recursive: true });
+    for (const [name, content] of Object.entries(adapters)) writeFileSync(join(stage, 'compat', name), content);
+    for (const component of lock.components) {
+        const source = join(checkout, component);
+        filesUnder(source);
+        cpSync(source, join(stage, 'upstream', component), { recursive: true });
+        cpSync(source, join(stage, 'runtime', component), { recursive: true });
+        rmSync(join(stage, 'runtime', component, '.cursor-plugin', 'plugin.json'), { force: true });
+        const skillHome = join(source, 'skills');
+        const names = readdirSync(skillHome).filter(name => existsSync(join(skillHome, name, 'SKILL.md'))).sort();
+        for (const name of lock.requiredSkills[component]) {
+            if (!names.includes(name)) throw new Error(`Missing dependency: ${component}:${name}`);
+        }
+        for (const slug of names) {
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) throw new Error(`Invalid skill directory: ${slug}`);
+            const name = `${component}-${slug}`;
+            const path = join('runtime', component, 'skills', slug);
+            const text = readFileSync(join(source, 'skills', slug, 'SKILL.md'), 'utf8');
+            writeFileSync(join(stage, path, 'SKILL.md'), adaptSkill(text, name, finalRoot, join(finalRoot, path)));
+            skills.push({ name, component, slug, path });
+        }
+        const agentHome = join(source, 'agents');
+        if (existsSync(agentHome)) {
+            for (const path of filesUnder(agentHome)) agents.push({ component, path: join('runtime', component, 'agents', relative(agentHome, path)) });
+        }
+    }
+    if (existsSync(join(checkout, 'LICENSE'))) cpSync(join(checkout, 'LICENSE'), join(stage, 'upstream', 'LICENSE'));
+    const creatorPath = join('runtime', 'cde-create-skill');
+    mkdirSync(join(stage, creatorPath), { recursive: true });
+    writeFileSync(join(stage, creatorPath, 'SKILL.md'), adapters['create-skill.md']);
+    skills.push({ name: 'cde-create-skill', component: 'cde', slug: 'create-skill', path: creatorPath });
+    const knownNames = new Set(skills.map(skill => `${skill.component}:${skill.slug}`));
+    for (const path of filesUnder(join(stage, 'upstream')).filter(path => path.endsWith('.md') && (path.includes(sep + 'skills' + sep) || path.includes(sep + 'agents' + sep)))) {
+        const references = readFileSync(path, 'utf8').matchAll(/\b(pstack|cursor-team-kit):([a-z][a-z0-9-]*)/g);
+        for (const [, component, slug] of references) {
+            if (!knownNames.has(`${component}:${slug}`)) throw new Error(`Unresolved skill dependency: ${component}:${slug}`);
+        }
+    }
+    const fileDigests = Object.fromEntries(filesUnder(stage).map(path => [relative(stage, path), digest(readFileSync(path))]));
+    const managedRoot = dirname(dirname(dirname(finalRoot)));
+    const agentsRoot = basename(managedRoot) === '.claude' ? join(dirname(managedRoot), '.agents') : managedRoot + '.agents';
+    const release = { preferencesDirectory: join(agentsRoot, 'rules'), selectorPath: join(finalRoot, 'compat', 'select_pstack_models.mjs'), schemaVersion: 1, commit: lock.commit, adapterVersion: lock.adapterVersion, skills, agents, fileDigests, verification: 'filesystem-only' };
+    writeFileSync(join(stage, 'release.json'), json(release));
+    return release;
+}
+
+function assertContained(root, path) {
+    const rel = relative(root, resolve(root, path));
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith('..' + sep) || resolve(root, path) === resolve(root)) throw new Error('Invalid release path');
+    return resolve(root, path);
+}
+
+export function verifyRelease(root) {
+    const release = readJson(join(root, 'release.json'));
+    if (release.schemaVersion !== 1 || !Array.isArray(release.skills) || !release.skills.length || !release.fileDigests) throw new Error('Invalid release manifest');
+    for (const [path, hash] of Object.entries(release.fileDigests)) {
+        if (digest(readFileSync(assertContained(root, path))) !== hash) throw new Error(`Changed installed file: ${path}`);
+    }
+    for (const skill of release.skills) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill.name)) throw new Error('Invalid installed skill name');
+        const path = join(assertContained(root, skill.path), 'SKILL.md');
+        if (!Object.hasOwn(release.fileDigests, relative(root, path)) || !existsSync(path)) throw new Error(`Missing entry: ${skill.name}`);
+    }
+    return release;
+}
+
+function layout(options) {
+    const root = resolve(options.root ?? (options.project ? join(options.project, '.claude') : process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude')));
+    const agents = basename(root) === '.claude' ? join(dirname(root), '.agents') : root + '.agents';
+    return { root, store: join(root, 'pstack'), skillHomes: [join(root, 'skills'), join(agents, 'skills')] };
+}
+
+function loadState(store) {
+    const path = join(store, 'installed.json');
+    return existsSync(path) ? readJson(path) : null;
+}
+
+export function verifyInstallation(options = {}) {
+    const { store } = layout(options);
+    const state = loadState(store);
+    if (!state) throw new Error('Pstack is not installed');
+    const release = verifyRelease(assertContained(join(store, 'releases'), state.release));
+    for (const [path, target] of Object.entries(state.links)) {
+        if (!lstatSync(path).isSymbolicLink() || realpathSync(path) !== realpathSync(target)) throw new Error(`Changed skill pointer: ${path}`);
+    }
+    return { ...state, skillCount: release.skills.length, verification: release.verification };
+}
+
+function publish(releaseRoot, release, homes, prior) {
+    const uniqueHomes = [...new Set(homes.map(home => { mkdirSync(home, { recursive: true }); return realpathSync(home); }))];
+    const links = Object.fromEntries(uniqueHomes.flatMap(home => release.skills.map(skill => [join(home, skill.name), join(releaseRoot, skill.path)])));
+    const paths = new Set([...Object.keys(prior?.links ?? {}), ...Object.keys(links)]);
+    const before = new Map();
+    for (const path of paths) {
+        if (entryExists(path)) {
+            if (!lstatSync(path).isSymbolicLink() || !prior?.links[path]
+                || resolve(dirname(path), readlinkSync(path)) !== resolve(prior.links[path])) {
+                throw new Error(`Keep existing unmanaged path: ${path}`);
+            }
+            before.set(path, readlinkSync(path));
+        } else before.set(path, null);
+    }
+    const restore = () => {
+        for (const [path, target] of before) {
+            if (entryExists(path)) unlinkSync(path);
+            if (target !== null) symlinkSync(target, path, process.platform === 'win32' ? 'junction' : 'dir');
+        }
+    };
+    try {
+        for (const path of paths) {
+            if (entryExists(path)) unlinkSync(path);
+            if (links[path]) symlinkSync(links[path], path, process.platform === 'win32' ? 'junction' : 'dir');
+        }
+    } catch (error) { restore(); throw error; }
+    return { links, restore };
+}
+
+function liveLeases(store) {
+    const root = join(store, 'sessions');
+    if (!existsSync(root)) return false;
+    return readdirSync(root).some(name => {
+        const pid = Number(name);
+        if (!Number.isSafeInteger(pid) || pid < 1) throw new Error('Invalid session lease');
+        try { process.kill(pid, 0); return true; } catch (error) {
+            if (error.code !== 'ESRCH') return true;
+            unlinkSync(join(root, name));
+            return false;
+        }
+    });
+}
+
+function readCentralLock(temporaryRoot) {
+    const repository = join(temporaryRoot, 'record');
+    mkdirSync(repository);
+    runGit(['init', '--quiet'], repository);
+    runGit(['fetch', '--quiet', '--depth=1', '--filter=blob:none', 'https://github.com/jl-cmd/claude-dev-env.git', 'main'], repository);
+    return JSON.parse(runGit(['show', 'FETCH_HEAD:packages/claude-dev-env/scripts/pstack.lock.json'], repository));
+}
+
+export function installPstack(options = {}, dependencies = {}) {
+    const { store, skillHomes } = layout(options);
+    mkdirSync(store, { recursive: true });
+    const lockDirectory = join(store, '.install-lock');
+    mkdirSync(lockDirectory);
+    let temporaryRoot;
+    const finish = installation => {
+        if (options.reserveSession) {
+            const sessions = join(store, 'sessions');
+            mkdirSync(sessions, { recursive: true });
+            writeFileSync(join(sessions, String(process.pid)), installation.release);
+        }
+        return installation;
+    };
+    try {
+        const prior = loadState(store);
+        if ((options.offline || liveLeases(store)) && prior) return finish({ ...verifyInstallation(options), status: 'retained' });
+        if (options.offline) throw new Error('Offline install needs an existing verified release');
+        temporaryRoot = mkdtempSync(join(store, '.prepare-'));
+        const now = dependencies.now ?? Date.now();
+        const interval = options.intervalMs ?? 3600000;
+        if (!Number.isFinite(interval) || interval < 0) throw new Error('Invalid update interval');
+        const bundled = options.lock ?? prior?.lock ?? readJson(bundledLockPath);
+        let lock = bundled;
+        let checkedAt = prior?.checkedAt ?? 0;
+        if (options.refresh && (options.force || now - checkedAt >= interval)) {
+            lock = (dependencies.readCentralLock ?? readCentralLock)(temporaryRoot);
+            checkedAt = now;
+        } else if (options.refresh && prior?.lock) lock = prior.lock;
+        validateLock(lock);
+        const adapters = adapterFiles(options.packageRoot ?? packageRoot);
+        const installerSource = readFileSync(fileURLToPath(import.meta.url), 'utf8').replace(/\r\n/g, '\n');
+        const adapterDigest = digest(json(adapters) + installerSource);
+        const id = `${lock.commit}-${adapterDigest.slice(0, 16)}`;
+        const releaseRoot = join(store, 'releases', id);
+        mkdirSync(dirname(releaseRoot), { recursive: true });
+        if (!existsSync(releaseRoot)) {
+            const checkout = join(temporaryRoot, 'source');
+            (dependencies.fetchSource ?? fetchUpstream)(lock, checkout);
+            const stage = join(temporaryRoot, 'release');
+            prepareRelease(checkout, stage, releaseRoot, lock, adapters);
+            verifyRelease(stage);
+            renameSync(stage, releaseRoot);
+        }
+        const release = verifyRelease(releaseRoot);
+        const publication = publish(releaseRoot, release, skillHomes, prior);
+        const state = { release: id, commit: lock.commit, adapterVersion: lock.adapterVersion, adapterDigest, checkedAt, lock, links: publication.links };
+        try {
+            writeFileSync(join(store, 'installed.next.json'), json(state));
+            renameSync(join(store, 'installed.next.json'), join(store, 'installed.json'));
+        } catch (error) { publication.restore(); throw error; }
+        return finish({ ...verifyInstallation(options), status: prior?.release === id ? 'unchanged' : 'installed' });
+    } catch (error) {
+        if (!options.strict) {
+            try { return finish({ ...verifyInstallation(options), status: 'retained', warning: error.message }); } catch { }
+        }
+        throw error;
+    } finally {
+        if (temporaryRoot) rmSync(temporaryRoot, { recursive: true, force: true });
+        rmSync(lockDirectory, { recursive: true, force: true });
+    }
+}
+
+function parseArguments(args) {
+    const options = {};
+    const tailIndex = args.indexOf('--');
+    const tokens = tailIndex < 0 ? args : args.slice(0, tailIndex);
+    const forwarded = tailIndex < 0 ? [] : args.slice(tailIndex + 1);
+    for (let index = 0; index < tokens.length; index++) {
+        const flag = tokens[index];
+        if (['--offline', '--refresh', '--force', '--strict'].includes(flag)) options[flag.slice(2)] = true;
+        else if (['--root', '--project', '--host', '--lock', '--interval-ms'].includes(flag)) {
+            const argument = tokens[++index];
+            if (!argument || argument.startsWith('--')) throw new Error(`${flag} requires a value`);
+            if (flag === '--lock') options.lock = readJson(resolve(argument));
+            else if (flag === '--interval-ms') options.intervalMs = Number(argument);
+            else options[flag.slice(2)] = argument;
+        } else throw new Error(`Unknown option: ${flag}`);
+    }
+    if (options.host && !hosts.includes(options.host)) throw new Error('Host must be claude, codex, or cursor');
+    if (options.root && options.project) throw new Error('Choose --root or --project');
+    return { options, forwarded };
+}
+
+export function main(args = process.argv.slice(2)) {
+    try {
+        const [command = 'help', ...rest] = args;
+        if (['help', '--help', '-h'].includes(command)) {
+            console.log('Usage: cde-pstack <install|verify|launch|hook> [--root PATH|--project PATH] [--refresh] [--offline] [--strict] [--lock PATH] [--host claude|codex|cursor] [-- agent arguments]');
+            return 0;
+        }
+        const { options, forwarded } = parseArguments(rest);
+        if (!['install', 'verify', 'launch', 'hook'].includes(command)) throw new Error(`Unknown command: ${command}`);
+        let hookInput;
+        if (command === 'hook') {
+            hookInput = JSON.parse(readFileSync(0, 'utf8') || '{}');
+            options.project ??= process.env.CLAUDE_PROJECT_DIR || process.cwd();
+            options.offline = hookInput.source !== 'startup';
+            options.refresh = !options.offline && loadState(layout(options).store) !== null;
+        }
+        if (command === 'launch' && !options.host) throw new Error('launch requires --host');
+        if (command === 'launch') { options.refresh = !options.offline && !options.lock; options.reserveSession = true; }
+        const installation = command === 'verify' ? verifyInstallation(options) : installPstack(options);
+        if (installation.warning) console.error(`Pstack update failed; keeping ${installation.commit}: ${installation.warning}`);
+        if (command === 'hook') {
+            const { store } = layout(options);
+            const release = join(store, 'releases', installation.release);
+            console.log(json({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: `Pstack ${installation.commit} is installed. Use the immutable release recorded by session-continuity or the loaded skill entry for this session. Read common.md and host-claude.md in that release's compat directory. New sessions can use the installed inventory at ${join(release, 'release.json')}. ${installation.warning ?? ''}` } }));
+        } else if (command === 'launch') {
+            const sessions = join(layout(options).store, 'sessions');
+            const lease = join(sessions, String(process.pid));
+            try {
+                const child = spawnSync(options.host, forwarded, { stdio: 'inherit', shell: false, env: { ...process.env, CDE_PSTACK_RELEASE: join(layout(options).store, 'releases', installation.release) } });
+                if (child.error) throw child.error;
+                return child.status ?? 1;
+            } finally { unlinkSync(lease); }
+        } else console.log(json(installation));
+        return 0;
+    } catch (error) { console.error(`Pstack: ${error.message}`); return 1; }
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main();

package/bin/pstack.test.mjs

@@ -0,0 +1,289 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { installPstack, prepareRelease, validateLock, verifyInstallation, verifyRelease } from './pstack.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const baseLock = JSON.parse(readFileSync(join(packageRoot, 'scripts', 'pstack.lock.json'), 'utf8'));
+
+function put(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
+
+function fixture(t) {
+    const temporary = mkdtempSync(join(tmpdir(), 'cde-pstack-'));
+    t.after(() => rmSync(temporary, { recursive: true, force: true }));
+    const checkout = join(temporary, 'checkout');
+    for (const [component, names] of Object.entries(baseLock.requiredSkills)) {
+        for (const name of names) put(join(checkout, component, 'skills', name, 'SKILL.md'), `---\nname: ${name}\ndescription: Test ${name}.\n---\n\nRun ${name}.\n`);
+        put(join(checkout, component, 'LICENSE'), `${component} license\n`);
+        put(join(checkout, component, '.cursor-plugin', 'plugin.json'), JSON.stringify({ name: component, skills: './skills' }));
+    }
+    put(join(checkout, 'pstack', 'skills', 'poteto-mode', 'playbooks', 'feature.md'), 'Build a small task, delegate, and verify it.\n');
+    put(join(checkout, 'pstack', 'agents', 'poteto-agent.md'), 'Read poteto-mode and report complete findings.\n');
+    put(join(checkout, 'pstack', 'scripts', 'proof.sh'), '#!/bin/sh\nprintf proof\n');
+    chmodSync(join(checkout, 'pstack', 'scripts', 'proof.sh'), 0o755);
+    put(join(checkout, 'pstack', 'assets', 'example.png'), Buffer.from([137, 80, 78, 71, 0, 255]));
+    const project = join(temporary, 'project with spaces');
+    const options = { project, lock: structuredClone(baseLock), packageRoot };
+    const dependencies = { fetchSource: (_lock, destination) => cpSync(checkout, destination, { recursive: true }), now: 10000000 };
+    return { temporary, checkout, options, dependencies, store: join(project, '.claude', 'pstack') };
+}
+
+for (const host of ['claude', 'codex', 'cursor']) {
+    test(`clean ${host} filesystem install publishes all entry points and supporting files`, t => {
+        const f = fixture(t);
+        const result = installPstack({ ...f.options, host }, f.dependencies);
+        assert.equal(result.status, 'installed');
+        assert.equal(result.skillCount, 5);
+        assert.equal(result.commit, '27e2a62ff94f9af4b5e68435e41cdceacadb840c');
+        assert.equal(result.verification, 'filesystem-only');
+        const release = join(f.store, 'releases', result.release);
+        const expected = ['cde-create-skill', 'cursor-team-kit-control-cli', 'cursor-team-kit-control-ui', 'cursor-team-kit-deslop', 'pstack-poteto-mode'];
+        for (const home of ['.claude', '.agents']) {
+            assert.deepEqual(readdirSync(join(f.options.project, home, 'skills')).sort(), expected);
+            const entry = join(f.options.project, home, 'skills', 'pstack-poteto-mode');
+            assert.equal(realpathSync(entry), join(release, 'runtime', 'pstack', 'skills', 'poteto-mode'));
+            const text = readFileSync(join(entry, 'SKILL.md'), 'utf8');
+            assert.match(text, /name: pstack-poteto-mode/);
+            assert.ok(text.includes(JSON.stringify(join(release, 'compat', 'common.md'))));
+            assert.equal(readFileSync(join(entry, 'playbooks', 'feature.md'), 'utf8'), 'Build a small task, delegate, and verify it.\n');
+        }
+        assert.equal(existsSync(join(f.options.project, '.cursor')), false);
+        for (const component of baseLock.components) {
+            assert.equal(existsSync(join(release, 'runtime', component, '.cursor-plugin', 'plugin.json')), false);
+            assert.equal(readFileSync(join(release, 'upstream', component, '.cursor-plugin', 'plugin.json'), 'utf8'),
+                readFileSync(join(f.checkout, component, '.cursor-plugin', 'plugin.json'), 'utf8'));
+        }
+        assert.equal(readFileSync(join(release, 'upstream', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8'), readFileSync(join(f.checkout, 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8'));
+        assert.deepEqual(readFileSync(join(release, 'upstream', 'pstack', 'assets', 'example.png')), Buffer.from([137, 80, 78, 71, 0, 255]));
+        assert.equal(readFileSync(join(release, 'runtime', 'pstack', 'agents', 'poteto-agent.md'), 'utf8'), 'Read poteto-mode and report complete findings.\n');
+        assert.equal(readFileSync(join(release, 'upstream', 'cursor-team-kit', 'LICENSE'), 'utf8'), 'cursor-team-kit license\n');
+        if (process.platform !== 'win32') assert.equal(statSync(join(release, 'runtime', 'pstack', 'scripts', 'proof.sh')).mode & 0o777, 0o755);
+    });
+}
+
+test('unchanged install avoids another upstream fetch', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const second = installPstack(f.options, { fetchSource: () => assert.fail('unexpected fetch') });
+    assert.equal(second.status, 'unchanged');
+    assert.equal(second.release, first.release);
+    assert.deepEqual(second.links, first.links);
+});
+
+test('changed, added, and removed skills converge while old releases remain readable', t => {
+    const f = fixture(t);
+    put(join(f.checkout, 'pstack', 'skills', 'old', 'SKILL.md'), '---\nname: old\ndescription: Old skill.\n---\nOld body.\n');
+    const before = installPstack(f.options, f.dependencies);
+    const oldRelease = join(f.store, 'releases', before.release);
+    const firstBody = readFileSync(join(oldRelease, 'runtime', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8');
+    rmSync(join(f.checkout, 'pstack', 'skills', 'old'), { recursive: true });
+    put(join(f.checkout, 'pstack', 'skills', 'new', 'SKILL.md'), '---\nname: new\ndescription: New skill.\n---\nNew body.\n');
+    put(join(f.checkout, 'pstack', 'skills', 'poteto-mode', 'playbooks', 'feature.md'), 'Changed playbook.\n');
+    const after = installPstack({ ...f.options, lock: { ...baseLock, commit: 'b'.repeat(40) } }, f.dependencies);
+    assert.equal(after.skillCount, 6);
+    for (const home of ['.claude', '.agents']) {
+        const path = join(f.options.project, home, 'skills');
+        assert.equal(existsSync(join(path, 'pstack-old')), false);
+        assert.equal(readFileSync(join(path, 'pstack-new', 'SKILL.md'), 'utf8').endsWith('New body.\n'), true);
+        assert.equal(readFileSync(join(path, 'pstack-poteto-mode', 'playbooks', 'feature.md'), 'utf8'), 'Changed playbook.\n');
+    }
+    assert.equal(readFileSync(join(oldRelease, 'runtime', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'utf8'), firstBody);
+});
+
+test('missing required dependency retains the previous complete installation', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const priorBytes = readFileSync(join(f.store, 'installed.json'), 'utf8');
+    rmSync(join(f.checkout, 'cursor-team-kit', 'skills', 'control-ui'), { recursive: true });
+    const result = installPstack({ ...f.options, lock: { ...baseLock, commit: 'c'.repeat(40) } }, f.dependencies);
+    assert.equal(result.status, 'retained');
+    assert.match(result.warning, /Missing dependency: cursor-team-kit:control-ui/);
+    assert.equal(result.release, first.release);
+    assert.equal(readFileSync(join(f.store, 'installed.json'), 'utf8'), priorBytes);
+    assert.equal(verifyInstallation(f.options).skillCount, 5);
+});
+
+test('a failed first install returns failure and publishes no skills', t => {
+    const f = fixture(t);
+    assert.throws(() => installPstack(f.options, { fetchSource: () => { throw new Error('network unavailable'); } }), /network unavailable/);
+    assert.equal(existsSync(join(f.options.project, '.claude', 'skills')), false);
+    assert.equal(existsSync(join(f.store, '.install-lock')), false);
+});
+
+test('unmanaged skill collision preserves user files', t => {
+    const f = fixture(t);
+    const userFile = join(f.options.project, '.claude', 'skills', 'pstack-poteto-mode', 'SKILL.md');
+    put(userFile, 'Personal workflow\n');
+    assert.throws(() => installPstack(f.options, f.dependencies), /Keep existing unmanaged path/);
+    assert.equal(readFileSync(userFile, 'utf8'), 'Personal workflow\n');
+    assert.equal(existsSync(join(f.store, 'installed.json')), false);
+});
+
+test('existing shared skills-directory pointer is preserved', t => {
+    const f = fixture(t);
+    const agents = join(f.options.project, '.agents', 'skills');
+    mkdirSync(agents, { recursive: true });
+    mkdirSync(join(f.options.project, '.claude'), { recursive: true });
+    symlinkSync(agents, join(f.options.project, '.claude', 'skills'), process.platform === 'win32' ? 'junction' : 'dir');
+    const before = readlinkSync(join(f.options.project, '.claude', 'skills'));
+    const result = installPstack(f.options, f.dependencies);
+    assert.equal(Object.keys(result.links).length, 5);
+    assert.equal(readlinkSync(join(f.options.project, '.claude', 'skills')), before);
+});
+
+test('offline reuse checks installed bytes and rejects corruption', t => {
+    const f = fixture(t);
+    const result = installPstack(f.options, f.dependencies);
+    assert.equal(installPstack({ ...f.options, offline: true }).release, result.release);
+    put(join(f.store, 'releases', result.release, 'runtime', 'pstack', 'skills', 'poteto-mode', 'SKILL.md'), 'corrupted');
+    assert.throws(() => installPstack({ ...f.options, offline: true }), /Changed installed file/);
+});
+
+test('unknown namespaced upstream dependency requires adapter review', t => {
+    const f = fixture(t);
+    put(join(f.checkout, 'pstack', 'skills', 'poteto-mode', 'reference.md'), 'Invoke cursor-team-kit:missing-skill.\n');
+    assert.throws(() => installPstack(f.options, f.dependencies), /Unresolved skill dependency/);
+});
+
+test('source symlinks are rejected before publication', t => {
+    const f = fixture(t);
+    const outside = join(f.temporary, 'outside-source');
+    mkdirSync(outside);
+    put(join(outside, 'personal.txt'), 'Retain this file.');
+    const dependencies = { ...f.dependencies, fetchSource: (lock, destination) => {
+        f.dependencies.fetchSource(lock, destination);
+        const link = join(destination, 'pstack', 'escape');
+        symlinkSync(outside, link, process.platform === 'win32' ? 'junction' : 'dir');
+        assert.equal(lstatSync(link).isSymbolicLink(), true);
+    } };
+    assert.throws(() => installPstack(f.options, dependencies), /symlinks require review/);
+    assert.equal(readFileSync(join(outside, 'personal.txt'), 'utf8'), 'Retain this file.');
+});
+
+test('update checks use the shared record and respect the interval', t => {
+    const f = fixture(t);
+    const shared = { ...baseLock, commit: 'd'.repeat(40) };
+    let calls = 0;
+    const dependencies = { ...f.dependencies, readCentralLock: () => { calls++; return shared; } };
+    const first = installPstack({ ...f.options, refresh: true }, dependencies);
+    assert.equal(first.commit, 'd'.repeat(40));
+    const second = installPstack({ ...f.options, refresh: true }, { ...dependencies, now: dependencies.now + 100 });
+    assert.equal(second.commit, 'd'.repeat(40));
+    assert.equal(calls, 1);
+    installPstack({ ...f.options, refresh: true }, { ...dependencies, now: dependencies.now + 3600001 });
+    assert.equal(calls, 2);
+});
+
+test('failed shared-record refresh retains and reports the previous revision', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const result = installPstack({ ...f.options, refresh: true }, { ...f.dependencies, readCentralLock: () => { throw new Error('record unavailable'); } });
+    assert.equal(result.release, first.release);
+    assert.equal(result.warning, 'record unavailable');
+});
+
+test('an active launcher lease defers updating shared instructions', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    put(join(f.store, 'sessions', String(process.pid)), first.release);
+    const result = installPstack({ ...f.options, lock: { ...baseLock, commit: 'e'.repeat(40) } }, { fetchSource: () => assert.fail('updated during an active session') });
+    assert.equal(result.status, 'retained');
+    assert.equal(result.release, first.release);
+});
+
+test('unsupported lock input fails before source fetch', t => {
+    const f = fixture(t);
+    for (const change of [{ commit: 'main' }, { adapterVersion: 2 }, { repository: 'https://example.test/repo' }, { components: ['../outside'] }, { requiredSkills: {} }]) {
+        assert.throws(() => installPstack({ ...f.options, lock: { ...baseLock, ...change } }, { fetchSource: () => assert.fail('unexpected fetch') }));
+    }
+    assert.equal(validateLock(baseLock), baseLock);
+});
+
+test('CLI exposes deterministic verification and rejects unknown flags', t => {
+    const f = fixture(t);
+    installPstack(f.options, f.dependencies);
+    const command = join(packageRoot, 'bin', 'pstack.mjs');
+    const verified = spawnSync(process.execPath, [command, 'verify', '--project', f.options.project], { encoding: 'utf8' });
+    assert.equal(verified.status, 0, verified.stderr);
+    assert.equal(JSON.parse(verified.stdout).skillCount, 5);
+    const invalid = spawnSync(process.execPath, [command, 'install', '--host', 'unknown'], { encoding: 'utf8' });
+    assert.equal(invalid.status, 1);
+    assert.match(invalid.stderr, /Host must be/);
+    const help = spawnSync(process.execPath, [command, '--help'], { encoding: 'utf8' });
+    assert.equal(help.status, 0);
+    assert.match(help.stdout, /cde-pstack/);
+});
+
+test('resumed Claude hook retains the cached release and emits native hook JSON', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const result = spawnSync(process.execPath, [join(packageRoot, 'bin', 'pstack.mjs'), 'hook', '--project', f.options.project], {
+        encoding: 'utf8', input: JSON.stringify({ source: 'resume' }),
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const output = JSON.parse(result.stdout);
+    assert.equal(output.hookSpecificOutput.hookEventName, 'SessionStart');
+    assert.ok(output.hookSpecificOutput.additionalContext.includes(first.commit));
+    assert.ok(output.hookSpecificOutput.additionalContext.includes('common.md'));
+});
+
+test('release validation catches missing files and escaping manifest paths', t => {
+    const f = fixture(t);
+    const result = installPstack(f.options, f.dependencies);
+    const root = join(f.store, 'releases', result.release);
+    assert.equal(verifyRelease(root).skills.length, 5);
+    const manifest = JSON.parse(readFileSync(join(root, 'release.json'), 'utf8'));
+    manifest.fileDigests['../../outside'] = 'bad';
+    put(join(root, 'release.json'), JSON.stringify(manifest));
+    assert.throws(() => verifyRelease(root), /Invalid release path/);
+});
+
+test('state-write failure restores the old published pointers', t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const priorBytes = readFileSync(join(f.store, 'installed.json'), 'utf8');
+    mkdirSync(join(f.store, 'installed.next.json'));
+    const result = installPstack({ ...f.options, lock: { ...baseLock, commit: 'f'.repeat(40) } }, f.dependencies);
+    assert.equal(result.status, 'retained');
+    assert.equal(result.release, first.release);
+    assert.equal(readFileSync(join(f.store, 'installed.json'), 'utf8'), priorBytes);
+    assert.equal(verifyInstallation(f.options).commit, first.commit);
+});
+
+test('npm-style linked CLI runs its entry point', t => {
+    const f = fixture(t);
+    if (process.platform === 'win32') return;
+    const link = join(f.temporary, 'cde-pstack');
+    symlinkSync(join(packageRoot, 'bin', 'pstack.mjs'), link);
+    const result = spawnSync(process.execPath, [link, '--help'], { encoding: 'utf8' });
+    assert.equal(result.status, 0);
+    assert.match(result.stdout, /Usage: cde-pstack/);
+});
+
+test('session reservation is recorded before install releases its lock', t => {
+    const f = fixture(t);
+    const result = installPstack({ ...f.options, reserveSession: true }, f.dependencies);
+    assert.equal(readFileSync(join(f.store, 'sessions', String(process.pid)), 'utf8'), result.release);
+    assert.equal(existsSync(join(f.store, '.install-lock')), false);
+});
+
+
+test('a changed installer creates a fresh generation for the same upstream pin', async t => {
+    const f = fixture(t);
+    const first = installPstack(f.options, f.dependencies);
+    const copied = join(f.temporary, 'updated-installer', 'bin', 'pstack.mjs');
+    put(copied, readFileSync(join(packageRoot, 'bin', 'pstack.mjs'), 'utf8') + '\n');
+    const updated = await import(pathToFileURL(copied).href);
+    const second = updated.installPstack(f.options, f.dependencies);
+    assert.equal(second.commit, first.commit);
+    assert.notEqual(second.adapterDigest, first.adapterDigest);
+    assert.notEqual(second.release, first.release);
+    assert.equal(verifyInstallation(f.options).release, second.release);
+});

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,10 +1,11 @@
 {
     "name": "claude-dev-env",
-    "version": "7.2.0",
+    "version": "7.3.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
         "claude-dev-env": "bin/install.mjs",
+        "cde-pstack": "bin/pstack.mjs",
         "codex-compat": "bin/codex-compat.mjs",
         "cde": "bin/cde.mjs"
     },

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.
 

package/scripts/pstack-adapters/common.md

@@ -0,0 +1,17 @@
+# Pstack compatibility
+
+Apply this mapping to the upstream workflow below. User instructions and host permissions stay in charge.
+
+Determine the active host from the session's native tools. Read host-claude.md, host-codex.md, or host-cursor.md beside this file for the active host. Read pstack-host-mapping.md and pstack-models.md beside this file before delegation. Those files are copied from claude-dev-env's existing rules into this immutable release. Run the selectorPath recorded in release.json and supply its preferencesDirectory in the selector input. This overrides the old global selector path. Model preferences remain outside the release.
+
+Installed skill names have a component prefix. Read the installed inventory in release.json. A pstack request for how, /how, or pstack:how means pstack-how. A cursor-team-kit request for deslop means cursor-team-kit-deslop. Resolve all other skill names through that inventory. Read each leaf skill in full when it applies. Keep each skill's scripts, references, playbooks, and agent definitions at its recorded source root.
+
+Every delegation prompt must include this compatibility file's absolute path, the active host file's absolute path, the selected skill's absolute path, and the requested upstream agent definition's absolute path when present. Tell the child to read them before working and to put the complete findings and evidence in its final message. The child receives the same host and model mapping as the parent.
+
+Treat upstream model identifiers as role preferences. Use only models and arguments accepted by the native tool in this session. Preserve required independence and model diversity. Report a missing capability when the session cannot supply the required independent panel. Use the native tool's supported concurrency and wait operations.
+
+For setup-pstack, configure only the current host's model preference file described in pstack-models.md. Keep that file outside this release. The Cursor .mdc output is a Cursor rule, not a cross-host model configuration.
+
+For create-skill, use Cursor's built-in skill on Cursor and cde-create-skill on Claude or Codex. For control-cli and control-ui, load the corresponding installed cursor-team-kit skill and use native terminal or browser tools. Check that the required CLI, browser, credentials, and permissions exist before executing its steps. State an unavailable dependency explicitly. Never claim an unattended browser or remote session ran from a filesystem check.
+
+Updates are prepared outside the active release. Follow absolute paths into the release named in this entry point for the rest of this task. Preserve supporting files and scripts, including executable modes and licenses.

package/scripts/pstack-adapters/create-skill.md

@@ -0,0 +1,14 @@
+---
+name: cde-create-skill
+description: Write or update a portable SKILL.md workflow when pstack requests create-skill on a host without Cursor's built-in skill.
+---
+
+# Create a portable skill
+
+State the user-visible outcome and the exact trigger first. Inspect applicable repository instructions and existing skills before adding a new skill.
+
+Create a lowercase, hyphenated skill directory under the project's .claude/skills. Give SKILL.md YAML frontmatter with a matching name and a one-line description that says when to use it. Put the workflow after the frontmatter. Keep supporting scripts and references together with the skill, and use relative links inside it. Add a Codex .agents/skills directory link where needed, preserving existing files.
+
+Use native host tools and capability checks. Give each step a concrete input, action, and observable result. Separate human choices from facts the agent can inspect. Read referenced instructions before using them.
+
+Verify metadata, links, and script behavior. Then invoke the installed skill in the intended host and record the actual result. Distinguish a filesystem check from a native invocation. Keep the scope to the requested workflow.

package/scripts/pstack-adapters/host-claude.md

@@ -0,0 +1,7 @@
+# Claude Code
+
+Use Claude Code's native Skill mechanism to load installed skills. Use Agent for Task requests, with only arguments the session exposes. For an upstream poteto-agent or another unavailable agent type, use an available general-purpose agent and include the upstream definition and compatibility files in its prompt. A file on disk does not register a native agent type.
+
+Use AskUserQuestion for a required human choice. Use Read, Glob, Grep, Edit, Write, Bash, and the available browser tools for their corresponding work. Read native tool schemas rather than forwarding Cursor-only arguments. Use background execution only when the current tool supports it.
+
+Choose model aliases accepted by this session. Omit the model argument for permitted parent inheritance. Keep host preferences in the profile's agents-home rules/pstack-model-preferences.claude.json. Use the current session's transcript location, or state that transcripts are unavailable.

package/scripts/pstack-adapters/host-codex.md

@@ -0,0 +1,11 @@
+# Codex
+
+Load SKILL.md with the native skill mechanism or read its complete file with the available file tool. Codex does not need a Claude Skill tool.
+
+Map Task or Agent to the native spawn_agent, wait, send_input, and close_agent operations that this session exposes. Field names vary by host version. Inspect the live schema. For poteto-agent, include the upstream agent definition, skill entry, and compatibility files in the child prompt. Select an available native agent type. Do not pass subagent_type, run_in_background, or a model argument unless that tool accepts it.
+
+Use the native shell for commands, apply_patch or the native editor for edits, and the available browser tool for UI work. Ask the user through the current session's supported interaction mechanism for a genuine preference decision.
+
+A multi-agent feature setting in a CLI profile does not establish subagent support in a cloud session. Check available tools. Required independent or cross-model review stops with a clear capability report when that session cannot provide it. Keep configured model preferences in the profile's agents-home rules/pstack-model-preferences.codex.json. Read the current transcript location from host context, not ~/.cursor/projects.
+
+The selector's availableModelIds contains only models selectable through this session's delegation tool. A tool without a model argument supplies an empty list and uses permitted parent inheritance. A provider's general model catalog is not proof of per-delegation model selection.

package/scripts/pstack-adapters/host-cursor.md

@@ -0,0 +1,7 @@
+# Cursor
+
+Use Cursor's available native skill and delegation tools. The installed component-prefixed names in release.json replace upstream plugin short names. Keep project skills under .claude/skills and use the .agents/skills links for shared discovery. The installer writes no skills under .cursor.
+
+For an upstream custom agent type absent from the live tool inventory, use an available native agent type and include that upstream agent definition, the skill entry, and compatibility files in the child prompt. Use the session's supported model identifiers and delegation fields. Preserve required panel independence and model diversity.
+
+Use Cursor's built-in create-skill when present. Otherwise read cde-create-skill. Keep Cursor-specific preferences separate from Claude and Codex preferences. Resolve transcripts from the current workspace and session context.

package/scripts/pstack.lock.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "adapterVersion": 1,
+  "repository": "https://github.com/cursor/plugins.git",
+  "commit": "27e2a62ff94f9af4b5e68435e41cdceacadb840c",
+  "components": ["pstack", "cursor-team-kit"],
+  "requiredSkills": {
+    "pstack": ["poteto-mode"],
+    "cursor-team-kit": ["deslop", "control-cli", "control-ui"]
+  }
+}