@fitlab-ai/agent-infra 0.9.3 → 0.9.5

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/git/worktree-identity.ts

@@ -0,0 +1,86 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+type GitWorktreeIdentity = Readonly<{
+  worktreeRoot: string;
+  commonDir: string;
+  branch: string;
+}>;
+
+function normalizeCanonicalPath(value: string, platform: NodeJS.Platform = process.platform): string {
+  return platform === 'win32'
+    ? path.win32.normalize(value).replaceAll('/', '\\').toLowerCase()
+    : path.posix.normalize(value);
+}
+
+function sameFilesystemEntry(left: string, right: string, platform: NodeJS.Platform = process.platform): boolean {
+  const leftReal = fs.realpathSync.native(left);
+  const rightReal = fs.realpathSync.native(right);
+  const leftStat = fs.statSync(leftReal, { bigint: true });
+  const rightStat = fs.statSync(rightReal, { bigint: true });
+  if (leftStat.ino !== 0n && rightStat.ino !== 0n) {
+    return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+  }
+  return normalizeCanonicalPath(leftReal, platform) === normalizeCanonicalPath(rightReal, platform);
+}
+
+function git(root: string, args: string[]): string {
+  return execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  }).trim();
+}
+
+function resolveGitWorktreeIdentity(worktreeRoot: string): GitWorktreeIdentity {
+  try {
+    const canonical = fs.realpathSync.native(worktreeRoot);
+    const topLevel = fs.realpathSync.native(git(canonical, ['rev-parse', '--show-toplevel']));
+    if (!sameFilesystemEntry(canonical, topLevel)) {
+      throw new Error('worktree root is not the Git top-level directory');
+    }
+    const commonDir = fs.realpathSync.native(git(canonical, [
+      'rev-parse', '--path-format=absolute', '--git-common-dir'
+    ]));
+    const branch = git(canonical, ['symbolic-ref', '--short', 'HEAD']);
+    return { worktreeRoot: canonical, commonDir, branch };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`SANDBOX_CONTROL_WORKTREE_INVALID: ${message}`);
+  }
+}
+
+function assertGitWorktreeBinding(
+  stateRoot: string,
+  worktreeRoot: string,
+  expectedBranch: string
+): GitWorktreeIdentity {
+  const state = resolveGitWorktreeIdentity(stateRoot);
+  const worktree = resolveGitWorktreeIdentity(worktreeRoot);
+  if (!sameFilesystemEntry(state.commonDir, worktree.commonDir)) {
+    throw new Error('SANDBOX_CONTROL_WORKTREE_INVALID: state and worktree roots have different Git common directories');
+  }
+  if (worktree.branch !== expectedBranch) {
+    throw new Error(`SANDBOX_CONTROL_WORKTREE_INVALID: expected branch '${expectedBranch}', got '${worktree.branch}'`);
+  }
+  return worktree;
+}
+
+function assertGitRepositoryBinding(stateRoot: string, worktreeRoot: string): GitWorktreeIdentity {
+  const state = resolveGitWorktreeIdentity(stateRoot);
+  const worktree = resolveGitWorktreeIdentity(worktreeRoot);
+  if (!sameFilesystemEntry(state.commonDir, worktree.commonDir)) {
+    throw new Error('SANDBOX_CONTROL_WORKTREE_INVALID: state and worktree roots have different Git common directories');
+  }
+  return worktree;
+}
+
+export {
+  assertGitWorktreeBinding,
+  assertGitRepositoryBinding,
+  normalizeCanonicalPath,
+  resolveGitWorktreeIdentity,
+  sameFilesystemEntry
+};
+export type { GitWorktreeIdentity };

package/lib/internal/codex-lifecycle.ts

