@fitlab-ai/agent-infra 0.9.3 → 0.9.4

package/lib/agent-clients/adapters/opencode-sandbox.ts

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type {
+  AgentClientSandboxHook,
+  AgentClientSandboxRecoveryCheck
+} from '../../sandbox/tool-types.ts';
+
+type JsonObject = Record<string, unknown>;
+
+function readJsonObject(filePath: string): JsonObject | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as JsonObject
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveXdgRoot(value: string | undefined, fallback: string): string {
+  return typeof value === 'string' && value !== '' && path.isAbsolute(value)
+    ? value
+    : fallback;
+}
+
+function ensureOpenCodeSandboxState(
+  toolDir: string,
+  hostHome: string,
+  hostEnv: Readonly<NodeJS.ProcessEnv> = {}
+): void {
+  const canonicalConfigDir = path.join(toolDir, '.xdg', 'config', 'opencode');
+  const canonicalStateDir = path.join(toolDir, '.xdg', 'state', 'opencode');
+  const canonicalConfigPath = path.join(canonicalConfigDir, 'opencode.json');
+  const legacyConfigPath = path.join(toolDir, 'opencode.json');
+  fs.mkdirSync(canonicalConfigDir, { recursive: true });
+  fs.mkdirSync(canonicalStateDir, { recursive: true });
+
+  if (!fs.existsSync(canonicalConfigPath) && fs.existsSync(legacyConfigPath)) {
+    fs.copyFileSync(legacyConfigPath, canonicalConfigPath, fs.constants.COPYFILE_EXCL);
+  }
+
+  const hostConfigRoot = resolveXdgRoot(
+    hostEnv.XDG_CONFIG_HOME,
+    path.join(hostHome, '.config')
+  );
+  const hostConfig = readJsonObject(
+    path.join(hostConfigRoot, 'opencode', 'opencode.json')
+  );
+  if (!hostConfig) {
+    return;
+  }
+
+  let sandboxConfig: JsonObject = {};
+  if (fs.existsSync(canonicalConfigPath)) {
+    const existing = readJsonObject(canonicalConfigPath);
+    if (!existing) {
+      return;
+    }
+    sandboxConfig = existing;
+  }
+
+  let changed = false;
+  for (const key of ['model', 'small_model']) {
+    if (Object.hasOwn(sandboxConfig, key)) {
+      continue;
+    }
+    const value = hostConfig[key];
+    if (typeof value === 'string' && value !== '') {
+      sandboxConfig[key] = value;
+      changed = true;
+    }
+  }
+  if (changed) {
+    fs.writeFileSync(canonicalConfigPath, JSON.stringify(sandboxConfig, null, 2), 'utf8');
+  }
+}
+
+const opencodeBeforeContainerCreateHook: AgentClientSandboxHook = {
+  id: 'opencode-before-container-create',
+  phase: 'before-container-create',
+  async run(context) {
+    const create = context.create;
+    const entry = create?.resolvedTools.find(({ tool }) => tool.id === 'opencode');
+    if (!create || !entry) {
+      return {
+        status: 'fatal',
+        message: 'OpenCode sandbox hook requires its resolved tool state.'
+      };
+    }
+    ensureOpenCodeSandboxState(entry.dir, create.hostHome, create.hostEnv);
+    return { status: 'ready' };
+  }
+};
+
+const opencodeRecoveryChecks: readonly AgentClientSandboxRecoveryCheck[] = [
+  {
+    id: 'command-available',
+    probe: { script: 'command -v "$1"', args: ['opencode'] },
+    finding: {
+      repairKind: 'hard-failure',
+      message: 'OpenCode is not available on PATH inside the sandbox.'
+    }
+  },
+  {
+    id: 'config-writable',
+    probe: {
+      script: 'probe="$1/.agent-infra-opencode-config-$$"; trap \'rm -f -- "$probe"\' EXIT; : > "$probe"',
+      args: ['/home/devuser/.local/share/opencode/.xdg/config/opencode']
+    },
+    finding: {
+      repairKind: 'permissions',
+      message: 'OpenCode config directory is not writable by devuser.',
+      path: '/home/devuser/.local/share/opencode/.xdg/config/opencode'
+    }
+  },
+  {
+    id: 'state-writable',
+    probe: {
+      script: 'probe="$1/.agent-infra-opencode-state-$$"; trap \'rm -f -- "$probe"\' EXIT; : > "$probe"',
+      args: ['/home/devuser/.local/share/opencode/.xdg/state/opencode']
+    },
+    finding: {
+      repairKind: 'permissions',
+      message: 'OpenCode state directory is not writable by devuser.',
+      path: '/home/devuser/.local/share/opencode/.xdg/state/opencode'
+    }
+  }
+];
+
+export {
+  ensureOpenCodeSandboxState,
+  opencodeBeforeContainerCreateHook,
+  opencodeRecoveryChecks
+};

