@fitlab-ai/agent-infra 0.9.3 → 0.9.5

package/lib/internal/task-orchestration.ts

@@ -1,21 +1,28 @@
 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,
-  statusOrchestration
+  startCommitAttempt,
+  statusCommitIntent,
+  statusOrchestration,
+  terminateCommitAttempt
 } 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-start|commit-begin|commit-checkpoint|commit-complete|commit-recover|commit-abort|commit-terminate|commit-status> [options]\n';
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({
@@ -36,21 +43,33 @@ 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-start', 'commit-begin', 'commit-checkpoint', 'commit-complete', 'commit-recover', 'commit-abort', 'commit-terminate', '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'
+      , '--attempt', '--git-worktree-root'
     ].includes(flag)) {
       usageFailure(`unknown option '${flag}'`);
       return;
@@ -67,13 +86,95 @@ function taskOrchestration(args: string[] = []): void {
     }
     values[flag] = value;
   }
+  const commitIntentFlags: Record<string, readonly string[]> = {
+    'commit-start': ['--agent', '--git-worktree-root'],
+    'commit-begin': ['--agent', '--baseline-head', '--attempt', '--orchestrated', '--git-worktree-root'],
+    'commit-checkpoint': ['--token', '--kind', '--head', '--remote', '--ref', '--git-worktree-root'],
+    'commit-complete': ['--token', '--agent', '--git-worktree-root'],
+    'commit-recover': ['--agent', '--git-worktree-root'],
+    'commit-abort': ['--token', '--expected-head', '--git-worktree-root'],
+    'commit-terminate': ['--attempt', '--agent', '--code', '--git-worktree-root'],
+    'commit-status': ['--git-worktree-root']
+  };
+  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', '--attempt', '--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);
+  const coreOptions = values['--git-worktree-root'] === undefined
+    ? {}
+    : { gitWorktreeRoot: values['--git-worktree-root'] };
   if (values['--client'] !== undefined && !isAgentClientId(values['--client'])) {
     usageFailure(`unknown client '${values['--client']}'`);
     return;
   }
   let result;
