claude-dev-env 7.6.0 → 7.6.1

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

@@ -1,7 +1,10 @@
 # Session continuity companion
 
 Status: draft implementation. Claude, Codex, and Cursor adapters have
-repository-level contract tests. Installed-host activation, reload, and agent
+repository-level contract tests. Claude installed-host automatic activation is
+verified: a headless `claude -p` session on Claude Code 2.1.268 created a new
+session-scope record carrying the `automatic` flag, with no user invocation.
+Codex and Cursor installed-host activation, post-compaction reload, and agent
 compliance remain unverified.
 
 Every supported host activates Poteto Mode automatically when a session starts
@@ -27,21 +30,28 @@ pstack manifest refresher exposes namespaced Claude skills and leaves pstack
 content with its existing owner. The companion edits none of that source,
 manifest, invocation code, or model policy.
 
-From this checkout, run the full existing installer, then the focused hook setup:
+From this checkout, run the full existing installer:
 
 ```sh
 node packages/claude-dev-env/bin/install.mjs
+```
+
+The full installer publishes this skill under the canonical agents home and
+registers its hooks in every host configuration the install root resolves. No
+second command is needed. A selective `--only <group>` install skips both steps,
+and a plugin-only installation needs the canonical installed skill first. For
+either of those, or to configure one host alone, run the focused setup:
+
+```sh
 node packages/claude-dev-env/bin/install-session-continuity.mjs
 ```
 
-The full installer publishes this skill under the canonical agents home. This
-setup is required once for each selected host/profile, not once per invocation.
-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 focused setup defaults to `claude codex cursor`. Pass one or more host names
+to configure that subset alone. Registration is idempotent, so running it after a
+full install reports each host as already configured.
 
-The setup defaults to `claude codex cursor`. Pass one or more host names to
-configure that subset alone.
+An uninstall removes the companion's registrations along with its files, so no
+host keeps a hook pointing at a script that is gone.
 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

package/bin/install-session-continuity.mjs

@@ -44,41 +44,84 @@ export function mergeContinuityHooks(existing, host, script) {
     return mergedConfiguration;
 }
 