package/lib/agent-clients/adapters/opencode.ts

@@ -1,5 +1,9 @@
 import { defineAgentClientAdapter } from '../adapter.ts';
 import { hostJoin } from '../../sandbox/engines/wsl2-paths.ts';
+import {
+  opencodeBeforeContainerCreateHook,
+  opencodeRecoveryChecks
+} from './opencode-sandbox.ts';
 
 const YOLO_PERMISSION = '{"*":"allow","read":"allow","bash":"allow","edit":"allow","webfetch":"allow","external_directory":"allow","doom_loop":"allow"}';
 
@@ -37,9 +41,17 @@ const opencodeAdapter = defineAgentClientAdapter({
         'zh-CN': '.opencode/commands/update-agent-infra.zh-CN.md'
       },
       target: '.opencode/commands/update-agent-infra.md'
-    }]
+    }],
+    customCommand: {
+      target: '.opencode/commands/${skillName}.md',
+      frontmatter: { agent: 'general', subtask: false },
+      argumentsToken: '$ARGUMENTS'
+    }
   },
   sandbox: {
+    image: {
+      dotfilesExclusions: ['.config/opencode']
+    },
     createTool: ({ home }) => ({
       id: 'opencode',
       name: 'OpenCode',
@@ -49,7 +61,9 @@ const opencodeAdapter = defineAgentClientAdapter({
       versionCmd: 'opencode --version',
       setupHint: 'Configure OpenCode credentials inside the container before first use.',
       envVars: {
-        OPENCODE_CONFIG: '/home/devuser/.local/share/opencode/opencode.json'
+        XDG_DATA_HOME: '/home/devuser/.local/share',
+        XDG_CONFIG_HOME: '/home/devuser/.local/share/opencode/.xdg/config',
+        XDG_STATE_HOME: '/home/devuser/.local/share/opencode/.xdg/state'
       },
       hostLiveMounts: [
         {
@@ -68,7 +82,8 @@ const opencodeAdapter = defineAgentClientAdapter({
         command: `OPENCODE_PERMISSION='${YOLO_PERMISSION}' opencode; tput ed`
       }
     ],
-    hooks: []
+    hooks: [opencodeBeforeContainerCreateHook],
+    recoveryChecks: opencodeRecoveryChecks
   }
 });
 

package/lib/agent-clients/adapters/runtimes/claude-code.dockerfile

@@ -0,0 +1,65 @@
+RUN cat > /usr/local/bin/cc-token-status <<'SCRIPT' && chmod +x /usr/local/bin/cc-token-status
+#!/bin/sh
+set -eu
+
+SETTINGS_FILE="/home/devuser/.claude/settings.json"
+if [ -r "$SETTINGS_FILE" ] && jq -e '
+  def has_nonempty($v):
+    if ($v | type) == "string" then ($v | gsub("^\\s+|\\s+$"; "") | length) > 0 else false end;
+  (if type == "object" then . else {} end) as $settings
+  | (if ($settings.env | type) == "object" then $settings.env else {} end) as $env
+  | has_nonempty($env.ANTHROPIC_AUTH_TOKEN)
+    or has_nonempty($env.ANTHROPIC_API_KEY)
+    or has_nonempty($settings.apiKeyHelper)
+' "$SETTINGS_FILE" >/dev/null 2>&1; then
+  exit 0
+fi
+
+CRED_FILE="/home/devuser/.claude/.credentials.json"
+[ -r "$CRED_FILE" ] || exit 0
+
+EXPIRES_MS=$(jq -r '(.claudeAiOauth.expiresAt // .expiresAt) // empty' "$CRED_FILE" 2>/dev/null || true)
+case "$EXPIRES_MS" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+
+NOW_MS=$(($(date +%s) * 1000))
+DIFF_MS=$((EXPIRES_MS - NOW_MS))
+DIFF_S=$((DIFF_MS / 1000))
+
+DIM='#[fg=colour245]'
+YELLOW='#[fg=yellow]'
+YELLOW_BOLD='#[fg=yellow,bold]'
+RED_BOLD='#[fg=red,bold]'
+RED_REV='#[fg=red,reverse]'
+RESET='#[default]'
+
+if [ "$DIFF_S" -le 0 ]; then
+  ELAPSED=$(( -DIFF_S ))
+  M=$((ELAPSED / 60))
+  printf '%sClaude Code auth EXPIRED %dm ago%s' "$RED_REV" "$M" "$RESET"
+elif [ "$DIFF_S" -lt 60 ]; then
+  printf '%sClaude Code auth expires in %ds%s' "$RED_BOLD" "$DIFF_S" "$RESET"
+elif [ "$DIFF_S" -lt 300 ]; then
+  M=$((DIFF_S / 60))
+  S=$((DIFF_S % 60))
+  printf '%sClaude Code auth expires in %dm %ds%s' "$RED_BOLD" "$M" "$S" "$RESET"
+elif [ "$DIFF_S" -lt 1800 ]; then
+  M=$((DIFF_S / 60))
+  printf '%sClaude Code auth expires in %dm%s' "$YELLOW_BOLD" "$M" "$RESET"
+elif [ "$DIFF_S" -lt 3600 ]; then
+  M=$((DIFF_S / 60))
+  printf '%sClaude Code auth expires in %dm%s' "$YELLOW" "$M" "$RESET"
+else
+  TOTAL_M=$((DIFF_S / 60))
+  H=$((TOTAL_M / 60))
+  M=$((TOTAL_M % 60))
+  printf '%sClaude Code auth expires in %dh %dm%s' "$DIM" "$H" "$M" "$RESET"
+fi
+SCRIPT
+
+RUN test -s /usr/local/bin/cc-token-status && test -x /usr/local/bin/cc-token-status
+
+RUN printf '%s\n' \
+      "set -g status-right '#(/usr/local/bin/cc-token-status) | %H:%M'" \
+    >> /etc/tmux.conf

package/lib/agent-clients/registry.ts

@@ -135,7 +135,15 @@ function createAgentClientManifest(): readonly AgentClientManifestEntry[] {
       ownedPathPrefixes: Object.freeze([...adapter.project.ownedPathPrefixes]),
       managed: Object.freeze([...adapter.project.managed]),
       merged: Object.freeze([...adapter.project.merged]),
-      ejected: Object.freeze([...adapter.project.ejected])
+      ejected: Object.freeze([...adapter.project.ejected]),
+      ...(adapter.project.customCommand === undefined
+        ? {}
+        : {
+          customCommand: Object.freeze({
+            ...adapter.project.customCommand,
+            frontmatter: Object.freeze({ ...adapter.project.customCommand.frontmatter })
+          })
+        })
     }))
   );
 }

