claude-dev-env 8.10.0 → 8.11.1

package/bin/codex-skill-load-block.mjs

@@ -0,0 +1,93 @@
+import { lstatSync, mkdirSync, readFileSync, readlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const SKILL_LOAD_BLOCK_START = '<!-- claude-dev-env skill load: start -->';
+export const SKILL_LOAD_BLOCK_END = '<!-- claude-dev-env skill load: end -->';
+export const SKILL_LOAD_INSTRUCTION = 'Load the pstack:poteto-mode skill before your first tool call or reply: '
+    + 'open its SKILL.md from your skills list and follow it. This binds every Codex agent, '
+    + 'including a helper started with spawn_agent, whatever its task message says.';
+export const PACKAGE_GUIDANCE_BLOCK_START = '<!-- claude-dev-env package guidance: start -->';
+export const PACKAGE_GUIDANCE_BLOCK_END = '<!-- claude-dev-env package guidance: end -->';
+
+const WINDOWS_LONG_PATH_PREFIX = '\\\\?\\';
+
+function managedBlock(blockStart, blockBody, blockEnd) {
+    const terminatedBody = blockBody.endsWith('\n') ? blockBody : `${blockBody}\n`;
+    return `${blockStart}\n${terminatedBody}${blockEnd}\n`;
+}
+
+function withBlockReplaced(guidanceText, blockStart, blockEnd, block) {
+    const startIndex = guidanceText.indexOf(blockStart);
+    const endIndex = startIndex === -1 ? -1 : guidanceText.indexOf(blockEnd, startIndex);
+    if (endIndex === -1) return null;
+    let afterBlockIndex = endIndex + blockEnd.length;
+    if (guidanceText[afterBlockIndex] === '\n') afterBlockIndex += 1;
+    return guidanceText.slice(0, startIndex) + block + guidanceText.slice(afterBlockIndex);
+}
+
+/**
+ * Return the Codex guidance text with the package's skill-load block in it.
+ *
+ * Codex starts a spawn_agent helper without running any hook, so the global
+ * AGENTS.md is the one channel that reaches every helper. A block already in
+ * the text is replaced where it stands; otherwise the block goes first.
+ */
+export function withSkillLoadBlock(guidanceText) {
+    const block = managedBlock(SKILL_LOAD_BLOCK_START, SKILL_LOAD_INSTRUCTION, SKILL_LOAD_BLOCK_END);
+    const replacedText = withBlockReplaced(guidanceText, SKILL_LOAD_BLOCK_START, SKILL_LOAD_BLOCK_END, block);
+    if (replacedText !== null) return replacedText;
+    return guidanceText ? `${block}\n${guidanceText}` : block;
+}
+
+function withPackageGuidanceBlock(guidanceText, packageGuidanceText) {
+    const block = managedBlock(PACKAGE_GUIDANCE_BLOCK_START, packageGuidanceText, PACKAGE_GUIDANCE_BLOCK_END);
+    const replacedText = withBlockReplaced(
+        guidanceText,
+        PACKAGE_GUIDANCE_BLOCK_START,
+        PACKAGE_GUIDANCE_BLOCK_END,
+        block,
+    );
+    return replacedText ?? `${guidanceText}\n${block}`;
+}
+
+function comparablePath(filePath) {
+    const withoutPrefix = filePath.startsWith(WINDOWS_LONG_PATH_PREFIX)
+        ? filePath.slice(WINDOWS_LONG_PATH_PREFIX.length)
+        : filePath;
+    const resolvedPath = resolve(withoutPrefix);
+    return process.platform === 'win32' ? resolvedPath.toLowerCase() : resolvedPath;
+}
+
+function linksToPackageGuidance(agentsPath, allPackageGuidancePaths) {
+    const linkTarget = comparablePath(resolve(dirname(agentsPath), readlinkSync(agentsPath)));
+    return allPackageGuidancePaths.some(eachPath => comparablePath(eachPath) === linkTarget);
+}
+
+/**
+ * Keep CODEX_HOME/AGENTS.md carrying the skill-load block.
+ *
+ * A symbolic link that points at the package guidance (the shared agents-home
+ * copy, or the retired copy under the Claude home) is replaced by a regular
+ * file holding the skill-load block and a package-guidance block, so Codex
+ * keeps both after the package moves its guidance. A file that already holds
+ * the package-guidance block gets the current guidance text. A link to any
+ * other file is left alone.
+ *
+ * Returns the file path when the file changed, and null otherwise.
+ */
+export function writeCodexAgentsGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths) {
+    const agentsPath = join(codexHome, 'AGENTS.md');
+    const agentsEntry = lstatSync(agentsPath, { throwIfNoEntry: false });
+    const isPackageGuidanceLink = agentsEntry?.isSymbolicLink() ?? false;
+    if (isPackageGuidanceLink && !linksToPackageGuidance(agentsPath, allPackageGuidancePaths)) return null;
+    const currentText = agentsEntry && !isPackageGuidanceLink ? readFileSync(agentsPath, 'utf8') : '';
+    let updatedText = withSkillLoadBlock(currentText);
+    if (isPackageGuidanceLink || updatedText.includes(PACKAGE_GUIDANCE_BLOCK_START)) {
+        updatedText = withPackageGuidanceBlock(updatedText, packageGuidanceText);
+    }
+    if (!isPackageGuidanceLink && updatedText === currentText) return null;
+    mkdirSync(codexHome, { recursive: true });
+    if (isPackageGuidanceLink) unlinkSync(agentsPath);
+    writeFileSync(agentsPath, updatedText, 'utf8');
+    return agentsPath;
+}

