Codex Subagents

dev/node_modules/
codex-subagent.map
.tmp/
.DS_Store
coverage/
.npm-debug.log*
.codex-subagent/
.codex-home/
.claude/
.pytest_cache/

[hooks.pre-commit]
steps = [
  { run = "npm run --prefix dev lint" },
  { run = "npm run --prefix dev format" },
  { run = "npm run --prefix dev typecheck" },
  { run = "npm run --prefix dev test" }
]

root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

engine-strict=true
fund=false
audit=false

{
  "singleQuote": true,
  "semi": true,
  "printWidth": 100,
  "trailingComma": "es5"
}

import { build } from 'esbuild';
import { writeFileSync, readFileSync, chmodSync } from 'fs';

const outfile = '../codex-subagent';

await build({
  entryPoints: ['src/bin/codex-subagent.ts'],
  bundle: true,
  platform: 'node',
  target: 'node20',
  format: 'cjs',
  outfile: outfile + '.tmp',
  sourcemap: true,
});

// Prepend shebang (esbuild's banner escapes the !)
const code = readFileSync(outfile + '.tmp', 'utf8');
writeFileSync(outfile, '#!/usr/bin/env node\n' + code);
writeFileSync(outfile + '.map', readFileSync(outfile + '.tmp.map'));
chmodSync(outfile, 0o755);

// Clean up temp files
import { unlinkSync } from 'fs';
unlinkSync(outfile + '.tmp');
unlinkSync(outfile + '.tmp.map');

console.log(`Built ${outfile}`);

You are a Codex subagent doing a tiny watch demo. Reply with a short status update and then finish.

#!/usr/bin/env tsx
import path from 'node:path';
import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { execa } from 'execa';

interface ThreadEntry {
  thread_id: string;
  updated_at?: string;
}

async function readLatestThread(stateFile: string): Promise<string> {
  const raw = await readFile(stateFile, 'utf8');
  const parsed = JSON.parse(raw) as Record<string, ThreadEntry>;
  const entries = Object.values(parsed);
  if (entries.length === 0) {
    throw new Error('No threads found in registry');
  }
  const latest = entries.sort((a, b) => {
    const left = a.updated_at ?? '';
    const right = b.updated_at ?? '';
    return right.localeCompare(left);
  })[0];
  return latest.thread_id;
}

async function main() {
  const repoRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
  const distBin = path.join(repoRoot, 'dist', 'codex-subagent.js');
  const promptFile = path.join(repoRoot, 'scripts', 'demo-watch-prompt.txt');
  const stateFile = path.join(repoRoot, '.codex-subagent', 'state', 'threads.json');

  console.log('Starting demo thread...');
  await execa(
    'node',
    [
      distBin,
      'start',
      '--role',
      'researcher',
      '--policy',
      'workspace-write',
      '--prompt-file',
      promptFile,
    ],
    {
      stdio: 'inherit',
    }
  );

  const latestThread = await readLatestThread(stateFile);
  console.log(`\nWatching thread ${latestThread}... (Ctrl+C to stop)`);
  await execa('node', [distBin, 'watch', '--thread', latestThread], {
    stdio: 'inherit',
  });
}

main().catch((error) => {
  console.error(error instanceof Error ? error.stack : error);
  process.exit(1);
});

import tseslint from 'typescript-eslint';

export default tseslint.config(
  {
    ignores: ['dist', 'node_modules', '*.config.js', '*.mjs'],
  },
  ...tseslint.configs.recommended,
  {
    files: ['tests/**/*.ts'],
    rules: {
      '@typescript-eslint/no-misused-promises': 'off',
    },
  }
);

{
  "name": "codex-subagent-cli",
  "version": "0.1.0",
  "description": "TypeScript CLI for managing Codex subagent threads",
  "type": "module",
  "bin": {
    "codex-subagent": "../codex-subagent"
  },
  "scripts": {
    "build": "node build.mjs",
    "dev": "tsx src/bin/codex-subagent.ts",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --check .",
    "format:fix": "prettier --write .",
    "test": "vitest run",
    "typecheck": "tsc --noEmit",
    "prepare": "node run-prek-install.mjs",
    "demo": "tsx demo-watch.ts"
  },
  "engines": {
    "node": ">=20",
    "npm": ">=10"
  },
  "devDependencies": {
    "@types/node": "^24.10.1",
    "@typescript-eslint/eslint-plugin": "^8.11.0",
    "@typescript-eslint/parser": "^8.11.0",
    "@vitest/coverage-istanbul": "^1.6.1",
    "chokidar": "^3.6.0",
    "eslint": "^9.13.0",
    "eslint-config-prettier": "^9.1.0",
    "globals": "^16.5.0",
    "npm-run-all": "^4.1.5",
    "prettier": "^3.3.3",
    "tsup": "^8.3.0",
    "tsx": "^4.19.2",
    "typescript": "^5.6.3",
    "typescript-eslint": "^8.48.0",
    "vitest": "^1.6.1"
  },
  "dependencies": {
    "execa": "^9.6.0",
    "yaml": "^2.4.3"
  }
}

import { spawnSync } from 'node:child_process';

function binaryExists(cmd) {
  const result = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
  return !result.error && result.status === 0;
}

if (!binaryExists('prek')) {
  console.log('[prek] binary not found on PATH; skipping prek install hook.');
  process.exit(0);
}

const installResult = spawnSync('prek', ['install'], { stdio: 'inherit' });
process.exit(installResult.status ?? 0);

import process from 'node:process';
import path from 'node:path';
import { readFile } from 'node:fs/promises';
import { listCommand } from '../commands/list.ts';
import { startCommand } from '../commands/start.ts';
import { sendCommand } from '../commands/send.ts';
import { peekCommand } from '../commands/peek.ts';
import { logCommand } from '../commands/log.ts';
import { watchCommand } from '../commands/watch.ts';
import { statusCommand } from '../commands/status.ts';
import { archiveCommand } from '../commands/archive.ts';
import { labelCommand } from '../commands/label.ts';
import { waitCommand } from '../commands/wait.ts';
import { cleanCommand } from '../commands/clean.ts';
import { RegistryLoadError } from '../lib/registry.ts';
import { getControllerId } from '../lib/controller-id.ts';
import { parseStartManifest, StartManifest } from '../lib/start-manifest.ts';
import { runStartThreadWorkflow } from '../lib/start-thread.ts';
import { runSendThreadWorkflow } from '../lib/send-thread.ts';
import type { PersonaRuntime } from '../lib/personas.ts';
import { Paths } from '../lib/paths.ts';
import { LaunchRegistry } from '../lib/launch-registry.ts';
import { markThreadError } from '../lib/thread-errors.ts';

