@cleocode/contracts 2026.9.8 → 2026.9.10

package/src/acceptance-gate-schema.ts

@@ -13,6 +13,8 @@
  */
 
 import { z } from 'zod';
+import type { AcceptanceGateBinding } from './acceptance-gate.js';
+import type { ProcessCaptureResult } from './resource-governor.js';
 
 // ─── Base schema ──────────────────────────────────────────────────────────────
 
@@ -79,6 +81,90 @@ export const testGateSchema = gateBaseSchema.extend({
   env: z.record(z.string(), z.string()).optional(),
 });
 
+/**
+ * Validates the structured JSON reporter subset used for minimum test counts.
+ *
+ * @remarks
+ * Audited against Vitest 4.1.4 JSON output, including nested suites, skipped
+ * tests and todos. Jest-compatible producers must satisfy this same shape;
+ * this is not a claim that every Jest version or custom reporter is supported.
+ * Counts must match individual assertions. Passed tests alone satisfy a gate's
+ * minimum; this schema validates structure, not execution provenance or success.
+ * Extra reporter metadata is ignored. Runtime callers must bound input bytes
+ * and obtain the report from the actual owned process, not a saved report file.
+ *
+ * @example
+ * ```ts
+ * const report = testCountReportSchema.safeParse(JSON.parse(captured.stdout));
+ * if (report.success) console.info(report.data.numPassedTests);
+ * ```
+ */
+export const testCountReportSchema = z
+  .object({
+    numTotalTests: z.number().int().nonnegative().safe(),
+    numPassedTests: z.number().int().nonnegative().safe(),
+    numFailedTests: z.number().int().nonnegative().safe(),
+    numPendingTests: z.number().int().nonnegative().safe(),
+    numTodoTests: z.number().int().nonnegative().safe(),
+    numTotalTestSuites: z.number().int().nonnegative().safe(),
+    numPassedTestSuites: z.number().int().nonnegative().safe(),
+    numFailedTestSuites: z.number().int().nonnegative().safe(),
+    numPendingTestSuites: z.number().int().nonnegative().safe(),
+    success: z.boolean(),
+    testResults: z.array(
+      z.object({
+        name: z.string().min(1),
+        status: z.enum(['passed', 'failed']),
+        assertionResults: z.array(
+          z.object({
+            fullName: z.string(),
+            status: z.enum(['passed', 'failed', 'pending', 'skipped', 'todo']),
+          }),
+        ),
+      }),
+    ),
+  })
+  .superRefine((report, context) => {
+    const assertions = report.testResults.flatMap((file) => file.assertionResults);
+    const passed = assertions.filter((test) => test.status === 'passed').length;
+    const failed = assertions.filter((test) => test.status === 'failed').length;
+    const pending = assertions.filter(
+      (test) => test.status === 'pending' || test.status === 'skipped',
+    ).length;
+    const todo = assertions.filter((test) => test.status === 'todo').length;
+    if (
+      report.numTotalTests !== assertions.length ||
+      report.numPassedTests !== passed ||
+      report.numFailedTests !== failed ||
+      report.numPendingTests !== pending ||
+      report.numTodoTests !== todo
+    ) {
+      context.addIssue({
+        code: 'custom',
+        message: 'Test counters disagree with assertion results',
+      });
+    }
+    if (
+      report.numTotalTestSuites !==
+      report.numPassedTestSuites + report.numFailedTestSuites + report.numPendingTestSuites
+    ) {
+      context.addIssue({ code: 'custom', message: 'Suite counters are inconsistent' });
+    }
+    if (
+      report.testResults.some(
+        (file) =>
+          file.status === 'passed' &&
+          file.assertionResults.some((test) => test.status === 'failed'),
+      ) ||
+      (report.success &&
+        (failed > 0 ||
+          report.numFailedTestSuites > 0 ||
+          report.testResults.some((file) => file.status === 'failed')))
+    ) {
+      context.addIssue({ code: 'custom', message: 'Success status contradicts failed results' });
+    }
+  });
+
 /** Zod schema for {@link FileGate}. */
 export const fileGateSchema = gateBaseSchema.extend({
   kind: z.literal('file'),
@@ -221,26 +307,246 @@ export type GateResultDetailsInput = z.input<typeof gateResultDetailsSchema>;
 
 // ─── Result schema ────────────────────────────────────────────────────────────
 
+/** Validate captured transport observations without treating their shape as execution authority. */
+const capturedExecutionSchema: z.ZodType<ProcessCaptureResult> = z
+  .object({
+    started: z.boolean(),
+    targetPid: z.number().int().positive().safe().nullable(),
+    exitCode: z.number().int().nonnegative().safe().nullable(),
+    signal: z.string().min(1).nullable(),
+    error: z.string().nullable(),
+    stopped: z
+      .enum([
+        'deadline',
+        'cancelled',
+        'teardown',
+        'output-limit',
+        'resource-limit',
+        'transport-error',
+      ])
+      .nullable(),
+    stdout: z.string(),
+    stderr: z.string(),
+    outputTruncated: z.boolean(),
+    durationMs: z.number().finite().nonnegative(),
+    mode: z.enum(['systemd', 'pgid']),
+    unitName: z.string().min(1).optional(),
+    nativeMemory: z.enum(['unverified', 'observed-cgroup']),
+    resourceLimits: z
+      .object({
+        cgroup: z.string().startsWith('/'),
+        memoryMaxBytes: z.number().int().positive().safe().nullable(),
+        tasksMax: z.number().int().positive().safe().nullable(),
+      })
+      .strict()
+      .optional(),
+    cleanupScope: z.enum(['process-group', 'direct-child']),
+    transportClosed: z.literal(true),
+    targetCloseObserved: z.boolean(),
+    cleanupObservation: z.enum([
+      'scope-terminal',
+      'process-group-absent',
+      'process-group-signalled',
+      'unverified',
+    ]),
+    cleanupErrors: z.array(z.string()),
+  })
+  .strict()
+  .superRefine((execution, context) => {
+    if (
+      execution.started !== (execution.targetPid !== null) ||
+      (!execution.started && (execution.exitCode !== null || execution.signal !== null)) ||
+      (execution.exitCode !== null && execution.signal !== null) ||
+      (!execution.targetCloseObserved && (execution.exitCode !== null || execution.signal !== null))
+    )
+      context.addIssue({ code: 'custom', message: 'Contradictory target lifecycle observation' });
+    if (execution.nativeMemory === 'observed-cgroup' && !execution.resourceLimits?.memoryMaxBytes)
+      context.addIssue({
+        code: 'custom',
+        message: 'Observed native-memory claim requires a finite kernel limit',
+      });
+    if (
+      execution.resourceLimits &&
+      (execution.mode !== 'systemd' ||
+        !execution.unitName ||
+        !execution.resourceLimits.cgroup.split('/').includes(execution.unitName) ||
+        execution.resourceLimits.cgroup.split('/').includes('..'))
+    )
+      context.addIssue({
+        code: 'custom',
+        message: 'Resource observation must name the exact owned scope',
+      });
+    if (
+      execution.cleanupObservation === 'scope-terminal' &&
+      (execution.mode !== 'systemd' || !execution.unitName)
+    )
+      context.addIssue({
+        code: 'custom',
+        message: 'Terminal scope observation requires an identified systemd scope',
+      });
+  });
+
+/** Absolute captured paths; canonical ownership is checked by the runtime verifier. */
+const gateBindingPathSchema = z
+  .string()
+  .min(1)
+  .refine(
+    (value) => /^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(value) && !value.includes('\0'),
+    'Captured gate paths must be absolute and contain no null byte',
+  );
+
+/** Strict persistence shape for existing acceptance-result provenance. */
+const acceptanceGateBindingSchema: z.ZodType<AcceptanceGateBinding> = z
+  .object({
+    version: z.literal(1),
+    verificationId: z.string().uuid(),
+    identity: z
+      .object({
+        projectId: z.string().min(1),
+        projectRoot: gateBindingPathSchema,
+        actor: z.string().min(1),
+        operation: z.literal('check.gate.verify'),
+        idempotencyKey: z.string().min(1),
+      })
+      .strict(),
+    taskId: z.string().min(1),
+    criterionId: z.string().uuid(),
+    criterionHash: z.string().regex(/^[a-f0-9]{64}$/),
+    gateHash: z.string().regex(/^[a-f0-9]{64}$/),
+    capturedAt: z.string().datetime(),
+    deadlineAt: z.number().int().positive().safe(),
+    invocation: z
+      .object({
+        command: z.string().min(1),
+        args: z.array(z.string()),
+        cwd: gateBindingPathSchema,
+        environmentHash: z.string().regex(/^[a-f0-9]{64}$/),
+      })
+      .strict()
+      .optional(),
+    artifacts: z.array(
+      z
+        .object({
+          path: gateBindingPathSchema,
+          sha256: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/)
+            .nullable(),
+          bytes: z.number().int().nonnegative().safe().nullable(),
+        })
+        .strict()
+        .superRefine((artifact, context) => {
+          if ((artifact.sha256 === null) !== (artifact.bytes === null))
+            context.addIssue({
+              code: 'custom',
+              message: 'Absent input requires both null digest and size',
+            });
+        }),
+    ),
+  })
+  .strict()
+  .superRefine((binding, context) => {
+    if (new Set(binding.artifacts.map(({ path }) => path)).size !== binding.artifacts.length)
+      context.addIssue({
+        code: 'custom',
+        path: ['artifacts'],
+        message: 'Input paths must be unique',
+      });
+    if (Date.parse(binding.capturedAt) >= binding.deadlineAt)
+      context.addIssue({
+        code: 'custom',
+        path: ['deadlineAt'],
+        message: 'Input capture must precede the original deadline',
+      });
+  });
+
 /**
  * Zod schema for {@link AcceptanceGateResult}.
  *
  * Validates the shape produced by the gate runner and stored in
  * `lifecycle_gate_results`.
+ * @remarks Historical records without execution detail remain readable. New detail is
+ * preserved strictly; interrupted or contradictory observations cannot supply a verdict.
+ * Validation proves shape consistency, not freshness, task binding or authentic execution.
+ * @example
+ * ```typescript
+ * const result = acceptanceGateResultSchema.parse(storedResult);
+ * ```
  */
-export const acceptanceGateResultSchema = z.object({
-  index: z.number().int().nonnegative(),
-  req: z.string().optional(),
-  kind: z.enum(['test', 'file', 'command', 'lint', 'http', 'manual']),
-  result: z.enum(['pass', 'fail', 'warn', 'skipped', 'error']),
-  durationMs: z.number().nonnegative(),
-  /** Typed kind-specific detail payload (T802). */
-  details: gateResultDetailsSchema.optional(),
-  evidence: z.string().optional(),
-  errorMessage: z.string().optional(),
-  /** ISO 8601 timestamp. */
-  checkedAt: z.string().datetime(),
-  checkedBy: z.string().min(1),
-});
+export const acceptanceGateResultSchema = z
+  .object({
+    binding: acceptanceGateBindingSchema.optional(),
+    index: z.number().int().nonnegative(),
+    req: z.string().optional(),
+    kind: z.enum(['test', 'file', 'command', 'lint', 'http', 'manual']),
+    result: z.enum(['pass', 'fail', 'warn', 'skipped', 'error']),
+    durationMs: z.number().nonnegative(),
+    /** Typed kind-specific detail payload (T802). */
+    details: gateResultDetailsSchema.optional(),
+    /** Actual target/transport/containment observations when supplied by the runner. */
+    execution: capturedExecutionSchema.optional(),
+    evidence: z.string().optional(),
+    errorMessage: z.string().optional(),
+    /** ISO 8601 timestamp. */
+    checkedAt: z.string().datetime(),
+    checkedBy: z.string().min(1),
+  })
+  .superRefine((result, context) => {
+    const binding = result.binding;
+    if (binding) {
+      if (binding.identity.actor !== result.checkedBy)
+        context.addIssue({
+          code: 'custom',
+          path: ['binding', 'identity', 'actor'],
+          message: 'Result actor must match captured operation identity',
+        });
+      if (Date.parse(binding.capturedAt) > Date.parse(result.checkedAt))
+        context.addIssue({
+          code: 'custom',
+          path: ['binding', 'capturedAt'],
+          message: 'Result cannot precede input capture',
+        });
+      const executable = ['test', 'command', 'lint'].includes(result.kind);
+      if (executable && !binding.invocation)
+        context.addIssue({
+          code: 'custom',
+          path: ['binding', 'invocation'],
+          message: 'Executable gate requires captured invocation',
+        });
+      if (['pass', 'fail', 'warn'].includes(result.result)) {
+        if (executable && !result.execution)
+          context.addIssue({
+            code: 'custom',
+            path: ['execution'],
+            message: 'Bound executable verdict requires process observation',
+          });
+        if (Date.parse(result.checkedAt) > binding.deadlineAt)
+          context.addIssue({
+            code: 'custom',
+            path: ['checkedAt'],
+            message: 'Verdict exceeds the original admitted deadline',
+          });
+      }
+    }
+    const execution = result.execution;
+    if (
+      execution &&
+      ['pass', 'fail', 'warn'].includes(result.result) &&
+      (!execution.started ||
+        !execution.targetCloseObserved ||
+        execution.exitCode === null ||
+        execution.signal !== null ||
+        execution.error !== null ||
+        execution.stopped !== null ||
+        execution.outputTruncated ||
+        execution.cleanupErrors.length > 0)
+    )
+      context.addIssue({
+        code: 'custom',
+        path: ['execution'],
+        message: 'Incomplete process observation cannot establish a gate verdict',
+      });
+  });
 
 /** Inferred TypeScript type from {@link acceptanceGateResultSchema}. */
 export type AcceptanceGateResultInput = z.input<typeof acceptanceGateResultSchema>;

package/src/acceptance-gate.ts

@@ -2,11 +2,11 @@
  * Acceptance gate discriminated union and result types.
  *
  * A machine-verifiable acceptance gate. Gates coexist with free-text criteria
- * in `Task.acceptance`; the runtime executes only gates and records results in
- * `task.verification.gateResults` and in the `lifecycle_gate_results` DB table.
+ * in `Task.acceptance`. The runner returns observed results; persistence and
+ * completion binding require the caller's explicit verification workflow.
  *
  * Six gate kinds are supported:
- * - `test`    — run a command and assert exit code / test-count
+ * - `test`    — run a command and assert exit code; unmeasured test-count requirements remain errors
  * - `file`    — assert properties of a file on disk
  * - `command` — run any CLI command and assert exit code / stdout
  * - `lint`    — run a static-analysis tool and require a clean result
@@ -19,6 +19,38 @@
  * @see {@link https://github.com/kryptobaseddev/cleo} T760 RCASD hardening
  */
 
+import type { OperationExecutionContext, OperationExecutionIdentity } from './jobs.js';
+import type {
+  ProcessCaptureOptions,
+  ProcessCaptureResult,
+  SystemdControlContext,
+} from './resource-governor.js';
+
+/**
+ * Captured options for evaluating acceptance gates without renewing operation authority.
+ * @remarks An absent execution context receives a two-second shared foreground budget.
+ * Per-gate timeouts can tighten it; long work requires explicit runtime admission.
+ * @example
+ * ```typescript
+ * const options: AcceptanceGateRunOptions = { projectRoot: '/project', execution };
+ * ```
+ */
+export interface AcceptanceGateRunOptions
+  extends Pick<ProcessCaptureOptions, 'memoryMaxMb' | 'tasksMax'> {
+  /** Explicit project root, or the captured operation's project root. */
+  projectRoot?: string;
+  /** Manual gates remain skipped and never become machine proof. */
+  skipManual?: boolean;
+  /** Original admitted operation, including project identity, deadline and cancellation. */
+  execution?: OperationExecutionContext;
+  /** Explicit captured environment; defaults to a copy of the calling environment. */
+  env?: Readonly<Record<string, string | undefined>>;
+  /** Aggregate process output and file-content read bound per gate. */
+  maxOutputBytes?: number;
+  /** Existing manager context, separate from the child environment. */
+  systemdControl?: SystemdControlContext;
+}
+
 // ─── Base ────────────────────────────────────────────────────────────────────
 
 /** Fields every gate variant carries. */
@@ -48,7 +80,7 @@ export interface GateBase {
   /**
    * Gate timeout in milliseconds.
    *
-   * @defaultValue 120_000
+   * @defaultValue 60_000 (further bounded by the shared operation deadline)
    */
   timeoutMs?: number;
 }
@@ -56,9 +88,14 @@ export interface GateBase {
 // ─── Variants ────────────────────────────────────────────────────────────────
 
 /**
- * Run a command; pass when exit code is 0 and when at least `minCount`
- * tests have run. Designed for test suites:
+ * Run a command and verify its actual exit status. Designed for test suites:
  * `{ kind: 'test', command: 'pnpm test', expect: 'pass' }`.
+ *
+ * A positive `minCount` additionally requires the gate's OWN command to emit a
+ * machine-readable report satisfying `testCountReportSchema` (e.g. by adding
+ * `--reporter=json`). A run that emits none is an error, never a pass: an exit
+ * code carries no count, and a report file written by some other invocation is
+ * not bound to this execution.
  */
 export interface TestGate extends GateBase {
   kind: 'test';
@@ -71,7 +108,13 @@ export interface TestGate extends GateBase {
    * - `"exit0"`: exit code 0 only (permissive mode).
    */
   expect: 'pass' | 'exit0';
-  /** Minimum number of tests that must have run. */
+  /**
+   * Minimum number of PASSING tests the run must report.
+   *
+   * Satisfied only by a structured report emitted by this gate's own command;
+   * a run that produces none returns an error rather than inferring a count
+   * from exit zero (T12308).
+   */
   minCount?: number;
   /** Working directory relative to project root. Default `.`. */
   cwd?: string;
@@ -181,8 +224,8 @@ export interface LintGate extends GateBase {
 
 /**
  * Hit a URL and assert HTTP status and optional body match. For tasks that
- * ship a webapp or API. The runner starts a server only if `startCommand`
- * is set and tears it down after the probe.
+ * ship a webapp or API. Probing an existing service is supported; `startCommand`
+ * currently returns an explicit error pending an admitted owned service lifetime.
  */
 export interface HttpGate extends GateBase {
   kind: 'http';
@@ -319,16 +362,92 @@ export type GateResultDetails =
 
 // ─── Result ──────────────────────────────────────────────────────────────────
 
+/**
+ * Exact bytes observed for one declared task input or resolved verification harness.
+ * @remarks A missing input is explicit, with both digest and size null. This inventory
+ * does not claim coverage of undeclared runtime dependencies or external services.
+ * @example
+ * ```typescript
+ * const input: AcceptanceGateArtifact = { path: '/project/check.mjs', sha256: 'a'.repeat(64), bytes: 42 };
+ * ```
+ */
+export interface AcceptanceGateArtifact {
+  /** Captured absolute input path, resolved within the admitted project scope. */
+  path: string;
+  /** SHA-256 of actual input bytes; null only for an observed absent path. */
+  sha256: string | null;
+  /** Exact byte length, or null alongside an absent digest. */
+  bytes: number | null;
+}
+
+/**
+ * Executable invocation captured before launching a typed verification gate.
+ * @remarks Environment values are represented only by a digest; credentials must
+ * not be duplicated into receipts. The verifier compares actual launch inputs.
+ * @example
+ * ```typescript
+ * const invocation: AcceptanceGateInvocation = { command: 'node', args: ['check.mjs'], cwd: '/project', environmentHash: 'b'.repeat(64) };
+ * ```
+ */
+export interface AcceptanceGateInvocation {
+  /** Exact executable passed to the existing process port. */
+  command: string;
+  /** Ordered arguments, without shell re-interpretation. */
+  args: string[];
+  /** Captured absolute process working directory. */
+  cwd: string;
+  /** SHA-256 of the canonically ordered effective environment. */
+  environmentHash: string;
+}
+
+/**
+ * Task and input binding attached to an explicitly verified acceptance result.
+ * @remarks This is provenance, not authority by itself. Persistence and completion
+ * must compare current canonical task/AC rows, input bytes and captured execution.
+ * No gate runs implicitly on task creation or editing. Historical unbound results
+ * remain readable but do not establish typed requirement completion.
+ * @example
+ * ```typescript
+ * const owner = result.binding?.identity.projectId;
+ * ```
+ */
+export interface AcceptanceGateBinding {
+  /** Version of the captured binding contract. */
+  version: 1;
+  /** Unique verification attempt whose result and receipt commit atomically. */
+  verificationId: string;
+  /** Existing captured operation identity, including actor and retry identity. */
+  identity: OperationExecutionIdentity;
+  /** Exact canonical task owning this criterion. */
+  taskId: string;
+  /** Current normalized acceptance row identifier. */
+  criterionId: string;
+  /** SHA-256 over the criterion's canonical persisted payload. */
+  criterionHash: string;
+  /** SHA-256 over the complete canonical gate, including REQ and launch options. */
+  gateHash: string;
+  /** ISO time of input capture before execution. */
+  capturedAt: string;
+  /** Original admitted absolute deadline in epoch milliseconds; never renewed. */
+  deadlineAt: number;
+  /** Actual process inputs; required for executable gate kinds. */
+  invocation?: AcceptanceGateInvocation;
+  /** Explicit bounded input inventory, including untracked harness/task files. */
+  artifacts: AcceptanceGateArtifact[];
+}
+
 /**
  * Result of running one acceptance gate.
  *
- * Persisted to `lifecycle_gate_results` and summarised in
- * `task.verification.gateResults`.
+ * Returned by the runner. Canonical verification explicitly persists bound results;
+ * the result shape alone does not prove persistence or authorize completion.
  *
  * NOTE: Named `AcceptanceGateResult` (not `GateResult`) for historical
  * clarity — it describes acceptance-criterion gate outcomes specifically.
  */
 export interface AcceptanceGateResult {
+  /** Explicit verification binding; absent on historical/unpersisted runner observations. */
+  binding?: AcceptanceGateBinding;
   /** Zero-based index in the task's acceptance array. */
   index: number;
   /** REQ-ID if the gate had one, else `undefined`. */
@@ -356,6 +475,8 @@ export interface AcceptanceGateResult {
   result: 'pass' | 'fail' | 'warn' | 'skipped' | 'error';
   /** Wall-clock duration of the gate execution in milliseconds. */
   durationMs: number;
+  /** Actual process outcome and containment evidence; wrapper status is not target proof. */
+  execution?: ProcessCaptureResult;
   /**
    * Typed kind-specific detail payload.
    *
@@ -384,3 +505,15 @@ export interface AcceptanceGateResult {
   /** Agent identifier or `"human"` that ran or attested the gate. */
   checkedBy: string;
 }
+
+/** Canonical typed-verification audit details stored with results in the task transaction. */
+export interface AcceptanceGateVerificationReceipt {
+  /** One admitted verification batch identity shared by every result. */
+  verificationId: string;
+  /** SHA-256 of the exact persisted result-array JSON bytes. */
+  resultHash: string;
+  /** Explicit verification operation; never inferred from generic completion evidence. */
+  operation: 'check.gate.verify';
+  /** Overall generic-plus-typed verification outcome at this observation. */
+  passed: boolean;
+}

package/src/audit.ts

@@ -13,6 +13,8 @@
  * @epic T1216
  */
 
+import type { ProcessCaptureResult, ProcessLaunchExecution } from './resource-governor.js';
+
 /**
  * A single commit entry extracted from git log.
  */
@@ -51,17 +53,22 @@ export interface ReleaseTagEntry {
  * necessarily from the task DB.
  */
 export interface ReconstructResult {
+  /** Assessment provenance; absent only on legacy results. New assessments always emit it.
+   * @defaultValue undefined on legacy records only
+   */
+  assessment?: ReconstructAssessment;
+
   /** The task ID being reconstructed (e.g. `T991`). */
   taskId: string;
 
   /**
    * Commits whose message directly references `taskId`.
-   * Pattern: `<taskId>:`, `(<taskId>):`, or `<taskId> ` (space-delimited).
+   * Exact word-boundary task tokens in the full subject and body, never numeric prefixes.
    */
   directCommits: CommitEntry[];
 
   /**
-   * Numeric child ID range inferred from commit-message mining and DB lookup.
+   * Numeric child ID range inferred from commit-message mining and numeric proximity (not authoritative containment).
    * Both bounds are inclusive. `null` when no children could be inferred.
    */
   childIdRange: { min: string; max: string } | null;
@@ -102,3 +109,66 @@ export interface ReconstructResult {
    */
   inferredChildren: string[];
 }
+
+/** Options for bounded Git-backed lineage assessment.
+ * @remarks These options may shorten but never extend an inherited operation lifetime.
+ * @example
+ * ```ts
+ * const options: ReconstructOptions = { execution: { deadlineAt: Date.now() + 1000 } };
+ * ```
+ */
+export interface ReconstructOptions {
+  /** Original caller deadline and cancellation.
+   * @defaultValue inherited context, otherwise one two-second foreground budget
+   */
+  execution?: ProcessLaunchExecution;
+  /** Combined capture byte ceiling across all commands.
+   * @defaultValue 8388608
+   */
+  maxOutputBytes?: number;
+}
+
+/** Observed bounded command outcome without duplicating captured Git history.
+ * @remarks Target outcome and cleanup evidence remain distinct.
+ * @example
+ * ```ts
+ * const stopped = command.stopped;
+ * ```
+ */
+export interface ReconstructCommand extends Omit<ProcessCaptureResult, 'stdout' | 'stderr'> {
+  /** Exact requested Git arguments. */
+  args: readonly string[];
+  /** Diagnostic stderr, bounded by the shared output limit. */
+  stderr: string;
+}
+
+/** Coverage and failure truth for a lineage assessment.
+ * @remarks Current means the observed local Git scope was assessed, not complete remote history
+ * or proven task containment. Partial results must not authorize provenance repair.
+ * @example
+ * ```ts
+ * if (result.assessment?.coverage !== 'current') return;
+ * ```
+ */
+export interface ReconstructAssessment {
+  /** Absolute repository root captured before asynchronous work. */
+  repositoryRoot: string;
+  /** One absolute execution deadline, shared with every command and computation stage. */
+  deadlineAt: number;
+  /** Completeness of the observed local Git history and release-tag assessment. */
+  coverage: 'current' | 'partial' | 'failed';
+  /** Shallow history is explicitly incomplete; null means the probe did not complete. */
+  shallow: boolean | null;
+  /** Number of commits parsed from the bounded history, not total remote commits. */
+  observedCommits: number;
+  /** Whether all history records were parsed successfully. */
+  historyComplete: boolean;
+  /** Whether every commit-targeting tag was assessed successfully. */
+  tagsComplete: boolean;
+  /** Captured process verdicts and cleanup observations. */
+  commands: ReconstructCommand[];
+  /** Explicit failures and incomplete-scope reasons; never replaced with healthy empty arrays. */
+  diagnostics: Array<{ code: string; stage: string; message: string }>;
+  /** Non-authoritative inference and local-scope limitations retained even for current coverage. */
+  limitations: string[];
+}