@@ -0,0 +1,204 @@
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  preflightCodexLifecycleEvidence,
+  resolveCodexTerminal,
+  resolveCodexThread
+} from '../agent-clients/adapters/codex-lifecycle/app-server.ts';
+import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.ts';
+import type { CodexLifecycleEvent } from '../agent-clients/adapters/codex-lifecycle/evidence.ts';
+
+const USAGE = 'Usage: agent-infra-internal codex-lifecycle <hook-event|resolve-start|resolve-stop|preflight|consume> [options]\n';
+const MANAGED_AGENT = /^agent-infra-lifecycle-(executor|reviewer)$/;
+
+type Parsed = Readonly<{ operation: string; values: Readonly<Record<string, string>> }>;
+
+function output(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function failure(code: string, message: string): void {
+  output({ status: 'failed', changed: false, evidence: null, diagnostics: [], error: { code, message } });
+  process.exitCode = 1;
+}
+
+function parse(args: string[]): Parsed | null {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return null;
+  }
+  const operation = args[0];
+  if (!operation) {
+    failure('CODEX_LIFECYCLE_PAYLOAD_INVALID', 'operation is required');
+    return null;
+  }
+  const allowed = {
+    'hook-event': ['--event'],
+    'resolve-start': ['--child-id'],
+    'resolve-stop': ['--child-id'],
+    preflight: ['--format', '--session-id', '--turn-id', '--tool-use-id'],
+    consume: ['--child-id', '--consumer']
+  }[operation];
+  if (!allowed) {
+    failure('CODEX_LIFECYCLE_PAYLOAD_INVALID', 'unknown operation');
+    return null;
+  }
+  const values: Record<string, string> = {};
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!allowed.includes(flag) || Object.hasOwn(values, flag)) {
+      failure('CODEX_LIFECYCLE_PAYLOAD_INVALID', `invalid or duplicate option '${flag}'`);
+      return null;
+    }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      failure('CODEX_LIFECYCLE_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+      return null;
+    }
+    values[flag] = value;
+  }
+  return Object.freeze({ operation, values: Object.freeze(values) });
+}
+
+function cliVersion(): string {
+  const result = spawnSync('codex', ['--version'], { encoding: 'utf8' });
+  const version = /codex-cli\s+(\d+\.\d+\.\d+)/.exec(result.stdout ?? '')?.[1];
+  if (result.status !== 0 || !version) throw new Error('Codex CLI version is unavailable');
+  return version;
+}
+
+function hookDefinitionHash(): string {
+  const file = path.join(process.cwd(), '.codex', 'hooks.json');
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+async function readStdin(): Promise<unknown> {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    input += chunk;
+    if (Buffer.byteLength(input) > 64 * 1024) throw new Error('Codex lifecycle input exceeds 64 KiB');
+  }
+  return JSON.parse(input || '{}') as unknown;
+}
+
+function recordFromPayload(phase: string, payload: unknown): CodexLifecycleEvent | null {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('Codex lifecycle hook payload must be an object');
+  }
+  const value = payload as Record<string, unknown>;
+  const text = (key: string) => typeof value[key] === 'string' ? value[key] as string : '';
+  if (!MANAGED_AGENT.test(text('nativeAgent'))) return null;
+  if (phase === 'pre-tool') return {
+    type: 'hook-spawn',
+    sessionId: text('sessionId'),
+    turnId: text('turnId'),
+    toolUseId: text('toolUseId'),
+    nativeAgent: text('nativeAgent'),
+    ...(text('requestedModel') ? { requestedModel: text('requestedModel') } : {}),
+    ...(text('requestedReasoningEffort') ? { requestedReasoningEffort: text('requestedReasoningEffort') } : {}),
+    hookDefinitionHash: text('hookDefinitionHash')
+  };
+  if (phase === 'subagent-start') return {
+    type: 'hook-child',
+    sessionId: text('sessionId'),
+    turnId: text('turnId'),
+    childThreadId: text('childThreadId'),
+    nativeAgent: text('nativeAgent')
+  };
+  if (phase === 'subagent-stop') return {
+    type: 'hook-stop',
+    sessionId: text('sessionId'),
+    turnId: text('turnId'),
+    childThreadId: text('childThreadId'),
+    nativeAgent: text('nativeAgent')
+  };
+  if (phase === 'post-tool') return null;
+  throw new Error(`unknown Codex lifecycle hook phase '${phase}'`);
+}
+
+async function codexLifecycle(args: string[] = []): Promise<void> {
+  const parsed = parse(args);
+  if (!parsed || process.exitCode) return;
+  try {
+    if (parsed.operation === 'preflight') {
+      const format = parsed.values['--format'] ?? 'json';
+      if (!['text', 'json'].includes(format)) throw new Error("format must be 'text' or 'json'");
+      const runtimeFields = [
+        parsed.values['--session-id'],
+        parsed.values['--turn-id'],
+        parsed.values['--tool-use-id']
+      ];
+      if (runtimeFields.some(Boolean) && !runtimeFields.every(Boolean)) {
+        throw new Error('preflight runtime identity requires --session-id, --turn-id, and --tool-use-id together');
+      }
+      const runtimeIdentity = runtimeFields.every(Boolean) ? {
+        sessionId: runtimeFields[0]!,
+        turnId: runtimeFields[1]!,
+        toolUseId: runtimeFields[2]!
+      } : undefined;
+      const result = await preflightCodexLifecycleEvidence(process.cwd(), runtimeIdentity);
+      if (format === 'text') {
+        process.stdout.write(`Codex lifecycle static preflight: ready\nCLI: ${result.cliVersion}\nRuntime hook liveness: ${result.runtimeLiveness ? 'observed' : 'not-yet-observed'}\n`);
+      } else output({ status: 'ready', changed: false, evidence: result, diagnostics: result.diagnostics, error: null });
+      return;
+    }
+
+    const store = createCodexLifecycleStore({ cliVersion: cliVersion() });
+    if (parsed.operation === 'hook-event') {
+      const phase = parsed.values['--event'];
+      if (!phase || !['pre-tool', 'subagent-start', 'post-tool', 'subagent-stop'].includes(phase)) {
+        throw new Error('hook-event requires a known --event');
+      }
+      const event = recordFromPayload(phase, await readStdin());
+      if (!event) {
+        output({ status: 'ignored', changed: false, evidence: null, diagnostics: [], error: null });
+        return;
+      }
+      const result = store.apply(event);
+      output({ status: result.state.status, changed: true, evidence: result.state, diagnostics: [], error: result.state.error });
+      if (result.state.status === 'invalid') process.exitCode = 1;
+      return;
+    }
+
+    const childThreadId = parsed.values['--child-id'];
+    if (!childThreadId) throw new Error(`operation '${parsed.operation}' requires --child-id`);
+    if (parsed.operation === 'resolve-start') {
+      if (store.read(childThreadId).state.spawn?.hookDefinitionHash !== hookDefinitionHash()) {
+        throw new Error('Codex lifecycle hook definition hash is stale');
+      }
+      const resolved = await resolveCodexThread(childThreadId);
+      let latest = store.apply(resolved.resolution.thread);
+      for (const reroute of resolved.reroutes) latest = store.apply(reroute);
+      latest = store.apply(resolved.resolution.settings);
+      output({ status: latest.state.status, changed: true, evidence: latest.state.startEvidence, diagnostics: resolved.diagnostics, error: latest.state.error });
+      if (latest.state.status !== 'start-ready') process.exitCode = 1;
+      return;
+    }
+    if (parsed.operation === 'resolve-stop') {
+      const terminal = await resolveCodexTerminal(childThreadId);
+      const latest = store.apply(terminal);
+      if (latest.state.status !== 'stop-ready') {
+        throw new Error(`Codex lifecycle stop evidence is not ready (status=${latest.state.status})`);
+      }
+      output({ status: latest.state.status, changed: true, evidence: latest.state.stopEvidence, diagnostics: [], error: latest.state.error });
+      return;
+    }
+    if (parsed.operation === 'consume') {
+      const consumer = parsed.values['--consumer'];
+      if (!consumer) throw new Error('consume requires --consumer');
+      const consumed = store.consume(childThreadId, consumer, hookDefinitionHash());
+      output({ status: 'consumed', changed: true, evidence: {
+        start: consumed.state.startEvidence,
+        stop: consumed.state.stopEvidence
+      }, diagnostics: [], error: null });
+    }
+  } catch (error) {
+    failure('CODEX_LIFECYCLE_FAILED', error instanceof Error ? error.message : String(error));
+  }
+}
+
+export { codexLifecycle };

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-create.ts

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { requestSandboxTaskCreate } from '../sandbox/control/client.ts';
+import { SANDBOX_CONTROL_MAX_BYTES } from '../sandbox/control/protocol.ts';
+import { validateTaskCreateCandidate } from '../task/create.ts';
+import { createTask, type TaskCreateResult } from '../task/create-service.ts';
+
+function failed(code: string, message: string): TaskCreateResult {
+  return {
+    status: 'failed', changed: false, task: { id: null, shortId: null }, issue: null,
+    operations: [], warnings: [], error: { code, message, retryable: false }
+  };
+}
+
+function output(result: TaskCreateResult): void {
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0;
+}
+
+function taskCreate(args: string[]): void {
+  const inputIndex = args.indexOf('--input');
+  const input = inputIndex >= 0 ? args[inputIndex + 1] : undefined;
+  if (!input || args.length !== 2 || inputIndex !== 0) {
+    output(failed('TASK_CREATE_PAYLOAD_INVALID', 'Usage: agent-infra-internal task-create --input <candidate.json>'));
+    return;
+  }
+  try {
+    const inputPath = path.resolve(input);
+    const stat = fs.lstatSync(inputPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('TASK_CREATE_INPUT_INVALID: input must be a regular file');
+    if (stat.size > SANDBOX_CONTROL_MAX_BYTES) throw new Error('TASK_CREATE_INPUT_TOO_LARGE: input exceeds the control limit');
+    const candidate = validateTaskCreateCandidate(JSON.parse(fs.readFileSync(inputPath, 'utf8')));
+    if (process.env.AGENT_INFRA_CONTROL_TOKEN) {
+      const response = requestSandboxTaskCreate({ candidate });
+      process.stdout.write(response.stdout);
+      process.stderr.write(response.stderr);
+      process.exitCode = response.exitCode;
+      return;
+    }
+    output(createTask(candidate, { repoRoot: process.cwd() }));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'TASK_CREATE_INPUT_INVALID';
+    output(failed(code, message));
+  }
+}
+
+export { taskCreate };

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;
 }