// Use process.argv[1] for bundled executable compatibility
const CLI_ENTRY_PATH = process.argv[1];

interface ParsedArgs {
  command: string;
  rootDir?: string;
  controllerId?: string;
  rest: string[];
}

function parseArgs(argv: string[]): ParsedArgs {
  let command: string | undefined;
  let rootDir: string | undefined;
  let controllerId: string | undefined;
  const rest: string[] = [];

  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === '--root') {
      const next = argv[i + 1];
      if (!next) {
        throw new Error('--root flag requires a path');
      }
      rootDir = path.resolve(next);
      i++; // skip path value
      continue;
    }
    if (arg === '--controller-id') {
      const next = argv[i + 1];
      if (!next) {
        throw new Error('--controller-id flag requires a value');
      }
      controllerId = next;
      i++;
      continue;
    }
    if (!command) {
      command = arg;
      continue;
    }
    rest.push(arg);
  }

  return { command: command ?? 'list', rootDir, controllerId, rest };
}

interface StartFlags {
  role?: string;
  permissions?: 'read-only' | 'workspace-write';
  profile?: string;
  promptFile?: string;
  prompt?: string;
  promptFromStdin?: boolean;
  outputLastPath?: string;
  wait?: boolean;
  workingDir?: string;
  label?: string;
  persona?: string;
  manifestPath?: string;
  manifestFromStdin?: boolean;
  jsonSource?: string;
  jsonFromStdin?: boolean;
  printPrompt?: boolean;
  dryRun?: boolean;
  backend?: 'codex' | 'claude';
  model?: string;
}

function parseStartFlags(args: string[]): StartFlags {
  const flags: StartFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];
    switch (arg) {
      case '--role':
        if (!next) {
          throw new Error('--role flag requires a value');
        }
        flags.role = next;
        i++;
        break;
      case '--permissions':
        if (!next) {
          throw new Error('--permissions flag requires a value (read-only or workspace-write)');
        }
        if (next !== 'read-only' && next !== 'workspace-write') {
          throw new Error('--permissions must be "read-only" or "workspace-write"');
        }
        flags.permissions = next;
        i++;
        break;
      case '--profile':
        if (!next) {
          throw new Error('--profile flag requires a value');
        }
        flags.profile = next;
        i++;
        break;
      case '-f':
      case '--prompt-file':
        if (!next) {
          throw new Error('--prompt-file flag requires a path');
        }
        flags.promptFile = path.resolve(next);
        i++;
        break;
      case '--prompt':
        if (!next) {
          throw new Error('--prompt flag requires text or "-" for stdin');
        }
        if (next === '-') {
          flags.promptFromStdin = true;
        } else {
          flags.prompt = next;
        }
        i++;
        break;
      case '--save-response':
      case '--output-last':
        if (!next) {
          throw new Error('--save-response flag requires a path');
        }
        flags.outputLastPath = path.resolve(next);
        i++;
        break;
      case '--cwd':
        if (!next) {
          throw new Error('--cwd flag requires a path');
        }
        flags.workingDir = path.resolve(next);
        i++;
        break;
      case '--label':
        if (!next) {
          throw new Error('--label flag requires a value');
        }
        flags.label = next;
        i++;
        break;
      case '--persona':
        if (!next) {
          throw new Error('--persona flag requires a value');
        }
        flags.persona = next;
        i++;
        break;
      case '--json':
        if (!next) {
          throw new Error('--json flag requires a path or "-" for stdin');
        }
        flags.jsonSource = next === '-' ? '-' : path.resolve(next);
        flags.jsonFromStdin = next === '-';
        i++;
        break;
      case '--manifest':
        if (!next) {
          throw new Error('--manifest flag requires a path or "-" for stdin');
        }
        if (next === '-') {
          flags.manifestFromStdin = true;
        } else {
          flags.manifestPath = path.resolve(next);
        }
        i++;
        break;
      case '--print-prompt':
        flags.printPrompt = true;
        break;
      case '--dry-run':
        flags.dryRun = true;
        break;
      case '-w':
      case '--wait':
        flags.wait = true;
        break;
      case '--backend':
        if (!next) {
          throw new Error('--backend flag requires a value (codex or claude)');
        }
        if (next !== 'codex' && next !== 'claude') {
          throw new Error('--backend must be "codex" or "claude"');
        }
        flags.backend = next;
        i++;
        break;
      case '--model':
        if (!next) {
          throw new Error('--model flag requires a value');
        }
        flags.model = next;
        i++;
        break;
      default:
        throw new Error(`Unknown flag for start command: ${arg}`);
    }
  }
  return flags;
}

async function loadManifestFromFlags(flags: StartFlags): Promise<StartManifest> {
  if (flags.manifestPath) {
    const body = await readFile(flags.manifestPath, 'utf8');
    const parsed = JSON.parse(body);
    return parseStartManifest(parsed, flags.manifestPath);
  }

  if (flags.manifestFromStdin) {
    const body = await readStdin();
    if (!body.trim()) {
      throw new Error('Manifest JSON from stdin was empty.');
    }
    const parsed = JSON.parse(body);
    return parseStartManifest(parsed, 'stdin');
  }

  throw new Error('Manifest flags were requested but no manifest source was provided.');
}

function readStdin(): Promise<string> {
  return new Promise((resolve, reject) => {
    const chunks: string[] = [];
    process.stdin.on('data', (chunk) => {
      if (typeof chunk === 'string') {
        chunks.push(chunk);
      } else {
        chunks.push(chunk.toString('utf8'));
      }
    });
    process.stdin.on('end', () => resolve(chunks.join('')));
    process.stdin.on('error', (error) => reject(error));
  });
}

