@haposoft/cafekit 0.14.1 → 0.15.0

package/bin/lib/codex-install.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const path = require('path');
+const { splitFrontmatter } = require('./codex-frontmatter');
+
+const CODEX_BLOCK_START = '<!-- CAFEKIT CODEX START -->';
+const CODEX_BLOCK_END = '<!-- CAFEKIT CODEX END -->';
+const INSTRUCTION_EXTENSIONS = new Set(['.md', '.mdx', '.txt']);
+
+const AGENT_NAMES = [
+  'brainstormer',
+  'code-auditor',
+  'debugger',
+  'deployer',
+  'docs-keeper',
+  'git-ops',
+  'god-developer',
+  'inspector',
+  'project-manager',
+  'researcher',
+  'spec-maker',
+  'test-runner',
+  'ui-ux-designer'
+];
+const INSTRUCTION_REPLACEMENTS = [
+  [/`?\bAskUserQuestion\b`?/g, 'a structured user-input request'],
+  [/`?\bTodoWrite\b`?/g, 'task-state tracking'],
+  [/`?\bTaskCreate\b`?/g, 'task creation'],
+  [/`?\bTaskUpdate\b`?/g, 'task-state updates'],
+  [/`?\bTaskList\b`?/g, 'task-state inspection'],
+  [/`?\bTaskGet\b`?/g, 'task detail inspection'],
+  [/`Bash`/g, '`exec_command`'],
+  [/`Glob`/g, '`rg --files`'],
+  [/`Grep`/g, '`rg`'],
+  [/`Read`/g, 'targeted file reads'],
+  [/`Write`|`Edit`|`NotebookEdit`/g, '`apply_patch`'],
+  [/`WebSearch`/g, 'native web search'],
+  [/`WebFetch`/g, 'native page retrieval'],
+  [/`?Agent`?\s+\(legacy\s+`?Task`?\)/g, 'subagent delegation']
+];
+
+function codexAgentName(value) {
+  const raw = path.basename(String(value || ''), path.extname(String(value || '')));
+  return raw
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase();
+}
+
+function normalizeAgentRole(name) {
+  return String(name || '').toLowerCase() === 'explore'
+    ? 'explorer'
+    : codexAgentName(name);
+}
+
+function applyReplacements(content, replacements) {
+  let next = content;
+  for (const [pattern, replacement] of replacements) {
+    next = next.replace(pattern, replacement);
+  }
+  return next;
+}
+
+function normalizeRuntimePaths(content) {
+  return content
+    .replace(/\.claude\/skills\b/g, '.agents/skills')
+    .replace(/\.claude\\skills\b/g, '.agents\\skills')
+    .replace(/\.claude(?=[/\\])/g, '.codex')
+    .replace(/(['"])\.claude\1/g, '$1.codex$1')
+    .replace(/`\.claude`/g, '`.codex`');
+}
+
+function normalizeSkillNames(content) {
+  return content
+    .replace(/\/hapo:([a-z0-9-]+)/gi, (_match, name) => `$hapo-${name}`)
+    .replace(/\bhapo:([a-z0-9-]+)/gi, (_match, name) => `hapo-${name}`)
+    .replace(
+      /(^|[\s("'`→])\/(brainstorm|code-review|debug|develop|docs|frontend-design|git|hotfix|inspect|question|research|specs|test)(?=$|[\s<`),.:])/gim,
+      (_match, prefix, name) => `${prefix}$hapo-${name}`
+    );
+}
+
+function normalizeAgentNames(content) {
+  let next = content;
+  for (const name of AGENT_NAMES) {
+    const snake = codexAgentName(name);
+    next = next.replace(new RegExp(`\\b${name}\\b`, 'g'), snake);
+  }
+  return next;
+}
+
+function normalizeAgentInvocations(content) {
+  return content
+    .replace(/\bAgent\s*\(/g, 'spawn_agent(')
+    .replace(/\bsubagent_type\s*=\s*"([^"]+)"/g, (_match, name) => (
+      `agent_type="${normalizeAgentRole(name)}", fork_turns="none"`
+    ))
+    .replace(/\bsubagent_type\s*:\s*"([^"]+)"/g, (_match, name) => (
+      `agent_type: "${normalizeAgentRole(name)}"\nfork_turns: "none"`
+    ))
+    .replace(/\bprompt\s*=/g, 'message=')
+    .replace(/\bdescription\s*=\s*"([^"]+)"/g, (_match, label) => (
+      `task_name="${codexAgentName(label) || 'cafekit_task'}"`
+    ))
+    .replace(/`Agent`/g, '`spawn_agent`')
+    .replace(/\bAgent tool\b/g, 'spawn_agent tool')
+    .replace(/\bExplore subagents?\b/g, (match) => match.replace('Explore', 'explorer'))
+    .replace(/`SendMessage`/g, '`send_message`')
+    .replace(/\bSendMessage\s*\(/g, 'send_message(');
+}
+
+function isInstructionAsset(sourcePath) {
+  if (!sourcePath) return true;
+  return INSTRUCTION_EXTENSIONS.has(path.extname(sourcePath).toLowerCase());
+}
+
+function normalizeCodexBody(content, sourcePath = '') {
+  let next = normalizeRuntimePaths(String(content));
+  next = next
+    .replace(/\bCLAUDE\.md\b/g, 'AGENTS.md')
+    .replace(/\bClaude Code\b/g, 'Codex CLI');
+
+  if (!isInstructionAsset(sourcePath)) return next;
+
+  next = normalizeAgentInvocations(normalizeAgentNames(normalizeSkillNames(next)));
+  return applyReplacements(next, INSTRUCTION_REPLACEMENTS);
+}
+
+function getCodexCopyOptions(baseOptions = {}) {
+  return {
+    ...baseOptions,
+    transform: (content, sourcePath) => normalizeCodexBody(content, sourcePath)
+  };
+}
+
+function convertCodexAgentContent(content, fileName = '') {
+  const { frontmatter, body } = splitFrontmatter(content);
+  const name = codexAgentName(frontmatter.name || fileName);
+  const description = normalizeCodexBody(
+    frontmatter.description || `CafeKit Codex agent: ${name}`
+  );
+  const instructions = normalizeCodexBody(body).trim();
+
+  return [
+    `name = ${JSON.stringify(name)}`,
+    `description = ${JSON.stringify(description)}`,
+    `developer_instructions = ${JSON.stringify(instructions)}`,
+    ''
+  ].join('\n');
+}
+
+function managedRange(content) {
+  const start = content.indexOf(CODEX_BLOCK_START);
+  const end = content.indexOf(CODEX_BLOCK_END);
+  if (start < 0 && end < 0) return null;
+  const duplicateStart = content.indexOf(CODEX_BLOCK_START, start + CODEX_BLOCK_START.length);
+  const duplicateEnd = content.indexOf(CODEX_BLOCK_END, end + CODEX_BLOCK_END.length);
+  return start >= 0 && end > start && duplicateStart < 0 && duplicateEnd < 0
+    ? { start, end }
+    : false;
+}
+
+function upsertManagedCodexBlock(existingContent, blockContent) {
+  const existing = String(existingContent || '');
+  const block = `${CODEX_BLOCK_START}\n${String(blockContent).trim()}\n${CODEX_BLOCK_END}`;
+  const range = managedRange(existing);
+  if (range === false) return existing;
+  if (range) {
+    return `${existing.slice(0, range.start)}${block}${existing.slice(range.end + CODEX_BLOCK_END.length)}`;
+  }
+  if (!existing) return `${block}\n`;
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${separator}${block}\n`;
+}
+
+/** Transform only the CafeKit-owned body, preserving all surrounding bytes. */
+function transformManagedCodexContent(content, transform) {
+  const existing = String(content || '');
+  const range = managedRange(existing);
+  if (!range || typeof transform !== 'function') return existing;
+  const bodyStart = range.start + CODEX_BLOCK_START.length;
+  const bodyEnd = range.end;
+  const body = existing.slice(bodyStart, bodyEnd);
+  return `${existing.slice(0, bodyStart)}${transform(body)}${existing.slice(bodyEnd)}`;
+}
+
+module.exports = {
+  normalizeCodexBody,
+  getCodexCopyOptions,
+  codexAgentName,
+  convertCodexAgentContent,
+  upsertManagedCodexBlock,
+  transformManagedCodexContent
+};

package/bin/lib/context.js

@@ -56,11 +56,13 @@ function loadClaudeMigrationManifest() {
 const DEPENDENCY_TEMPLATES = {
   commands: {
     claude: {},
-    opencode: {}
+    opencode: {},
+    codex: {}
   },
   agents: {
     claude: {},
-    opencode: {}
+    opencode: {},
+    codex: {}
   }
 };
 
@@ -79,7 +81,16 @@ const PLATFORMS = {
     skillsRef: '.claude/skills',
     commandPrefix: '/',
     sourceDir: 'claude',       // Maps to src/claude/
-    sourceSubdir: 'commands'   // Source subfolder within src/claude/
+    sourceSubdir: 'commands',  // Source subfolder within src/claude/
+    backupTargets: ['.claude', 'CLAUDE.md'],
+    capabilities: {
+      skills: true,
+      agents: true,
+      references: true,
+      scripts: true,
+      rules: true,
+      commands: true
+    }
   },
   opencode: {
     id: 'opencode',
@@ -93,7 +104,43 @@ const PLATFORMS = {
     skillsRef: '.opencode/skills',
     commandPrefix: '/',
     sourceDir: 'claude',
-    sourceSubdir: 'archive-command'
+    sourceSubdir: 'commands',  // Dead config (manifest commands.core is []); kept for shape parity
+    backupTargets: ['.opencode', 'AGENTS.md', 'opencode.json', 'opencode.jsonc'],
+    capabilities: {
+      skills: true,
+      agents: true,
+      references: true,
+      scripts: true,
+      rules: true,
+      commands: false
+    }
+  },
+  codex: {
+    id: 'codex',
+    name: 'Codex CLI',
+    description: 'OpenAI Codex CLI',
+    folder: '.codex',
+    detectFiles: ['.codex'],
+    commandsDir: null,
+    skillsDir: '.agents/skills',
+    agentsDir: '.codex/agents',
+    skillsRef: '.agents/skills',
+    commandPrefix: '$',
+    sourceDir: 'claude',
+    sourceSubdir: null,
+    backupTargets: ['.codex', '.agents', 'AGENTS.md'],
+    ownership: {
+      recordRoot: '.',
+      allowedRoots: ['.codex', '.agents']
+    },
+    capabilities: {
+      skills: true,
+      agents: true,
+      references: true,
+      scripts: true,
+      rules: true,
+      commands: false
+    }
   }
   // Add new platforms here:
   // cursor: {
@@ -136,8 +183,8 @@ function getPlatformKeys() {
   return Object.keys(PLATFORMS);
 }
 
-function isClaudeCompatibleRuntime(platformKey) {
-  return platformKey === 'claude' || platformKey === 'opencode';
+function hasPlatformCapability(platformKey, capability) {
+  return Boolean(PLATFORMS[platformKey]?.capabilities?.[capability]);
 }
 
 function getRuntimeSupportTargetDir(platformKey, subdir) {
@@ -164,6 +211,11 @@ function getCopyOptions(platformKey, baseOptions = {}) {
   if (platformKey === 'opencode') {
     return getOpenCodeCopyOptions(baseOptions);
   }
+  if (platformKey === 'codex') {
+    // Lazy require avoids coupling the shared registry to a runtime adapter
+    // during module initialization.
+    return require('./codex-install').getCodexCopyOptions(baseOptions);
+  }
   return baseOptions;
 }
 
@@ -186,7 +238,8 @@ function parseInstallerArgs(argv) {
     dryRun: false,
     yes: false,
     withSkillsDeps: false,
-    withRtk: false
+    withRtk: false,
+    platforms: []
   };
 
   for (let i = 2; i < argv.length; i++) {
@@ -202,6 +255,10 @@ function parseInstallerArgs(argv) {
       args.withSkillsDeps = true;
     } else if (arg === '--with-rtk') {
       args.withRtk = true;
+    } else if (arg === '--platform') {
+      args.platforms.push(...String(argv[++i] || '').split(',').filter(Boolean));
+    } else if (arg.startsWith('--platform=')) {
+      args.platforms.push(...arg.slice('--platform='.length).split(',').filter(Boolean));
     } else if (arg === '--lang') {
       args.lang = argv[++i];
     } else if (arg.startsWith('--lang=')) {
@@ -288,7 +345,7 @@ module.exports = {
   detectPlatforms,
   formatPlatformList,
   getPlatformKeys,
-  isClaudeCompatibleRuntime,
+  hasPlatformCapability,
   getRuntimeSupportTargetDir,
   warnLegacyClaudeFolder,
   getCopyOptions,

package/bin/lib/copy-utils.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 
 const TEXT_REWRITE_EXTENSIONS = new Set([
-  '.md', '.mdx', '.txt', '.json', '.cjs', '.js', '.mjs', '.ts', '.sh', '.yml', '.yaml'
+  '.md', '.mdx', '.txt', '.json', '.cjs', '.js', '.mjs', '.ts', '.py', '.sh', '.toml', '.yml', '.yaml'
 ]);
 
 function isTextAsset(filePath) {

package/bin/lib/i18n.js

@@ -38,7 +38,7 @@ const MESSAGES = {
     modeInstall:  'Mode: install / update  •  your customisations are preserved',
 
     // Intro
-    introDesc:    'AI-native development workflow for Claude Code',
+    introDesc:    'AI-native development workflow',
 
     // Platform install spinner
     installingPlatform:    'Installing {name}',
@@ -108,6 +108,7 @@ const MESSAGES = {
     nextStepsTitle:  'Next steps',
     nsClaude:        'Start coding: /hapo:specs <feature>',
     nsOpencode:      'Start coding: ask the agent to begin a new feature or brainstorm',
+    nsCodex:         'Start with `$hapo-specs <feature>`; review and trust project hooks with `/hooks`',
     nsKeys:          'Some skills need API keys: {skills}\n  Copy <skill>/.env.example → .env and fill in the values',
     nsForce:         'To force-refresh managed files: npx @haposoft/cafekit --force-overwrite',
     dryRunOnly:      'Dry-run complete — no files were changed.\n  Re-run without --dry-run to apply.',
@@ -115,11 +116,13 @@ const MESSAGES = {
 
     // Version check
     versionUpToDate:      'Already up to date ({v}). Use --force-overwrite to reinstall.',
+    versionRefreshing:    'Refreshing CafeKit {v}; your modified files will be preserved.',
     versionDowngrade:     'Downgrading {from} → {to}. Features may be removed. Continue?',
     versionSamePrompt:    'CafeKit {v} is already installed. What would you like to do?',
     versionForceReinstall: 'Reinstalling CafeKit {v} (--force-overwrite)...',
     versionUpgradePrompt: 'CafeKit {from} → {to}: Update available!',
     updateOption:         'Update to {v}',
+    refreshOption:        'Refresh managed files (preserve your edits)',
     reinstallOption:      'Reinstall (overwrite managed files)',
     reinstallCurrentOption: 'Reinstall {v}',
     skipOption:           'Skip (exit)',
@@ -158,7 +161,7 @@ const MESSAGES = {
     modeInstall:  'モード: インストール / 更新  •  カスタマイズは保持されます',
 
     // Intro
-    introDesc:    'Claude Code 向け AI ネイティブ開発ワークフロー',
+    introDesc:    'AI ネイティブ開発ワークフロー',
 
     installingPlatform:    '{name} をインストール中',
     platformInstalled:     '{name} — {files} ファイル、{skills} スキル',
@@ -223,17 +226,20 @@ const MESSAGES = {
     nextStepsTitle:  '次のステップ',
     nsClaude:        'コーディング開始: /hapo:specs <機能名>',
     nsOpencode:      'コーディング開始: エージェントに新機能の開始またはブレストを依頼',
+    nsCodex:         '`$hapo-specs <機能名>` で開始し、`/hooks` でプロジェクトフックを確認・信頼',
     nsKeys:          '一部のスキルに API キーが必要です: {skills}\n  <skill>/.env.example を .env にコピーし、値を入力してください',
     nsForce:         '管理ファイルを強制更新: npx @haposoft/cafekit --force-overwrite',
     dryRunOnly:      'ドライラン完了 — ファイルへの変更はありませんでした。\n  変更を適用するには --dry-run なしで再実行してください。',
     outroDone:       '完了！  ドキュメント: https://github.com/haposoft/cafekit',
 
     versionUpToDate:      '最新バージョンです（{v}）。再インストールするには --force-overwrite を使用してください。',
+    versionRefreshing:    'CafeKit {v} を更新します。編集済みファイルは保持されます。',
     versionDowngrade:     '{from} → {to} へのダウングレードです。機能が削除される可能性があります。続けますか？',
     versionSamePrompt:    'CafeKit {v} は既にインストールされています。何をしますか？',
     versionForceReinstall: 'CafeKit {v} を再インストール中 (--force-overwrite)...',
     versionUpgradePrompt: 'CafeKit {from} → {to}: アップデートが利用可能です！',
     updateOption:         '{v} にアップデート',
+    refreshOption:        '管理対象ファイルを更新（編集内容を保持）',
     reinstallOption:      '再インストール（管理対象ファイルを上書き）',
     reinstallCurrentOption: '{v} を再インストール',
     skipOption:           'スキップ（終了）',
@@ -272,7 +278,7 @@ const MESSAGES = {
     modeInstall:  'Chế độ: cài / cập nhật  •  nội dung bạn tuỳ chỉnh được giữ nguyên',
 
     // Intro
-    introDesc:    'Quy trình phát triển AI-native cho Claude Code',
+    introDesc:    'Quy trình phát triển AI-native',
 
     installingPlatform:    'Đang cài {name}',
     platformInstalled:     '{name} — {files} tệp, {skills} skill',
@@ -337,17 +343,20 @@ const MESSAGES = {
     nextStepsTitle:  'Bước tiếp theo',
     nsClaude:        'Bắt đầu code: /hapo:specs <mô-tả-tính-năng>',
     nsOpencode:      'Bắt đầu code: yêu cầu agent khởi động tính năng mới hoặc brainstorm',
+    nsCodex:         'Bắt đầu bằng `$hapo-specs <tính-năng>`; kiểm tra và trust project hooks bằng `/hooks`',
     nsKeys:          'Một số skill cần API key: {skills}\n  Sao chép <skill>/.env.example → .env rồi điền giá trị',
     nsForce:         'Làm mới file được quản lý: npx @haposoft/cafekit --force-overwrite',
     dryRunOnly:      'Dry-run hoàn tất — không có tệp nào thay đổi.\n  Chạy lại không có --dry-run để áp dụng.',
     outroDone:       'Xong!  Tài liệu: https://github.com/haposoft/cafekit',
 
     versionUpToDate:      'Đã là phiên bản mới nhất ({v}). Dùng --force-overwrite để cài lại.',
+    versionRefreshing:    'Đang làm mới CafeKit {v}; các tệp bạn đã sửa sẽ được giữ nguyên.',
     versionDowngrade:     'Đang hạ cấp {from} → {to}. Một số tính năng có thể bị xoá. Tiếp tục?',
     versionSamePrompt:    'CafeKit {v} đã được cài đặt. Bạn muốn làm gì?',
     versionForceReinstall: 'Đang cài lại CafeKit {v} (--force-overwrite)...',
     versionUpgradePrompt: 'CafeKit {from} → {to}: Có bản cập nhật mới!',
     updateOption:         'Cập nhật lên {v}',
+    refreshOption:        'Làm mới file được quản lý (giữ phần bạn đã sửa)',
     reinstallOption:      'Cài lại (ghi đè file được quản lý)',
     reinstallCurrentOption: 'Cài lại {v}',
     skipOption:           'Bỏ qua (thoát)',

package/bin/lib/managed-writer.js

@@ -22,6 +22,7 @@ const fs = require('fs');
 const path = require('path');
 const { isTextAsset } = require('./copy-utils');
 const manifest = require('./manifest');
+const { assertNoSymlinkPath } = require('./path-safety');
 
 /**
  * Resolve the payload bytes for a source file, applying a text transform when
@@ -47,6 +48,7 @@ function writeManagedFile(opts) {
   if (!fs.existsSync(src)) {
     return { action: 'missing', state: 'absent' };
   }
+  assertNoSymlinkPath(dest);
 
   const { data, utf8 } = readPayload(src, transform);
   const payloadHash = manifest.sha256(data);
@@ -56,7 +58,9 @@ function writeManagedFile(opts) {
   // A file already written earlier THIS run (e.g. a spec template copied as part
   // of the specs/ tree, then revisited by the template-sync loop) is ours — treat
   // it as pristine against what we just wrote, not as a user-created file.
-  const relForRun = path.relative(platformFolder, dest).replace(/\\/g, '/');
+  const relForRun = tracker?.keyFor
+    ? tracker.keyFor(dest)
+    : path.relative(platformFolder, dest).replace(/\\/g, '/');
   const writtenThisRun = tracker ? tracker.recorded(relForRun) : null;
 
   let cls;
@@ -68,7 +72,13 @@ function writeManagedFile(opts) {
       changed: writtenThisRun !== payloadHash
     };
   } else {
-    cls = manifest.classify(dest, platformFolder, ownership, payloadHash);
+    cls = manifest.classify(
+      dest,
+      platformFolder,
+      ownership,
+      payloadHash,
+      tracker?.recordRoot || platformFolder
+    );
   }
   const forced = Boolean(ctx.options.forceOverwrite);
 
@@ -102,6 +112,11 @@ function writeManagedFile(opts) {
     } else {
       fs.writeFileSync(dest, data);
     }
+    if (process.platform !== 'win32') {
+      const sourceMode = fs.statSync(src).mode;
+      const destinationMode = fs.statSync(dest).mode;
+      fs.chmodSync(dest, (destinationMode & ~0o111) | (sourceMode & 0o111));
+    }
   }
 
   // Record created/updated/unchanged files so the manifest reflects reality.

package/bin/lib/manifest.js

@@ -17,6 +17,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { assertNoSymlinkPath, isInside } = require('./path-safety');
 
 const MANIFEST_FILE = 'cafekit-manifest.json';
 const SCHEMA_VERSION = 1;
@@ -75,10 +76,26 @@ function read(platformFolder) {
  * writes them back as the new baseline. relPath keys are normalized to forward
  * slashes and are relative to the platform folder.
  */
-function createTracker(platformFolder, version) {
+function createTracker(platformFolder, version, options = {}) {
   const files = {};
+  const recordRoot = path.resolve(options.recordRoot || platformFolder);
+  const allowedRoots = (options.allowedRoots || [options.recordRoot || platformFolder])
+    .map((root) => path.resolve(root));
+
+  function keyFor(filePath) {
+    const target = path.resolve(filePath);
+    if (!allowedRoots.some((root) => isInside(root, target))) {
+      throw new Error(`Managed file is outside allowed roots: ${filePath}`);
+    }
+    assertNoSymlinkPath(target);
+    return path.relative(recordRoot, target).replace(/\\/g, '/');
+  }
 
   return {
+    recordRoot,
+    allowedRoots,
+    keyFor,
+
     /**
      * Record a managed file by its on-disk path. Hashes the file as written.
      * Skips silently if the file is missing (e.g. dry-run).
@@ -86,7 +103,7 @@ function createTracker(platformFolder, version) {
     record(absPath) {
       const hash = hashFile(absPath);
       if (hash === null) return;
-      const rel = path.relative(platformFolder, absPath).replace(/\\/g, '/');
+      const rel = keyFor(absPath);
       files[rel] = { sha256: hash, version };
     },
 
@@ -159,8 +176,8 @@ function createTracker(platformFolder, version) {
  *   state: 'absent' | 'pristine' | 'user-modified' | 'user-created'
  *   changed: whether the payload differs from what's on disk (false → skip copy)
  */
-function classify(absPath, platformFolder, manifest, payloadHash) {
-  const rel = path.relative(platformFolder, absPath).replace(/\\/g, '/');
+function classify(absPath, platformFolder, manifest, payloadHash, recordRoot = platformFolder) {
+  const rel = path.relative(recordRoot, absPath).replace(/\\/g, '/');
   const recorded = manifest.files[rel];
   const recordedHash = recorded ? recorded.sha256 : null;
   const diskHash = hashFile(absPath);

package/bin/lib/opencode-install.js

@@ -419,6 +419,20 @@ function upsertCafeKitAgentsBlock(existingContent, blockContent) {
     return existingContent.replace(blockPattern, managedBlock);
   }
 
+  // Pre-managed-block releases wrote the shipped template as the whole file.
+  // Wrap only an exact shipped prefix and preserve any user/Codex suffix.
+  if (existingContent.startsWith(blockContent)) {
+    return `${managedBlock}${existingContent.slice(blockContent.length)}`;
+  }
+  const trimmedLegacy = blockContent.trimEnd();
+  if (
+    existingContent.startsWith(trimmedLegacy)
+    && ['', '\n', '\r'].includes(existingContent.charAt(trimmedLegacy.length))
+  ) {
+    return `${managedBlock}${existingContent.slice(trimmedLegacy.length)}`;
+  }
+  if (!existingContent) return `${managedBlock}\n`;
+
   const separator = existingContent.endsWith('\n') ? '\n' : '\n\n';
   return `${existingContent}${separator}${managedBlock}\n`;
 }
@@ -442,35 +456,23 @@ function getOpenCodeAgentsTemplateContent() {
 function copyOpenCodeAgentsMdFile(platformKey, results, options = {}) {
   if (platformKey !== 'opencode') return;
 
-  const shouldOverwriteManagedFiles = Boolean(options.upgrade);
   const dest = 'AGENTS.md';
   const content = getOpenCodeAgentsTemplateContent();
 
   if (content) {
     const destinationExists = fs.existsSync(dest);
+    const existingContent = destinationExists ? fs.readFileSync(dest, 'utf8') : '';
+    const nextContent = upsertCafeKitAgentsBlock(existingContent, content);
 
-    if (destinationExists && !shouldOverwriteManagedFiles) {
-      const existingContent = fs.readFileSync(dest, 'utf8');
-      const nextContent = upsertCafeKitAgentsBlock(existingContent, content);
-
-      if (nextContent === existingContent) {
-        console.log(`  → Skipped: AGENTS.md (already up to date)`);
-        results.skipped++;
-        return;
-      }
-
+    if (nextContent === existingContent) {
+      console.log(`  → Skipped: AGENTS.md (already up to date)`);
+      results.skipped++;
+    } else if (destinationExists) {
       fs.writeFileSync(dest, nextContent, 'utf8');
       console.log(`  ↻ AGENTS.md merged`);
       results.updated++;
-      return;
-    }
-
-    fs.writeFileSync(dest, content, 'utf8');
-
-    if (destinationExists && shouldOverwriteManagedFiles) {
-      console.log(`  ↻ AGENTS.md overwritten`);
-      results.updated++;
     } else {
+      fs.writeFileSync(dest, nextContent, 'utf8');
       console.log(`  ✓ AGENTS.md installed`);
       results.copied++;
     }

package/bin/lib/path-safety.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function isInside(base, target) {
+  const relative = path.relative(base, target);
+  return relative === ''
+    || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+/**
+ * Reject installer targets that traverse symlinks below the project root.
+ * Managed payloads and rollback snapshots must never follow a project-owned
+ * link into another directory.
+ */
+function assertNoSymlinkPath(filePath, basePath = process.cwd()) {
+  const base = path.resolve(basePath);
+  const target = path.resolve(filePath);
+  if (!isInside(base, target)) {
+    throw new Error(`Managed path is outside the project root: ${filePath}`);
+  }
+
+  const relative = path.relative(base, target);
+  let cursor = base;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    cursor = path.join(cursor, segment);
+    try {
+      if (fs.lstatSync(cursor).isSymbolicLink()) {
+        throw new Error(`Refusing to follow symlinked managed path: ${filePath}`);
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+  return target;
+}
+
+module.exports = { assertNoSymlinkPath, isInside };