package/lib/internal/sandbox-control.ts

@@ -0,0 +1,24 @@
+import { requestSandboxControl } from '../sandbox/control/client.ts';
+import { serveSandboxControl } from '../sandbox/control/server.ts';
+
+function sandboxControl(args: string[]): void {
+  const [operation, ...rest] = args;
+  if (operation === 'serve') {
+    const manifestIndex = rest.indexOf('--manifest');
+    const manifest = manifestIndex >= 0 ? rest[manifestIndex + 1] : undefined;
+    if (!manifest) throw new Error('sandbox-control serve requires --manifest');
+    serveSandboxControl(manifest);
+    return;
+  }
+  if (operation === 'client') {
+    const [family = '', ...commandArgs] = rest;
+    const response = requestSandboxControl({ family, args: commandArgs });
+    process.stdout.write(response.stdout);
+    process.stderr.write(response.stderr);
+    process.exitCode = response.exitCode;
+    return;
+  }
+  throw new Error('Usage: agent-infra-internal sandbox-control serve --manifest <path> | client <family> [args...]');
+}
+
+export { sandboxControl };

package/lib/internal/task-activity.ts

@@ -1,13 +1,36 @@
-import { applyActivityAppendIntent } from '../task/activity-intent.ts';
-import type { ActivityAppendIntent } from '../task/activity-intent.ts';
+import {
+  applyPrReviewActivityIntent,
+  inspectPrReviewActivity
+} from '../task/activity-intent.ts';
+import type {
+  PrReviewActivityIntent,
+  PrReviewInspectIntent
+} from '../task/activity-intent.ts';
 
