@fitlab-ai/agent-infra 0.5.5 → 0.5.7

package/README.md

@@ -314,6 +314,7 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 |-------|-------------|------------|----------------------|
 | `release` | Execute the version release workflow. | `version` (`X.Y.Z`) | Publish a new project release. |
 | `create-release-note` | Generate release notes from PRs and commits. | `version`, `previous-version` (optional) | Prepare a changelog before shipping. |
+| `post-release` | Run post-release follow-up tasks (version bump, artifact rebuild, optional demo capture). | None | Finalize the release cycle after pushing a release tag. |
 
 <a id="security-skills"></a>
 
@@ -341,6 +342,140 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 
 > Every skill works across supported AI TUIs. The command prefix changes, but the workflow semantics stay the same.
 
+<a id="custom-skills"></a>
+
+## Custom Skills
+
+Built-in skills cover the standard delivery lifecycle, but teams often need project-specific instructions such as coding standards, deployment checks, or internal review rules. agent-infra supports that through **custom skills**.
+
+### Create a custom skill in the project
+
+Create a directory under `.agents/skills/<name>/` and add a `SKILL.md` file:
+
+```text
+.agents/skills/
+  enforce-style/
+    SKILL.md
+    reference/
+      style-guide.md
+```
+
+Minimum frontmatter:
+
+```yaml
+---
+name: enforce-style
+description: "Apply team style checks before submitting code"
+args: "<task-id>"   # optional
+---
+```
+
+- `name`: user-facing skill name
+- `description`: used when generating editor command metadata
+- `args`: optional argument hint; agent-infra uses it when generating slash commands for supported AI TUIs
+
+After adding the skill, run `update-agent-infra` again:
+
+| TUI | Command |
+|-----|---------|
+| Claude Code | `/update-agent-infra` |
+| Codex | `$update-agent-infra` |
+| Gemini CLI | `/{{project}}:update-agent-infra` |
+| OpenCode | `/update-agent-infra` |
+
+That refresh detects non-built-in skill directories in `.agents/skills/` and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.
+
+### Sync custom skills from shared sources
+
+If you maintain reusable team skills outside the repository, declare them in `.agents/.airc.json`:
+
+```json
+{
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" },
+      { "type": "local", "path": "~/team-skills" }
+    ]
+  }
+}
+```
+
+Expected source layout:
+
+```text
+~/private-skills/
+  enforce-style/
+    SKILL.md
+  release-check/
+    SKILL.md
+    reference/
+      checklist.md
+```
+
+Behavior:
+
+- Sources are applied in list order; later sources overwrite earlier custom sources when they define the same file
+- `type: "local"` is the only supported source type today; the structure leaves room for future source types
+- `~` in source paths is expanded to the current user's home directory
+
+### Sync behavior and conflict rules
+
+When `update-agent-infra` runs:
+
+- Manually created custom skills in `.agents/skills/` are protected from managed-file cleanup
+- Files synced from external custom sources are copied into `.agents/skills/`
+- For synced skills that still exist in a configured source, files removed from the source are also removed locally during the next sync
+- Built-in skills always win over custom sources; if a source defines a skill with the same name as a built-in skill, agent-infra skips that custom source skill instead of overriding the built-in one
+- If you truly need to replace a built-in skill or command, use the existing `ejected` mechanism and own that file in the project
+
+## Custom TUI Configuration
+
+Use the top-level `.agents/.airc.json` `customTUIs` array when your team uses an AI TUI that is not one of the built-in command targets. This config lets agent-infra show the correct next-step commands and generate command files for project custom skills by learning from an existing command in the custom TUI directory.
+
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `name` | Yes | Display name shown in reports and next-step guidance, for example `Acme TUI`. |
+| `dir` | Yes | Command directory relative to the project root, for example `.acme/commands`. The path must stay inside the project root. |
+| `invoke` | Yes | User-facing command template used in next-step guidance. |
+
+Supported `invoke` placeholders:
+
+| Placeholder | Replaced with | Example |
+|-------------|---------------|---------|
+| `${skillName}` | The skill command name, such as `review-task` or `commit`. | `acme ${skillName}` -> `acme review-task` |
+| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+
+Non-namespaced custom TUI:
+
+```json
+{
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ]
+}
+```
+
+Namespaced custom TUI:
+
+```json
+{
+  "project": "agent-infra",
+  "customTUIs": [
+    {
+      "name": "Internal Gemini",
+      "dir": ".internal-gemini/commands",
+      "invoke": "/${projectName}:${skillName}"
+    }
+  ]
+}
+```
+
+`customTUIs` should contain one entry per custom TUI. To let `update-agent-infra` generate command files for custom skills, keep at least one existing command file in `dir` that references a built-in skill path such as `.agents/skills/analyze-task/SKILL.md`; agent-infra uses that file as the format reference.
+
 <a id="prebuilt-workflows"></a>
 
 ## Prebuilt Workflows