-  if (intent === 'begin-or-resume') {
+  if (intent === 'commit-start') {
+    const missing = requireValues(['--agent']);
+    if (missing) { usageFailure(`intent 'commit-start' requires '${missing}'`); return; }
+    const agent = normalizeAgentToken(values['--agent']!);
+    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
+    result = startCommitAttempt(taskRef!, { agent }, coreOptions);
+  } else if (intent === 'commit-begin') {
+    const missing = requireValues(['--agent', '--baseline-head', '--attempt']);
+    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']!, attempt: values['--attempt']!
+    }, coreOptions);
+  } 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']
+    }, coreOptions);
+  } 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 }, coreOptions);
+  } 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 }, coreOptions);
+  } 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']! }, coreOptions);
+  } else if (intent === 'commit-terminate') {
+    const missing = requireValues(['--attempt', '--agent', '--code']);
+    if (missing) { usageFailure(`intent 'commit-terminate' requires '${missing}'`); return; }
+    const agent = normalizeAgentToken(values['--agent']!);
+    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
+    if (!/^[A-Z][A-Z0-9_]{2,63}$/.test(values['--code']!)) {
+      usageFailure('--code must be a stable uppercase identifier'); return;
+    }
+    result = terminateCommitAttempt(taskRef!, {
+      attempt: values['--attempt']!, agent, code: values['--code']!
+    }, coreOptions);
+  } else if (intent === 'commit-status') {
+    result = statusCommitIntent(taskRef!, coreOptions);
+  } 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']);
@@ -90,6 +191,7 @@ function taskOrchestration(args: string[] = []): void {
       return;
     }
     result = beginOrResumeOrchestration(taskRef!, {
+      ...coreOptions,
       maxSteps,
       client: values['--client'] as AgentClientId,
       modelPolicy: hasAnyPolicy ? {
@@ -104,9 +206,9 @@ function taskOrchestration(args: string[] = []): void {
       } : undefined
     });
   } else if (intent === 'route') {
-    result = routeOrchestration(taskRef!);
+    result = routeOrchestration(taskRef!, coreOptions);
   } else if (intent === 'status') {
-    result = statusOrchestration(taskRef!);
+    result = statusOrchestration(taskRef!, coreOptions);
   } else if (intent === 'prepare') {
     const missing = requireValues(['--client']);
     if (missing) { usageFailure(`intent 'prepare' requires '${missing}'`); return; }
@@ -114,7 +216,7 @@ function taskOrchestration(args: string[] = []): void {
       client: values['--client'] as AgentClientId,
       requestedModel: values['--requested-model'],
       requestedReasoningEffort: values['--requested-reasoning-effort']
-    });
+    }, coreOptions);
   } else if (intent === 'hook-start') {
     const missing = requireValues([
       ...(taskRef === 'auto' ? ['--client'] : []),
@@ -130,15 +232,15 @@ function taskOrchestration(args: string[] = []): void {
       reasoningEffortFallbackReason: values['--reasoning-effort-fallback-reason']
     };
     result = taskRef === 'auto'
-      ? activateMatchingOrchestrationDelegation(values['--client'] as AgentClientId, event)
-      : activateOrchestrationDelegation(taskRef!, event);
+      ? activateMatchingOrchestrationDelegation(values['--client'] as AgentClientId, event, coreOptions)
+      : activateOrchestrationDelegation(taskRef!, event, coreOptions);
   } else if (intent === 'hook-stop') {
     if (taskRef === 'auto') {
       const missing = requireValues(['--client', '--native-agent', '--child-id']);
       if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
       result = sealMatchingOrchestrationDelegation(values['--client'] as AgentClientId, {
         nativeAgent: values['--native-agent']!, childId: values['--child-id']!
-      });
+      }, coreOptions);
     } else {
       const missing = requireValues(['--child-id', '--exit-code', '--after-fingerprint']);
       if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
@@ -148,21 +250,15 @@ function taskOrchestration(args: string[] = []): void {
         childId: values['--child-id']!, exitCode,
         afterFingerprint: values['--after-fingerprint']!,
         changedPaths: values['--changed-paths'] ? values['--changed-paths']!.split(',').filter(Boolean) : []
-      });
+      }, coreOptions);
     }
-  } 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!);
+    result = advanceOrchestration(taskRef!, coreOptions);
   } else {
     const missing = requireValues(['--code', '--message', '--recoverable']);
     if (missing) { usageFailure(`intent 'pause' requires '${missing}'`); return; }
     if (!['true', 'false'].includes(values['--recoverable']!)) { usageFailure('--recoverable must be true or false'); return; }
-    result = pauseOrchestration(taskRef!, values['--code']!, values['--message']!, values['--recoverable'] === 'true');
+    result = pauseOrchestration(taskRef!, values['--code']!, values['--message']!, values['--recoverable'] === 'true', coreOptions);
   }
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;

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

package/lib/platform/pr-checks.ts

@@ -109,7 +109,7 @@ registerPlatformCapabilities('github', {
   inspectRequiredChecks({ client, repository, number, cwd }) {
     const github = (client as GitHubClient | undefined) || createGitHubClient();
     const inspected = github.json<unknown>([
-      'pr', 'checks', String(number), '--repo', repository, '--required',
+      'pr', 'checks', String(number), '--repo', repository,
       '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'
     ], { cwd });
     return inspected.ok

package/lib/platform/pull-requests.ts

@@ -19,6 +19,8 @@ import { planPullRequestMetadata } from './pull-request-metadata.ts';
 import { platformResult } from './types.ts';
 import type { PlatformOperation, PlatformResult } from './types.ts';
 import { inspectCompletionArtifacts } from '../task/finalization-artifacts.ts';
+import { inspectCreatePrCommitGate } from '../task/commit-finalization.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
 type PullRequestSnapshot = PlatformChangeRequestSnapshot;
 
@@ -747,13 +749,23 @@ function resolveExternalPullRequest(taskRef: string, options: ResolveExternalOpt
   }), { mode: 'external', authorization: selected.source, candidates: selected.candidates, eligible: selected.eligible, selected: selected.selected });
 }
 