-async function main() {
-    const requested = process.argv.slice(2);
-    const selected = requested.length ? requested : supportedHosts;
+export const CONTINUITY_SCRIPT_MARKER = '/session-continuity/continuity.mjs';
+
+export function isContinuityHookCommand(command) {
+    return typeof command === 'string' && command.includes(CONTINUITY_SCRIPT_MARKER);
+}
+
+export function continuityScriptPath(roots) {
+    return join(roots.skillsInstallDirectory, 'session-continuity', 'continuity.mjs');
+}
+
+export function continuityHostConfigurationPaths(roots) {
+    return {
+        claude: join(roots.managedRoot, 'settings.json'),
+        codex: join(dirname(roots.codexRulesInstallDirectory), 'hooks.json'),
+        cursor: join(roots.cursorInstallDirectory, 'hooks.json'),
+    };
+}
+
+export function removeContinuityHooks(configuration) {
+    let removedCount = 0;
+    for (const [event, entries] of Object.entries(configuration.hooks || {})) {
+        const kept = entries.flatMap(entry => {
+            if (!entry.hooks) {
+                if (!isContinuityHookCommand(entry.command)) return [entry];
+                removedCount += 1;
+                return [];
+            }
+            const hooks = entry.hooks.filter(hook => !isContinuityHookCommand(hook.command));
+            removedCount += entry.hooks.length - hooks.length;
+            return hooks.length ? [{ ...entry, hooks }] : [];
+        });
+        if (kept.length) configuration.hooks[event] = kept;
+        else delete configuration.hooks[event];
+    }
+    return removedCount;
+}
+
+function continuityConfigurationPlan(host, path, script) {
+    if (!existsSync(dirname(path))) throw new Error(`Host config directory is absent: ${dirname(path)}`);
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    const merged = mergeContinuityHooks(existing ? JSON.parse(existing) : {}, host, script);
+    return { host, path, existing, content: JSON.stringify(merged, null, 2) + '\n' };
+}
+
+function applyContinuityConfigurationPlan(plan) {
+    if (plan.existing === plan.content) return { host: plan.host, path: plan.path, changed: false };
+    if (plan.existing !== null) {
+        const backup = `${plan.path}.before-session-continuity`;
+        if (!existsSync(backup)) writeFileSync(backup, plan.existing, { flag: 'wx', mode: 0o600 });
+    }
+    const current = existsSync(plan.path) ? readFileSync(plan.path, 'utf8') : null;
+    if (current !== plan.existing) throw new Error(`Config changed during setup: ${plan.path}. Rerun setup.`);
+    const temporary = `${plan.path}.continuity-${process.pid}.tmp`;
+    writeFileSync(temporary, plan.content, { flag: 'wx', mode: 0o600 });
+    renameSync(temporary, plan.path);
+    if (readFileSync(plan.path, 'utf8') !== plan.content) throw new Error(`Config read-back mismatch: ${plan.path}`);
+    return { host: plan.host, path: plan.path, changed: true };
+}
+
+export function configureContinuityHosts(roots, selected) {
     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');
+    const script = continuityScriptPath(roots);
     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'),
-        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)}`);
-        const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
-        return { path, existing, content: JSON.stringify(mergeContinuityHooks(existing ? JSON.parse(existing) : {}, host, script), null, 2) + '\n' };
-    });
-    for (const plan of plans) {
-        if (plan.existing === plan.content) { console.log(`Already configured: ${plan.path}`); continue; }
-        if (plan.existing !== null) {
-            const backup = `${plan.path}.before-session-continuity`;
-            if (!existsSync(backup)) writeFileSync(backup, plan.existing, { flag: 'wx', mode: 0o600 });
-        }
-        const current = existsSync(plan.path) ? readFileSync(plan.path, 'utf8') : null;
-        if (current !== plan.existing) throw new Error(`Config changed during setup: ${plan.path}. Rerun setup.`);
-        const temporary = `${plan.path}.continuity-${process.pid}.tmp`;
-        writeFileSync(temporary, plan.content, { flag: 'wx', mode: 0o600 });
-        renameSync(temporary, plan.path);
-        if (readFileSync(plan.path, 'utf8') !== plan.content) throw new Error(`Config read-back mismatch: ${plan.path}`);
-        console.log(`Configured and read back: ${plan.path}`);
+    const paths = continuityHostConfigurationPaths(roots);
+    return selected
+        .map(host => continuityConfigurationPlan(host, paths[host], script))
+        .map(applyContinuityConfigurationPlan);
+}
+
+async function main() {
+    const requested = process.argv.slice(2);
+    const selected = requested.length ? requested : supportedHosts;
+    const { resolveInstallRoot } = await import('./resolve-install-root.mjs');
+    for (const result of configureContinuityHosts(resolveInstallRoot(), selected)) {
+        console.log(`${result.changed ? 'Configured and read back' : 'Already configured'}: ${result.path}`);
     }
     console.log('Review and trust the new hooks in each host.');
 }

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

@@ -1,6 +1,30 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { continuityHookConfiguration, mergeContinuityHooks } from './install-session-continuity.mjs';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+    configureContinuityHosts,
+    continuityHookConfiguration,
+    mergeContinuityHooks,
+    removeContinuityHooks,
+} from './install-session-continuity.mjs';
+
+function installRootFixture() {
+    const root = mkdtempSync(join(tmpdir(), 'continuity-roots-'));
+    const skillsInstallDirectory = join(root, 'agents', 'skills');
+    const companionDirectory = join(skillsInstallDirectory, 'session-continuity');
+    mkdirSync(companionDirectory, { recursive: true });
+    writeFileSync(join(companionDirectory, 'continuity.mjs'), 'export default null;\n');
+    writeFileSync(join(companionDirectory, 'SKILL.md'), '# companion\n');
+    const managedRoot = join(root, 'claude');
+    const codexRulesInstallDirectory = join(root, 'codex', 'rules');
+    const cursorInstallDirectory = join(root, 'cursor');
+    for (const directory of [managedRoot, codexRulesInstallDirectory, cursorInstallDirectory]) {
+        mkdirSync(directory, { recursive: true });
+    }
+    return { managedRoot, skillsInstallDirectory, codexRulesInstallDirectory, cursorInstallDirectory };
+}
 
 test('setup preserves other hooks and settings, is idempotent, and rejects competing profiles', () => {
     const existing = { permissions: { deny: ['secret'] }, hooks: { SessionStart: [{ hooks: [{ type: 'command', command: 'existing-hook' }] }] } };
@@ -53,3 +77,30 @@ for (const host of ['claude', 'codex']) {
         }
     });
 }
+
+test('configureContinuityHosts writes each host config, reads it back, and repeats without a change', () => {
+    const roots = installRootFixture();
+    const settingsPath = join(roots.managedRoot, 'settings.json');
+    writeFileSync(settingsPath, JSON.stringify({ permissions: { deny: ['secret'] } }, null, 2) + '\n');
+    const first = configureContinuityHosts(roots, ['claude', 'codex', 'cursor']);
+    assert.deepEqual(first.map(result => result.changed), [true, true, true]);
+    const written = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    assert.deepEqual(written.permissions.deny, ['secret']);
+    const command = written.hooks.SessionStart[0].hooks[0].command;
+    assert.equal(command.endsWith('session-continuity/continuity.mjs" hook claude'), true);
+    const second = configureContinuityHosts(roots, ['claude', 'codex', 'cursor']);
+    assert.deepEqual(second.map(result => result.changed), [false, false, false]);
+});
+
+test('removeContinuityHooks takes out only the companion registrations', () => {
+    const roots = installRootFixture();
+    configureContinuityHosts(roots, ['claude']);
+    const settingsPath = join(roots.managedRoot, 'settings.json');
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    settings.hooks.SessionStart.unshift({ hooks: [{ type: 'command', command: 'python other_hook.py' }] });
+    const removedCount = removeContinuityHooks(settings);
+    assert.equal(removedCount, 3);
+    assert.deepEqual(Object.keys(settings.hooks), ['SessionStart']);
+    assert.equal(settings.hooks.SessionStart.length, 1);
+    assert.equal(settings.hooks.SessionStart[0].hooks[0].command, 'python other_hook.py');
+});

package/bin/install.mjs

@@ -44,6 +44,11 @@ import {
     refreshPstackPluginManifest,
 } from '../scripts/refresh_pstack_plugin_skills.mjs';
 import { installPstack } from './pstack.mjs';
+import {
+    configureContinuityHosts,
+    continuityHostConfigurationPaths,
+    removeContinuityHooks,
+} from './install-session-continuity.mjs';
 import {
     resolveInstallRoot,
     parseExplicitTargetFromArgv,
@@ -509,6 +514,63 @@ function seedPstackPreferences(preferenceFileName) {
     }
 }
 
+/**
+ * Registers the session-continuity companion in each host configuration this
+ * install root resolves. Without this step the companion ships to the agents
+ * home but no host ever calls it, so Poteto Mode only activates when someone
+ * remembers a second setup command.
+ *
+ * A competing profile's registration, or an unwritable host configuration, is
+ * reported and leaves the rest of the install intact.
+ *
+ * @returns {string[]} The host configuration paths this run registered.
+ */
+function registerSessionContinuityHooks() {
+    const configurationPaths = continuityHostConfigurationPaths(INSTALL_ROOT_RESOLUTION);
+    const hosts = Object.keys(configurationPaths)
+        .filter(host => existsSync(dirname(configurationPaths[host])));
+    if (hosts.length === 0) return [];
+    try {
+        const results = configureContinuityHosts(INSTALL_ROOT_RESOLUTION, hosts);
+        for (const result of results) {
+            const state = result.changed ? 'registered' : 'already registered';
+            console.log(`  Session continuity: ${state} in ${result.path}`);
+        }
+        return results.map(result => result.path);
+    } catch (registrationError) {
+        console.warn(
+            `  Warning: session-continuity hooks were not registered (${registrationError.message}) — `
+            + 'run bin/install-session-continuity.mjs once the cause is resolved.',
+        );
+        return [];
+    }
+}
+
+/**
+ * Removes the companion's registrations from the Codex and Cursor hook files
+ * during an uninstall. The Claude settings.json copy is pruned inside the
+ * settings block, which owns that file's single write.
+ *
+ * Each host this installer registered is a host it has to clean, or the host
+ * keeps calling a script the uninstall deleted.
+ *
+ * @returns {string[]} The host configuration paths this run changed.
+ */
+function removeSessionContinuityHooksFromOtherHosts() {
+    const configurationPaths = continuityHostConfigurationPaths(INSTALL_ROOT_RESOLUTION);
+    const changedPaths = [];
+    for (const host of ['codex', 'cursor']) {
+        const configurationPath = configurationPaths[host];
+        if (!existsSync(configurationPath)) continue;
+        const configuration = JSON.parse(readFileSync(configurationPath, 'utf8'));
+        if (removeContinuityHooks(configuration) === 0) continue;
+        writeFileSync(configurationPath, JSON.stringify(configuration, null, 2) + '\n');
+        changedPaths.push(configurationPath);
+        console.log(`  Session continuity: hook registrations removed from ${configurationPath}`);
+    }
+    return changedPaths;
+}
+
 /**
  * Formats an absolute interpreter path as a settings.json hook command prefix:
  * forward-slash separators, double-quoted when the path contains a space so the
@@ -2922,6 +2984,9 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         console.log(`  \u2713 ${relative(CLAUDE_HOME, agentsHubDest)} (canonical guidance)`);
     }
     const isFullInstall = !selectedGroups;
+    if (isFullInstall && shouldInstallAnyHooks) {
+        summary.sessionContinuity = { configuredPaths: registerSessionContinuityHooks() };
+    }
     const didPruneRun = isFullInstall && UNRESOLVED_DEPENDENCY_NAMES.length === 0;
     let failedPrunePaths = [];
     let stalePrunedTotal = 0;
@@ -3139,6 +3204,10 @@ function executeUninstallPlan(plan, helpers = {}) {
             pruneManagedHooksFromSettings(settings, managedHookRelativePaths);
             didSettingsChange = true;
             console.log('  Hook entries removed from settings.json');
+            const removedContinuityCount = removeContinuityHooks(settings);
+            if (removedContinuityCount > 0) {
+                console.log(`  Session continuity: ${removedContinuityCount} hook registration(s) removed from settings.json`);
+            }
         }
         const managedDenyFromPlan = plan.managedPermissionDenyEntries.length > 0
             ? plan.managedPermissionDenyEntries
@@ -3156,6 +3225,7 @@ function executeUninstallPlan(plan, helpers = {}) {
             writeFileSync(plan.settingsPath, JSON.stringify(settings, null, 4) + '\n');
         }
     }
+    removeSessionContinuityHooksFromOtherHosts();
     throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
 
     unsetGlobalGitHooksPathIfOurs();

package/bin/install.test.mjs

@@ -3088,3 +3088,60 @@ test('--no-pstack leaves the pstack store absent', t => {
         assert.equal(existsSync(join(homeDirectory, '.claude', 'pstack')), false);
     });
 });
+
+function runContinuityInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [PSTACK_TEST_INSTALLER_PATH, ...extraArguments], {
+        cwd: dirname(PSTACK_TEST_PACKAGE_ROOT),
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            CDE_INSTALL_PSTACK: '0',
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            CODEX_HOME: join(homeDirectory, '.codex'),
+        },
+    });
+}
+
+function continuityCommandCount(configurationPath) {
+    if (!existsSync(configurationPath)) return 0;
+    const configuration = JSON.parse(readFileSync(configurationPath, 'utf8'));
+    const allCommands = Object.values(configuration.hooks || {})
+        .flat()
+        .flatMap(entry => (entry.hooks ? entry.hooks.map(eachHook => eachHook.command) : [entry.command]));
+    return allCommands.filter(
+        eachCommand => typeof eachCommand === 'string'
+            && eachCommand.includes('session-continuity/continuity.mjs'),
+    ).length;
+}
+
+test('a full install registers the session-continuity companion in every host, and uninstall takes it back out', t => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-continuity-install-'));
+    t.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    const allConfigurationPaths = [
+        join(homeDirectory, '.claude', 'settings.json'),
+        join(homeDirectory, '.codex', 'hooks.json'),
+        join(homeDirectory, '.cursor', 'hooks.json'),
+    ];
+
+    runContinuityInstaller(homeDirectory, []);
+
+    for (const configurationPath of allConfigurationPaths) {
+        assert.equal(
+            continuityCommandCount(configurationPath) > 0,
+            true,
+            `the install registers the companion in ${configurationPath} without a second setup command`,
+        );
+    }
+
+    runContinuityInstaller(homeDirectory, ['--uninstall']);
+
+    for (const configurationPath of allConfigurationPaths) {
+        assert.equal(
+            continuityCommandCount(configurationPath),
+            0,
+            `uninstall leaves no registration in ${configurationPath} pointing at a removed script`,
+        );
+    }
+});

package/package.json

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