@fitlab-ai/agent-infra 0.7.2 → 0.7.4

package/dist/lib/task/commands/status.js

@@ -0,0 +1,239 @@
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { resolveTaskRef } from "../resolve-ref.js";
+import { enumerateArtifacts } from "../artifacts.js";
+import { parseTaskFrontmatter, extractTitle } from "../frontmatter.js";
+import { loadShortIdByTaskId } from "../short-id.js";
+const USAGE = `Usage: ai task status <N | #N | TASK-id>
+
+Prints an aggregated "health check" view for a task: header, metadata, an
+artifacts summary, git branch state, and best-effort GitHub issue/PR status.
+  <ref>   Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+
+Git and Platform rows are best-effort: a failed git/gh call degrades that row to
+'-' without failing the command.
+`;
+const DASH = '-';
+function makeRunner(cwd) {
+    return (file, args) => execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+// Run `run` and swallow any failure into null, so a single failing git/gh call
+// degrades only its own field instead of aborting the whole view.
+function tryRun(run, file, args) {
+    try {
+        return run(file, args);
+    }
+    catch {
+        return null;
+    }
+}
+// Frontmatter keys shown in the Metadata section, in a fixed display order.
+const METADATA_KEYS = [
+    'type',
+    'status',
+    'current_step',
+    'priority',
+    'effort',
+    'branch',
+    'assigned_to',
+    'created_at',
+    'updated_at',
+    'issue_number',
+    'pr_status'
+];
+function collectMetadata(fm) {
+    return METADATA_KEYS.map((key) => [key, fm[key] ? fm[key] : DASH]);
+}
+// Workflow stages in timeline order; artifacts are bucketed by filename prefix.
+// `review-*` prefixes are matched before their bare counterparts so that, e.g.,
+// `review-analysis.md` is never swallowed by the `analysis` bucket.
+const STAGE_ORDER = [
+    'analysis',
+    'review-analysis',
+    'plan',
+    'review-plan',
+    'code',
+    'review-code',
+    'task',
+    'other'
+];
+function stageOf(name) {
+    const stem = name.replace(/\.md$/, '');
+    if (stem === 'task')
+        return 'task';
+    if (stem.startsWith('review-analysis'))
+        return 'review-analysis';
+    if (stem.startsWith('review-plan'))
+        return 'review-plan';
+    if (stem.startsWith('review-code'))
+        return 'review-code';
+    if (stem.startsWith('analysis'))
+        return 'analysis';
+    if (stem.startsWith('plan'))
+        return 'plan';
+    if (stem.startsWith('code'))
+        return 'code';
+    return 'other';
+}
+// Group artifacts by workflow stage, preserving the input order (mtime ascending
+// from enumerateArtifacts) within each stage and dropping empty stages.
+function groupArtifacts(artifacts) {
+    const byStage = new Map();
+    for (const artifact of artifacts) {
+        const stage = stageOf(artifact.name);
+        const bucket = byStage.get(stage);
+        if (bucket)
+            bucket.push(artifact.name);
+        else
+            byStage.set(stage, [artifact.name]);
+    }
+    const groups = [];
+    for (const stage of STAGE_ORDER) {
+        const files = byStage.get(stage);
+        if (files && files.length > 0)
+            groups.push({ stage, files });
+    }
+    return groups;
+}
+// `frontmatterBranch` is the task.md `branch` field (caller passes '' when absent).
+// It is read straight from frontmatter and never depends on a subprocess, so it
+// keeps its value even when every git call fails. All other fields degrade to '-'
+// on failure of their own command.
+function collectGit(frontmatterBranch, run) {
+    const frontmatter = frontmatterBranch ? frontmatterBranch : DASH;
+    let current = DASH;
+    const cur = tryRun(run, 'git', ['rev-parse', '--abbrev-ref', 'HEAD']);
+    if (cur !== null && cur.trim())
+        current = cur.trim();
+    let match = DASH;
+    if (current !== DASH && frontmatter !== DASH) {
+        match = current === frontmatter ? 'yes' : 'no';
+    }
+    let exists = DASH;
+    if (frontmatter !== DASH) {
+        const verified = tryRun(run, 'git', ['rev-parse', '--verify', '--quiet', `refs/heads/${frontmatter}`]);
+        exists = verified === null ? 'no' : 'yes';
+    }
+    let uncommitted = DASH;
+    const porcelain = tryRun(run, 'git', ['status', '--porcelain']);
+    if (porcelain !== null) {
+        const changed = porcelain.split('\n').filter((line) => line.trim() !== '');
+        uncommitted = changed.length === 0 ? 'clean' : `${changed.length} file(s)`;
+    }
+    let aheadBehind = DASH;
+    if (frontmatter !== DASH) {
+        const counts = tryRun(run, 'git', [
+            'rev-list',
+            '--left-right',
+            '--count',
+            `${frontmatter}...${frontmatter}@{upstream}`
+        ]);
+        if (counts !== null) {
+            const parts = counts.trim().split(/\s+/);
+            if (parts.length === 2)
+                aheadBehind = `${parts[0]} ahead / ${parts[1]} behind`;
+        }
+    }
+    return { current, frontmatter, match, exists, uncommitted, aheadBehind };
+}
+function collectPlatform(fm, run) {
+    let issue = DASH;
+    if (fm.issue_number && /^\d+$/.test(fm.issue_number)) {
+        const out = tryRun(run, 'gh', ['issue', 'view', fm.issue_number, '--json', 'state,labels']);
+        if (out !== null) {
+            try {
+                const data = JSON.parse(out);
+                const labels = Array.isArray(data.labels)
+                    ? data.labels.map((label) => label.name).join(', ')
+                    : '';
+                issue = labels ? `${data.state} [${labels}]` : `${data.state}`;
+            }
+            catch {
+                issue = DASH;
+            }
+        }
+    }
+    let pr = DASH;
+    if (fm.pr_status === 'created' && fm.pr_number && /^\d+$/.test(fm.pr_number)) {
+        const out = tryRun(run, 'gh', ['pr', 'view', fm.pr_number, '--json', 'state,statusCheckRollup']);
+        if (out !== null) {
+            try {
+                const data = JSON.parse(out);
+                const rollup = Array.isArray(data.statusCheckRollup) ? data.statusCheckRollup : [];
+                const passed = rollup.filter((check) => check.conclusion === 'SUCCESS' || check.state === 'SUCCESS').length;
+                pr = rollup.length > 0 ? `${data.state}, checks: ${passed}/${rollup.length}` : `${data.state}`;
+            }
+            catch {
+                pr = DASH;
+            }
+        }
+    }
+    return { issue, pr };
+}
+// Indent each label/value pair by two spaces and pad labels to a common width so
+// every section reads as an aligned "key   value" block.
+function renderPairs(rows) {
+    const width = rows.reduce((max, [label]) => Math.max(max, label.length), 0);
+    return rows.map(([label, value]) => `  ${label.padEnd(width)}  ${value}`.trimEnd());
+}
+function renderStatus(model) {
+    const lines = [];
+    lines.push(`Task ${model.taskId}  (${model.shortId})`);
+    if (model.title)
+        lines.push(model.title);
+    lines.push('', 'Metadata', ...renderPairs(model.metadata));
+    lines.push('', `Artifacts (${model.artifacts.count})`);
+    if (model.artifacts.groups.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        lines.push(...renderPairs(model.artifacts.groups.map((group) => [group.stage, group.files.join(', ')])));
+    }
+    lines.push('', 'Git', ...renderPairs([
+        ['current', model.git.current],
+        ['frontmatter', model.git.frontmatter],
+        ['match', model.git.match],
+        ['exists', model.git.exists],
+        ['uncommitted', model.git.uncommitted],
+        ['ahead/behind', model.git.aheadBehind]
+    ]));
+    const issueLabel = model.issueNumber ? `issue #${model.issueNumber}` : 'issue';
+    lines.push('', 'Platform', ...renderPairs([
+        [issueLabel, model.platform.issue],
+        ['pr', model.platform.pr]
+    ]));
+    return lines;
+}
+function status(args = []) {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        if (args.length === 0)
+            process.exitCode = 1;
+        return;
+    }
+    const resolved = resolveTaskRef(args[0]);
+    if (!resolved.ok) {
+        process.stderr.write(`ai task status: ${resolved.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    const fm = parseTaskFrontmatter(content);
+    const run = makeRunner(resolved.repoRoot);
+    const artifacts = enumerateArtifacts(resolved.taskDir);
+    const model = {
+        taskId: resolved.taskId,
+        shortId: loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId) ?? DASH,
+        title: extractTitle(content),
+        issueNumber: fm.issue_number && /^\d+$/.test(fm.issue_number) ? fm.issue_number : '',
+        metadata: collectMetadata(fm),
+        artifacts: { count: artifacts.length, groups: groupArtifacts(artifacts) },
+        git: collectGit(fm.branch ?? '', run),
+        platform: collectPlatform(fm, run)
+    };
+    for (const line of renderStatus(model)) {
+        process.stdout.write(`${line}\n`);
+    }
+}
+export { status, makeRunner, collectMetadata, groupArtifacts, collectGit, collectPlatform, renderStatus, METADATA_KEYS };
+//# sourceMappingURL=status.js.map

package/dist/lib/task/index.js

@@ -1,13 +1,25 @@
 const USAGE = `Usage: ai task <command> [options]
 
 Commands:
+  cat <ref> <artifact | N>               Print a task artifact (by name or number)
+  files <ref>                            List artifacts in a task dir (numbered)
+  grep <pattern> [ref] [artifact | N]    Literal search across task artifacts (omit ref to scan all)
+  log <ref>                              Render a task's activity log as a timeline
   ls [--all | --blocked | --completed]   List tasks (default: active)
   show <N | #N | TASK-id>                Print a task.md
+  status <ref>                           Aggregated status view (metadata / artifacts / git / platform)
 
 Examples:
+  ai task cat 11 analysis
+  ai task cat 11 3
+  ai task files 11
+  ai task grep resolveArtifact
+  ai task grep resolveArtifact 11
+  ai task log 11
   ai task ls
   ai task show 11
   ai task show TASK-20260612-162737
+  ai task status 11
 
 Run 'ai task <command> --help' for details.`;
 export async function runTask(args) {
@@ -32,6 +44,31 @@ export async function runTask(args) {
             show(rest);
             break;
         }
+        case 'files': {
+            const { files } = await import("./commands/files.js");
+            files(rest);
+            break;
+        }
+        case 'cat': {
+            const { cat } = await import("./commands/cat.js");
+            cat(rest);
+            break;
+        }
+        case 'grep': {
+            const { grep } = await import("./commands/grep.js");
+            grep(rest);
+            break;
+        }
+        case 'log': {
+            const { log } = await import("./commands/log.js");
+            log(rest);
+            break;
+        }
+        case 'status': {
+            const { status } = await import("./commands/status.js");
+            status(rest);
+            break;
+        }
         default:
             process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
             process.stdout.write(`${USAGE}\n`);

package/dist/lib/task/resolve-ref.js

@@ -0,0 +1,150 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { normalizeShortIdInput } from "./short-id.js";
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+// Flat-structured workspace dirs that hold tasks under `{dir}/{taskId}/task.md`.
+// Note: `archive` uses a three-level YYYY/MM/DD layout and is handled separately.
+const FLAT_WORKSPACE_DIRS = ['active', 'blocked', 'completed'];
+function detectRepoRoot() {
+    try {
+        return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+    }
+    catch {
+        throw new Error('ai task: current directory is not inside a git repository');
+    }
+}
+function readShortIdLength(repoRoot) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
+        const v = cfg?.task?.shortIdLength;
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 1)
+            return v;
+    }
+    catch {
+        // fall through to default
+    }
+    return 2;
+}
+function resolveShortIdToTaskId(arg, repoRoot) {
+    const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
+    if (!fs.existsSync(scriptPath)) {
+        throw new Error(`task-short-id.js not found at ${scriptPath}`);
+    }
+    const result = spawnSync('node', [scriptPath, 'resolve', arg], {
+        encoding: 'utf8',
+        cwd: repoRoot
+    });
+    if (result.status !== 0) {
+        throw new Error((result.stderr || '').trim() || `failed to resolve '${arg}'`);
+    }
+    return result.stdout.trim();
+}
+function listSortedNumeric(dir, width) {
+    if (!fs.existsSync(dir))
+        return [];
+    const pattern = new RegExp(`^\\d{${width}}$`);
+    return fs
+        .readdirSync(dir)
+        .filter((entry) => pattern.test(entry))
+        .sort()
+        .reverse();
+}
+function findInArchive(repoRoot, taskId) {
+    // archive-tasks SKILL writes to .agents/workspace/archive/YYYY/MM/DD/{taskId}/task.md
+    // where YYYY/MM/DD comes from completed_at (or updated_at fallback) — NOT from
+    // the task id's creation date. So we cannot derive the path from taskId alone;
+    // walk the bounded YYYY/MM/DD tree instead. Newest-first to favor recent archives.
+    const archiveDir = path.join(repoRoot, '.agents', 'workspace', 'archive');
+    for (const year of listSortedNumeric(archiveDir, 4)) {
+        const yearDir = path.join(archiveDir, year);
+        for (const month of listSortedNumeric(yearDir, 2)) {
+            const monthDir = path.join(yearDir, month);
+            for (const day of listSortedNumeric(monthDir, 2)) {
+                const candidate = path.join(monthDir, day, taskId, 'task.md');
+                if (fs.existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return null;
+}
+function findTaskMd(repoRoot, taskId) {
+    for (const sub of FLAT_WORKSPACE_DIRS) {
+        const candidate = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return findInArchive(repoRoot, taskId);
+}
+/**
+ * Enumerate every task directory under the flat workspace states
+ * (active / blocked / completed) — archive is intentionally excluded so a
+ * full-tree scan never pulls in cold data. Ordered by state, then task id
+ * ascending, giving callers a deterministic traversal.
+ */
+function enumerateTaskDirs(repoRoot) {
+    const out = [];
+    for (const sub of FLAT_WORKSPACE_DIRS) {
+        const base = path.join(repoRoot, '.agents', 'workspace', sub);
+        if (!fs.existsSync(base))
+            continue;
+        for (const entry of fs.readdirSync(base).sort()) {
+            if (!TASK_ID_RE.test(entry))
+                continue;
+            const taskDir = path.join(base, entry);
+            if (!fs.existsSync(path.join(taskDir, 'task.md')))
+                continue;
+            out.push({ taskId: entry, taskDir });
+        }
+    }
+    return out;
+}
+/**
+ * Resolve a task ref (bare short id, `#N`, or `TASK-YYYYMMDD-HHMMSS`) to its
+ * task directory across active / blocked / completed / archive.
+ *
+ * The returned `message` on failure is command-agnostic (no `ai task <cmd>:`
+ * prefix); callers prepend their own prefix so each command keeps its existing
+ * stderr wording byte-for-byte.
+ */
+function resolveTaskRef(arg) {
+    const repoRoot = detectRepoRoot();
+    let taskId;
+    if (TASK_ID_RE.test(arg)) {
+        taskId = arg;
+    }
+    else {
+        const shortIdLength = readShortIdLength(repoRoot);
+        const normalized = normalizeShortIdInput(arg, { shortIdLength });
+        if (normalized.kind === 'error') {
+            return { ok: false, message: normalized.message };
+        }
+        if (normalized.kind === 'pass') {
+            return {
+                ok: false,
+                message: `'${arg}' is not a valid short id or TASK-id; ` +
+                    `expected bare digits, '#N', or 'TASK-YYYYMMDD-HHMMSS'`
+            };
+        }
+        try {
+            taskId = resolveShortIdToTaskId(normalized.value, repoRoot);
+        }
+        catch (e) {
+            return { ok: false, message: e.message };
+        }
+    }
+    const taskMdPath = findTaskMd(repoRoot, taskId);
+    if (!taskMdPath) {
+        return {
+            ok: false,
+            message: `task ${taskId} not found in active / blocked / completed / archive`
+        };
+    }
+    return { ok: true, repoRoot, taskId, taskDir: path.dirname(taskMdPath), taskMdPath };
+}
+export { resolveTaskRef, detectRepoRoot, enumerateTaskDirs, TASK_ID_RE };
+//# sourceMappingURL=resolve-ref.js.map

package/dist/lib/task/short-id.js

@@ -58,6 +58,16 @@ function loadShortIdByTaskId(repoRoot) {
     }
     return map;
 }
+/**
+ * Resolve a branch to its active-task short id (`#NN`), or `null` when no
+ * active task is bound to that branch.
+ *
+ * Two-state semantics: this only consults the active registry
+ * (`active/.short-ids.json`) plus each `active/{taskId}/task.md`. Tasks moved
+ * to completed/blocked/cancelled/archive have already released their short id,
+ * so their branches return `null` — in `ai sandbox ls` that surfaces as `-`,
+ * meaning the sandbox is free to remove.
+ */
 function lookupShortIdByBranch(branch, repoRoot, _opts) {
     const registry = readRegistry(repoRoot);
     if (!registry)

package/dist/lib/update.js

@@ -7,6 +7,24 @@ import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from "./builtin-tuis.js"
 const defaults = JSON.parse(fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8'));
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
+// One-time migration of the legacy project-level PR switch to the three-state
+// `prFlow` preference. `true` (the old default / "PR flow on") maps to the
+// strong constraint `required`; `false` maps to `disabled`. A missing or
+// already-migrated config is left untouched (idempotent). Returns the new
+// prFlow value when a migration happened, otherwise null.
+function migratePrFlow(config) {
+    if (config.requiresPullRequest === true) {
+        delete config.requiresPullRequest;
+        config.prFlow = 'required';
+        return 'required';
+    }
+    if (config.requiresPullRequest === false) {
+        delete config.requiresPullRequest;
+        config.prFlow = 'disabled';
+        return 'disabled';
+    }
+    return null;
+}
 function isPathOwnedByOtherPlatform(relativePath, platformType) {
     const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
     if (!top.startsWith('.'))
@@ -134,7 +152,7 @@ async function cmdUpdate() {
     const sandboxAdded = !config.sandbox;
     const taskAdded = !config.task;
     const labelsAdded = !config.labels;
-    const requiresPullRequestAdded = config.requiresPullRequest === undefined;
+    const prFlowMigrated = migratePrFlow(config);
     let configChanged = changed;
     if (platformAdded) {
         config.platform = structuredClone(defaults.platform);
@@ -152,8 +170,7 @@ async function cmdUpdate() {
         config.labels = structuredClone(defaults.labels);
         configChanged = true;
     }
-    if (requiresPullRequestAdded) {
-        config.requiresPullRequest = defaults.requiresPullRequest;
+    if (prFlowMigrated) {
         configChanged = true;
     }
     if (configChanged) {
@@ -167,7 +184,7 @@ async function cmdUpdate() {
                 ok(`  merged: ${entry}`);
             }
         }
-        else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || requiresPullRequestAdded) {
+        else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || prFlowMigrated) {
             if (platformAdded) {
                 info(`Default platform config added to ${CONFIG_PATH}.`);
             }
@@ -180,8 +197,8 @@ async function cmdUpdate() {
             if (labelsAdded) {
                 info(`Default labels.in config added to ${CONFIG_PATH}.`);
             }
-            if (requiresPullRequestAdded) {
-                info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+            if (prFlowMigrated) {
+                info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
             }
         }
         else {
@@ -199,8 +216,8 @@ async function cmdUpdate() {
         if (hasNewEntries && platformAdded) {
             info(`Default platform config added to ${CONFIG_PATH}.`);
         }
-        if (hasNewEntries && requiresPullRequestAdded) {
-            info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+        if (hasNewEntries && prFlowMigrated) {
+            info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
         }
         fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
         ok(`Updated ${CONFIG_PATH}`);

package/lib/defaults.json

@@ -2,7 +2,6 @@
   "platform": {
     "type": "github"
   },
-  "requiresPullRequest": true,
   "sandbox": {
     "engine": null,
     "runtimes": [

package/lib/init.ts

@@ -32,7 +32,6 @@ type Defaults = {
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
   labels: Record<string, unknown>;
-  requiresPullRequest: boolean;
 };
 
 type AgentConfig = {
@@ -40,7 +39,6 @@ type AgentConfig = {
   org: string;
   language: string;
   platform: { type: string };
-  requiresPullRequest: boolean;
   templateVersion: string;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
@@ -224,13 +222,6 @@ async function cmdInit(): Promise<void> {
     );
   }
 
-  const requiresPRChoice = await select(
-    'Require Pull Request flow?',
-    ['yes', 'no'],
-    'yes'
-  );
-  const requiresPullRequest = requiresPRChoice !== 'no';
-
   let enabledTUIs: string[];
   try {
     enabledTUIs = await multiSelect(
@@ -324,7 +315,6 @@ async function cmdInit(): Promise<void> {
     org: orgName,
     language,
     platform: { type: platformType },
-    requiresPullRequest,
     templateVersion: VERSION,
     sandbox: structuredClone(defaults.sandbox),
     task: structuredClone(defaults.task),

package/lib/sandbox/commands/create.ts

@@ -840,7 +840,34 @@ export function ensureClaudeSettings(toolDir: string, hostHomeDir?: string): voi
   }
 }
 
-export function ensureCodexModelInheritance(toolDir: string, hostHomeDir?: string): void {
+function resolveHostCatalogPath(value: unknown, hostHomeDir: string): string | null {
+  if (typeof value !== 'string' || value === '') {
+    return null;
+  }
+  let resolved: string;
+  if (value === '~' || value.startsWith('~/') || value.startsWith('~\\')) {
+    resolved = path.join(hostHomeDir, value.slice(1).replace(/^[/\\]+/, ''));
+  } else if (path.isAbsolute(value)) {
+    resolved = value;
+  } else {
+    resolved = path.join(hostHomeDir, '.codex', value);
+  }
+  try {
+    if (!fs.statSync(resolved).isFile()) {
+      return null;
+    }
+    fs.accessSync(resolved, fs.constants.R_OK);
+    return resolved;
+  } catch {
+    return null;
+  }
+}
+
+export function ensureCodexModelInheritance(
+  toolDir: string,
+  hostHomeDir?: string,
+  containerCodexDir: string = '/home/devuser/.codex'
+): void {
   if (!hostHomeDir) {
     return;
   }
@@ -890,6 +917,22 @@ export function ensureCodexModelInheritance(toolDir: string, hostHomeDir?: strin
     changed = true;
   }
 
+  if (!Object.hasOwn(sandboxParsed, 'model_catalog_json')) {
+    const hostCatalogPath = resolveHostCatalogPath(hostParsed['model_catalog_json'], hostHomeDir);
+    if (hostCatalogPath) {
+      try {
+        const basename = path.basename(hostCatalogPath);
+        const destDir = path.join(toolDir, 'model-catalogs');
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.copyFileSync(hostCatalogPath, path.join(destDir, basename));
+        sandboxParsed['model_catalog_json'] = path.posix.join(containerCodexDir, 'model-catalogs', basename);
+        changed = true;
+      } catch {
+        // Copy failed (e.g. permissions): skip catalog, keep scalar inheritance intact.
+      }
+    }
+  }
+
   if (changed) {
     fs.writeFileSync(sandboxConfigPath, `${toml.stringify(sandboxParsed)}\n`, 'utf8');
   }
@@ -1042,7 +1085,7 @@ function runEngineTaskCommand(engine: string, cmd: string, args: string[], opts:
 }
 
 export function buildImage(
-  config: SandboxCreateConfig,
+  config: Pick<SandboxCreateConfig, 'project' | 'imageName' | 'repoRoot'> & { engine?: string | null },
   tools: SandboxTool[],
   dockerfilePath: string,
   imageSignature: string,
@@ -1060,7 +1103,7 @@ export function buildImage(
     env?: NodeJS.ProcessEnv;
   } = {}
 ): void {
-  const selectedEngine = engine ?? detectEngine(config);
+  const selectedEngine = engine ?? detectEngine({ engine: config.engine });
   const { uid: hostUid, gid: hostGid } = resolveBuildUid({
     engine: selectedEngine,
     runFn,
@@ -1342,7 +1385,7 @@ export async function create(args: string[]): Promise<void> {
             }
             const codexEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'codex');
             if (codexEntry) {
-              ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home);
+              ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home, codexEntry.tool.containerMount);
               ensureCodexWorkspaceTrust(codexEntry.dir);
             }
             const geminiEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'gemini-cli');