interface StartJsonPayload {
  promptBody?: string;
  promptFile?: string;
  role?: string;
  permissions?: 'read-only' | 'workspace-write';
  profile?: string;
  workingDir?: string;
  label?: string;
  persona?: string;
  outputLastPath?: string;
  wait?: boolean;
}

async function loadStartJsonPayload(
  flags: StartFlags
): Promise<{ manifest?: StartManifest; single?: StartJsonPayload }> {
  if (!flags.jsonSource) {
    return {};
  }

  const body = flags.jsonFromStdin ? await readStdin() : await readFile(flags.jsonSource, 'utf8');
  if (!body.trim()) {
    throw new Error('JSON prompt payload was empty.');
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(body);
  } catch (error) {
    throw new Error(
      `Failed to parse JSON prompt payload: ${error instanceof Error ? error.message : String(error)}`
    );
  }

  const sourceLabel = flags.jsonFromStdin ? 'stdin' : (flags.jsonSource ?? 'json');
  const baseDir =
    flags.jsonFromStdin || !flags.jsonSource ? process.cwd() : path.dirname(flags.jsonSource);

  if (
    Array.isArray(parsed) ||
    (parsed &&
      typeof parsed === 'object' &&
      Array.isArray((parsed as Record<string, unknown>).tasks as unknown[]))
  ) {
    return { manifest: parseStartManifest(parsed, sourceLabel) };
  }

  return { single: normalizeStartJsonPayload(parsed, sourceLabel, baseDir) };
}

function normalizeStartJsonPayload(
  data: unknown,
  source: string,
  baseDir: string
): StartJsonPayload {
  if (!data || typeof data !== 'object' || Array.isArray(data)) {
    throw new Error(`Start JSON payload from ${source} must be an object.`);
  }
  const record = data as Record<string, unknown>;
  const pickString = (...keys: string[]) => {
    for (const key of keys) {
      const value = record[key];
      if (typeof value === 'string' && value.trim().length > 0) {
        return value;
      }
    }
    return undefined;
  };

  const permissions = pickString('permissions') as 'read-only' | 'workspace-write' | undefined;
  return {
    promptBody: pickString('prompt'),
    promptFile: resolveMaybePath(pickString('promptFile', 'prompt_file'), baseDir),
    role: pickString('role'),
    permissions,
    profile: pickString('profile'),
    workingDir: resolveMaybePath(pickString('cwd'), baseDir),
    label: pickString('label'),
    persona: pickString('persona'),
    outputLastPath: resolveMaybePath(pickString('outputLast', 'output_last'), baseDir),
    wait: typeof record.wait === 'boolean' ? record.wait : undefined,
  };
}

function resolveMaybePath(value: string | undefined, baseDir: string): string | undefined {
  if (!value) {
    return undefined;
  }
  if (path.isAbsolute(value)) {
    return value;
  }
  return path.resolve(baseDir, value);
}

interface SendJsonPayload {
  promptBody?: string;
  promptFile?: string;
  workingDir?: string;
  persona?: string;
  outputLastPath?: string;
  wait?: boolean;
}

async function loadSendJsonPayload(flags: SendFlags): Promise<SendJsonPayload | undefined> {
  if (!flags.jsonSource) {
    return undefined;
  }

  const body = flags.jsonFromStdin ? await readStdin() : await readFile(flags.jsonSource, 'utf8');
  if (!body.trim()) {
    throw new Error('Send JSON payload was empty.');
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(body);
  } catch (error) {
    throw new Error(
      `Failed to parse JSON payload: ${error instanceof Error ? error.message : String(error)}`
    );
  }

  const baseDir =
    flags.jsonFromStdin || !flags.jsonSource ? process.cwd() : path.dirname(flags.jsonSource);
  return normalizeSendJsonPayload(
    parsed,
    flags.jsonFromStdin ? 'stdin' : (flags.jsonSource ?? 'json'),
    baseDir
  );
}

function normalizeSendJsonPayload(data: unknown, source: string, baseDir: string): SendJsonPayload {
  if (!data || typeof data !== 'object' || Array.isArray(data)) {
    throw new Error(`Send JSON payload from ${source} must be an object.`);
  }
  const record = data as Record<string, unknown>;
  const pickString = (...keys: string[]) => {
    for (const key of keys) {
      const value = record[key];
      if (typeof value === 'string' && value.trim().length > 0) {
        return value;
      }
    }
    return undefined;
  };

  return {
    promptBody: pickString('prompt'),
    promptFile: resolveMaybePath(pickString('promptFile', 'prompt_file'), baseDir),
    workingDir: resolveMaybePath(pickString('cwd'), baseDir),
    persona: pickString('persona'),
    outputLastPath: resolveMaybePath(pickString('outputLast', 'output_last'), baseDir),
    wait: typeof record.wait === 'boolean' ? record.wait : undefined,
  };
}

interface SendFlags {
  threadId?: string;
  promptFile?: string;
  prompt?: string;
  promptFromStdin?: boolean;
  outputLastPath?: string;
  wait?: boolean;
  workingDir?: string;
  persona?: string;
  jsonSource?: string;
  jsonFromStdin?: boolean;
  printPrompt?: boolean;
  dryRun?: boolean;
}