-const USAGE = `Usage: agent-infra-internal task-activity <task-ref> append --step <step> --agent <agent> --note <note> [--artifact <canonical.md>] [--dry-run]
+const USAGE = `Usage: agent-infra-internal task-activity <task-ref> pr-review-inspect
+       agent-infra-internal task-activity <task-ref> pr-review-start --agent <agent> --artifact <canonical.md> --head <40hex> [--dry-run]
+       agent-infra-internal task-activity <task-ref> pr-review-complete --agent <agent> --artifact <canonical.md> --head <40hex> --verdict <approved|changes-requested|commented> --blockers <N> --major <N> --minor <N> [--dry-run]
+       agent-infra-internal task-activity <task-ref> pr-review-terminate --agent <agent> --artifact <canonical.md> --head <40hex> --outcome <aborted|superseded> --reason <single-line> [--dry-run]
 `;
+
+const OPERATIONS = new Set(['pr-review-inspect', 'pr-review-start', 'pr-review-complete', 'pr-review-terminate']);
 const FLAGS: Record<string, string> = {
-  '--step': 'step',
   '--agent': 'agent',
-  '--note': 'note',
-  '--artifact': 'artifact'
+  '--artifact': 'artifact',
+  '--head': 'head',
+  '--verdict': 'verdict',
+  '--blockers': 'blockers',
+  '--major': 'major',
+  '--minor': 'minor',
+  '--outcome': 'outcome',
+  '--reason': 'reason'
+};
+const COMMON = ['agent', 'artifact', 'head'] as const;
+const ALLOWED: Record<string, ReadonlySet<string>> = {
+  'pr-review-inspect': new Set(['kind', 'taskRef']),
+  'pr-review-start': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'dryRun']),
+  'pr-review-complete': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'verdict', 'blockers', 'major', 'minor', 'dryRun']),
+  'pr-review-terminate': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'outcome', 'reason', 'dryRun'])
 };
 
 function usageFailure(message: string): void {
@@ -19,8 +42,8 @@ function usageFailure(message: string): void {
 function taskActivity(args: string[] = []): void {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const [taskRef, kind] = args;
-  if (!taskRef || taskRef.startsWith('--') || !kind || kind !== 'append') {
-    usageFailure('task ref and the append intent are required');
+  if (!taskRef || taskRef.startsWith('--') || !kind || !OPERATIONS.has(kind)) {
+    usageFailure('task ref and a supported PR review intent are required');
     return;
   }
   const values: Record<string, unknown> = { kind, taskRef };
@@ -39,15 +62,28 @@ function taskActivity(args: string[] = []): void {
     const value = args[++index];
     if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
     seen.add(flag);
-    values[key] = value;
+    values[key] = ['blockers', 'major', 'minor'].includes(key) ? Number(value) : value;
   }
-  const allowed = new Set(['kind', 'taskRef', 'dryRun', 'step', 'agent', 'note', 'artifact']);
+
+  const allowed = ALLOWED[kind]!;
   const unexpected = Object.keys(values).find((key) => !allowed.has(key));
-  if (unexpected) { usageFailure(`append does not accept '${unexpected}'`); return; }
-  for (const key of ['step', 'agent', 'note']) {
-    if (values[key] === undefined) { usageFailure(`append requires '${key}'`); return; }
+  if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
+  if (kind === 'pr-review-inspect') {
+    const result = inspectPrReviewActivity(values as PrReviewInspectIntent);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed') process.exitCode = 1;
+    return;
+  }
+  for (const key of COMMON) {
+    if (values[key] === undefined) { usageFailure(`${kind} requires '${key}'`); return; }
+  }
+  const operationRequired = kind === 'pr-review-complete'
+    ? ['verdict', 'blockers', 'major', 'minor']
+    : kind === 'pr-review-terminate' ? ['outcome', 'reason'] : [];
+  for (const key of operationRequired) {
+    if (values[key] === undefined) { usageFailure(`${kind} requires '${key}'`); return; }
   }
-  const result = applyActivityAppendIntent(values as ActivityAppendIntent);
+  const result = applyPrReviewActivityIntent(values as PrReviewActivityIntent);
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;
 }

package/lib/internal/task-ledger.ts

@@ -9,9 +9,10 @@ const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [inte
 const FLAGS: Record<string, string> = {
   '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
   '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
-  '--status': 'status', '--artifact': 'artifact'
+  '--status': 'status', '--artifact': 'artifact', '--needs-implementation': 'needsImplementation'
 };
 const NUMERIC = new Set(['ordinal', 'round']);
+const BOOLEAN = new Set(['needsImplementation']);
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LEDGER_PAYLOAD_INVALID', message } })}\n`);
@@ -39,7 +40,11 @@ function taskLedger(args: string[] = []): void {
     if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
     const value = args[++index];
     if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
-    seen.add(flag); values[key] = NUMERIC.has(key) ? Number(value) : value;
+    if (BOOLEAN.has(key) && value !== 'true' && value !== 'false') {
+      usageFailure(`option '${flag}' must be true or false`); return;
+    }
+    seen.add(flag);
+    values[key] = NUMERIC.has(key) ? Number(value) : BOOLEAN.has(key) ? value === 'true' : value;
   }
   const required: Record<string, string[]> = {
     'finding-upsert': ['stage', 'reviewArtifact', 'ordinal', 'severity', 'evidence'],
@@ -49,7 +54,11 @@ function taskLedger(args: string[] = []): void {
     'decision-upsert': ['id', 'stage', 'artifact'],
     'stage-status': ['stage']
   };
-  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!]);
+  const optional: Record<string, string[]> = {
+    'finding-review': ['needsImplementation'],
+    'decision-upsert': ['needsImplementation']
+  };
+  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...(optional[kind] ?? [])]);
   const unexpected = Object.keys(values).find((key) => !allowed.has(key));
   const missing = required[kind]!.find((key) => values[key] === undefined);
   if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }

