@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/lib/sandbox/control/state.ts

@@ -1,7 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { buildProcessTreeStopCommand } from '../../server/process-control.ts';
 import { getProcessIdentityState } from '../../server/process-state.ts';
 import type { ProcessIdentity, ProcessIdentityProbe } from '../../server/process-state.ts';
@@ -9,8 +9,21 @@ import type {
   SandboxControlExecution,
   SandboxControlLease,
   SandboxControlManifest,
+  SandboxControlPayload,
+  SandboxControlReservation,
+  SandboxControlResultEvidence,
   SandboxControlStatus
 } from './protocol.ts';
+import {
+  parseSandboxControlResultEvidence,
+  parseSandboxControlPayload,
+  parseSandboxControlReservation,
+  SANDBOX_CONTROL_MAX_RESPONSE_BYTES,
+  SANDBOX_CONTROL_MAX_LOGICAL_RECORDS,
+  SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES,
+  SANDBOX_CONTROL_RESERVATION_BYTES
+} from './protocol.ts';
+import { parseSandboxTaskView, taskViewForManifest, type SandboxTaskView } from './task-view.ts';
 
 export const SANDBOX_CONTROL_AUDIT_MAX_BYTES = 1024 * 1024;
 export const SANDBOX_CONTROL_EXECUTION_STOP_MS = 2_000;
@@ -31,11 +44,249 @@ export function atomicWriteJson(filePath: string, value: unknown, mode = 0o600,
   }
 }
 
+export function sandboxControlEncodedJsonBytes(value: unknown): number {
+  return Buffer.byteLength(`${JSON.stringify(value)}\n`, 'utf8');
+}
+
+export function atomicWriteJsonNoReplace(
+  filePath: string,
+  value: unknown,
+  mode = 0o600,
+  createParent = true
+): void {
+  atomicCreateJson(filePath, value, 'SANDBOX_CONTROL_TERMINAL_ALREADY_EXISTS', mode, createParent);
+}
+
+function atomicCreateJson(
+  filePath: string,
+  value: unknown,
+  duplicateCode: string,
+  mode = 0o600,
+  createParent = true
+): void {
+  if (createParent) fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode, flag: 'wx' });
+    try {
+      fs.linkSync(temporary, filePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+        throw new Error(duplicateCode);
+      }
+      throw error;
+    }
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
 export function readJsonFile(filePath: string): unknown {
   assertRegularFile(filePath);
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
 }
 