function parseSendFlags(args: string[]): SendFlags {
  const flags: SendFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];

    // Handle positional thread ID (first non-flag argument)
    if (!arg.startsWith('-') && !flags.threadId) {
      flags.threadId = arg;
      continue;
    }

    switch (arg) {
      case '-t':
      case '--thread':
        if (!next) {
          throw new Error('--thread flag requires a value');
        }
        flags.threadId = next;
        i++;
        break;
      case '-f':
      case '--prompt-file':
        if (!next) {
          throw new Error('--prompt-file flag requires a path');
        }
        flags.promptFile = path.resolve(next);
        i++;
        break;
      case '--prompt':
        if (!next) {
          throw new Error('--prompt flag requires text or "-" for stdin');
        }
        if (next === '-') {
          flags.promptFromStdin = true;
        } else {
          flags.prompt = next;
        }
        i++;
        break;
      case '--save-response':
      case '--output-last':
        if (!next) {
          throw new Error('--save-response flag requires a path');
        }
        flags.outputLastPath = path.resolve(next);
        i++;
        break;
      case '--cwd':
        if (!next) {
          throw new Error('--cwd flag requires a path');
        }
        flags.workingDir = path.resolve(next);
        i++;
        break;
      case '--persona':
        if (!next) {
          throw new Error('--persona flag requires a value');
        }
        flags.persona = next;
        i++;
        break;
      case '--json':
        if (!next) {
          throw new Error('--json flag requires a path or "-" for stdin');
        }
        flags.jsonSource = next === '-' ? '-' : path.resolve(next);
        flags.jsonFromStdin = next === '-';
        i++;
        break;
      case '--print-prompt':
        flags.printPrompt = true;
        break;
      case '--dry-run':
        flags.dryRun = true;
        break;
      case '-w':
      case '--wait':
        flags.wait = true;
        break;
      default:
        throw new Error(`Unknown flag for send command: ${arg}`);
    }
  }
  return flags;
}

interface PeekFlags {
  threadId?: string;
  outputLastPath?: string;
  verbose?: boolean;
}

function parsePeekFlags(args: string[]): PeekFlags {
  const flags: PeekFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];

    // Handle positional thread ID (first non-flag argument)
    if (!arg.startsWith('-') && !flags.threadId) {
      flags.threadId = arg;
      continue;
    }

    switch (arg) {
      case '-t':
      case '--thread':
        if (!next) {
          throw new Error('--thread flag requires a value');
        }
        flags.threadId = next;
        i++;
        break;
      case '--save-response':
      case '--output-last':
        if (!next) {
          throw new Error('--save-response flag requires a path');
        }
        flags.outputLastPath = path.resolve(next);
        i++;
        break;
      case '--verbose':
        flags.verbose = true;
        break;
      default:
        throw new Error(`Unknown flag for peek command: ${arg}`);
    }
  }
  return flags;
}

interface LogFlags {
  threadId?: string;
  tail?: number;
  raw?: boolean;
  verbose?: boolean;
}

interface LabelFlags {
  threadId?: string;
  label?: string;
}

interface StatusFlags {
  threadId?: string;
  tail?: number;
  raw?: boolean;
  staleMinutes?: number;
}

interface ArchiveFlags {
  threadId?: string;
  completed?: boolean;
  yes?: boolean;
  dryRun?: boolean;
}

interface WaitFlags {
  threads?: string[];
  labels?: string[];
  all?: boolean;
  intervalMs?: number;
  timeoutMs?: number;
  followLast?: boolean;
}

interface ListFlags {
  filterStatus?: string;
  filterLabel?: string;
  filterRole?: string;
}

interface CleanFlags {
  olderThanDays?: number;
  yes?: boolean;
  dryRun?: boolean;
}

function parseListFlags(args: string[]): ListFlags {
  const flags: ListFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];
    switch (arg) {
      case '--status':
        if (!next) {
          throw new Error('--status flag requires a value');
        }
        flags.filterStatus = next;
        i++;
        break;
      case '--label':
        if (!next) {
          throw new Error('--label flag requires a value');
        }
        flags.filterLabel = next;
        i++;
        break;
      case '--role':
        if (!next) {
          throw new Error('--role flag requires a value');
        }
        flags.filterRole = next;
        i++;
        break;
      default:
        throw new Error(`Unknown flag for list command: ${arg}`);
    }
  }
  return flags;
}

function parseLogFlags(args: string[]): LogFlags {
  const flags: LogFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];

    // Handle positional thread ID (first non-flag argument)
    if (!arg.startsWith('-') && !flags.threadId) {
      flags.threadId = arg;
      continue;
    }

    switch (arg) {
      case '-t':
      case '--thread':
        if (!next) {
          throw new Error('--thread flag requires a value');
        }
        flags.threadId = next;
        i++;
        break;
      case '--tail':
        if (!next) {
          throw new Error('--tail flag requires a value');
        }
        flags.tail = Number(next);
        if (Number.isNaN(flags.tail) || flags.tail! < 1) {
          throw new Error('--tail must be a positive integer');
        }
        i++;
        break;
      case '--json':
      case '--raw':
        flags.raw = true;
        break;
      case '--verbose':
        flags.verbose = true;
        break;
      default:
        throw new Error(`Unknown flag for log command: ${arg}`);
    }
  }
  return flags;
}

function parseStatusFlags(args: string[]): StatusFlags {
  const flags: StatusFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];

    // Handle positional thread ID (first non-flag argument)
    if (!arg.startsWith('-') && !flags.threadId) {
      flags.threadId = arg;
      continue;
    }

    switch (arg) {
      case '-t':
      case '--thread':
        if (!next) {
          throw new Error('--thread flag requires a value');
        }
        flags.threadId = next;
        i++;
        break;
      case '--tail':
        if (!next) {
          throw new Error('--tail flag requires a value');
        }
        flags.tail = Number(next);
        if (Number.isNaN(flags.tail) || flags.tail! < 1) {
          throw new Error('--tail must be a positive integer');
        }
        i++;
        break;
      case '--json':
      case '--raw':
        flags.raw = true;
        break;
      case '--stale-minutes':
        if (!next) {
          throw new Error('--stale-minutes flag requires a value');
        }
        flags.staleMinutes = Number(next);
        if (Number.isNaN(flags.staleMinutes) || flags.staleMinutes! <= 0) {
          throw new Error('--stale-minutes must be greater than 0');
        }
        i++;
        break;
      default:
        throw new Error(`Unknown flag for status command: ${arg}`);
    }
  }
  return flags;
}