package/bin/codex-skill-load-block.test.mjs

@@ -0,0 +1,134 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { lstatSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+    PACKAGE_GUIDANCE_BLOCK_END,
+    PACKAGE_GUIDANCE_BLOCK_START,
+    SKILL_LOAD_BLOCK_END,
+    SKILL_LOAD_BLOCK_START,
+    SKILL_LOAD_INSTRUCTION,
+    withSkillLoadBlock,
+    writeCodexAgentsGuidance,
+} from './codex-skill-load-block.mjs';
+
+const EXPECTED_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n${SKILL_LOAD_BLOCK_END}\n`;
+const PACKAGE_GUIDANCE = 'Status\n\nChanged / proof / blocked.\n';
+
+function guidanceBlock(guidanceText) {
+    return `${PACKAGE_GUIDANCE_BLOCK_START}\n${guidanceText}${PACKAGE_GUIDANCE_BLOCK_END}\n`;
+}
+
+function makeHomes(context) {
+    const root = mkdtempSync(join(tmpdir(), 'cde-skill-load-'));
+    context.after(() => rmSync(root, { recursive: true, force: true }));
+    const codexHome = join(root, '.codex');
+    const retiredGuidancePath = join(root, '.claude', 'AGENTS.md');
+    const sharedGuidancePath = join(root, '.agents', 'AGENTS.md');
+    return {
+        root,
+        codexHome,
+        agentsPath: join(codexHome, 'AGENTS.md'),
+        retiredGuidancePath,
+        sharedGuidancePath,
+        allPackageGuidancePaths: [retiredGuidancePath, sharedGuidancePath],
+    };
+}
+
+function writeGuidance(homes) {
+    return writeCodexAgentsGuidance(homes.codexHome, PACKAGE_GUIDANCE, homes.allPackageGuidancePaths);
+}
+
+test('the instruction names the skill and binds spawned helpers', () => {
+    assert.match(SKILL_LOAD_INSTRUCTION, /pstack:poteto-mode/);
+    assert.match(SKILL_LOAD_INSTRUCTION, /spawn_agent/);
+});
+
+test('a missing Codex guidance file is created holding only the skill-load block', (context) => {
+    const homes = makeHomes(context);
+
+    const writtenPath = writeGuidance(homes);
+
+    assert.equal(writtenPath, homes.agentsPath);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), EXPECTED_BLOCK);
+});
+
+test('existing guidance keeps every line and gains the skill-load block first', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, '# pstack model configuration\n\nbug-fix: gpt-6-astra\n');
+
+    writeGuidance(homes);
+
+    assert.equal(
+        readFileSync(homes.agentsPath, 'utf8'),
+        `${EXPECTED_BLOCK}\n# pstack model configuration\n\nbug-fix: gpt-6-astra\n`,
+    );
+});
+
+test('a repeat install leaves the file unchanged and reports no write', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, 'Custom agents\n');
+    writeGuidance(homes);
+    const afterFirstInstall = readFileSync(homes.agentsPath, 'utf8');
+
+    assert.equal(writeGuidance(homes), null);
+    assert.equal(readFileSync(homes.agentsPath, 'utf8'), afterFirstInstall);
+});
+
+test('an outdated block is replaced in place and the text around it is kept', () => {
+    const outdated = `Intro\n${SKILL_LOAD_BLOCK_START}\nOld wording\n${SKILL_LOAD_BLOCK_END}\nOutro\n`;
+
+    assert.equal(withSkillLoadBlock(outdated), `Intro\n${EXPECTED_BLOCK}Outro\n`);
+});
+
+test('a start marker with no end marker gets a fresh block and keeps the stray text', () => {
+    const broken = `${SKILL_LOAD_BLOCK_START}\nHalf a block\n`;
+
+    assert.equal(withSkillLoadBlock(broken), `${EXPECTED_BLOCK}\n${broken}`);
+});
+
+for (const linkName of ['retiredGuidancePath', 'sharedGuidancePath']) {
+    test(`a link to package guidance at ${linkName} becomes a file with both blocks`, (context) => {
+        const homes = makeHomes(context);
+        mkdirSync(homes.codexHome);
+        symlinkSync(homes[linkName], homes.agentsPath);
+
+        const writtenPath = writeGuidance(homes);
+
+        assert.equal(writtenPath, homes.agentsPath);
+        assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), false);
+        assert.equal(
+            readFileSync(homes.agentsPath, 'utf8'),
+            `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
+        );
+    });
+}
+
+test('a converted file takes the new package guidance on the next install', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, `${EXPECTED_BLOCK}\n${guidanceBlock('Old guidance\n')}`);
+
+    writeGuidance(homes);
+
+    assert.equal(
+        readFileSync(homes.agentsPath, 'utf8'),
+        `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
+    );
+});
+
+test('a link to a file the package does not own is left alone', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    const ownGuidancePath = join(homes.root, 'notes', 'codex.md');
+    mkdirSync(join(homes.root, 'notes'));
+    writeFileSync(ownGuidancePath, 'My own Codex notes\n');
+    symlinkSync(ownGuidancePath, homes.agentsPath);
+
+    assert.equal(writeGuidance(homes), null);
+    assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), true);
+    assert.equal(readFileSync(ownGuidancePath, 'utf8'), 'My own Codex notes\n');
+});

