@fitlab-ai/agent-infra 0.5.10 → 0.6.0

package/lib/sandbox/commands/{enter.js → enter.ts}

@@ -1,16 +1,16 @@
-import { loadConfig } from '../config.js';
-import { assertValidBranchName, containerNameCandidates } from '../constants.js';
-import { detectEngine } from '../engine.js';
+import { loadConfig } from '../config.ts';
+import { assertValidBranchName, containerNameCandidates } from '../constants.ts';
+import { detectEngine } from '../engine.ts';
 import {
   formatCredentialWarnings,
   formatRemaining,
   reconcileClaudeCredentials,
   redactCommandError,
   validateClaudeCredentialsEnvOverride
-} from '../credentials.js';
-import { runInteractiveEngine, runSafeEngine } from '../shell.js';
-import { resolveTaskBranch } from '../task-resolver.js';
-import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.js';
+} from '../credentials.ts';
+import { runInteractiveEngine, runSafeEngine } from '../shell.ts';
+import { resolveTaskBranch } from '../task-resolver.ts';
+import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 
 const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
@@ -27,8 +27,8 @@ const FORWARDED_TERMINAL_ENV = [
   'LC_TERMINAL_VERSION'
 ];
 
-export function terminalEnvFlags(env = process.env) {
-  const flags = [];
+export function terminalEnvFlags(env: NodeJS.ProcessEnv = process.env): string[] {
+  const flags: string[] = [];
   for (const name of FORWARDED_TERMINAL_ENV) {
     const value = env[name];
     if (value) {
@@ -38,7 +38,10 @@ export function terminalEnvFlags(env = process.env) {
   return flags;
 }
 
-export function formatCredentialSyncStatus(result, isTTY = process.stderr.isTTY) {
+export function formatCredentialSyncStatus(
+  result: ReturnType<typeof reconcileClaudeCredentials>,
+  isTTY = process.stderr.isTTY
+): string | null {
   if (result.status === 'STALE_ACCESS') {
     return 'Warning: Claude Code credentials on host appear stale. Run "ai sandbox refresh" or "claude /login" to renew.\n';
   }
@@ -62,7 +65,7 @@ export function formatCredentialSyncStatus(result, isTTY = process.stderr.isTTY)
   return null;
 }
 
-export function enter(args) {
+export function enter(args: string[]): number {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(`${USAGE}\n`);
     if (args.length === 0) {
@@ -74,7 +77,7 @@ export function enter(args) {
   const config = loadConfig();
   validateClaudeCredentialsEnvOverride();
   const engine = detectEngine(config);
-  const [branchOrTaskId, ...cmd] = args;
+  const [branchOrTaskId = '', ...cmd] = args;
   const branch = resolveTaskBranch(branchOrTaskId, config.repoRoot);
   assertValidBranchName(branch);
   const running = runSafeEngine(engine, 'docker', ['ps', '--format', '{{.Names}}']).split('\n');
@@ -93,7 +96,7 @@ export function enter(args) {
         process.stderr.write(message);
       }
     } catch (error) {
-      process.stderr.write(`Warning: Failed to sync Claude Code credentials: ${redactCommandError(error?.message ?? 'unknown error')}\n`);
+      process.stderr.write(`Warning: Failed to sync Claude Code credentials: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}\n`);
     }
   }
 
@@ -102,7 +105,7 @@ export function enter(args) {
     try {
       materializeDotfiles(config.dotfilesDir, dotfilesCacheDir(config.home, config.project));
     } catch (error) {
-      process.stderr.write(`Warning: dotfiles snapshot rebuild failed: ${redactCommandError(error?.message ?? 'unknown error')}\n`);
+      process.stderr.write(`Warning: dotfiles snapshot rebuild failed: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}\n`);
     }
 
     return runInteractiveEngine(engine, 'docker', ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH]);

package/lib/sandbox/commands/{ls.js → ls.ts}

@@ -2,26 +2,26 @@ import fs from 'node:fs';
 import path from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { loadConfig } from '../config.js';
-import { sandboxBranchLabel, sandboxLabel } from '../constants.js';
-import { detectEngine } from '../engine.js';
-import { runSafeEngine } from '../shell.js';
-import { resolveTools, toolProjectDirCandidates } from '../tools.js';
+import { loadConfig } from '../config.ts';
+import { sandboxBranchLabel, sandboxLabel } from '../constants.ts';
+import { detectEngine } from '../engine.ts';
+import { runSafeEngine } from '../shell.ts';
+import { resolveTools, toolProjectDirCandidates } from '../tools.ts';
 
 const USAGE = 'Usage: ai sandbox ls';
 const CONTAINER_LIST_HEADER = 'NAMES\tSTATUS\tBRANCH';
 
 // Exported to lock the docker/podman-compatible format in unit tests.
-export function containerListFormat() {
+export function containerListFormat(): string {
   return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
 }
 
-export function parseLabels(csv) {
+export function parseLabels(csv: string): Record<string, string> {
   if (!csv) {
     return {};
   }
 
-  const labels = {};
+  const labels: Record<string, string> = {};
   for (const pair of csv.split(',')) {
     if (!pair) {
       continue;
@@ -35,7 +35,7 @@ export function parseLabels(csv) {
   return labels;
 }
 
-function listChildren(dir) {
+function listChildren(dir: string): string[] {
   if (!fs.existsSync(dir)) {
     return [];
   }
@@ -43,7 +43,7 @@ function listChildren(dir) {
   return fs.readdirSync(dir).sort().map((entry) => path.join(dir, entry));
 }
 
-export function ls(args = []) {
+export function ls(args: string[] = []): void {
   if (args.length > 0 && (args[0] === '--help' || args[0] === '-h')) {
     process.stdout.write(`${USAGE}\n`);
     return;

package/lib/sandbox/commands/{rebuild.js → rebuild.ts}

@@ -2,18 +2,24 @@ import { parseArgs } from 'node:util';
 import { createHash } from 'node:crypto';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { loadConfig } from '../config.js';
-import { prepareDockerfile } from '../dockerfile.js';
-import { sandboxImageConfigLabel, sandboxLabel } from '../constants.js';
-import { detectEngine, ensureDocker } from '../engine.js';
-import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shell.js';
-import { resolveTools, toolNpmPackagesArg } from '../tools.js';
-import { toEnginePath } from '../engines/wsl2-paths.js';
-import { resolveBuildUid } from '../engines/native.js';
+import { loadConfig } from '../config.ts';
+import type { SandboxConfig } from '../config.ts';
+import { prepareDockerfile } from '../dockerfile.ts';
+import { sandboxImageConfigLabel, sandboxLabel } from '../constants.ts';
+import { detectEngine, ensureDocker } from '../engine.ts';
+import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
+import { resolveTools, toolNpmPackagesArg } from '../tools.ts';
+import type { SandboxTool } from '../tools.ts';
+import { toEnginePath } from '../engines/wsl2-paths.ts';
+import { resolveBuildUid } from '../engines/native.ts';
 
 const USAGE = `Usage: ai sandbox rebuild [--quiet]`;
 
-function buildSignature(preparedDockerfile, tools) {
+type PreparedDockerfile = ReturnType<typeof prepareDockerfile>;
+type EngineRunFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string }) => string;
+type EngineRunSafeFn = EngineRunFn;
+
+function buildSignature(preparedDockerfile: PreparedDockerfile, tools: SandboxTool[]): string {
   return createHash('sha256')
     .update(JSON.stringify({
       dockerfile: preparedDockerfile.signature,
@@ -24,14 +30,25 @@ function buildSignature(preparedDockerfile, tools) {
 }
 
 export function buildArgs(
-  config,
-  tools,
-  dockerfilePath,
-  imageSignature,
-  { engine, runFn = runEngine, runSafeFn = runSafeEngine, env = process.env } = {}
-) {
-  const { uid: hostUid, gid: hostGid } = resolveBuildUid({
+  config: SandboxConfig,
+  tools: SandboxTool[],
+  dockerfilePath: string,
+  imageSignature: string,
+  {
     engine,
+    runFn = runEngine,
+    runSafeFn = runSafeEngine,
+    env = process.env
+  }: {
+    engine?: string;
+    runFn?: EngineRunFn;
+    runSafeFn?: EngineRunSafeFn;
+    env?: NodeJS.ProcessEnv;
+  } = {}
+): string[] {
+  const selectedEngine = engine ?? detectEngine(config);
+  const { uid: hostUid, gid: hostGid } = resolveBuildUid({
+    engine: selectedEngine,
     runFn,
     runSafeFn,
     env
@@ -52,18 +69,18 @@ export function buildArgs(
     '--label',
     `${sandboxImageConfigLabel(config)}=${imageSignature}`,
     '-f',
-    toEnginePath(engine, dockerfilePath),
-    toEnginePath(engine, config.repoRoot)
+    toEnginePath(selectedEngine, dockerfilePath),
+    toEnginePath(selectedEngine, config.repoRoot)
   ];
 }
 
-function removeImageIfPresent(imageName, engine) {
+function removeImageIfPresent(imageName: string, engine: string): void {
   if (runOkEngine(engine, 'docker', ['image', 'inspect', imageName])) {
     runEngine(engine, 'docker', ['rmi', imageName]);
   }
 }
 
-export async function rebuild(args) {
+export async function rebuild(args: string[]): Promise<void> {
   const { values } = parseArgs({
     args,
     allowPositionals: true,
@@ -86,7 +103,7 @@ export async function rebuild(args) {
   const quiet = values.quiet ?? false;
   const engine = detectEngine(config);
 
-  await ensureDocker(config);
+  await ensureDocker(config, undefined);
   p.intro(pc.cyan('Rebuilding sandbox image'));
 
   try {

package/lib/sandbox/commands/{refresh.js → refresh.ts}

@@ -8,12 +8,21 @@ import {
   reconcileClaudeCredentials,
   redactCommandError,
   validateClaudeCredentialsEnvOverride
-} from '../credentials.js';
-import { runProbe } from '../shell.js';
+} from '../credentials.ts';
+import { runProbe } from '../shell.ts';
 
 const USAGE = 'Usage: ai sandbox refresh';
 
-export function probeClaudeStatus(spawnFn = runProbe) {
+type ReconcileOptions = NonNullable<Parameters<typeof reconcileClaudeCredentials>[1]>;
+
+type RefreshDeps = Partial<ReconcileOptions> & {
+  spawnFn?: typeof runProbe;
+  discoverFn?: typeof discoverProjects;
+  writeStdout?: (chunk: string) => unknown;
+  writeStderr?: (chunk: string) => unknown;
+};
+
+export function probeClaudeStatus(spawnFn: typeof runProbe = runProbe): { ok: boolean; stderr: string; error: string | null } {
   const result = spawnFn('claude', ['/status'], {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -21,12 +30,12 @@ export function probeClaudeStatus(spawnFn = runProbe) {
   });
   return {
     ok: result.status === 0,
-    stderr: result.stderr ?? '',
+    stderr: result.stderr?.toString() ?? '',
     error: result.error?.message ?? null
   };
 }
 
-export async function refresh(args, deps = {}) {
+export async function refresh(args: string[], deps: RefreshDeps = {}): Promise<number> {
   const {
     spawnFn = runProbe,
     execFn,
@@ -35,8 +44,8 @@ export async function refresh(args, deps = {}) {
     writeFn,
     writeHostFn,
     discoverFn = discoverProjects,
-    writeStdout = (chunk) => process.stdout.write(chunk),
-    writeStderr = (chunk) => process.stderr.write(chunk)
+    writeStdout = (chunk: string) => process.stdout.write(chunk),
+    writeStderr = (chunk: string) => process.stderr.write(chunk)
   } = deps;
 
   if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {

package/lib/sandbox/commands/{rm.js → rm.ts}

@@ -3,7 +3,8 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { loadConfig } from '../config.js';
+import { loadConfig } from '../config.ts';
+import type { SandboxConfig } from '../config.ts';
 import {
   assertValidBranchName,
   containerNameCandidates,
@@ -11,19 +12,20 @@ import {
   sandboxLabel,
   shareBranchDir,
   worktreeDirCandidates
-} from '../constants.js';
-import { ENGINES, detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.js';
-import { run, runOk, runSafe, runSafeEngine } from '../shell.js';
-import { resolveTaskBranch } from '../task-resolver.js';
-import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.js';
+} from '../constants.ts';
+import { ENGINES, detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.ts';
+import { run, runOk, runSafe, runSafeEngine } from '../shell.ts';
+import { resolveTaskBranch } from '../task-resolver.ts';
+import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.ts';
+import type { SandboxTool } from '../tools.ts';
 
 const USAGE = `Usage: ai sandbox rm <branch> [--all]`;
 
-function projectToolDirs(config, tools) {
+function projectToolDirs(config: SandboxConfig, tools: SandboxTool[]): string[] {
   return tools.flatMap((tool) => toolProjectDirCandidates(tool, config.project));
 }
 
-export function assertManagedPath(root, target) {
+export function assertManagedPath(root: string, target: string): void {
   const resolvedRoot = path.resolve(root);
   const resolvedTarget = path.resolve(target);
   const relative = path.relative(resolvedRoot, resolvedTarget);
@@ -34,7 +36,7 @@ export function assertManagedPath(root, target) {
   throw new Error(`Refusing to remove path outside managed sandbox root: ${target}`);
 }
 
-async function rmOne(config, tools, branch) {
+async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string): Promise<void> {
   assertValidBranchName(branch);
   const engine = detectEngine(config);
   let effectiveBranch = branch;
@@ -55,7 +57,7 @@ async function rmOne(config, tools, branch) {
       'inspect',
       '-f',
       `{{ index .Config.Labels "${sandboxBranchLabel(config)}" }}`,
-      matchedContainers[0]
+      matchedContainers[0] ?? ''
     ]);
     if (resolvedBranch) {
       effectiveBranch = resolvedBranch;
@@ -136,7 +138,7 @@ async function rmOne(config, tools, branch) {
   p.outro(pc.green('Sandbox removed'));
 }
 
-async function rmAll(config, tools) {
+async function rmAll(config: SandboxConfig, tools: SandboxTool[]): Promise<void> {
   const engine = detectEngine(config);
   p.intro(pc.cyan(`Removing all sandboxes for ${config.project}`));
 
@@ -228,7 +230,7 @@ async function rmAll(config, tools) {
   p.outro(pc.green('All project sandboxes removed'));
 }
 
-export async function rm(args) {
+export async function rm(args: string[]): Promise<void> {
   const { values, positionals } = parseArgs({
     args,
     allowPositionals: true,
@@ -256,6 +258,6 @@ export async function rm(args) {
     return;
   }
 
-  const branch = resolveTaskBranch(positionals[0], config.repoRoot);
+  const branch = resolveTaskBranch(positionals[0] ?? '', config.repoRoot);
   await rmOne(config, tools, branch);
 }

package/lib/sandbox/commands/{vm.js → vm.ts}

@@ -1,8 +1,8 @@
 import { parseArgs } from 'node:util';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
-import { loadConfig } from '../config.js';
-import { parsePositiveIntegerOption } from '../constants.js';
+import { loadConfig } from '../config.ts';
+import { parsePositiveIntegerOption } from '../constants.ts';
 import {
   ENGINES,
   detectEngine,
@@ -10,12 +10,12 @@ import {
   isManagedEngine,
   startManagedVm,
   stopManagedVm
-} from '../engine.js';
-import { runOk, runSafe } from '../shell.js';
+} from '../engine.ts';
+import { runOk, runSafe } from '../shell.ts';
 
 const USAGE = `Usage: ai sandbox vm <status|start|stop> [--cpu <n>] [--memory <n>]`;
 
-export function ensureManagedVm(engine) {
+export function ensureManagedVm(engine: string): void {
   if (engine === ENGINES.NATIVE) {
     throw new Error(
       "Linux native Docker does not use a managed VM. Use 'ai sandbox create' directly."
@@ -32,14 +32,17 @@ export function ensureManagedVm(engine) {
   }
 }
 
-export function wsl2BackendStatus({ runOkFn = runOk } = {}) {
+export function wsl2BackendStatus({ runOkFn = runOk }: { runOkFn?: typeof runOk } = {}): {
+  wslAvailable: boolean;
+  dockerAvailable: boolean;
+} {
   const wslAvailable = runOkFn('wsl.exe', ['--status']) || runOkFn('wsl.exe', ['--', 'true']);
   const dockerAvailable = wslAvailable && runOkFn('wsl.exe', ['--', 'docker', 'info']);
 
   return { wslAvailable, dockerAvailable };
 }
 
-function status() {
+function status(): void {
   const config = loadConfig();
   const engine = detectEngine(config);
   const name = engineDisplayName(engine);
@@ -79,7 +82,7 @@ function status() {
   process.stdout.write(`${runSafe('orb', ['status'])}\n`);
 }
 
-async function start(args) {
+async function start(args: string[]): Promise<void> {
   const { values } = parseArgs({
     args,
     allowPositionals: true,
@@ -118,7 +121,7 @@ async function start(args) {
     }
   };
 
-  const onMessage = (detail) => {
+  const onMessage = (detail: string) => {
     p.log.info(detail);
   };
 
@@ -126,7 +129,7 @@ async function start(args) {
   p.outro(pc.green('VM ready'));
 }
 
-function stop() {
+function stop(): void {
   const config = loadConfig();
   const engine = detectEngine(config);
   const name = engineDisplayName(engine);
@@ -151,7 +154,7 @@ function stop() {
   p.outro(pc.green('VM stopped'));
 }
 
-export async function vm(args) {
+export async function vm(args: string[]): Promise<void> {
   const [subcommand, ...rest] = args;
 
   if (!subcommand || subcommand === '--help' || subcommand === '-h') {

package/lib/sandbox/{config.js → config.ts}

@@ -2,8 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { homedir, platform } from 'node:os';
 import { execFileSync } from 'node:child_process';
-import { validateSandboxEngine } from './engine.js';
-import { hostJoin } from './engines/wsl2-paths.js';
+import { validateSandboxEngine } from './engine.ts';
+import { hostJoin } from './engines/wsl2-paths.ts';
 
 const DEFAULTS = Object.freeze({
   engine: null,
@@ -17,7 +17,47 @@ const DEFAULTS = Object.freeze({
   }
 });
 
-function detectRepoRoot() {
+type PlatformFn = typeof platform;
+
+type SandboxConfigInput = {
+  engine?: string | null;
+  runtimes?: string[];
+  tools?: string[];
+  dockerfile?: string | null;
+  vm?: Record<string, unknown>;
+};
+
+type SandboxVmConfig = {
+  cpu: number | null;
+  memory: number | null;
+  disk: number | null;
+};
+
+export type SandboxConfig = {
+  repoRoot: string;
+  configPath: string;
+  project: string;
+  org: string;
+  home: string;
+  containerPrefix: string;
+  imageName: string;
+  worktreeBase: string;
+  shareBase: string;
+  dotfilesDir: string;
+  engine: string | null;
+  runtimes: string[];
+  tools: string[];
+  dockerfile: string | null;
+  vm: SandboxVmConfig;
+};
+
+type AircConfig = {
+  project?: unknown;
+  org?: unknown;
+  sandbox?: SandboxConfigInput;
+};
+
+function detectRepoRoot(): string {
   try {
     return execFileSync('git', ['rev-parse', '--show-toplevel'], {
       encoding: 'utf8',
@@ -28,7 +68,11 @@ function detectRepoRoot() {
   }
 }
 
-function cloneDefaults() {
+function asPositiveNumberOrNull(value: unknown): number | null {
+  return typeof value === 'number' ? value : null;
+}
+
+function cloneDefaults(): SandboxConfigInput & { vm: SandboxVmConfig; runtimes: string[]; tools: string[] } {
   return {
     engine: DEFAULTS.engine,
     runtimes: [...DEFAULTS.runtimes],
@@ -38,7 +82,7 @@ function cloneDefaults() {
   };
 }
 
-export function loadConfig({ platformFn = platform } = {}) {
+export function loadConfig({ platformFn = platform }: { platformFn?: PlatformFn } = {}): SandboxConfig {
   const repoRoot = detectRepoRoot();
   const home = homedir();
 
@@ -51,7 +95,7 @@ export function loadConfig({ platformFn = platform } = {}) {
     throw new Error('No .agents/.airc.json found. Run "ai init" first.');
   }
 
-  const airc = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const airc = JSON.parse(fs.readFileSync(configPath, 'utf8')) as AircConfig;
   const defaults = cloneDefaults();
   const sandbox = airc.sandbox ?? {};
   const engine = validateSandboxEngine(sandbox.engine ?? defaults.engine, { platformFn });
@@ -65,7 +109,7 @@ export function loadConfig({ platformFn = platform } = {}) {
     repoRoot,
     configPath,
     project,
-    org: airc.org ?? '',
+    org: typeof airc.org === 'string' ? airc.org : '',
     home,
     containerPrefix: `${project}-dev`,
     imageName: `${project}-sandbox:latest`,
@@ -79,10 +123,11 @@ export function loadConfig({ platformFn = platform } = {}) {
     tools: Array.isArray(sandbox.tools) && sandbox.tools.length > 0
       ? [...sandbox.tools]
       : defaults.tools,
-    dockerfile: sandbox.dockerfile ?? defaults.dockerfile,
+    dockerfile: typeof sandbox.dockerfile === 'string' ? sandbox.dockerfile : defaults.dockerfile ?? null,
     vm: {
-      ...defaults.vm,
-      ...(sandbox.vm ?? {})
+      cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,
+      memory: asPositiveNumberOrNull(sandbox.vm?.memory) ?? defaults.vm.memory,
+      disk: asPositiveNumberOrNull(sandbox.vm?.disk) ?? defaults.vm.disk
     }
   };
 }

package/lib/sandbox/{constants.js → constants.ts}

@@ -1,14 +1,26 @@
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
-import { hostJoin } from './engines/wsl2-paths.js';
+import { hostJoin } from './engines/wsl2-paths.ts';
 
 const validatedBranches = new Set();
 
-function dedupe(items) {
+type SandboxPathConfig = {
+  project: string;
+  containerPrefix: string;
+  worktreeBase: string;
+  shareBase: string;
+};
+
+type HostResources = {
+  cpu: number;
+  memory: number;
+};
+
+function dedupe(items: string[]): string[] {
   return [...new Set(items)];
 }
 
-export function assertValidBranchName(branch) {
+export function assertValidBranchName(branch: string): void {
   if (validatedBranches.has(branch)) {
     return;
   }
@@ -32,61 +44,61 @@ export function assertValidBranchName(branch) {
   validatedBranches.add(branch);
 }
 
-export function sanitizeBranchName(branch) {
+export function sanitizeBranchName(branch: string): string {
   assertValidBranchName(branch);
   return branch.replace(/\//g, '..');
 }
 
-export function legacySanitizeBranchName(branch) {
+export function legacySanitizeBranchName(branch: string): string {
   assertValidBranchName(branch);
   return branch.replace(/\//g, '-');
 }
 
-export function safeNameCandidates(branch) {
+export function safeNameCandidates(branch: string): string[] {
   return dedupe([sanitizeBranchName(branch), legacySanitizeBranchName(branch)]);
 }
 
-export function containerName(config, branch) {
+export function containerName(config: Pick<SandboxPathConfig, 'containerPrefix'>, branch: string): string {
   return `${config.containerPrefix}-${sanitizeBranchName(branch)}`;
 }
 
-export function containerNameCandidates(config, branch) {
+export function containerNameCandidates(config: Pick<SandboxPathConfig, 'containerPrefix'>, branch: string): string[] {
   return safeNameCandidates(branch).map((name) => `${config.containerPrefix}-${name}`);
 }
 
-export function worktreeDir(config, branch) {
+export function worktreeDir(config: Pick<SandboxPathConfig, 'worktreeBase'>, branch: string): string {
   return hostJoin(config.worktreeBase, sanitizeBranchName(branch));
 }
 
-export function worktreeDirCandidates(config, branch) {
+export function worktreeDirCandidates(config: Pick<SandboxPathConfig, 'worktreeBase'>, branch: string): string[] {
   return safeNameCandidates(branch).map((name) => hostJoin(config.worktreeBase, name));
 }
 
-export function shareDir(config) {
+export function shareDir(config: Pick<SandboxPathConfig, 'shareBase'>): string {
   return config.shareBase;
 }
 
-export function shareCommonDir(config) {
+export function shareCommonDir(config: Pick<SandboxPathConfig, 'shareBase'>): string {
   return hostJoin(config.shareBase, 'common');
 }
 
-export function shareBranchDir(config, branch) {
+export function shareBranchDir(config: Pick<SandboxPathConfig, 'shareBase'>, branch: string): string {
   return hostJoin(config.shareBase, 'branches', sanitizeBranchName(branch));
 }
 
-export function sandboxLabel(config) {
+export function sandboxLabel(config: Pick<SandboxPathConfig, 'project'>): string {
   return `${config.project}.sandbox`;
 }
 
-export function sandboxBranchLabel(config) {
+export function sandboxBranchLabel(config: Pick<SandboxPathConfig, 'project'>): string {
   return `${sandboxLabel(config)}.branch`;
 }
 
-export function sandboxImageConfigLabel(config) {
+export function sandboxImageConfigLabel(config: Pick<SandboxPathConfig, 'project'>): string {
   return `${sandboxLabel(config)}.image-config`;
 }
 
-export function parsePositiveIntegerOption(value, optionName) {
+export function parsePositiveIntegerOption(value: unknown, optionName: string): number | undefined {
   if (value === undefined || value === null) {
     return undefined;
   }
@@ -99,7 +111,7 @@ export function parsePositiveIntegerOption(value, optionName) {
   return parsed;
 }
 
-export function detectHostResources() {
+export function detectHostResources(): HostResources {
   // Resource hints are for engines that pre-allocate a managed VM. macOS uses
   // sysctl for Colima defaults, while the generic fallback supports WSL2 or
   // other direct callers that need conservative CPU and memory defaults.