-function createPlatformPullRequest(taskRef: string, options: CreateOptions): PullRequestResult {
+function createPlatformPullRequestUnlocked(taskRef: string, options: CreateOptions): PullRequestResult {
   const base = resolvedContext(taskRef, options);
   if (!base.ok) return base.output;
   if (!options.base || !options.head || !options.title.trim() || !options.body.trim()) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
     error: { code: 'PR_PAYLOAD_INVALID', message: 'base, head, title and body are required', retryable: false }
   });
   if (base.prNumber) return inspectPlatformPullRequest(taskRef, options);
+  const gate = inspectCreatePrCommitGate(base.resolved.taskDir, base.resolved.repoRoot, base.resolved.taskId);
+  if (!gate.allowed) return result('blocked', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform,
+    capabilities: base.context.capabilities,
+    error: {
+      code: gate.code!,
+      message: `${gate.message}; action=${gate.action}`,
+      retryable: gate.action === 'rerun-commit' || gate.action === 'rerun-review-code'
+    }
+  });
   const located = locatePullRequest(base, options.head, options.base);
   if (!located.ok && located.error.code === 'PR_IDENTITY_AMBIGUOUS') return result('failed', base.resolved.taskId, base.issueNumber, null, {
     platform: base.context.platform, capabilities: base.context.capabilities, error: located.error
@@ -811,6 +823,42 @@ function createPlatformPullRequest(taskRef: string, options: CreateOptions): Pul
   });
 }
 