+export function resultEvidencePath(manifest: SandboxControlManifest, requestId: string): string {
+  if (!/^[a-f0-9-]{16,64}$/u.test(requestId)) throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+  return path.join(manifest.processingDir, requestId, 'result.json');
+}
+
+export function payloadPath(manifest: SandboxControlManifest, requestId: string): string {
+  if (!/^[a-f0-9-]{16,64}$/u.test(requestId)) throw new Error('SANDBOX_CONTROL_PAYLOAD_INVALID');
+  return path.join(manifest.channelDir, 'responses', `${requestId}.payload.json`);
+}
+
+export function reservationPath(manifest: SandboxControlManifest, requestId: string): string {
+  if (!/^[a-f0-9-]{16,64}$/u.test(requestId)) throw new Error('SANDBOX_CONTROL_RESERVATION_INVALID');
+  return path.join(manifest.processingDir, requestId, 'reservation.json');
+}
+
+export function readSandboxControlResultEvidence(filePath: string): SandboxControlResultEvidence {
+  assertRegularFile(filePath);
+  const raw = fs.readFileSync(filePath, 'utf8');
+  if (Buffer.byteLength(raw, 'utf8') > SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES) {
+    throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_TOO_LARGE');
+  }
+  try {
+    return parseSandboxControlResultEvidence(JSON.parse(raw));
+  } catch (error) {
+    if (error instanceof Error && error.message === 'SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID') throw error;
+    throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+  }
+}
+
+export function sanitizeSandboxControlOutput(manifest: SandboxControlManifest, output: string): string {
+  return manifest.token.length === 0 ? output : output.split(manifest.token).join('[REDACTED]');
+}
+
+export function sanitizeSandboxControlResult(
+  manifest: SandboxControlManifest,
+  result: Readonly<{ exitCode: number; stdout: string; stderr: string }>
+): { exitCode: number; stdout: string; stderr: string } {
+  return {
+    exitCode: result.exitCode,
+    stdout: sanitizeSandboxControlOutput(manifest, result.stdout),
+    stderr: sanitizeSandboxControlOutput(manifest, result.stderr)
+  };
+}
+
+export function writeSandboxControlResultEvidence(
+  manifest: SandboxControlManifest,
+  requestId: string,
+  result: Readonly<{ exitCode: number; stdout: string; stderr: string }>
+): SandboxControlResultEvidence {
+  const normalized = sanitizeSandboxControlResult(manifest, result);
+  const stdout = normalized.stdout;
+  const stderr = normalized.stderr;
+  if (!/^[a-f0-9-]{16,64}$/u.test(requestId)
+    || !Number.isSafeInteger(result.exitCode)
+    || Buffer.byteLength(stdout, 'utf8') + Buffer.byteLength(stderr, 'utf8') > SANDBOX_CONTROL_MAX_RESPONSE_BYTES) {
+    throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+  }
+  const evidence: SandboxControlResultEvidence = {
+    version: 1,
+    id: requestId,
+    generation: manifest.generation,
+    exitCode: result.exitCode,
+    stdoutBytes: Buffer.byteLength(stdout, 'utf8'),
+    stderrBytes: Buffer.byteLength(stderr, 'utf8'),
+    stdoutSha256: createHash('sha256').update(stdout, 'utf8').digest('hex'),
+    stderrSha256: createHash('sha256').update(stderr, 'utf8').digest('hex'),
+    captureState: 'metadata-only'
+  };
+  if (sandboxControlEncodedJsonBytes(evidence) > SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES) {
+    throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_TOO_LARGE');
+  }
+  atomicCreateJson(
+    resultEvidencePath(manifest, requestId), evidence,
+    'SANDBOX_CONTROL_RESULT_EVIDENCE_ALREADY_EXISTS'
+  );
+  return readSandboxControlResultEvidence(resultEvidencePath(manifest, requestId));
+}
+
+export function writeSandboxControlPayload(
+  manifest: SandboxControlManifest,
+  requestId: string,
+  result: Readonly<{ stdout: string; stderr: string }>
+): SandboxControlPayload {
+  const payload = createSandboxControlPayload(manifest, requestId, result);
+  atomicCreateJson(payloadPath(manifest, requestId), payload, 'SANDBOX_CONTROL_PAYLOAD_ALREADY_EXISTS');
+  return readSandboxControlPayload(payloadPath(manifest, requestId));
+}
+
+export function createSandboxControlPayload(
+  manifest: SandboxControlManifest,
+  requestId: string,
+  result: Readonly<{ stdout: string; stderr: string }>
+): SandboxControlPayload {
+  const stdout = sanitizeSandboxControlOutput(manifest, result.stdout);
+  const stderr = sanitizeSandboxControlOutput(manifest, result.stderr);
+  const payload: SandboxControlPayload = {
+    version: 1,
+    id: requestId,
+    generation: manifest.generation,
+    stdout,
+    stderr,
+    stdoutBytes: Buffer.byteLength(stdout, 'utf8'),
+    stderrBytes: Buffer.byteLength(stderr, 'utf8'),
+    stdoutSha256: createHash('sha256').update(stdout, 'utf8').digest('hex'),
+    stderrSha256: createHash('sha256').update(stderr, 'utf8').digest('hex')
+  };
+  if (payload.stdoutBytes + payload.stderrBytes > SANDBOX_CONTROL_MAX_RESPONSE_BYTES) {
+    throw new Error('SANDBOX_CONTROL_PAYLOAD_TOO_LARGE');
+  }
+  if (sandboxControlEncodedJsonBytes(payload) > SANDBOX_CONTROL_MAX_RESPONSE_BYTES) {
+    throw new Error('SANDBOX_CONTROL_PAYLOAD_TOO_LARGE');
+  }
+  return payload;
+}
+
+export function readSandboxControlPayload(filePath: string): SandboxControlPayload {
+  assertRegularFile(filePath);
+  const raw = fs.readFileSync(filePath, 'utf8');
+  if (Buffer.byteLength(raw, 'utf8') > SANDBOX_CONTROL_MAX_RESPONSE_BYTES) {
+    throw new Error('SANDBOX_CONTROL_PAYLOAD_TOO_LARGE');
+  }
+  try {
+    return parseSandboxControlPayload(JSON.parse(raw));
+  } catch {
+    throw new Error('SANDBOX_CONTROL_PAYLOAD_INVALID');
+  }
+}
+
+export function writeSandboxControlReservation(
+  manifest: SandboxControlManifest,
+  requestId: string,
+  usage: Readonly<{ logicalRecords: number; bytes: number }>,
+  now = Date.now()
+): SandboxControlReservation {
+  if (usage.logicalRecords >= SANDBOX_CONTROL_MAX_LOGICAL_RECORDS
+    || usage.bytes + SANDBOX_CONTROL_RESERVATION_BYTES > SANDBOX_CONTROL_MAX_RESPONSE_BYTES) {
+    throw new Error('SANDBOX_CONTROL_CAPACITY_EXHAUSTED');
+  }
+  const reservation: SandboxControlReservation = {
+    version: 1,
+    id: requestId,
+    generation: manifest.generation,
+    logicalRecords: 1,
+    bytes: SANDBOX_CONTROL_RESERVATION_BYTES,
+    createdAt: now
+  };
+  atomicCreateJson(reservationPath(manifest, requestId), reservation, 'SANDBOX_CONTROL_RESERVATION_ALREADY_EXISTS');
+  return parseSandboxControlReservation(readJsonFile(reservationPath(manifest, requestId)));
+}
+
+export function readSandboxControlReservation(filePath: string): SandboxControlReservation {
+  return parseSandboxControlReservation(readJsonFile(filePath));
+}
+
+export function sandboxControlGenerationUsage(manifest: SandboxControlManifest): { logicalRecords: number; bytes: number } {
+  const records = new Map<string, { baseBytes: number; payloadBytes: number; logical: boolean }>();
+  const responsesDir = path.join(manifest.channelDir, 'responses');
+  if (fs.existsSync(responsesDir)) {
+    for (const entry of fs.readdirSync(responsesDir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const terminal = entry.name.match(/^([a-f0-9-]{16,64})\.json$/u);
+      const accepted = entry.name.match(/^([a-f0-9-]{16,64})\.accepted\.json$/u);
+      const payload = entry.name.match(/^([a-f0-9-]{16,64})\.payload\.json$/u);
+      if (!terminal && !accepted && !payload) continue;
+      const id = (terminal ?? accepted ?? payload)![1]!;
+      const previous = records.get(id) ?? { baseBytes: 0, payloadBytes: 0, logical: false };
+      const fileBytes = fs.statSync(path.join(responsesDir, entry.name)).size;
+      if (payload) previous.payloadBytes += fileBytes;
+      else previous.baseBytes += fileBytes;
+      previous.logical ||= Boolean(terminal || accepted);
+      records.set(id, previous);
+    }
+  }
+  if (fs.existsSync(manifest.processingDir)) {
+    for (const entry of fs.readdirSync(manifest.processingDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !/^[a-f0-9-]{16,64}$/u.test(entry.name)) continue;
+      const resultPath = resultEvidencePath(manifest, entry.name);
+      const filePath = reservationPath(manifest, entry.name);
+      const previous = records.get(entry.name) ?? { baseBytes: 0, payloadBytes: 0, logical: false };
+      if (fs.existsSync(resultPath)) {
+        const result = readSandboxControlResultEvidence(resultPath);
+        if (result.id !== entry.name || result.generation !== manifest.generation) {
+          throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+        }
+        previous.baseBytes += fs.statSync(resultPath).size;
+        previous.logical = true;
+      }
+      if (fs.existsSync(filePath)) {
+        const reservation = readSandboxControlReservation(filePath);
+        previous.baseBytes = Math.max(previous.baseBytes, reservation.bytes);
+        previous.logical = true;
+      }
+      records.set(entry.name, previous);
+    }
+  }
+  return {
+    logicalRecords: [...records.values()].filter((record) => record.logical).length,
+    bytes: [...records.values()].reduce((total, record) => total + record.baseBytes + record.payloadBytes, 0)
+  };
+}
+
 export function statusPath(manifest: SandboxControlManifest): string {
   return path.join(manifest.publicStatusDir, 'status.json');
 }
@@ -46,10 +297,11 @@ export function writeSandboxControlStatus(
   state: SandboxControlStatus['state'],
   reasonCode: string | null,
   activeRequestId: string | null,
-  now = Date.now()
+  now = Date.now(),
+  taskView: SandboxTaskView = taskViewForManifest(manifest)
 ): SandboxControlStatus {
   const status: SandboxControlStatus = {
-    version: 2, generation: manifest.generation, broker, state, reasonCode, activeRequestId, updatedAt: now
+    version: 3, generation: manifest.generation, broker, state, reasonCode, activeRequestId, updatedAt: now, taskView
   };
   atomicWriteJson(statusPath(manifest), status, 0o600, false);
   return status;
@@ -57,7 +309,7 @@ export function writeSandboxControlStatus(
 
 export function parseSandboxControlStatus(value: unknown): SandboxControlStatus {
   const status = value as Partial<SandboxControlStatus> | null;
-  if (!status || status.version !== 2 || typeof status.generation !== 'string'
+  if (!status || status.version !== 3 || typeof status.generation !== 'string'
     || !status.broker || !Number.isSafeInteger(status.broker.pid) || typeof status.broker.startTime !== 'number'
     || !Number.isSafeInteger(status.broker.startTime) || typeof status.broker.brokerId !== 'string'
     || status.broker.brokerId.length === 0
@@ -65,6 +317,7 @@ export function parseSandboxControlStatus(value: unknown): SandboxControlStatus
     || (status.reasonCode !== null && typeof status.reasonCode !== 'string')
     || (status.activeRequestId !== null && typeof status.activeRequestId !== 'string')
     || !Number.isSafeInteger(status.updatedAt)) throw new Error('SANDBOX_CONTROL_STATUS_INVALID');
+  parseSandboxTaskView(status.taskView);
   return status as SandboxControlStatus;
 }
 

package/lib/sandbox/control/task-view.ts

@@ -0,0 +1,240 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SANDBOX_TASK_VIEW_STATES = ['not-applicable', 'current', 'finalized-stale', 'unknown'] as const;
+export const SANDBOX_TASK_VIEW_SOURCES = ['active', 'completed', 'unknown'] as const;
+
+export type SandboxTaskViewState = typeof SANDBOX_TASK_VIEW_STATES[number];
+export type SandboxTaskViewSource = typeof SANDBOX_TASK_VIEW_SOURCES[number];
+export type SandboxTaskViewReceipt = Readonly<{
+  receiptId: string;
+  revision: number;
+  generation: string;
+  requestId: string;
+}>;
+export type SandboxTaskView = Readonly<{
+  state: SandboxTaskViewState;
+  taskId: string | null;
+  observedSource: SandboxTaskViewSource | null;
+  receipt: SandboxTaskViewReceipt | null;
+  reasonCode: string | null;
+}>;
+
+export type TaskViewProjectionInput = Readonly<{
+  mode: 'task-bound' | 'branch-only';
+  taskId: string | null;
+  generation: string;
+  source: SandboxTaskViewSource;
+  sourceMatches: boolean;
+  receipt?: unknown;
+  requestId?: string;
+}>;
+
+export type TaskViewAccessEffect =
+  | 'diagnostic'
+  | 'progress'
+  | 'artifact-write'
+  | 'terminal-verdict'
+  | 'recovery'
+  | 'cleanup'
+  | 'remote-write';
+
+export type TaskViewAccess = Readonly<{
+  allowed: boolean;
+  state: SandboxTaskViewState;
+  reasonCode: string | null;
+  message: string | null;
+}>;
+
+function invalidView(message: string): Error {
+  return new Error(`SANDBOX_TASK_VIEW_INVALID: ${message}`);
+}
+
+function receiptIdentity(value: unknown, generation: string, requestId?: string): SandboxTaskViewReceipt | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const receipt = value as Record<string, unknown>;
+  const binding = receipt.controlBinding;
+  if (!binding || typeof binding !== 'object' || Array.isArray(binding)) return null;
+  const controlBinding = binding as Record<string, unknown>;
+  if (receipt.version !== 2 || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
+    || !Number.isSafeInteger(receipt.revision) || (receipt.revision as number) < 0
+    || receipt.lifecycle !== 'done'
+    || controlBinding.generation !== generation
+    || typeof controlBinding.requestId !== 'string'
+    || !/^[a-f0-9-]{16,64}$/u.test(controlBinding.requestId)
+    || (requestId !== undefined && controlBinding.requestId !== requestId)) return null;
+  return {
+    receiptId: receipt.receiptId,
+    revision: receipt.revision as number,
+    generation,
+    requestId: controlBinding.requestId
+  };
+}
+
+export function parseSandboxTaskView(value: unknown): SandboxTaskView {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalidView('taskView must be an object');
+  const view = value as Record<string, unknown>;
+  const receipt = view.receipt === null ? null : parseSandboxTaskViewReceipt(view.receipt);
+  if (!SANDBOX_TASK_VIEW_STATES.includes(view.state as SandboxTaskViewState)
+    || (view.taskId !== null && typeof view.taskId !== 'string')
+    || (view.observedSource !== null && !SANDBOX_TASK_VIEW_SOURCES.includes(view.observedSource as SandboxTaskViewSource))
+    || (view.reasonCode !== null && typeof view.reasonCode !== 'string')
+    || (view.receipt !== null && receipt === null)) {
+    throw invalidView('taskView schema is invalid');
+  }
+  if (view.state === 'not-applicable' && (view.taskId !== null || view.observedSource !== null || view.receipt !== null)) {
+    throw invalidView('not-applicable taskView cannot carry task evidence');
+  }
+  if (view.state === 'current' && (view.taskId === null || view.observedSource === null)) {
+    throw invalidView('current taskView requires taskId and observedSource');
+  }
+  if (view.state === 'current' && view.observedSource === 'completed' && view.receipt === null) {
+    throw invalidView('completed current taskView requires receipt');
+  }
+  if (view.state === 'finalized-stale' && (view.taskId === null || view.receipt === null)) {
+    throw invalidView('finalized-stale taskView requires taskId and receipt');
+  }
+  return view as SandboxTaskView;
+}
+
+function parseSandboxTaskViewReceipt(value: unknown): SandboxTaskViewReceipt | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const receipt = value as Record<string, unknown>;
+  if (Object.keys(receipt).sort().join(',') !== 'generation,receiptId,requestId,revision'
+    || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
+    || !Number.isSafeInteger(receipt.revision) || (receipt.revision as number) < 0
+    || typeof receipt.generation !== 'string' || receipt.generation.length === 0
+    || typeof receipt.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(receipt.requestId)) return null;
+  return receipt as SandboxTaskViewReceipt;
+}
+
+export function taskViewForManifest(params: Readonly<{
+  repoRoot: string;
+  mode: 'task-bound' | 'branch-only';
+  taskId: string | null;
+  generation: string;
+  receipt?: unknown;
+}>): SandboxTaskView {
+  if (params.mode !== 'task-bound' || !params.taskId) {
+    return { state: 'not-applicable', taskId: null, observedSource: null, receipt: null, reasonCode: null };
+  }
+  const active = path.join(params.repoRoot, '.agents', 'workspace', 'active', params.taskId, 'task.md');
+  const completed = path.join(params.repoRoot, '.agents', 'workspace', 'completed', params.taskId, 'task.md');
+  const activeExists = fs.existsSync(active);
+  const completedExists = fs.existsSync(completed);
+  if (activeExists === completedExists) {
+    return {
+      state: 'unknown', taskId: params.taskId,
+      observedSource: activeExists ? 'unknown' : null,
+      receipt: null, reasonCode: activeExists ? 'SANDBOX_TASK_VIEW_SOURCE_CONFLICT' : 'SANDBOX_TASK_VIEW_SOURCE_MISSING'
+    };
+  }
+  const source = completedExists ? 'completed' : 'active';
+  const receipt = receiptIdentity(params.receipt, params.generation);
+  const receiptProvided = params.receipt !== undefined && params.receipt !== null;
+  if (source === 'completed' && receipt) {
+    return { state: 'current', taskId: params.taskId, observedSource: source, receipt, reasonCode: null };
+  }
+  if (source === 'active' && receipt) {
+    return {
+      state: 'finalized-stale', taskId: params.taskId, observedSource: source, receipt,
+      reasonCode: 'SANDBOX_TASK_VIEW_SOURCE_STALE'
+    };
+  }
+  if (receiptProvided) {
+    return {
+      state: 'unknown', taskId: params.taskId, observedSource: source, receipt: null,
+      reasonCode: 'SANDBOX_TASK_VIEW_RECEIPT_INVALID'
+    };
+  }
+  if (source === 'active') {
+    return { state: 'current', taskId: params.taskId, observedSource: source, receipt: null, reasonCode: null };
+  }
+  return {
+    state: 'unknown', taskId: params.taskId, observedSource: source, receipt: null,
+    reasonCode: 'SANDBOX_TASK_VIEW_EVIDENCE_UNAVAILABLE'
+  };
+}
+
+export function projectSandboxTaskView(input: TaskViewProjectionInput): SandboxTaskView {
+  if (input.mode !== 'task-bound' || !input.taskId) {
+    return { state: 'not-applicable', taskId: null, observedSource: null, receipt: null, reasonCode: null };
+  }
+  const receipt = receiptIdentity(input.receipt, input.generation, input.requestId);
+  if (input.source === 'completed' && receipt && input.sourceMatches) {
+    return { state: 'current', taskId: input.taskId, observedSource: 'completed', receipt, reasonCode: null };
+  }
+  if (receipt && input.source === 'active' && !input.sourceMatches) {
+    return { state: 'finalized-stale', taskId: input.taskId, observedSource: 'active', receipt, reasonCode: 'SANDBOX_TASK_VIEW_SOURCE_STALE' };
+  }
+  if (!receipt && input.source === 'active' && input.sourceMatches) {
+    return { state: 'current', taskId: input.taskId, observedSource: 'active', receipt: null, reasonCode: null };
+  }
+  return {
+    state: 'unknown',
+    taskId: input.taskId,
+    observedSource: input.source,
+    receipt,
+    reasonCode: receipt ? 'SANDBOX_TASK_VIEW_SOURCE_UNCONFIRMED' : 'SANDBOX_TASK_VIEW_EVIDENCE_UNAVAILABLE'
+  };
+}
+
+export function taskViewAfterFinalization(params: Readonly<{
+  taskId: string;
+  generation: string;
+  requestId: string;
+  receipt: unknown;
+}>): SandboxTaskView {
+  const receipt = receiptIdentity(params.receipt, params.generation, params.requestId);
+  if (!receipt) {
+    return {
+      state: 'unknown', taskId: params.taskId, observedSource: 'unknown', receipt: null,
+      reasonCode: 'SANDBOX_TASK_VIEW_RECEIPT_INVALID'
+    };
+  }
+  return {
+    state: 'finalized-stale', taskId: params.taskId, observedSource: 'active', receipt,
+    reasonCode: 'SANDBOX_TASK_VIEW_FINALIZED'
+  };
+}
+
+export function mergeSandboxTaskView(
+  canonical: SandboxTaskView,
+  previous: SandboxTaskView
+): SandboxTaskView {
+  if (previous.state !== 'finalized-stale' && previous.state !== 'unknown') return canonical;
+  return previous;
+}
+
+export function accessSandboxTaskView(view: SandboxTaskView, effect: TaskViewAccessEffect): TaskViewAccess {
+  if (effect === 'diagnostic' || effect === 'cleanup' || effect === 'recovery') {
+    return { allowed: true, state: view.state, reasonCode: view.reasonCode, message: null };
+  }
+  if (view.state === 'current' && view.observedSource === 'active') {
+    return { allowed: true, state: view.state, reasonCode: null, message: null };
+  }
+  const reasonCode = view.state === 'current'
+    ? 'SANDBOX_TASK_VIEW_COMPLETED_READ_ONLY'
+    : view.reasonCode ?? `SANDBOX_TASK_VIEW_${view.state.toUpperCase().replaceAll('-', '_')}`;
+  return {
+    allowed: false,
+    state: view.state,
+    reasonCode,
+    message: view.state === 'unknown'
+      ? 'task view cannot be confirmed; inspect status, recover the original request, or explicitly clean up the sandbox'
+      : view.state === 'finalized-stale'
+        ? 'task view is finalized/stale; exit or clean up the sandbox, or use a validated re-entry'
+        : 'completed task views are read-only'
+  };
+}
+
+export function taskViewFromStatus(value: unknown): SandboxTaskView {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalidView('status must be an object');
+  const status = value as Record<string, unknown>;
+  if (status.version !== 3) throw invalidView('status version is unsupported');
+  const taskView = parseSandboxTaskView(status.taskView);
+  if (taskView.receipt && taskView.receipt.generation !== status.generation) {
+    throw invalidView('taskView receipt generation does not match status generation');
+  }
+  return taskView;
+}