function parseArchiveFlags(args: string[]): ArchiveFlags {
  const flags: ArchiveFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];

    // Handle positional thread ID (first non-flag argument)
    if (!arg.startsWith('-') && !flags.threadId) {
      flags.threadId = arg;
      continue;
    }

    switch (arg) {
      case '-t':
      case '--thread':
        if (!next) {
          throw new Error('--thread flag requires a value');
        }
        flags.threadId = next;
        i++;
        break;
      case '--completed':
        flags.completed = true;
        break;
      case '--yes':
        flags.yes = true;
        break;
      case '--dry-run':
        flags.dryRun = true;
        break;
      default:
        throw new Error(`Unknown flag for archive command: ${arg}`);
    }
  }
  return flags;
}

function parseLabelFlags(args: string[]): LabelFlags {
  const flags: LabelFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];

    // Handle positional thread ID (first non-flag argument)
    if (!arg.startsWith('-') && !flags.threadId) {
      flags.threadId = arg;
      continue;
    }

    switch (arg) {
      case '-t':
      case '--thread':
        if (!next) {
          throw new Error('--thread flag requires a value');
        }
        flags.threadId = next;
        i++;
        break;
      case '--label':
        if (!next) {
          throw new Error('--label flag requires a value');
        }
        flags.label = next;
        i++;
        break;
      default:
        throw new Error(`Unknown flag for label command: ${arg}`);
    }
  }
  return flags;
}

function parseWaitFlags(args: string[]): WaitFlags {
  const flags: WaitFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];
    switch (arg) {
      case '--threads':
        if (!next) {
          throw new Error('--threads flag requires a comma-separated list of thread IDs');
        }
        flags.threads = next
          .split(',')
          .map((value) => value.trim())
          .filter(Boolean);
        i++;
        break;
      case '--labels':
        if (!next) {
          throw new Error('--labels flag requires a comma-separated list of labels');
        }
        flags.labels = next
          .split(',')
          .map((value) => value.trim())
          .filter(Boolean);
        i++;
        break;
      case '--all':
      case '--all-controller':
        flags.all = true;
        break;
      case '--interval-ms':
        if (!next) {
          throw new Error('--interval-ms flag requires a value');
        }
        flags.intervalMs = Number(next);
        if (Number.isNaN(flags.intervalMs) || flags.intervalMs! <= 0) {
          throw new Error('--interval-ms must be greater than 0');
        }
        i++;
        break;
      case '--timeout-ms':
        if (!next) {
          throw new Error('--timeout-ms flag requires a value');
        }
        flags.timeoutMs = Number(next);
        if (Number.isNaN(flags.timeoutMs) || flags.timeoutMs! <= 0) {
          throw new Error('--timeout-ms must be greater than 0');
        }
        i++;
        break;
      case '--follow-last':
        flags.followLast = true;
        break;
      default:
        throw new Error(`Unknown flag for wait command: ${arg}`);
    }
  }
  return flags;
}

interface WatchFlags {
  threadId?: string;
  intervalMs?: number;
  outputLastPath?: string;
  durationMs?: number;
}

function parseWatchFlags(args: string[]): WatchFlags {
  const flags: WatchFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];

    // Handle positional thread ID (first non-flag argument)
    if (!arg.startsWith('-') && !flags.threadId) {
      flags.threadId = arg;
      continue;
    }

    switch (arg) {
      case '-t':
      case '--thread':
        if (!next) {
          throw new Error('--thread flag requires a value');
        }
        flags.threadId = next;
        i++;
        break;
      case '--interval-ms':
        if (!next) {
          throw new Error('--interval-ms flag requires a value');
        }
        flags.intervalMs = Number(next);
        if (Number.isNaN(flags.intervalMs) || flags.intervalMs! < 1) {
          throw new Error('--interval-ms must be a positive integer');
        }
        i++;
        break;
      case '--save-response':
      case '--output-last':
        if (!next) {
          throw new Error('--save-response flag requires a path');
        }
        flags.outputLastPath = path.resolve(next);
        i++;
        break;
      case '--timeout-ms':
      case '--duration-ms':
        if (!next) {
          throw new Error('--timeout-ms flag requires a value');
        }
        flags.durationMs = Number(next);
        if (Number.isNaN(flags.durationMs) || flags.durationMs! < 1) {
          throw new Error('--timeout-ms must be a positive integer');
        }
        i++;
        break;
      default:
        throw new Error(`Unknown flag for watch command: ${arg}`);
    }
  }
  return flags;
}

function parseCleanFlags(args: string[]): CleanFlags {
  const flags: CleanFlags = {};
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = args[i + 1];
    switch (arg) {
      case '--older-than-days':
        if (!next) {
          throw new Error('--older-than-days flag requires a value');
        }
        flags.olderThanDays = Number(next);
        if (Number.isNaN(flags.olderThanDays) || flags.olderThanDays! <= 0) {
          throw new Error('--older-than-days must be greater than 0');
        }
        i++;
        break;
      case '--yes':
        flags.yes = true;
        break;
      case '--dry-run':
        flags.dryRun = true;
        break;
      default:
        throw new Error(`Unknown flag for clean command: ${arg}`);
    }
  }
  return flags;
}