package/lib/internal/task-lifecycle.ts

@@ -1,6 +1,8 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { applyTaskLifecycle, lifecycleIntentCatalog } from '../task/lifecycle.ts';
 import type { TaskLifecycleRequest } from '../task/lifecycle.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
 const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\n`;
 const FLAGS: Record<string, string> = {
@@ -37,7 +39,26 @@ function taskLifecycle(args: string[] = []): void {
   const agent = normalizeAgentToken(String(values.agent ?? ''));
   if (!agent) { usageFailure(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
   values.agent = agent;
-  const result = applyTaskLifecycle(values as TaskLifecycleRequest);
+  const resolved = resolveTaskRef(String(values.taskRef));
+  if (!resolved.ok) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  let result: ReturnType<typeof applyTaskLifecycle>;
+  try {
+    result = withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      `task-lifecycle.${String(values.intent)}`,
+      () => applyTaskLifecycle(values as TaskLifecycleRequest)
+    );
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;
 }

package/lib/internal/task-orchestration.ts

@@ -1,21 +1,26 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
+  abortCommitIntent,
   activateMatchingOrchestrationDelegation,
   activateOrchestrationDelegation,
   advanceOrchestration,
+  beginCommitIntent,
   beginOrResumeOrchestration,
-  completeCommitOrchestrationStage,
+  checkpointCommitIntent,
+  completeCommitIntent,
   pauseOrchestration,
   prepareOrchestrationDelegation,
+  recoverCommitIntent,
   routeOrchestration,
   sealMatchingOrchestrationDelegation,
   sealOrchestrationDelegation,
+  statusCommitIntent,
   statusOrchestration
 } from '../task/orchestration.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
 import type { AgentClientId } from '../agent-clients/types.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|hook-start|stage-completed|hook-stop|advance|pause|status> [options]\n';
+const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|hook-start|hook-stop|advance|pause|status|commit-begin|commit-checkpoint|commit-complete|commit-recover|commit-abort|commit-status> [options]\n';
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({
@@ -36,21 +41,32 @@ function taskOrchestration(args: string[] = []): void {
     return;
   }
   const [taskRef, intent] = args;
-  if (!['begin-or-resume', 'route', 'prepare', 'hook-start', 'stage-completed', 'hook-stop', 'advance', 'pause', 'status'].includes(intent!)) {
+  if (![
+    'begin-or-resume', 'route', 'prepare', 'hook-start', 'hook-stop', 'advance', 'pause', 'status',
+    'commit-begin', 'commit-checkpoint', 'commit-complete', 'commit-recover', 'commit-abort', 'commit-status'
+  ].includes(intent!)) {
     usageFailure(`unknown intent '${intent}'`);
     return;
   }
   const values: Record<string, string> = {};
   const seen = new Set<string>();
+  let orchestrated = false;
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;
+    if (flag === '--orchestrated') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag);
+      orchestrated = true;
+      continue;
+    }
     if (![
       '--max-steps', '--executor-model', '--executor-reasoning-effort',
       '--reviewer-model', '--reviewer-reasoning-effort',
       '--client', '--requested-model', '--requested-reasoning-effort', '--parent-id', '--before-fingerprint',
       '--native-agent', '--child-id', '--spawn-mode', '--actual-model', '--actual-reasoning-effort',
       '--model-fallback-reason', '--reasoning-effort-fallback-reason',
-      '--exit-code', '--after-fingerprint', '--changed-paths', '--code', '--message', '--recoverable', '--agent'
+      '--exit-code', '--after-fingerprint', '--changed-paths', '--code', '--message', '--recoverable', '--agent',
+      '--baseline-head', '--token', '--kind', '--head', '--remote', '--ref', '--expected-head'
     ].includes(flag)) {
       usageFailure(`unknown option '${flag}'`);
       return;
@@ -67,13 +83,73 @@ function taskOrchestration(args: string[] = []): void {
     }
     values[flag] = value;
   }
+  const commitIntentFlags: Record<string, readonly string[]> = {
+    'commit-begin': ['--agent', '--baseline-head', '--orchestrated'],
+    'commit-checkpoint': ['--token', '--kind', '--head', '--remote', '--ref'],
+    'commit-complete': ['--token', '--agent'],
+    'commit-recover': ['--agent'],
+    'commit-abort': ['--token', '--expected-head'],
+    'commit-status': []
+  };
+  if (intent! in commitIntentFlags) {
+    const allowed = commitIntentFlags[intent!]!;
+    const invalid = [...seen].find((flag) => !allowed.includes(flag));
+    if (invalid) { usageFailure(`intent '${intent}' does not accept '${invalid}'`); return; }
+  } else {
+    const commitOnly = [...seen].find((flag) => [
+      '--orchestrated', '--baseline-head', '--token', '--kind', '--head', '--remote', '--ref', '--expected-head'
+    ].includes(flag));
+    if (commitOnly) { usageFailure(`intent '${intent}' does not accept '${commitOnly}'`); return; }
+  }
   const requireValues = (flags: string[]) => flags.find((flag) => values[flag] === undefined);
   if (values['--client'] !== undefined && !isAgentClientId(values['--client'])) {
     usageFailure(`unknown client '${values['--client']}'`);
     return;
   }
   let result;
-  if (intent === 'begin-or-resume') {
+  if (intent === 'commit-begin') {
+    const missing = requireValues(['--agent', '--baseline-head']);
+    if (missing) { usageFailure(`intent 'commit-begin' requires '${missing}'`); return; }
+    const agent = normalizeAgentToken(values['--agent']!);
+    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
+    result = beginCommitIntent(taskRef!, {
+      agent, orchestrated, baselineHead: values['--baseline-head']!
+    });
+  } else if (intent === 'commit-checkpoint') {
+    const missing = requireValues(['--token', '--kind', '--head']);
+    if (missing) { usageFailure(`intent 'commit-checkpoint' requires '${missing}'`); return; }
+    if (!['committed', 'pushed'].includes(values['--kind']!)) {
+      usageFailure('--kind must be committed or pushed'); return;
+    }
+    if (values['--kind'] === 'pushed') {
+      const pushedMissing = requireValues(['--remote', '--ref']);
+      if (pushedMissing) { usageFailure(`pushed checkpoint requires '${pushedMissing}'`); return; }
+    } else if (values['--remote'] !== undefined || values['--ref'] !== undefined) {
+      usageFailure('committed checkpoint does not accept --remote or --ref'); return;
+    }
+    result = checkpointCommitIntent(taskRef!, {
+      token: values['--token']!, kind: values['--kind'] as 'committed' | 'pushed',
+      head: values['--head']!, remote: values['--remote'], ref: values['--ref']
+    });
+  } else if (intent === 'commit-complete') {
+    const missing = requireValues(['--token', '--agent']);
+    if (missing) { usageFailure(`intent 'commit-complete' requires '${missing}'`); return; }
+    const agent = normalizeAgentToken(values['--agent']!);
+    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
+    result = completeCommitIntent(taskRef!, { token: values['--token']!, agent });
+  } else if (intent === 'commit-recover') {
+    const missing = requireValues(['--agent']);
+    if (missing) { usageFailure(`intent 'commit-recover' requires '${missing}'`); return; }
+    const agent = normalizeAgentToken(values['--agent']!);
+    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
+    result = recoverCommitIntent(taskRef!, { agent });
+  } else if (intent === 'commit-abort') {
+    const missing = requireValues(['--token', '--expected-head']);
+    if (missing) { usageFailure(`intent 'commit-abort' requires '${missing}'`); return; }
+    result = abortCommitIntent(taskRef!, { token: values['--token']!, expectedHead: values['--expected-head']! });
+  } else if (intent === 'commit-status') {
+    result = statusCommitIntent(taskRef!);
+  } else if (intent === 'begin-or-resume') {
     const missing = requireValues(['--client']);
     if (missing) { usageFailure(`intent 'begin-or-resume' requires '${missing}'`); return; }
     const maxSteps = values['--max-steps'] === undefined ? undefined : Number(values['--max-steps']);
@@ -150,12 +226,6 @@ function taskOrchestration(args: string[] = []): void {
         changedPaths: values['--changed-paths'] ? values['--changed-paths']!.split(',').filter(Boolean) : []
       });
     }
-  } else if (intent === 'stage-completed') {
-    const missing = requireValues(['--agent']);
-    if (missing) { usageFailure(`intent 'stage-completed' requires '${missing}'`); return; }
-    const agent = normalizeAgentToken(values['--agent']!);
-    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
-    result = completeCommitOrchestrationStage(taskRef!, agent);
   } else if (intent === 'advance') {
     result = advanceOrchestration(taskRef!);
   } else {

package/lib/platform/github-client.ts

@@ -24,6 +24,15 @@ type ClientOptions = {
 };
 
 const MINIMUM_GITHUB_CLI_VERSION = '2.16.0';
+const GITHUB_CLI_MAX_BUFFER = 64 * 1024 * 1024;
+const ERROR_DETAIL_LIMIT = 4096;
+
+function boundedFailureDetail(result: RunResult): string {
+  const diagnostic = `${result.stderr}\n${result.error?.message || ''}`.trim() || result.stdout.trim();
+  return diagnostic.length <= ERROR_DETAIL_LIMIT
+    ? diagnostic
+    : `${diagnostic.slice(0, ERROR_DETAIL_LIMIT)}… [truncated]`;
+}
 
 function defaultRunner(args: string[], options: RunOptions): RunResult {
   const command = process.env.AGENT_INFRA_GH_BIN || 'gh';
@@ -38,6 +47,7 @@ function defaultRunner(args: string[], options: RunOptions): RunResult {
     encoding: 'utf8',
     env: process.env,
     input: options.input,
+    maxBuffer: GITHUB_CLI_MAX_BUFFER,
     shell: false
   });
   return {
@@ -60,7 +70,15 @@ function defaultSleep(delayMs: number): void {
 }
 
 function classifyGitHubFailure(result: RunResult): PlatformError {
-  const detail = `${result.stderr}\n${result.stdout}\n${result.error?.message || ''}`.trim();
+  const errorCode = result.error && 'code' in result.error ? (result.error as NodeJS.ErrnoException).code : undefined;
+  if (errorCode === 'ENOBUFS') {
+    return {
+      code: 'PLATFORM_OUTPUT_TOO_LARGE',
+      message: 'GitHub CLI output exceeded the configured limit',
+      retryable: false
+    };
+  }
+  const detail = boundedFailureDetail(result);
   const lower = detail.toLowerCase();
   if (/\b401\b|bad credentials|authentication required|not logged into/.test(lower)) {
     return { code: 'AUTH_REQUIRED', message: detail || 'GitHub authentication is required', retryable: false };
@@ -77,7 +95,7 @@ function classifyGitHubFailure(result: RunResult): PlatformError {
   if (/\b422\b|validation failed/.test(lower)) {
     return { code: 'PLATFORM_REQUEST_INVALID', message: detail || 'GitHub rejected the request', retryable: false };
   }
-  if (result.error && 'code' in result.error && (result.error as NodeJS.ErrnoException).code === 'ENOENT') {
+  if (errorCode === 'ENOENT') {
     return { code: 'PLATFORM_DEPENDENCY_MISSING', message: detail || 'GitHub CLI is unavailable', retryable: false };
   }
   return { code: 'PLATFORM_REQUEST_FAILED', message: detail || 'GitHub request failed', retryable: false };