+function createPlatformPullRequest(taskRef: string, options: CreateOptions): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!options.base || !options.head || !options.title.trim() || !options.body.trim()) {
+    return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+      error: { code: 'PR_PAYLOAD_INVALID', message: 'base, head, title and body are required', retryable: false }
+    });
+  }
+  if (base.prNumber) return inspectPlatformPullRequest(taskRef, options);
+  try {
+    return withTaskExecutionLock(
+      base.resolved.repoRoot,
+      base.resolved.taskId,
+      'platform-pr.create',
+      () => createPlatformPullRequestUnlocked(taskRef, options)
+    );
+  } catch (error) {
+    if (error instanceof TaskExecutionLockError) {
+      return result('blocked', base.resolved.taskId, base.issueNumber, null, {
+        platform: base.context.platform,
+        capabilities: base.context.capabilities,
+        error: { code: error.code, message: error.message, retryable: true }
+      });
+    }
+    return result('failed', base.resolved.taskId, base.issueNumber, null, {
+      platform: base.context.platform,
+      capabilities: base.context.capabilities,
+      error: {
+        code: 'PR_CREATE_FAILED',
+        message: error instanceof Error ? error.message : String(error),
+        retryable: false
+      }
+    });
+  }
+}
+
 function syncPlatformPullRequest(taskRef: string, options: SyncOptions): PullRequestResult {
   const base = resolvedContext(taskRef, options);
   if (!base.ok) return base.output;

package/lib/platform/releases.ts

@@ -48,18 +48,30 @@ function reconcileReleaseMilestones(version: string, options: ReleaseOptions = {
   if (!listed.ok) return { ...platformResult(listed.error.retryable ? 'blocked' : 'failed'), changed: false, operations: [], error: listed.error };
   const milestones = flattenPages(listed.value).map((item) => ({ title: String(item.title || ''), number: Number(item.number), state: String(item.state || '') }));
   const major = Number(match[1]); const minor = Number(match[2]); const patch = Number(match[3]);
-  const ensure = [`${major}.${minor}.${patch + 1}`, `${major}.${minor}.x`];
-  if (patch === 0) ensure.push(`${major}.${minor + 1}.0`, `${major}.${minor + 1}.x`);
+  const nextPatch = `${major}.${minor}.${patch + 1}`;
+  const currentLine = `${major}.${minor}.x`;
+  const ensure = [
+    { title: nextPatch, description: `Issues that we want to release in v${nextPatch}.` },
+    { title: currentLine, description: `Issues that we want to resolve in ${major}.${minor} line.` }
+  ];
+  if (patch === 0) {
+    const nextMinor = `${major}.${minor + 1}.0`;
+    const nextLine = `${major}.${minor + 1}.x`;
+    ensure.push(
+      { title: nextMinor, description: `Issues that we want to release in v${nextMinor}.` },
+      { title: nextLine, description: `Issues that we want to resolve in ${major}.${minor + 1} line.` }
+    );
+  }
   const operations: Array<{ name: string; title: string; status: 'applied' | 'no-op' | 'failed' }> = [];
   const current = milestones.find((item) => item.title === version);
   if (current && current.state !== 'closed') {
     const closed = client.json(['api', '--method', 'PATCH', `repos/${context.platform.repository}/milestones/${current.number}`, '-f', 'state=closed'], { cwd: options.cwd });
     operations.push({ name: 'close-milestone', title: version, status: closed.ok ? 'applied' : 'failed' });
   } else operations.push({ name: 'close-milestone', title: version, status: 'no-op' });
-  for (const title of ensure) {
+  for (const { title, description } of ensure) {
     if (milestones.some((item) => item.title === title)) operations.push({ name: 'ensure-milestone', title, status: 'no-op' });
     else {
-      const created = client.json(['api', '--method', 'POST', `repos/${context.platform.repository}/milestones`, '-f', `title=${title}`], { cwd: options.cwd });
+      const created = client.json(['api', '--method', 'POST', `repos/${context.platform.repository}/milestones`, '-f', `title=${title}`, '-f', `description=${description}`], { cwd: options.cwd });
       operations.push({ name: 'ensure-milestone', title, status: created.ok ? 'applied' : 'failed' });
     }
   }

package/lib/process-data/index.ts

@@ -0,0 +1,224 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+import { detectRepoRoot } from '../task/resolve-ref.ts';
+import { normalizeObjects } from './normalize.ts';
+import { reconcileRecords } from './reconcile.ts';
+import { readAppliedOverlays, repairSnapshot } from './repair.ts';
+import { collectGitHubObjects, collectLocalObjects } from './sources.ts';
+import { canonicalJsonBytes, createObjectStore, publishSnapshot, verifySnapshot } from './store.ts';
+
+import type { CapturedObject, NormalizedRecord, RestCollectionEvidence } from './types.ts';
+
+const USAGE = `Usage: ai data <command> [options]
+
+Commands:
+  capture [--source all|local|github] [--root <dir>] [--include-excerpts]
+  verify <snapshot-id> [--root <dir>]
+  audit <snapshot-id> [--root <dir>] [--format json|text]
+  repair <snapshot-id> [--root <dir>] [--apply]
+  export <snapshot-id> [--root <dir>] [--repairs none|applied] [--output <file|->]
+`;
+
+type ParsedArgs = { positionals: string[]; options: Map<string, string | true> };
+
+function parseArgs(args: string[], valueOptions: Set<string>, booleanOptions: Set<string>): ParsedArgs {
+  const positionals: string[] = [];
+  const options = new Map<string, string | true>();
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    if (booleanOptions.has(arg)) {
+      if (options.has(arg)) throw new Error(`duplicate option: ${arg}`);
+      options.set(arg, true);
+      continue;
+    }
+    if (!valueOptions.has(arg)) throw new Error(`unknown option: ${arg}`);
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`missing value for ${arg}`);
+    if (options.has(arg)) throw new Error(`duplicate option: ${arg}`);
+    options.set(arg, value);
+    index += 1;
+  }
+  return { positionals, options };
+}
+
+function dataRoot(repoRoot: string, requested?: string): string {
+  const workspace = path.resolve(repoRoot, '.agents', 'workspace');
+  const resolved = path.resolve(repoRoot, requested ?? path.join('.agents', 'workspace', 'process-data'));
+  const relative = path.relative(repoRoot, resolved);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('data root must be inside the repository');
+  const taskRoots = ['active', 'blocked', 'completed', 'archive'].map((state) => path.join(workspace, state));
+  if (resolved === workspace || taskRoots.some((taskRoot) => resolved === taskRoot || resolved.startsWith(`${taskRoot}${path.sep}`))) {
+    throw new Error('data root cannot be the workspace root or a task directory');
+  }
+  let current = resolved;
+  while (current !== repoRoot) {
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) throw new Error('data root cannot traverse a symlink');
+    current = path.dirname(current);
+  }
+  return resolved;
+}
+
+function repositoryIdentity(repoRoot: string): string {
+  try {
+    return execFileSync('git', ['config', '--get', 'remote.origin.url'], { cwd: repoRoot, encoding: 'utf8' }).trim() || path.basename(repoRoot);
+  } catch {
+    return path.basename(repoRoot);
+  }
+}
+
+function writeJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function optionString(parsed: ParsedArgs, name: string): string | undefined {
+  const value = parsed.options.get(name);
+  return typeof value === 'string' ? value : undefined;
+}
+
+function capture(args: string[]): number {
+  const parsed = parseArgs(args, new Set(['--source', '--root']), new Set(['--include-excerpts']));
+  if (parsed.positionals.length > 0) throw new Error('capture does not accept positional arguments');
+  const scope = optionString(parsed, '--source') ?? 'all';
+  if (!['all', 'local', 'github'].includes(scope)) throw new Error('--source must be all, local, or github');
+  const repoRoot = detectRepoRoot();
+  const root = dataRoot(repoRoot, optionString(parsed, '--root'));
+  const observedFrom = new Date().toISOString();
+  const objects: CapturedObject[] = [];
+  const endpoints: RestCollectionEvidence[] = [];
+  let repository = repositoryIdentity(repoRoot);
+
+  if (scope === 'all' || scope === 'local') {
+    const local = collectLocalObjects(repoRoot, { includeExcerpts: parsed.options.has('--include-excerpts') });
+    if (!local.ok) { writeJson({ ok: false, error: local.error }); return 2; }
+    objects.push(...local.value);
+  }
+  if (scope === 'all' || scope === 'github') {
+    const github = collectGitHubObjects(repoRoot);
+    if (!github.ok) { writeJson({ ok: false, error: github.error }); return 2; }
+    objects.push(...github.value.objects);
+    endpoints.push(...github.value.endpoints);
+    repository = github.value.repository;
+  }
+
+  const store = createObjectStore(root);
+  for (const object of objects) {
+    if (object.content !== undefined && object.disposition?.state === 'included') {
+      const stored = store.put(Buffer.from(object.content, 'utf8'));
+      if (stored.sha256 !== object.sha256) throw new Error(`source hash mismatch: ${object.sourceIdentity}`);
+    }
+  }
+  const records = normalizeObjects(objects);
+  const reconciliation = reconcileRecords(records, scope as 'all' | 'local' | 'github');
+  const observedTo = new Date().toISOString();
+  const published = publishSnapshot(root, {
+    scope: scope as 'all' | 'local' | 'github',
+    repository,
+    observedFrom,
+    observedTo,
+    objects: objects.map(({ content: _content, ...object }) => object),
+    endpoints,
+    excerptsEnabled: parsed.options.has('--include-excerpts'),
+    records,
+    quality: reconciliation.findings,
+    repairs: reconciliation.repairs
+  });
+  writeJson({ ok: true, snapshotId: published.snapshotId, scope, created: published.created, objects: objects.length, records: records.length });
+  return 0;
+}
+
+function verify(args: string[]): number {
+  const parsed = parseArgs(args, new Set(['--root']), new Set());
+  if (parsed.positionals.length !== 1) throw new Error('verify requires one snapshot id');
+  const repoRoot = detectRepoRoot();
+  const result = verifySnapshot(dataRoot(repoRoot, optionString(parsed, '--root')), parsed.positionals[0]!);
+  writeJson(result);
+  return result.ok ? 0 : 1;
+}
+
+function audit(args: string[]): number {
+  const parsed = parseArgs(args, new Set(['--root', '--format']), new Set());
+  if (parsed.positionals.length !== 1) throw new Error('audit requires one snapshot id');
+  const format = optionString(parsed, '--format') ?? 'text';
+  if (!['json', 'text'].includes(format)) throw new Error('--format must be json or text');
+  const repoRoot = detectRepoRoot();
+  const root = dataRoot(repoRoot, optionString(parsed, '--root'));
+  const verified = verifySnapshot(root, parsed.positionals[0]!);
+  if (!verified.ok || !verified.snapshotPath || !verified.manifest) { writeJson(verified); return 1; }
+  const quality = JSON.parse(fs.readFileSync(path.join(verified.snapshotPath, 'quality.json'), 'utf8')) as { findings: unknown[] };
+  const records = fs.readFileSync(path.join(verified.snapshotPath, 'normalized.jsonl'), 'utf8').split('\n').filter(Boolean).map((line) => {
+    const { schema: _schema, ...record } = JSON.parse(line) as { schema: string } & NormalizedRecord;
+    return record;
+  });
+  const recomputed = reconcileRecords(records, verified.manifest.scope);
+  if (!canonicalJsonBytes(recomputed.findings).equals(canonicalJsonBytes(quality.findings))) {
+    writeJson({ ok: false, error: { code: 'QUALITY_MISMATCH', message: 'stored quality baseline does not match recomputed findings' } });
+    return 1;
+  }
+  if (format === 'json') writeJson({ ok: true, snapshotId: parsed.positionals[0], findings: recomputed.findings });
+  else process.stdout.write(`Snapshot ${parsed.positionals[0]}: ${quality.findings.length} findings\n`);
+  return 0;
+}
+
+function repair(args: string[]): number {
+  const parsed = parseArgs(args, new Set(['--root']), new Set(['--apply']));
+  if (parsed.positionals.length !== 1) throw new Error('repair requires one snapshot id');
+  const repoRoot = detectRepoRoot();
+  const result = repairSnapshot(dataRoot(repoRoot, optionString(parsed, '--root')), parsed.positionals[0]!, parsed.options.has('--apply'));
+  writeJson({ ok: true, ...result });
+  return 0;
+}
+
+function exportSnapshot(args: string[]): number {
+  const parsed = parseArgs(args, new Set(['--root', '--repairs', '--output']), new Set());
+  if (parsed.positionals.length !== 1) throw new Error('export requires one snapshot id');
+  const repairMode = optionString(parsed, '--repairs') ?? 'none';
+  if (!['none', 'applied'].includes(repairMode)) throw new Error('--repairs must be none or applied');
+  const output = optionString(parsed, '--output') ?? '-';
+  const repoRoot = detectRepoRoot();
+  const root = dataRoot(repoRoot, optionString(parsed, '--root'));
+  const verified = verifySnapshot(root, parsed.positionals[0]!);
+  if (!verified.ok || !verified.snapshotPath) { writeJson(verified); return 1; }
+  let content = fs.readFileSync(path.join(verified.snapshotPath, 'normalized.jsonl'), 'utf8');
+  if (repairMode === 'applied') content += readAppliedOverlays(root, parsed.positionals[0]!);
+  if (output === '-') process.stdout.write(content);
+  else {
+    const destination = path.resolve(repoRoot, output);
+    const relative = path.relative(repoRoot, destination);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('export output must be inside the repository');
+    fs.writeFileSync(destination, content, { flag: 'wx', mode: 0o600 });
+    writeJson({ ok: true, snapshotId: parsed.positionals[0], output: relative });
+  }
+  return 0;
+}
+
+async function cmdData(args: string[]): Promise<number> {
+  const [command, ...rest] = args;
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    process.stdout.write(USAGE);
+    return command ? 0 : 1;
+  }
+  try {
+    switch (command) {
+      case 'capture': return capture(rest);
+      case 'verify': return verify(rest);
+      case 'audit': return audit(rest);
+      case 'repair': return repair(rest);
+      case 'export': return exportSnapshot(rest);
+      default:
+        process.stderr.write(`Unknown data command: ${command}\n`);
+        process.stdout.write(USAGE);
+        return 1;
+    }
+  } catch (error) {
+    writeJson({ ok: false, error: { code: 'DATA_COMMAND_FAILED', message: error instanceof Error ? error.message : String(error) } });
+    return 1;
+  }
+}
+
+export { cmdData, dataRoot };