function printHelp(): void {
  const lines = [
    'codex-subagent <command>',
    '',
    'Commands:',
    '  list            List stored threads (default)',
    '  start           Launch a new Codex exec thread',
    '  send            Send a new prompt to an existing thread (resume)',
    '  peek            Show the newest unseen assistant message for a thread',
    '  log             Print the stored log for a thread (no Codex call)',
    '  status          Summarize the latest activity for a thread',
    '  watch           Continuously peek a thread until interrupted',
    '  wait            Block until threads reach a stopped state',
    '  archive         Move completed thread logs/state into archive',
    '  label           Attach or update a friendly label for a thread',
    '  clean           Remove old archived threads to free disk space',
    '',
    'Options:',
    '  --root <path>          Override the .codex-subagent root directory',
    '  --controller-id <id>   Override auto-detected controller session ID',
    '  list flags:',
    '    --status <status>     Filter by status (running, completed, etc.)',
    '    --label <text>        Filter by label substring (case-insensitive)',
    '    --role <role>         Filter by exact role',
    '  start flags:',
    '    --role <name>              Required role (e.g., researcher)',
    '    --permissions <level>      Required: read-only or workspace-write',
    '    --profile <name>           Codex-only: custom profile (overrides permissions)',
    '    --backend <backend>        Backend: codex (default) or claude',
    '    --model <model>            Model to use (e.g., sonnet, opus, haiku)',
    '    --prompt <text|->          Prompt text directly, or - for stdin',
    '    -f, --prompt-file <path>   Prompt contents from file',
    '    --save-response <path>     Optional file for last message text',
    '    --cwd <path>               Optional working directory instruction for the subagent',
    '    --label <text>             Optional friendly label stored with the thread',
    '    --persona <name>           Optional persona to load from .codex/agents',
    '    --manifest <path|->        Launch multiple tasks from JSON manifest (use - for stdin)',
    '    --json <path|->            Alternative JSON input format (use - for stdin)',
    '    -w, --wait                 Block until finished (default: detach)',
    '  send flags:',
    '    <thread-id>                Positional thread ID (alternative to --thread)',
    '    -t, --thread <id>          Target thread to resume (required)',
    '    --prompt <text|->          Prompt text directly, or - for stdin',
    '    -f, --prompt-file <path>   Prompt contents from file',
    '    --save-response <path>     Optional file for last message text',
    '    --cwd <path>               Optional working directory instruction for the subagent',
    '    --persona <name>           Optional persona override for this turn',
    '    --json <path|->            Alternative JSON input format (use - for stdin)',
    '    -w, --wait                 Block until Codex finishes (default: detach)',
    '  peek flags:',
    '    <thread-id>             Positional thread ID (alternative to --thread)',
    '    -t, --thread <id>       Target thread to inspect (required)',
    '    --save-response <path>  Optional file for last message text',
    '    --verbose               Include last-activity metadata even when no updates',
    '  log flags:',
    '    <thread-id>        Positional thread ID (alternative to --thread)',
    '    -t, --thread <id>  Target thread to inspect (required)',
    '    --tail <n>         Optional number of most recent entries to show',
    '    --json             Output raw NDJSON lines',
    '    --verbose          Append last-activity metadata',
    '  status flags:',
    '    <thread-id>          Positional thread ID (alternative to --thread)',
    '    -t, --thread <id>    Target thread to inspect (required)',
    '    --tail <n>           Optional number of most recent entries to show',
    '    --json               Output raw NDJSON lines',
    '    --stale-minutes <n>  Override idle threshold for follow-up suggestion (default 15)',
    '  archive flags:',
    '    <thread-id>        Positional thread ID (alternative to --thread)',
    '    -t, --thread <id>  Archive a specific thread',
    '    --completed        Archive all completed threads (per controller)',
    '    --yes              Required to actually archive (safety guard)',
    '    --dry-run          Show what would archive without moving files',
    '  watch flags:',
    '    <thread-id>             Positional thread ID (alternative to --thread)',
    '    -t, --thread <id>       Target thread to watch (required)',
    '    --interval-ms <n>       Interval between peeks (default 5000)',
    '    --save-response <path>  Optional file for last message text',
    '    --timeout-ms <n>        Optional max runtime before exiting cleanly',
    '  label flags:',
    '    <thread-id>        Positional thread ID (alternative to --thread)',
    '    -t, --thread <id>  Target thread to label (required)',
    '    --label <text>     Friendly label text (empty string clears it)',
    '  wait flags:',
    '    --threads <ids>    Comma-separated thread IDs to wait on',
    '    --labels <labels>  Comma-separated labels to wait on',
    '    --all              Wait for every thread owned by this controller',
    '    --interval-ms <n>  Polling interval (default 5000)',
    '    --timeout-ms <n>   Optional timeout before exiting with failure',
    '    --follow-last      Print the last assistant message when each thread stops',
    '  clean flags:',
    '    --older-than-days <n> Age threshold in days (default 30)',
    '    --yes                 Required to actually delete (safety guard)',
    '    --dry-run             Show what would be deleted without removing files',
    '',
    'Examples:',
    '  # Launch with prompt from stdin (no tempfile needed)',
    '  echo "Research topic X" | codex-subagent start --role researcher --permissions read-only --prompt -',
    '  # Launch a detached researcher subagent with Codex',
    '  codex-subagent start --role researcher --permissions workspace-write --prompt-file task.txt',
    '  # Launch with Claude backend (requires CODEX_SUBAGENT_ENABLE_CLAUDE=1)',
    '  CODEX_SUBAGENT_ENABLE_CLAUDE=1 codex-subagent start --role researcher --permissions workspace-write --backend claude --prompt-file task.txt',
    '  # Resume a thread but wait for completion (positional thread ID)',
    '  codex-subagent send 019... --prompt-file followup.txt --wait',
    '  # Or with explicit --thread flag (both work)',
    '  codex-subagent send --thread 019... --prompt-file followup.txt --wait',
    '  # Peek the most recent assistant turn without resuming',
    '  codex-subagent peek 019...',
    '  # Watch for new turns for up to 60 seconds, then exit cleanly',
    '  codex-subagent watch 019... --timeout-ms 60000',
    '  # Give a friendly label to a thread',
    '  codex-subagent label 019... --label "Task 3 – log summaries"',
    '',
    'Notes:',
    '  start/send run detached unless you pass --wait.',
    '  watch never resumes the agent; it only replays peek output. Prefer peek/log when you just need the latest turn.',
  ];
  process.stdout.write(`${lines.join('\n')}\n`);
}