@@ -410,7 +545,24 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.5",
+  "templateVersion": "v0.5.7",
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  },
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ],
   "files": {
     "managed": [
       ".agents/workspace/README.md",
@@ -439,8 +591,37 @@ The generated `.agents/.airc.json` file is the central contract between the boot
 | `org` | GitHub organization or owner used by generated metadata and links. |
 | `language` | Primary project language or locale used by rendered templates. |
 | `templateVersion` | Installed template version for future upgrades and drift tracking. |
+| `templates` | Optional external template overlay configuration. |
+| `templates.sources` | Optional ordered list of external template sources. Only `type: "local"` is supported today. |
+| `skills` | Optional custom skill sync configuration. |
+| `skills.sources` | Optional ordered list of external custom skill sources. Only `type: "local"` is supported today. |
+| `customTUIs` | Optional top-level list of custom AI TUI adapters. |
 | `files` | Per-path update strategy configuration for managed, merged, and ejected files. |
 
+### External template and skill sources
+
+Use external sources when your team maintains private platform templates, private rules, or shared custom skills outside this repository. You can configure them during `agent-infra init` or later by editing `.agents/.airc.json`:
+
+```json
+{
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" },
+      { "type": "local", "path": "~/team-overrides/templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+Template source precedence is built-in templates first, then external sources as supplements. External files with the same path as built-in templates are ignored and reported in `templateSources.conflicts`; between external sources, later entries override earlier entries and conflicts are also reported. Skill sources use the same local-source shape, but custom skills cannot replace built-in skills.
+
+External template files and skill scripts can include executable JavaScript or shell commands that AI workflows may run. Only use trusted local paths.
+
 <a id="file-management-strategies"></a>
 
 ## File Management Strategies

package/README.zh-CN.md

@@ -314,6 +314,7 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 |-------|------|------|---------|
 | `release` | 执行版本发布流程。 | `version`（`X.Y.Z`） | 发布新版本时。 |
 | `create-release-note` | 基于 PR 和 commit 生成发布说明。 | `version`、`previous-version`（可选） | 发布前准备 changelog 时。 |
+| `post-release` | 执行版本发布后的收尾工作（版本 bump、产物重建、可选动图录制）。 | 无 | 推送发布标签后完成收尾。 |
 
 <a id="security-skills"></a>
 
@@ -341,6 +342,140 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 
 > 所有 skills 都可跨支持的 AI TUI 复用。变化的只是命令前缀，工作流语义保持一致。
 
+<a id="custom-skills"></a>
+
+## 自定义 Skills
+
+内置 skills 覆盖了标准交付生命周期，但很多团队还需要项目特有的指令，例如编码规范、发布检查或内部审查规则。agent-infra 通过**自定义 skill**支持这些场景。
+
+### 在项目中创建自定义 skill
+
+在 `.agents/skills/<name>/` 下创建目录，并添加 `SKILL.md`：
+
+```text
+.agents/skills/
+  enforce-style/
+    SKILL.md
+    reference/
+      style-guide.md
+```
+
+最小 frontmatter 示例：
+
+```yaml
+---
+name: enforce-style
+description: "在提交代码前执行团队风格检查"
+args: "<task-id>"   # 可选
+---
+```
+
+- `name`：对用户可见的 skill 名称
+- `description`：用于生成编辑器命令元数据
+- `args`：可选参数提示；agent-infra 会在生成支持的 AI TUI 命令时使用它
+
+添加 skill 后，再执行一次 `update-agent-infra`：
+
+| TUI | 命令 |
+|-----|------|
+| Claude Code | `/update-agent-infra` |
+| Codex | `$update-agent-infra` |
+| Gemini CLI | `/{{project}}:update-agent-infra` |
+| OpenCode | `/update-agent-infra` |
+
+同步时会自动检测 `.agents/skills/` 下的非内置 skill 目录，并为 Claude Code、Gemini CLI、OpenCode 生成对应命令。
+
+### 从共享源同步自定义 skills
+
+如果团队在仓库外统一维护可复用 skill，可以在 `.agents/.airc.json` 中声明：
+
+```json
+{
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" },
+      { "type": "local", "path": "~/team-skills" }
+    ]
+  }
+}
+```
+
+源目录结构示例：
+
+```text
+~/private-skills/
+  enforce-style/
+    SKILL.md
+  release-check/
+    SKILL.md
+    reference/
+      checklist.md
+```
+
+行为说明：
+
+- 多个 source 按数组顺序应用；后面的 source 如果定义了同名文件，会覆盖前面的自定义 source 文件
+- 当前只支持 `type: "local"`；配置结构已为未来扩展其他来源类型预留
+- source 路径中的 `~` 会自动展开为当前用户的 home 目录
+
+### 同步行为与冲突规则
+
+执行 `update-agent-infra` 时：
+
+- 手动放在 `.agents/skills/` 下的自定义 skill 不会被 managed 文件清理删除
+- 外部 source 中的 skill 会同步复制到 `.agents/skills/`
+- 对于仍存在于配置 source 中的 skill，如果源里删掉某个文件，下次同步时本地对应残留文件也会被删除
+- 内置 skill 始终优先于自定义 source；如果 source 里出现与内置 skill 同名的目录，agent-infra 会跳过该 source skill，而不是覆盖内置实现
+- 如果你确实需要替换内置 skill 或命令，请使用现有的 `ejected` 机制，让项目自己接管该文件
+
+## 自定义 TUI 配置
+
+当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。
+
+| 字段 | 必填 | 含义 |
+|------|------|------|
+| `name` | 是 | 报告和下一步提示中展示的工具名称，例如 `Acme TUI`。 |
+| `dir` | 是 | 相对项目根目录的命令目录，例如 `.acme/commands`。路径必须位于项目根目录内。 |
+| `invoke` | 是 | 面向用户展示的命令模板，用于生成下一步提示。 |
+
+`invoke` 支持的占位符：
+
+| 占位符 | 替换为 | 示例 |
+|--------|--------|------|
+| `${skillName}` | skill 命令名，例如 `review-task` 或 `commit`。 | `acme ${skillName}` -> `acme review-task` |
+| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+
+不带命名空间的自定义 TUI：
+
+```json
+{
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ]
+}
+```
+
+带命名空间的自定义 TUI：
+
+```json
+{
+  "project": "agent-infra",
+  "customTUIs": [
+    {
+      "name": "Internal Gemini",
+      "dir": ".internal-gemini/commands",
+      "invoke": "/${projectName}:${skillName}"
+    }
+  ]
+}
+```
+
+`customTUIs` 每个条目对应一个自定义 TUI。若希望 `update-agent-infra` 为自定义 skill 生成命令文件，请在 `dir` 中保留至少一个引用内置 skill 路径的既有命令文件，例如 `.agents/skills/analyze-task/SKILL.md`；agent-infra 会以该文件作为格式参考。
+
 <a id="prebuilt-workflows"></a>
 
 ## 预置工作流
@@ -410,7 +545,24 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.5",
+  "templateVersion": "v0.5.7",
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  },
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ],
   "files": {
     "managed": [
       ".agents/workspace/README.md",
@@ -439,8 +591,37 @@ import-issue #42                    从 GitHub Issue 导入任务
 | `org` | 生成元数据和链接时使用的 GitHub 组织或拥有者。 |
 | `language` | 渲染模板时采用的项目主语言或区域设置。 |
 | `templateVersion` | 当前安装的模板版本，用于升级和差异追踪。 |
+| `templates` | 可选的外部模板叠加配置。 |
+| `templates.sources` | 可选的外部模板源列表，按顺序应用。当前仅支持 `type: "local"`。 |
+| `skills` | 可选的自定义 skill 同步配置。 |
+| `skills.sources` | 可选的外部自定义 skill 源列表，按顺序应用。当前仅支持 `type: "local"`。 |
+| `customTUIs` | 可选的顶层自定义 AI TUI 适配配置列表。 |
 | `files` | 针对具体路径配置 `managed`、`merged`、`ejected` 三类更新策略。 |
 
+### 外部模板与 skill 源
+
+当团队在仓库外维护私有平台模板、私有规则或共享自定义 skill 时，可以使用外部源。你可以在 `agent-infra init` 时配置，也可以之后手动编辑 `.agents/.airc.json`：
+
+```json
+{
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" },
+      { "type": "local", "path": "~/team-overrides/templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+模板源优先级是内置模板优先，外部源作为补充。外部源中与内置模板同路径的文件会被忽略，并记录到 `templateSources.conflicts`；多个外部源之间，后面的条目覆盖前面的条目，冲突同样会记录。Skill 源使用相同的本地源结构，但自定义 skill 不能替换内置 skill。
+
+外部模板文件和 skill 脚本可能包含 AI 工作流会执行的 JavaScript 或 shell 命令。只使用可信的本地路径。
+
 <a id="file-management-strategies"></a>
 
 ## 文件管理策略

package/bin/cli.js

@@ -35,9 +35,27 @@ Examples:
 
 const command = process.argv[2] || '';
 
+async function importCommand(importPath) {
+  try {
+    return await import(importPath);
+  } catch (error) {
+    if (error?.code === 'ERR_MODULE_NOT_FOUND') {
+      process.stderr.write(
+        'Error: Missing npm dependency. Run npm install before using agent-infra from a development checkout.\n'
+      );
+      process.stderr.write(`${error.message}\n`);
+      process.exitCode = 1;
+      return null;
+    }
+    throw error;
+  }
+}
+
 switch (command) {
   case 'init': {
-    const { cmdInit } = await import('../lib/init.js');
+    const imported = await importCommand('../lib/init.js');
+    if (!imported) break;
+    const { cmdInit } = imported;
     await cmdInit().catch((e) => {
       process.stderr.write(`Error: ${e.message}\n`);
       process.exitCode = 1;
@@ -45,7 +63,9 @@ switch (command) {
     break;
   }
   case 'update': {
-    const { cmdUpdate } = await import('../lib/update.js');
+    const imported = await importCommand('../lib/update.js');
+    if (!imported) break;
+    const { cmdUpdate } = imported;
     await cmdUpdate().catch((e) => {
       process.stderr.write(`Error: ${e.message}\n`);
       process.exitCode = 1;
@@ -53,7 +73,9 @@ switch (command) {
     break;
   }
   case 'merge': {
-    const { cmdMerge } = await import('../lib/merge.js');
+    const imported = await importCommand('../lib/merge.js');
+    if (!imported) break;
+    const { cmdMerge } = imported;
     await cmdMerge(process.argv.slice(3)).catch((e) => {
       process.stderr.write(`Error: ${e.message}\n`);
       process.exitCode = 1;
@@ -61,7 +83,9 @@ switch (command) {
     break;
   }
   case 'sandbox': {
-    const { runSandbox } = await import('../lib/sandbox/index.js');
+    const imported = await importCommand('../lib/sandbox/index.js');
+    if (!imported) break;
+    const { runSandbox } = imported;
     await runSandbox(process.argv.slice(3)).catch((e) => {
       process.stderr.write(`Error: ${e.message}\n`);
       process.exitCode = 1;

package/lib/defaults.json

@@ -3,6 +3,7 @@
     "type": "github"
   },
   "sandbox": {
+    "engine": null,
     "runtimes": [
       "node20"
     ],

package/lib/init.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
 import { info, ok, err } from './log.js';
-import { prompt, closePrompt } from './prompt.js';
+import { prompt, select, closePrompt } from './prompt.js';
 import { resolveTemplateDir } from './paths.js';
-import { renderFile, copySkillDir } from './render.js';
+import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.js';
 import { VERSION } from './version.js';
 
 const defaults = JSON.parse(
@@ -39,10 +40,19 @@ function detectOrgName() {
 
 const VALID_NAME_RE = /^[a-zA-Z0-9_.@-]+$/;
 
+function parseLocalSources(input) {
+  return input
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => ({ type: 'local', path: entry }));
+}
+
 async function cmdInit() {
   console.log('');
   console.log('  agent-infra init');
   console.log('  ================================');
+  console.log('  Optional template and skill sources can be added now or later in .agents/.airc.json.');
   console.log('');
 
   // resolve templates
@@ -100,14 +110,52 @@ async function cmdInit() {
     return;
   }
 
-  const platformType = (await prompt('Platform type', 'github')).trim() || 'github';
-  closePrompt();
+  let sandboxEngine = null;
+  if (platform() === 'darwin') {
+    sandboxEngine = await select(
+      'Sandbox engine (macOS)',
+      ['colima', 'orbstack', 'docker-desktop'],
+      'colima'
+    );
+  }
+
+  const platformChoices = [...KNOWN_PLATFORMS, 'other'];
+  let platformType = await select('Platform', platformChoices, 'github');
+
+  if (platformType === 'other') {
+    platformType = (await prompt('Custom platform type', '')).trim();
+    if (!platformType) {
+      closePrompt();
+      err('Custom platform type is required.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   if (!/^[a-z0-9][a-z0-9-]*$/.test(platformType)) {
+    closePrompt();
     err(`Platform type must match /^[a-z0-9][a-z0-9-]*$/. Got: ${platformType}`);
     process.exitCode = 1;
     return;
   }
 
+  if (!KNOWN_PLATFORMS.has(platformType)) {
+    info(
+      `Custom platform '${platformType}' selected. Built-in templates are only complete for github;`
+      + ` provide matching '.${platformType}.' or generic templates before running update-agent-infra.`
+    );
+  }
+
+  const templateSources = parseLocalSources(await prompt(
+    'Template sources (optional, comma-separated local paths, e.g. ~/my-templates; Enter to skip)',
+    ''
+  ));
+  const skillSources = parseLocalSources(await prompt(
+    'Skill sources (optional, comma-separated local paths, e.g. ~/my-skills; Enter to skip)',
+    ''
+  ));
+  closePrompt();
+
   const project = projectName;
   const replacements = { project, org: orgName };
 
@@ -177,6 +225,22 @@ async function cmdInit() {
     files: structuredClone(defaults.files)
   };
 
+  if (sandboxEngine) {
+    config.sandbox.engine = sandboxEngine;
+  }
+
+  if (templateSources.length > 0) {
+    config.templates = {
+      sources: templateSources
+    };
+  }
+
+  if (skillSources.length > 0) {
+    config.skills = {
+      sources: skillSources
+    };
+  }
+
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
   ok(`Generated ${configPath}`);

package/lib/prompt.js

@@ -59,6 +59,33 @@ async function prompt(question, defaultValue) {
   return line.trim() || defaultValue || '';
 }
 
+async function select(question, choices, defaultValue) {
+  const defaultIndex = choices.indexOf(defaultValue);
+
+  process.stdout.write(`  ${question}:\n`);
+  choices.forEach((choice, index) => {
+    const suffix = index === defaultIndex ? ' (default)' : '';
+    process.stdout.write(`      ${index + 1}) ${choice}${suffix}\n`);
+  });
+
+  ask(defaultIndex >= 0 ? `Select [${defaultIndex + 1}]: ` : 'Select: ');
+
+  setupInterface();
+
+  const line = await nextLine();
+  if (line === null || line.trim() === '') {
+    return defaultValue || choices[0];
+  }
+
+  const trimmed = line.trim();
+  const selectedIndex = Number.parseInt(trimmed, 10);
+  if (String(selectedIndex) === trimmed && selectedIndex >= 1 && selectedIndex <= choices.length) {
+    return choices[selectedIndex - 1];
+  }
+
+  return trimmed;
+}
+
 function closePrompt() {
   if (_rl) {
     _rl.close();
@@ -67,4 +94,4 @@ function closePrompt() {
   }
 }
 
-export { prompt, closePrompt };
+export { prompt, select, closePrompt };

package/lib/render.js

@@ -158,4 +158,4 @@ function copySkillDir(srcDir, dstDir, replacements, language, platform = 'github
   }
 }
 
-export { renderFile, copyFile, copySkillDir };
+export { renderFile, copyFile, copySkillDir, KNOWN_PLATFORMS };

package/lib/sandbox/commands/create.js

@@ -63,6 +63,10 @@ function buildSignature(preparedDockerfile, tools) {
     .slice(0, 12);
 }
 
+function hostJoin(basePath, ...segments) {
+  return basePath.startsWith('/') ? path.posix.join(basePath, ...segments) : path.join(basePath, ...segments);
+}
+
 function resolveToolDirs(config, tools, branch) {
   return tools.map((tool) => {
     const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -266,7 +270,7 @@ export function prepareHostShellConfig({ home, project, branch, repoRoot }) {
 }
 
 function gpgCacheDir(home, project) {
-  return path.join(home, '.agent-infra', 'gpg-cache', project);
+  return hostJoin(home, '.agent-infra', 'gpg-cache', project);
 }
 
 function normalizeSigningKey(signingKey) {
@@ -649,11 +653,11 @@ export function extractClaudeCredentialsBlob(home, execFn = execFileSync) {
 }
 
 export function claudeCredentialsDir(home, project) {
-  return path.join(home, '.agent-infra', 'credentials', project, 'claude-code');
+  return hostJoin(home, '.agent-infra', 'credentials', project, 'claude-code');
 }
 
 export function claudeCredentialsPath(home, project) {
-  return path.join(claudeCredentialsDir(home, project), '.credentials.json');
+  return hostJoin(claudeCredentialsDir(home, project), '.credentials.json');
 }
 
 export function writeClaudeCredentialsFile(home, project, blob) {