package/bin/install.agents-home.test.mjs

@@ -18,7 +18,7 @@ import {
     writeFileSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CONTENT_DIRECTORIES } from './install.mjs';
 import {
@@ -209,6 +209,81 @@ test('a full install writes skills and agents under .agents and points .claude a
     }
 });
 
+/**
+ * @param {string} hubPath
+ * @returns {string}
+ */
+function resolveHubImportTarget(hubPath) {
+    const hubText = readFileSync(hubPath, 'utf8').trim();
+    assert.match(hubText, /^@\S+$/, 'the Claude hub holds one import line');
+    return resolve(dirname(hubPath), hubText.slice(1));
+}
+
+for (const eachLayout of [
+    { label: 'default home', extraArguments: [], claudeHomeName: '.claude', agentsHomeName: '.agents' },
+    {
+        label: 'profile root',
+        extraArguments: ['--target', '.claude-profile-a'],
+        claudeHomeName: '.claude-profile-a',
+        agentsHomeName: '.claude-profile-a.agents',
+    },
+]) {
+    test(`a ${eachLayout.label} install loads the package guidance from the agents home through the Claude hub`, () => {
+        const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-hub-'));
+        const claudeHome = join(homeDirectory, eachLayout.claudeHomeName);
+        const sharedGuidancePath = join(homeDirectory, eachLayout.agentsHomeName, 'AGENTS.md');
+        try {
+            runInstaller(homeDirectory, eachLayout.extraArguments.map(
+                (eachArgument) => (eachArgument.startsWith('.') ? join(homeDirectory, eachArgument) : eachArgument),
+            ));
+
+            assert.equal(
+                readFileSync(sharedGuidancePath, 'utf8'),
+                readFileSync(join(PACKAGE_DIRECTORY, 'AGENTS.md'), 'utf8'),
+                'the package guidance lives once in the agents home',
+            );
+            assert.equal(
+                resolveHubImportTarget(join(claudeHome, 'CLAUDE.md')),
+                sharedGuidancePath,
+                'the Claude hub import resolves to the shared guidance file',
+            );
+            assert.equal(
+                existsSync(join(claudeHome, 'AGENTS.md')),
+                false,
+                'no second guidance copy lands in the Claude home',
+            );
+        } finally {
+            rmSync(homeDirectory, { recursive: true, force: true });
+        }
+    });
+}
+
+test('an upgrade moves the guidance copy an earlier install left in the Claude home into the run backup', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-hub-upgrade-'));
+    const claudeHome = join(homeDirectory, '.claude');
+    const retiredGuidancePath = join(claudeHome, 'AGENTS.md');
+    const retiredGuidanceText = 'guidance an earlier install copied here\n';
+    try {
+        runInstaller(homeDirectory, []);
+        writeFileSync(retiredGuidancePath, retiredGuidanceText);
+        const manifestPath = join(claudeHome, '.claude-dev-env-manifest.json');
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        manifest.files.push(retiredGuidancePath);
+        writeFileSync(manifestPath, JSON.stringify(manifest));
+
+        runInstaller(homeDirectory, []);
+
+        assert.equal(existsSync(retiredGuidancePath), false, 'the old Claude-home copy is gone');
+        const backupRoot = join(claudeHome, '.claude-dev-env-pruned');
+        const backupName = readdirSync(backupRoot, { recursive: true })
+            .find(name => name.endsWith('AGENTS.md'));
+        assert.ok(backupName, 'the old copy sits in the run backup');
+        assert.equal(readFileSync(join(backupRoot, backupName), 'utf8'), retiredGuidanceText);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
 test('installs omit retired agents in each active agents home', () => {
     const runRoot = mkdtempSync(join(tmpdir(), 'cdev-active-roots-'));
     const homeDirectory = join(runRoot, 'home');

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, copyFileSync, unlinkSync, rmSync, rmdirSync, renameSync, realpathSync, lstatSync, constants as filesystemConstants } from 'node:fs';
-import { join, dirname, resolve, relative, basename, isAbsolute, extname } from 'node:path';
+import { join, dirname, resolve, relative, basename, isAbsolute, extname, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync, execFileSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -44,6 +44,8 @@ import {
     installPstackPlugin,
     shouldInstallPstackPlugin,
 } from './install-pstack-plugin.mjs';
+import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
+import { writeCodexAgentsGuidance } from './codex-skill-load-block.mjs';
 import {
     continuityHostConfigurationPaths,
     removeContinuityHooks,
@@ -1173,11 +1175,9 @@ export function copyTree(sourceBase, destBase, options = {}) {
  * @param {string} backupName The managed file name used in the backup path.
  * @returns {string|null} The backup path when existing content differs.
  */
-function backupHubBeforeOverwrite(destPath, incomingPath, backupName) {
+function backupHubBeforeOverwrite(destPath, incomingText, backupName) {
     if (!existsSync(destPath)) return null;
-    const existingBytes = readFileSync(destPath);
-    const incomingBytes = readFileSync(incomingPath);
-    if (existingBytes.equals(incomingBytes)) return null;
+    if (readFileSync(destPath, 'utf8') === incomingText) return null;
     const backupsDir = join(CLAUDE_HOME, 'backups');
     mkdirSync(backupsDir, { recursive: true });
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
@@ -2371,6 +2371,15 @@ function pruneStaleFilesAcrossManagedRoots(priorInstalledFiles, currentInstalled
             skillsPrunedCount += rootOutcome.prunedCount;
         }
     }
+    const retiredClaudeGuidancePath = join(CLAUDE_HOME, 'AGENTS.md');
+    const retiredGuidanceOutcome = pruneStaleInstalledFiles(
+        priorInstalledFiles?.filter(priorFile => resolve(priorFile) === retiredClaudeGuidancePath) ?? null,
+        currentInstalledFiles,
+        CLAUDE_HOME,
+        backupRoot,
+    );
+    prunedCount += retiredGuidanceOutcome.prunedCount;
+    failedPaths.push(...retiredGuidanceOutcome.failedPaths);
     return { prunedCount, skillsPrunedCount, failedPaths };
 }
 
@@ -2769,6 +2778,25 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     if (!selectedGroups && shouldInstallPstackPlugin()) {
         const pstackPlugin = installPstackPluginForHosts();
         summary.pstackPlugin = pstackPlugin;
+        if (pstackPlugin.hosts.some(host => host.host === 'codex' && host.status === 'installed')) {
+            summary.codexPstackModels = seedCodexPstackModels(
+                INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
+            );
+            if (summary.codexPstackModels) {
+                allInstalledFiles.push(...summary.codexPstackModels);
+                for (const eachPath of summary.codexPstackModels) {
+                    allUserOwnedPreferencePaths.add(eachPath);
+                }
+            }
+            const skillLoadGuidancePath = writeCodexAgentsGuidance(
+                INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
+                readFileSync(join(PACKAGE_ROOT, 'AGENTS.md'), 'utf8'),
+                [join(CLAUDE_HOME, 'AGENTS.md'), join(AGENTS_HOME, 'AGENTS.md')],
+            );
+            if (skillLoadGuidancePath) {
+                console.log(`  \u2713 ${skillLoadGuidancePath} (Codex skill-load line)`);
+            }
+        }
         for (const eachHost of pstackPlugin.hosts) {
             console.log(eachHost.warning
                 ? `  Pstack (${eachHost.host}): ${eachHost.status} \u2014 ${eachHost.warning}`
@@ -2877,31 +2905,27 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         );
     }
 
-    const claudeHubSource = join(PACKAGE_ROOT, '.claude', 'CLAUDE.md');
-    if (existsSync(claudeHubSource)) {
-        const claudeHubDest = join(CLAUDE_HOME, 'CLAUDE.md');
-        const backupPath = backupHubBeforeOverwrite(claudeHubDest, claudeHubSource, 'CLAUDE.md');
-        if (backupPath) {
-            console.log(
-                `  \u21bb ${relative(CLAUDE_HOME, backupPath)} (previous CLAUDE.md hub preserved)`
-            );
-        }
-        copyFileSync(claudeHubSource, claudeHubDest);
-        allInstalledFiles.push(claudeHubDest);
-        console.log(`  \u2713 ${relative(CLAUDE_HOME, claudeHubDest)} (hub)`);
-    }
     const agentsHubSource = join(PACKAGE_ROOT, 'AGENTS.md');
     if (existsSync(agentsHubSource)) {
-        const agentsHubDest = join(CLAUDE_HOME, 'AGENTS.md');
-        const backupPath = backupHubBeforeOverwrite(agentsHubDest, agentsHubSource, 'AGENTS.md');
-        if (backupPath) {
-            console.log(
-                `  \u21bb ${relative(CLAUDE_HOME, backupPath)} (previous AGENTS.md guidance preserved)`
-            );
+        const agentsHubDest = join(AGENTS_HOME, 'AGENTS.md');
+        const claudeHubDest = join(CLAUDE_HOME, 'CLAUDE.md');
+        const claudeHubText = `@${relative(CLAUDE_HOME, agentsHubDest).split(sep).join('/')}\n`;
+        const allHubWrites = [
+            { destPath: agentsHubDest, text: readFileSync(agentsHubSource, 'utf8'), label: 'AGENTS.md', role: 'shared guidance' },
+            { destPath: claudeHubDest, text: claudeHubText, label: 'CLAUDE.md', role: 'hub' },
+        ];
+        mkdirSync(AGENTS_HOME, { recursive: true });
+        for (const eachHubWrite of allHubWrites) {
+            const backupPath = backupHubBeforeOverwrite(eachHubWrite.destPath, eachHubWrite.text, eachHubWrite.label);
+            if (backupPath) {
+                console.log(
+                    `  \u21bb ${relative(CLAUDE_HOME, backupPath)} (previous ${eachHubWrite.label} preserved)`
+                );
+            }
+            writeFileSync(eachHubWrite.destPath, eachHubWrite.text);
+            allInstalledFiles.push(eachHubWrite.destPath);
+            console.log(`  \u2713 ${eachHubWrite.destPath} (${eachHubWrite.role})`);
         }
-        copyFileSync(agentsHubSource, agentsHubDest);
-        allInstalledFiles.push(agentsHubDest);
-        console.log(`  \u2713 ${relative(CLAUDE_HOME, agentsHubDest)} (canonical guidance)`);
     }
     const isFullInstall = !selectedGroups;
     const didPruneRun = isFullInstall && UNRESOLVED_DEPENDENCY_NAMES.length === 0;
@@ -3322,10 +3346,10 @@ Profile selection (--profile/--profiles) is mutually exclusive with --target.
 Target selection finishes before any mutation. Each target writes its own manifest
 with package, version, targetIdentity, managedRoot, files, and skills.
 
-If ~/.claude/CLAUDE.md already exists and differs from the package copy, the installer
-writes the previous contents to ~/.claude/backups/CLAUDE.md.<timestamp>.bak first.
-If ~/.claude/AGENTS.md already exists and differs from the package copy, the installer
-writes the previous contents to ~/.claude/backups/AGENTS.md.<timestamp>.bak first.
+The package guidance lands once at ~/.agents/AGENTS.md, and ~/.claude/CLAUDE.md
+holds one import line that loads it. If either file already exists with other
+contents, the installer writes the previous contents to
+~/.claude/backups/<name>.<timestamp>.bak first.
 `);
 }
 

package/bin/install.test.mjs

@@ -11,6 +11,7 @@ import {
     readdirSync,
     existsSync,
     copyFileSync,
+    lstatSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
@@ -52,6 +53,11 @@ import {
     retainNewestRunBackupOnly,
 } from './install.mjs';
 import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
+import {
+    SKILL_LOAD_BLOCK_START,
+    SKILL_LOAD_INSTRUCTION,
+    withSkillLoadBlock,
+} from './codex-skill-load-block.mjs';
 
 
 test('installer reports the authoritative Git hook names', () => {
@@ -3064,6 +3070,53 @@ test('a full install adds the pstack marketplace and plugin on both hosts', t =>
     ]);
     assert.match(installerOutput, /Pstack \(claude\): installed/);
     assert.match(installerOutput, /Pstack \(codex\): installed/);
+    const codexHome = join(sandbox.homeDirectory, '.codex');
+    const sheet = readFileSync(join(codexHome, 'pstack-models.md'), 'utf8');
+    const agents = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
+    assert.match(sheet, /^session hook: on$/m);
+    assert.match(agents, /^feature, refactoring: gpt-6-sol$/m);
+    assert.doesNotMatch(agents, /^session hook:/m);
+    assert.ok(agents.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assert.equal(existsSync(join(sandbox.homeDirectory, '.claude', 'pstack-models.md')), false);
+    const manifestPath = join(sandbox.homeDirectory, '.claude', '.claude-dev-env-manifest.json');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    assert.equal(manifest.files.includes(join(codexHome, 'pstack-models.md')), false);
+    assert.equal(manifest.files.includes(join(codexHome, 'AGENTS.md')), false);
+});
+
+test('a repeat install preserves Codex pstack configuration', t => {
+    const sandbox = pstackPluginSandbox(t);
+    const codexHome = join(sandbox.homeDirectory, '.codex');
+    runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
+    writeFileSync(join(codexHome, 'AGENTS.md'), 'Custom Codex guidance\n');
+    writeFileSync(join(codexHome, 'pstack-models.md'), 'session hook: off\n');
+
+    runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
+
+    assert.equal(
+        readFileSync(join(codexHome, 'AGENTS.md'), 'utf8'),
+        withSkillLoadBlock('Custom Codex guidance\n'),
+    );
+    assert.equal(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), 'session hook: off\n');
+});
+
+test('a Codex guidance link to the retired Claude copy becomes a file Codex can read', t => {
+    const sandbox = pstackPluginSandbox(t);
+    const codexHome = join(sandbox.homeDirectory, '.codex');
+    const codexAgentsPath = join(codexHome, 'AGENTS.md');
+    mkdirSync(codexHome, { recursive: true });
+    symlinkSync(join(sandbox.homeDirectory, '.claude', 'AGENTS.md'), codexAgentsPath);
+
+    runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
+
+    const packageGuidance = readFileSync(
+        join(dirname(fileURLToPath(import.meta.url)), '..', 'AGENTS.md'),
+        'utf8',
+    );
+    assert.equal(lstatSync(codexAgentsPath).isSymbolicLink(), false);
+    const codexGuidance = readFileSync(codexAgentsPath, 'utf8');
+    assert.ok(codexGuidance.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assert.ok(codexGuidance.includes(packageGuidance));
 });
 
 test('an absent host command is reported and leaves the other host installed', t => {
@@ -3085,6 +3138,8 @@ test('an absent host command is reported and leaves the other host installed', t
         sandbox.recordedCommands().filter(eachCommand => eachCommand.startsWith('codex')),
         [],
     );
+    assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'pstack-models.md')), false);
+    assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md')), false);
 });
 
 test('--no-pstack leaves both hosts untouched', t => {
@@ -3096,6 +3151,8 @@ test('--no-pstack leaves both hosts untouched', t => {
 
     assert.deepEqual(sandbox.recordedCommands(), []);
     assert.doesNotMatch(installerOutput, /Pstack \(/);
+    assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'pstack-models.md')), false);
+    assert.equal(existsSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md')), false);
 });
 
 function continuityCommandCount(configurationPath) {

package/bin/install.transaction.test.mjs

@@ -270,13 +270,6 @@ test('runWithInstallTransaction commits and discards journal on success', () =>
     rmSync(box.root, { recursive: true, force: true });
 });
 
-/**
- * Spawn the real installer against a sandbox home with optional fault phase.
- *
- * @param {string} homeDirectory
- * @param {string[]} extraArguments
- * @param {{ faultPhase?: string|null }} [options]
- */
 function runInstaller(homeDirectory, extraArguments, options = {}) {
     const childEnvironment = {
         ...process.env,
@@ -285,6 +278,7 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
         CODEX_HOME: join(homeDirectory, '.codex'),
+        ...options.environment,
     };
     if (options.faultPhase) {
         childEnvironment[INSTALL_FAULT_ENV] = options.faultPhase;
@@ -298,6 +292,34 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
     });
 }
 
+test('a later install fault removes newly seeded Codex pstack files', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-txn-codex-pstack-'));
+    try {
+        const codexCommandPath = join(
+            homeDirectory,
+            process.platform === 'win32' ? 'codex.cmd' : 'codex',
+        );
+        writeFileSync(
+            codexCommandPath,
+            process.platform === 'win32' ? '@echo off\r\nexit /b 0\r\n' : '#!/bin/sh\nexit 0\n',
+            { mode: 0o755 },
+        );
+        const failedRun = runInstaller(homeDirectory, [], {
+            faultPhase: FAULT_PHASES.AFTER_MANIFEST_WRITE,
+            environment: {
+                CDE_INSTALL_PSTACK: '1',
+                CDE_CODEX_EXECUTABLE: codexCommandPath,
+            },
+        });
+        assert.notEqual(failedRun.status, 0, failedRun.stdout + failedRun.stderr);
+        assert.match(`${failedRun.stdout}${failedRun.stderr}`, /after_manifest_write/);
+        assert.equal(existsSync(join(homeDirectory, '.codex', 'pstack-models.md')), false);
+        assert.equal(existsSync(join(homeDirectory, '.codex', 'AGENTS.md')), false);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});
+
 function seedPriorInstall(homeDirectory) {
     const claudeDirectory = join(homeDirectory, '.claude');
     const rulesFile = join(claudeDirectory, 'rules', 'prior.md');

package/bin/seed-codex-pstack-models.mjs

@@ -0,0 +1,27 @@
+import { copyFileSync, lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, constants as filesystemConstants } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CODEX_PRESET_PATH = fileURLToPath(new URL('../pstack-codex-models.md', import.meta.url));
+
+function pathExists(path) {
+    return lstatSync(path, { throwIfNoEntry: false }) !== undefined;
+}
+
+export function seedCodexPstackModels(codexHome, writeAgentGuidance = writeFileSync) {
+    const sheetPath = join(codexHome, 'pstack-models.md');
+    const agentsPath = join(codexHome, 'AGENTS.md');
+    if (pathExists(sheetPath) || pathExists(agentsPath)) return null;
+
+    const preset = readFileSync(CODEX_PRESET_PATH, 'utf8');
+    const agentGuidance = preset.replace(/^session hook: on\n?$/m, '');
+    mkdirSync(codexHome, { recursive: true });
+    copyFileSync(CODEX_PRESET_PATH, sheetPath, filesystemConstants.COPYFILE_EXCL);
+    try {
+        writeAgentGuidance(agentsPath, agentGuidance, { encoding: 'utf8', flag: 'wx' });
+    } catch (writeError) {
+        unlinkSync(sheetPath);
+        throw writeError;
+    }
+    return [sheetPath, agentsPath];
+}