async function run(): Promise<void> {
  const {
    command,
    rootDir,
    controllerId: overrideControllerId,
    rest,
  } = parseArgs(process.argv.slice(2));
  const controllerId = getControllerId({ override: overrideControllerId });

  switch (command) {
    case 'list':
      try {
        const flags = parseListFlags(rest);
        await listCommand({
          rootDir,
          controllerId,
          filterStatus: flags.filterStatus,
          filterLabel: flags.filterLabel,
          filterRole: flags.filterRole,
        });
      } catch (error) {
        if (error instanceof RegistryLoadError) {
          process.stderr.write(`${error.message}\n`);
          process.exitCode = 1;
        } else {
          throw error;
        }
      }
      break;
    case 'start':
      try {
        const flags = parseStartFlags(rest);
        // Validate stdin conflicts
        const stdinSources = [
          flags.promptFromStdin && '--prompt -',
          flags.jsonFromStdin && '--json -',
          flags.manifestFromStdin && '--manifest -',
        ].filter(Boolean);
        if (stdinSources.length > 1) {
          throw new Error(`Cannot combine multiple stdin sources: ${stdinSources.join(', ')}`);
        }
        // Read prompt from stdin if requested
        let stdinPrompt: string | undefined;
        if (flags.promptFromStdin) {
          stdinPrompt = await readStdin();
          if (!stdinPrompt.trim()) {
            throw new Error('Prompt from stdin was empty.');
          }
        }
        let manifest: StartManifest | undefined;
        if (flags.manifestPath || flags.manifestFromStdin) {
          manifest = await loadManifestFromFlags(flags);
        }
        const { manifest: jsonManifest, single: jsonSingle } = await loadStartJsonPayload(flags);
        if (jsonManifest) {
          if (manifest) {
            throw new Error('Cannot combine --manifest with a JSON manifest payload.');
          }
          manifest = jsonManifest;
        }
        if (manifest) {
          if (flags.printPrompt || flags.dryRun) {
            throw new Error('--print-prompt/--dry-run are not supported with manifest mode yet.');
          }
          await startCommand({
            rootDir,
            controllerId,
            manifest,
            cliPath: CLI_ENTRY_PATH,
          });
          break;
        }
        const resolvedRole = jsonSingle?.role ?? flags.role ?? '';
        const resolvedPermissions = jsonSingle?.permissions ?? flags.permissions;
        const resolvedProfile = jsonSingle?.profile ?? flags.profile;
        const resolvedPromptFile = jsonSingle?.promptFile ?? flags.promptFile;
        const resolvedPromptBody = jsonSingle?.promptBody ?? stdinPrompt ?? flags.prompt;
        const resolvedWorkingDir = jsonSingle?.workingDir ?? flags.workingDir;
        const resolvedLabel = jsonSingle?.label ?? flags.label;
        const resolvedPersona = jsonSingle?.persona ?? flags.persona;
        const resolvedOutputLast = jsonSingle?.outputLastPath ?? flags.outputLastPath;
        const resolvedWait = jsonSingle?.wait ?? Boolean(flags.wait);
        await startCommand({
          rootDir,
          role: resolvedRole,
          permissions: resolvedPermissions,
          profile: resolvedProfile,
          promptFile: resolvedPromptFile,
          promptBody: resolvedPromptBody,
          outputLastPath: resolvedOutputLast,
          wait: resolvedWait,
          controllerId,
          workingDir: resolvedWorkingDir,
          label: resolvedLabel,
          personaName: resolvedPersona,
          printPrompt: Boolean(flags.printPrompt),
          dryRun: Boolean(flags.dryRun),
          cliPath: CLI_ENTRY_PATH,
          backend: flags.backend,
          model: flags.model,
        });
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'send':
      try {
        const flags = parseSendFlags(rest);
        // Validate stdin conflicts
        const stdinSources = [
          flags.promptFromStdin && '--prompt -',
          flags.jsonFromStdin && '--json -',
        ].filter(Boolean);
        if (stdinSources.length > 1) {
          throw new Error(`Cannot combine multiple stdin sources: ${stdinSources.join(', ')}`);
        }
        // Read prompt from stdin if requested
        let stdinPrompt: string | undefined;
        if (flags.promptFromStdin) {
          stdinPrompt = await readStdin();
          if (!stdinPrompt.trim()) {
            throw new Error('Prompt from stdin was empty.');
          }
        }
        const jsonPayload = await loadSendJsonPayload(flags);
        const resolvedPromptFile = jsonPayload?.promptFile ?? flags.promptFile;
        const resolvedPromptBody = jsonPayload?.promptBody ?? stdinPrompt ?? flags.prompt;
        const resolvedWorkingDir = jsonPayload?.workingDir ?? flags.workingDir;
        const resolvedPersona = jsonPayload?.persona ?? flags.persona;
        const resolvedOutputLast = jsonPayload?.outputLastPath ?? flags.outputLastPath;
        const resolvedWait = jsonPayload?.wait ?? Boolean(flags.wait);
        await sendCommand({
          rootDir,
          threadId: flags.threadId ?? '',
          promptFile: resolvedPromptFile,
          promptBody: resolvedPromptBody,
          outputLastPath: resolvedOutputLast,
          controllerId,
          wait: resolvedWait,
          workingDir: resolvedWorkingDir,
          personaName: resolvedPersona,
          printPrompt: Boolean(flags.printPrompt),
          dryRun: Boolean(flags.dryRun),
          cliPath: CLI_ENTRY_PATH,
        });
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'worker-start':
      try {
        await runWorkerStart(rest);
      } catch (error) {
        process.stderr.write(
          `Detached start failed: ${error instanceof Error ? error.message : String(error)}\n`
        );
        process.exitCode = 1;
      }
      break;
    case 'worker-send':
      try {
        await runWorkerSend(rest);
      } catch (error) {
        process.stderr.write(
          `Detached send failed: ${error instanceof Error ? error.message : String(error)}\n`
        );
        process.exitCode = 1;
      }
      break;
    case 'peek':
      try {
        const flags = parsePeekFlags(rest);
        await peekCommand({
          rootDir,
          threadId: flags.threadId ?? '',
          outputLastPath: flags.outputLastPath,
          verbose: Boolean(flags.verbose),
          controllerId,
        });
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'log':
      try {
        const flags = parseLogFlags(rest);
        await logCommand({
          rootDir,
          threadId: flags.threadId ?? '',
          tail: flags.tail,
          raw: Boolean(flags.raw),
          verbose: Boolean(flags.verbose),
          controllerId,
        });
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'status':
      try {
        const flags = parseStatusFlags(rest);
        await statusCommand({
          rootDir,
          threadId: flags.threadId ?? '',
          tail: flags.tail,
          raw: Boolean(flags.raw),
          staleMinutes: flags.staleMinutes,
          controllerId,
        });
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'watch':
      try {
        const flags = parseWatchFlags(rest);
        const controller = new AbortController();
        const handleSigint = () => {
          controller.abort();
        };
        process.on('SIGINT', handleSigint);
        try {
          await watchCommand({
            rootDir,
            threadId: flags.threadId ?? '',
            intervalMs: flags.intervalMs,
            outputLastPath: flags.outputLastPath,
            durationMs: flags.durationMs,
            signal: controller.signal,
            controllerId,
          });
        } finally {
          process.off('SIGINT', handleSigint);
        }
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'wait':
      try {
        const flags = parseWaitFlags(rest);
        const controller = new AbortController();
        const handleSigint = () => {
          controller.abort();
        };
        process.on('SIGINT', handleSigint);
        try {
          await waitCommand({
            rootDir,
            controllerId,
            threadIds: flags.threads,
            labels: flags.labels,
            includeAll: Boolean(flags.all),
            intervalMs: flags.intervalMs,
            timeoutMs: flags.timeoutMs,
            followLast: Boolean(flags.followLast),
            signal: controller.signal,
          });
        } finally {
          process.off('SIGINT', handleSigint);
        }
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'label':
      try {
        const flags = parseLabelFlags(rest);
        await labelCommand({
          rootDir,
          threadId: flags.threadId ?? '',
          label: flags.label ?? '',
          controllerId,
        });
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'archive':
      try {
        const flags = parseArchiveFlags(rest);
        await archiveCommand({
          rootDir,
          threadId: flags.threadId,
          completed: Boolean(flags.completed),
          yes: Boolean(flags.yes),
          dryRun: Boolean(flags.dryRun),
          controllerId,
        });
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'clean':
      try {
        const flags = parseCleanFlags(rest);
        await cleanCommand({
          rootDir,
          olderThanDays: flags.olderThanDays,
          yes: Boolean(flags.yes),
          dryRun: Boolean(flags.dryRun),
        });
      } catch (error) {
        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
        process.exitCode = 1;
      }
      break;
    case 'help':
    case '--help':
    case '-h':
      printHelp();
      break;
    default:
      process.stderr.write(`Unknown command: ${command}\n`);
      printHelp();
      process.exitCode = 1;
  }
}

async function runWorkerStart(rest: string[]): Promise<void> {
  const payload = decodeWorkerPayload(rest);
  const role = asString(payload.role);
  const permissions = asString(payload.permissions) as 'read-only' | 'workspace-write' | undefined;
  const profile = asString(payload.profile);
  const rootDir = asPath(payload.rootDir);
  const launchId = asString(payload.launchId);
  const paths = new Paths(rootDir);
  const launchRegistry = launchId ? new LaunchRegistry(paths) : undefined;
  if (!role) {
    throw new Error('worker payload missing role');
  }
  if (!permissions) {
    throw new Error('worker payload missing permissions');
  }

  const backend = asString(payload.backend) as 'codex' | 'claude' | undefined;
  const model = asString(payload.model);

  try {
    const result = await runStartThreadWorkflow({
      rootDir,
      role,
      permissions,
      profile,
      promptFile: asPath(payload.promptFile),
      promptBody: asString(payload.promptBody),
      outputLastPath: asPath(payload.outputLastPath),
      controllerId: asString(payload.controllerId) ?? '',
      workingDir: asPath(payload.workingDir),
      label: asString(payload.label),
      persona: asPersonaRuntime(payload.persona),
      launchId,
      backend,
      model,
    });
    if (launchRegistry && launchId) {
      await launchRegistry.markSuccess(launchId, { threadId: result.threadId });
    }
  } catch (error) {
    if (launchRegistry && launchId) {
      await launchRegistry.markFailure(launchId, { error });
    }
    throw error;
  }
}

async function runWorkerSend(rest: string[]): Promise<void> {
  const payload = decodeWorkerPayload(rest);
  const threadId = asString(payload.threadId);
  if (!threadId) {
    throw new Error('worker payload missing threadId');
  }

  const rootDir = asPath(payload.rootDir);
  const controllerId = asString(payload.controllerId) ?? '';
  const launchId = asString(payload.launchId);
  const paths = new Paths(rootDir);
  const launchRegistry = launchId ? new LaunchRegistry(paths) : undefined;

  try {
    await runSendThreadWorkflow({
      rootDir,
      threadId,
      promptFile: asPath(payload.promptFile),
      promptBody: asString(payload.promptBody),
      outputLastPath: asPath(payload.outputLastPath),
      controllerId,
      workingDir: asPath(payload.workingDir),
      personaName: asString(payload.personaName),
    });
    if (launchRegistry && launchId) {
      await launchRegistry.markSuccess(launchId, { threadId });
    }
  } catch (error) {
    if (launchRegistry && launchId) {
      await launchRegistry.markFailure(launchId, { error });
    }
    await markThreadError(paths, {
      threadId,
      controllerId,
      message: error instanceof Error ? error.message : String(error),
    });
    throw error;
  }
}

function decodeWorkerPayload(rest: string[]): Record<string, unknown> {
  const payloadIndex = rest.indexOf('--payload');
  if (payloadIndex === -1 || payloadIndex === rest.length - 1) {
    throw new Error('worker command requires --payload <base64>');
  }
  const base64 = rest[payloadIndex + 1];
  const json = Buffer.from(base64, 'base64').toString('utf8');
  try {
    const parsed = JSON.parse(json);
    if (parsed && typeof parsed === 'object') {
      return parsed as Record<string, unknown>;
    }
  } catch (error) {
    throw new Error(
      `failed to parse worker payload JSON: ${error instanceof Error ? error.message : String(error)}`
    );
  }
  throw new Error('worker payload must decode to an object');
}

function asString(value: unknown): string | undefined {
  return typeof value === 'string' && value.length > 0 ? value : undefined;
}

function asPath(value: unknown): string | undefined {
  if (typeof value !== 'string' || value.length === 0) {
    return undefined;
  }
  return path.resolve(value);
}

function asPersonaRuntime(value: unknown): PersonaRuntime | undefined {
  if (value && typeof value === 'object') {
    return value as PersonaRuntime;
  }
  return undefined;
}

run().catch((error) => {
  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
  process.exitCode = 1;
});