@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/harness-runtime/lib/agy-error-boundary.mjs

@@ -0,0 +1,87 @@
+import { parseLifecycleCommand, commandOption, commandPosition } from "./lifecycle-command.mjs";
+import { entityReferenceVariants } from "./entity-references.mjs";
+import { agyTerminalEnvelope, ownedAgyOutput } from "./agy-terminal-envelope.mjs";
+
+/** Ordered native transcript evidence, never assistant text as a success signal. */
+export function recoveredAgyErrorBoundary(text, error, floor = -1, source = null, sessionId = null) {
+  let rows;
+  try { rows = text.trim().split("\n").filter(Boolean).map(JSON.parse); } catch { return null; }
+  const reducer = createAgyErrorBoundary(error, floor, source, sessionId);
+  for (const row of rows) reducer.add(row);
+  return reducer.finish();
+}
+
+/** Stateful equivalent for an owned, validated JSONL snapshot. */
+export function createAgyErrorBoundary(error, floor = -1, source = null, sessionId = null) {
+  let previous = -1, lastError = null, boundary = null, invocation = null, call = null;
+  const launches = new Map(); let invalid = false;
+  function add(row) {
+    if (invalid) return;
+    if (!Number.isInteger(row.step_index) || row.step_index <= previous) { invalid = true; return; }
+    previous = row.step_index;
+    if (row.step_index <= (floor ?? -1)) return;
+    if (row.type === "USER_INPUT") { lastError = null; boundary = null; invocation = null; call = null; launches.clear(); return; }
+    if (row.type === "ERROR_MESSAGE") { lastError = row; boundary = null; invocation = null; return; }
+    if (Array.isArray(row.tool_calls)) {
+      invocation = null;
+      call = row.tool_calls.length === 1 ? row.tool_calls[0] : null;
+      if (row.tool_calls.length === 1 && row.tool_calls[0]?.name === "run_command") {
+        let command = row.tool_calls[0]?.args?.CommandLine;
+        if (typeof command === "string") {
+          try { const unquoted = JSON.parse(command); if (typeof unquoted === "string") command = unquoted; } catch { /* ordinary shell bytes */ }
+          const parsed = parseLifecycleCommand(command);
+          if ((parsed.kind === "standalone" || parsed.kind === "compound" && parsed.supported === true && parsed.invocations?.length === 1) && ["stage_finish", "work_finish", "stage_pause", "recovery_accept"].includes(parsed.invocation.operation)) invocation = parsed.invocation;
+        }
+      }
+    }
+    if (row.type === 'GENERIC' && row.status === 'RUNNING') {
+      const task = row.content?.match(/^Created At: [^\n]+\nTool is running as a background task with task id: ([\w-]+\/task-\d+)\n/);
+      if (task && invocation && (!sessionId || task[1].startsWith(`${sessionId}/`))) launches.set(task[1], launches.has(task[1]) ? null : { invocation, step: row.step_index });
+      call = null; invocation = null; return;
+    }
+    const envelope = agyTerminalEnvelope(row, call);
+    let launchStep = null;
+    if (envelope?.task_id) {
+      const launch = launches.get(envelope.task_id);
+      invocation = launch && launch.step < row.step_index ? launch.invocation : null;
+      launchStep = launch?.step ?? null;
+    }
+    if (!lastError || envelope?.exit_code !== 0) return;
+    const retained = envelope.output_reference && source && sessionId ? ownedAgyOutput(envelope.output_reference, source, sessionId, envelope.task_id) : null;
+    const full = retained ? agyTerminalEnvelope({ type: 'GENERIC', status: 'DONE', content: retained.text }) : null;
+    const output = (retained ? full?.exit_code === 0 ? full.output : null : envelope.output)?.replaceAll("\r", "");
+    if (!output) return;
+    for (const match of output.matchAll(/^\s*\{/gm)) {
+      let receipt;
+      const candidate = output.slice(match.index).trim();
+      try { receipt = JSON.parse(candidate); } catch {
+        // AGY's transcript renderer can unescape control characters inside
+        // pause.user_message. Parse only the intact machine header, never the
+        // rendered question; the controller must still verify the DB receipt.
+        const end = candidate.indexOf(',\n    "user_message":');
+        if (end < 0) continue;
+        try { receipt = JSON.parse(`${candidate.slice(0, end)}}}`); } catch { continue; }
+      }
+      if (receipt.ok === true && invocation && invocation.operation !== "stage_pause") {
+        if (invocation.operation === "recovery_accept" && receipt.accepted === true && typeof receipt.recovery_id === "string") boundary = { receipt: { ok: true, outcome: "completed", lifecycle_operation: "recovery_accept", recovery_id: receipt.recovery_id }, error_step: lastError.step_index, boundary_step: row.step_index };
+        const stage = receipt.stage ?? commandOption(invocation, "stage");
+        const runId = receipt.run_id;
+        const workId = receipt.work_id ?? receipt.work?.work_id ?? commandOption(invocation, "work") ?? (invocation.operation === "work_finish" ? commandPosition(invocation, 0) : null);
+        if (invocation.operation === "work_finish" && receipt.status === "completed" && typeof workId === "string") boundary = { receipt: { ok: true, outcome: "completed", work_id: workId, lifecycle_operation: "work_finish" }, error_step: lastError.step_index, boundary_step: row.step_index };
+        if (typeof stage === "string" && typeof runId === "string" && (invocation.operation === "work_finish" || entityReferenceVariants(runId).includes(commandPosition(invocation, 0)))) {
+          boundary = { receipt: { ok: true, outcome: "completed", run_id: runId, stage, ...(workId ? { work_id: workId } : {}), lifecycle_operation: invocation.operation }, error_step: lastError.step_index, boundary_step: row.step_index };
+        }
+      }
+      if (invocation?.operation === "stage_pause" && commandOption(invocation, "stage") === receipt.stage && receipt.ok === true && receipt.outcome === "paused"
+        && [receipt.run_id, receipt.stage, receipt.work_id].every(value => typeof value === "string" && value)
+        && (receipt.outcome !== "paused" || typeof receipt.pause?.id === "string")) boundary = { receipt: { ok: true, outcome: receipt.outcome, run_id: receipt.run_id, stage: receipt.stage, work_id: receipt.work_id,
+          lifecycle_operation: "stage_pause", pause: { id: receipt.pause.id } }, error_step: lastError.step_index, boundary_step: row.step_index };
+      if (boundary?.boundary_step === row.step_index) {
+        if (launchStep !== null) boundary.invocation_step = launchStep;
+        if (retained) boundary.output_source = { locator: retained.locator, sha256: retained.sha256 };
+      }
+    }
+  }
+  return { add, finish: () => !invalid && boundary && lastError?.error === error ? boundary : null };
+}
+

package/dist/harness-runtime/lib/agy-hooks.d.mts

@@ -0,0 +1 @@
+export function agyWorkspaceHooks(): Record<string, unknown>;

package/dist/harness-runtime/lib/agy-hooks.mjs

@@ -0,0 +1,9 @@
+// Qualified hooks are stable; only the launching process selects its pinned
+// entrypoint and daemon. Keep this document shared with product-file policy.
+export function agyWorkspaceHooks() {
+  const command = '"${DD_AGY_HOOK_NODE:?missing AGY hook binding}" "${DD_AGY_HOOK_ENTRY:?missing AGY hook binding}" hook handle --event __EVENT__ --state-dir "${DD_AGY_STATE_DIR:?missing AGY hook binding}" --daemon-id "${DD_AGY_DAEMON_ID:?missing AGY hook binding}" --json';
+  return { "dd-flow": {
+    PreToolUse: [{ matcher: "^run_command$", hooks: [{ type: "command", command: command.replace("__EVENT__", "PreToolUse"), timeout: 30 }] }],
+    Stop: [{ type: "command", command: command.replace("__EVENT__", "Stop"), timeout: 30 }]
+  } };
+}

package/dist/harness-runtime/lib/agy-native-inspection.mjs

@@ -0,0 +1,225 @@
+import * as grpc from '@grpc/grpc-js';
+import { create, toBinary, fromBinary } from '@bufbuild/protobuf';
+import { WaitForConversationFullyIdleRequestSchema, WaitForConversationFullyIdleResponseSchema, GetConversationMetadataRequestSchema, GetConversationMetadataResponseSchema, ForceStopCascadeTreeRequestSchema, ForceStopCascadeTreeResponseSchema, StreamAgentStateUpdatesRequestSchema, StreamAgentStateUpdatesResponseSchema } from './agy-native_pb.js';
+import { randomUUID } from 'node:crypto';
+import { readFile, lstat, realpath, open } from 'node:fs/promises';
+import { createReadStream, constants } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { processSnapshot } from './process-snapshot.mjs';
+
+export const AGY_NATIVE_INSPECTION_CONTRACT = 'agy-native-inspection@2';
+export const AGY_NATIVE_LIVE_CASES = ['root_child_running', 'child_background_running', 'grandchild_running', 'completion_delivery', 'fully_idle', 'timer_delivery', 'daemon_excluded_from_required_execution', 'owned_daemon_retirement'];
+export const AGY_NATIVE_SAFETY_CASES = ['executor_error', 'timeout', 'late_activity_cancel_restart'];
+export const AGY_NATIVE_QUALIFICATION_CASES = [...AGY_NATIVE_LIVE_CASES, ...AGY_NATIVE_SAFETY_CASES];
+export const AGY_NATIVE_EVIDENCE_CONTRACT = 'agy-native-inspection-evidence@2';
+/** Operator-retained native observations, not a bag of manually asserted PASSes.
+ * This validates evidence structure/meaning, not its authenticity: the operator
+ * still owns capture and review, as with every local qualification receipt. */
+export function validateAgyNativeEvidence(evidence, identity) {
+  const checks = Object.fromEntries(AGY_NATIVE_QUALIFICATION_CASES.map(name => [name, false]));
+  const failed = new Set();
+  const fencedChanges = new Set();
+  const liveServices = new Map(), retiredServices = [];
+  if (evidence?.schema_id !== AGY_NATIVE_EVIDENCE_CONTRACT || evidence.binary_sha256 !== identity.sha256 || evidence.client_contract_sha256 !== identity.client_contract_sha256 || !['self', 'empty_self'].includes(evidence.root_relation) || !Array.isArray(evidence.observations)) return { qualified: false, checks };
+  for (const item of evidence.observations) {
+    if (!item || !AGY_NATIVE_QUALIFICATION_CASES.includes(item.case)) continue;
+    if (AGY_NATIVE_LIVE_CASES.includes(item.case) && item.evidence_kind !== 'live' || AGY_NATIVE_SAFETY_CASES.includes(item.case) && !['live', 'deterministic'].includes(item.evidence_kind)) { failed.add(item.case); continue; }
+    if (item.source !== 'agy.native' || typeof item.session_id !== 'string' || !item.session_id || typeof item.locator !== 'string' || !item.locator || !Number.isFinite(Date.parse(item.observed_at))) { failed.add(item.case); continue; }
+    const before = item.before, after = item.after, wait = item.wait;
+    // Observation itself must not create a user/model turn; background model
+    // work may continue, hence the explicit inspection-attributed counters.
+    if (!before || !after || !['user_turns', 'model_requests'].every(key => Number.isSafeInteger(before[key]) && before[key] >= 0 && after[key] === before[key]) || !wait || !Number.isInteger(wait.grpc_code) || wait.grpc_code < 0 || wait.grpc_code > 16 || typeof item.idle_granted !== 'boolean') { failed.add(item.case); continue; }
+    const idle = wait.grpc_code === 0 && wait.timed_out === false;
+    const busy = wait.grpc_code === 4 || wait.grpc_code === 0 && wait.timed_out === true;
+    const noGrant = item.idle_granted === false;
+    const work = Array.isArray(item.work) ? item.work : [];
+    const has = (kind, status) => work.some(record => record?.kind === kind && record.status === status && typeof record.id === 'string' && record.id && record.root_session_id === item.session_id);
+    const prior = checks[item.case]; checks[item.case] = false;
+    if (item.case === 'root_child_running' && item.root_status === 'terminal' && has('child', 'running') && busy && noGrant) checks[item.case] = true;
+    if (item.case === 'child_background_running' && has('child', 'terminal') && has('background', 'running') && busy && noGrant) checks[item.case] = true;
+    if (item.case === 'grandchild_running' && item.root_status === 'terminal' && item.inventory_complete === true && has('child', 'terminal') && has('grandchild', 'running') && work.every(record => record?.kind === 'grandchild' || record?.status === 'terminal') && busy && noGrant) checks[item.case] = true;
+    if (item.case === 'completion_delivery' && has('completion', 'pending') && busy && noGrant) checks[item.case] = true;
+    if (item.case === 'timer_delivery' && has('timer', 'terminal') && has('completion', 'terminal') && item.inventory_complete === true && work.every(record => record?.status === 'terminal' && record.root_session_id === item.session_id) && item.root_status === 'terminal' && idle && item.idle_granted === true) checks[item.case] = true;
+    if (item.case === 'fully_idle' && item.root_status === 'terminal' && item.inventory_complete === true && work.every(record => record?.status === 'terminal' && typeof record.id === 'string' && record.id && record.root_session_id === item.session_id) && idle && item.idle_granted === true) checks[item.case] = true;
+    if (item.case === 'executor_error' && typeof item.executor_error === 'string' && item.executor_error && noGrant && (busy || wait.grpc_code !== 0)) checks[item.case] = true;
+    if (item.case === 'timeout' && busy && noGrant) checks[item.case] = true;
+    if (item.case === 'late_activity_cancel_restart' && ['activity', 'cancel', 'restart'].includes(item.fence?.change) && typeof item.fence.before === 'string' && item.fence.before && typeof item.fence.after === 'string' && item.fence.after && item.fence.after !== item.fence.before && idle && noGrant) { checks[item.case] = true; fencedChanges.add(item.fence.change); }
+    const service = work.find(record => record?.kind === 'persistent' && record.native_tool === 'run_command' && record.native_is_daemon === true && record.root_session_id === item.session_id && typeof record.id === 'string' && record.id && Number.isSafeInteger(record.process?.pid) && record.process.pid > 0 && typeof record.process.birth === 'string' && record.process.birth && record.process.owned === true);
+    const serviceKey = service && JSON.stringify([item.session_id, service.id, service.process.pid, service.process.birth]);
+    if (item.case === 'daemon_excluded_from_required_execution' && service?.status === 'running' && service.process.live === true && item.root_status === 'terminal' && item.native_result_status === 'SUCCESS' && item.inventory_complete === true && work.every(record => record === service || record?.status === 'terminal' && typeof record.id === 'string' && record.id && record.root_session_id === item.session_id) && idle && item.idle_granted === true) { checks[item.case] = true; liveServices.set(serviceKey, Date.parse(item.observed_at)); }
+    if (item.case === 'owned_daemon_retirement' && service?.status === 'terminal' && service.process.live === false && item.cleanup?.coverage === 'complete' && item.cleanup.provider_stopped === true && typeof item.cleanup.snapshot_locator === 'string' && item.cleanup.snapshot_locator && noGrant) { checks[item.case] = true; retiredServices.push([serviceKey, Date.parse(item.observed_at)]); }
+    if (!checks[item.case]) failed.add(item.case);
+    checks[item.case] ||= prior;
+  }
+  checks.late_activity_cancel_restart &&= fencedChanges.size === 3;
+  checks.owned_daemon_retirement &&= liveServices.size > 0 && [...liveServices].every(([key, started]) => retiredServices.some(([retiredKey, at]) => retiredKey === key && at >= started));
+  for (const name of failed) checks[name] = false;
+  return { qualified: Object.values(checks).every(Boolean), checks };
+}
+const run = promisify(execFile);
+const invalid = reason => Object.assign(new Error(`AGY native inspection unavailable: ${reason}`), { code: 'agy_native_inspection_unavailable', details: { reason, capability: AGY_NATIVE_INSPECTION_CONTRACT } });
+const codec = schema => ({ serialize: value => Buffer.from(toBinary(schema, create(schema, value))), deserialize: bytes => fromBinary(schema, bytes) });
+const method = (name, request, response) => ({ path: `/exa.language_server_pb.LanguageServerService/${name}`, requestStream: false, responseStream: false, requestSerialize: codec(request).serialize, requestDeserialize: codec(request).deserialize, responseSerialize: codec(response).serialize, responseDeserialize: codec(response).deserialize });
+export const agyNativeService = {
+  wait: method('WaitForConversationFullyIdle', WaitForConversationFullyIdleRequestSchema, WaitForConversationFullyIdleResponseSchema),
+  metadata: method('GetConversationMetadata', GetConversationMetadataRequestSchema, GetConversationMetadataResponseSchema),
+  stop: method('ForceStopCascadeTree', ForceStopCascadeTreeRequestSchema, ForceStopCascadeTreeResponseSchema),
+  state: { ...method('StreamAgentStateUpdates', StreamAgentStateUpdatesRequestSchema, StreamAgentStateUpdatesResponseSchema), responseStream: true }
+};
+const Client = grpc.makeGenericClientConstructor(agyNativeService, 'AgyReadOnlyInspection');
+
+async function readRegular(file, maximum, prefix = false) {
+  if (!path.isAbsolute(file)) throw invalid('native_file_path_invalid');
+  const before = await lstat(file);
+  if (!before.isFile() || before.isSymbolicLink() || !prefix && before.size > maximum) throw invalid('native_file_rejected');
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino || !prefix && stat.size > maximum) throw invalid('native_file_changed');
+    const bytes = Buffer.alloc(prefix ? Math.min(stat.size, maximum) : maximum + 1);
+    const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+    const after = await lstat(file);
+    if (!after.isFile() || after.dev !== stat.dev || after.ino !== stat.ino || !prefix && bytesRead > maximum) throw invalid('native_file_changed');
+    return { bytes: bytes.subarray(0, bytesRead), stat };
+  } finally { await handle.close(); }
+}
+
+export async function agyBinaryIdentity(bin) {
+  if (typeof bin !== 'string' || !bin) throw invalid('native_binary_missing');
+  const candidate = path.isAbsolute(bin) ? bin : (await Promise.all((process.env.PATH ?? '').split(path.delimiter).map(async dir => {
+    const file = path.join(dir, bin); try { return (await lstat(file)).isFile() || (await lstat(file)).isSymbolicLink() ? file : null; } catch { return null; }
+  }))).find(Boolean);
+  if (!candidate) throw invalid('native_binary_missing');
+  const file = await realpath(candidate), hash = createHash('sha256');
+  for await (const chunk of createReadStream(file)) hash.update(chunk);
+  return { file, sha256: hash.digest('hex') };
+}
+export async function agyInspectionPolicyIdentity() {
+  const manifest = JSON.parse(await readFile(new URL('../../../package.json', import.meta.url), 'utf8'));
+  const versions = [manifest.dependencies?.['@grpc/grpc-js'], manifest.dependencies?.['@bufbuild/protobuf']];
+  if (versions[0] !== '1.14.6' || versions[1] !== '2.16.0') throw invalid('native_protocol_dependency_unqualified');
+  return createHash('sha256').update(AGY_NATIVE_INSPECTION_CONTRACT).update(JSON.stringify(versions)).update(await readFile(new URL('./agy-native_pb.js', import.meta.url))).update(await readFile(new URL('./agy-native-inspection.mjs', import.meta.url))).digest('hex');
+}
+export async function readAgyNativeQualification(stateDir, bin, receiptFile = null) {
+  const binary = await agyBinaryIdentity(bin);
+  const clientContract = await agyInspectionPolicyIdentity();
+  let receipt;
+  const file = receiptFile ?? path.join(stateDir, 'native-inspection-qualification.json');
+  if (!path.isAbsolute(file)) throw invalid('qualification_path_invalid');
+  try {
+    receipt = JSON.parse((await readRegular(file, 64 * 1024)).bytes.toString('utf8'));
+  }
+  catch (error) { if (error.code !== 'ENOENT') throw invalid('qualification_receipt_invalid'); }
+  let evidenceValid = false;
+  if (typeof receipt?.evidence_path === 'string' && path.isAbsolute(receipt.evidence_path)) {
+    try {
+      const evidence = (await readRegular(receipt.evidence_path, 1024 * 1024)).bytes;
+      const parsed = JSON.parse(evidence.toString('utf8'));
+      evidenceValid = createHash('sha256').update(evidence).digest('hex') === receipt.evidence_sha256
+        && parsed.root_relation === receipt.root_relation
+        && validateAgyNativeEvidence(parsed, { ...binary, client_contract_sha256: clientContract }).qualified;
+    } catch { /* No retained evidence means no qualification grant. */ }
+  }
+  const qualified = evidenceValid && receipt?.schema_id === AGY_NATIVE_INSPECTION_CONTRACT && receipt.scope === 'required_execution' && receipt.binary_sha256 === binary.sha256
+    && receipt.client_contract_sha256 === clientContract
+    && ['self', 'empty_self'].includes(receipt.root_relation)
+    && AGY_NATIVE_QUALIFICATION_CASES.every(name => receipt.checks?.[name] === true)
+    && typeof receipt.evidence_sha256 === 'string' && /^[a-f0-9]{64}$/.test(receipt.evidence_sha256);
+  return { ...binary, client_contract_sha256: clientContract, qualified, rootRelation: qualified ? receipt.root_relation : null };
+}
+
+/** Only the log for this physical launch may nominate an endpoint. Its live
+ * listener must be this provider or an OS descendant, with retained PID birth. */
+export async function ownedAgyEndpoint({ logFile, providerPid, providerBirth, snapshot = processSnapshot, listeners = async port => {
+  const { stdout } = await run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpn'], { timeout: 5_000, maxBuffer: 64 * 1024 });
+  let pid; return stdout.trim().split('\n').flatMap(line => line.startsWith('p') ? (pid = Number(line.slice(1)), []) : line.startsWith('n') ? [{ pid, address: line.slice(1) }] : []);
+} }) {
+  if (!path.isAbsolute(logFile ?? '') || !Number.isSafeInteger(providerPid) || !providerBirth) throw invalid('provider_binding_missing');
+  // Startup prefix only: later log growth is not an expiry or model progress.
+  const { bytes, stat } = await readRegular(logFile, 1024 * 1024, true), text = bytes.toString('utf8');
+  const ports = [...new Set([...text.matchAll(/Language server listening on random port at (\d+) for HTTP(?:\r?$)/gm)].map(match => Number(match[1])))];
+  if (ports.length !== 1 || ports[0] < 1 || ports[0] > 65535) throw invalid('native_endpoint_missing_or_ambiguous');
+  const records = await snapshot(), provider = records.find(record => record.pid === providerPid);
+  if (!provider || provider.started !== providerBirth || provider.zombie) throw invalid('provider_birth_changed');
+  const allowed = new Set([providerPid]); let changed;
+  do { changed = false; for (const record of records) if (allowed.has(record.ppid) && !allowed.has(record.pid) && !record.zombie) { allowed.add(record.pid); changed = true; } } while (changed);
+  const owners = await listeners(ports[0]);
+  if (!owners.length || owners.some(owner => !allowed.has(owner.pid) || !/^(?:127\.0\.0\.1|\[::1\]|localhost):\d+$/.test(owner.address))) throw invalid('native_endpoint_foreign_or_nonloopback');
+  const births = owners.map(owner => ({ pid: owner.pid, started: records.find(record => record.pid === owner.pid)?.started }));
+  if (births.some(owner => !owner.started)) throw invalid('listener_birth_missing');
+  return { target: `127.0.0.1:${ports[0]}`, provider_pid: providerPid, provider_birth: providerBirth, listeners: births, log_identity: `${stat.dev}:${stat.ino}` };
+}
+
+/** No model request: metadata read followed by the native idle barrier. The
+ * caller owns freshness fencing and qualification; a raw reply is not a grant. */
+async function agyNativeRequest({ endpoint, sessionId, cwd, remainingMs, signal, rootRelation = null, onMetadata = null, csrfToken, rootSessionId = sessionId, parentSessionId = '' }, action = 'wait', ownedSessions = []) {
+  if (!/^127\.0\.0\.1:\d+$/.test(endpoint?.target ?? '') || Number(endpoint.target.split(':')[1]) < 1 || Number(endpoint.target.split(':')[1]) > 65535) throw invalid('native_endpoint_nonloopback');
+  if (!Number.isFinite(remainingMs) || remainingMs < 1) throw invalid('observation_budget_exhausted');
+  const deadline = Date.now() + remainingMs;
+  const client = new Client(endpoint.target, grpc.credentials.createInsecure(), { 'grpc.max_receive_message_length': -1, 'grpc.max_send_message_length': 64 * 1024, 'grpc.enable_retries': 0 });
+  let active;
+  const headers = new grpc.Metadata();
+  if (typeof csrfToken === 'string' && csrfToken) headers.set('x-codeium-csrf-token', csrfToken);
+  const abort = () => active?.cancel();
+  // Native error details may contain request or authentication material. Keep
+  // the method and numeric status for diagnosis without copying those bytes.
+  const grpcError = (name, error) => {
+    const code = Number.isInteger(error?.code) ? error.code : null;
+    const failure = invalid(`grpc_${code ?? 'unknown'}`);
+    failure.details.grpc_method = agyNativeService[name].path;
+    failure.details.grpc_code = code;
+    return failure;
+  };
+  const unary = (name, request) => new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(invalid('inspection_cancelled'));
+    active = client[name](request, headers, { deadline }, (error, value) => error ? reject(grpcError(name, error)) : value ? resolve(value) : reject(invalid('grpc_message_missing')));
+  });
+  signal?.addEventListener('abort', abort, { once: true });
+  try {
+    const metadata = await unary('metadata', { conversationId: sessionId });
+    onMetadata?.(metadata);
+    const relation = metadata.metadata;
+    const rootMatches = relation?.rootConversationId === rootSessionId || rootRelation === 'empty_self' && rootSessionId === sessionId && relation?.rootConversationId === '';
+    const workspaces = await Promise.all((relation?.workspaceUris ?? []).map(async uri => { try { return await realpath(fileURLToPath(uri)); } catch { return null; } }));
+    if (!relation || relation.parentConversationId !== (action === 'state' ? parentSessionId : '') || action !== 'state' && rootSessionId !== sessionId || !rootMatches || !metadata.trajectoryId || !workspaces.includes(await realpath(cwd))) throw invalid('native_metadata_binding_unproven');
+    if (action === 'state') {
+      return await new Promise((resolve, reject) => {
+        if (signal?.aborted) return reject(invalid('inspection_cancelled'));
+        active = client.state({ conversationId: sessionId, subscriberId: randomUUID() }, headers, { deadline });
+        let done = false;
+        active.on('data', value => {
+          if (done) return;
+          const update = value.update;
+          // Every subscription begins with a native full snapshot. Never fold
+          // deltas from a previous subscription into a new incarnation.
+          if (!update || update.conversationId !== sessionId || update.trajectoryId !== metadata.trajectoryId) return;
+          const snapshot = JSON.parse(JSON.stringify(update, (key, value) => key.startsWith('$') ? undefined : value));
+          done = true; resolve({ ...snapshot, observed_at: new Date().toISOString(), method: agyNativeService.state.path }); active.cancel();
+        });
+        active.on('error', error => { if (!done) { done = true; reject(grpcError('state', error)); } });
+        active.on('end', () => { if (!done) { done = true; reject(invalid('native_state_snapshot_missing')); } });
+      });
+    }
+    if (action === 'stop') {
+      const reply = await unary('stop', { conversationId: sessionId });
+      const stopped = reply.stoppedConversationIds, owned = new Set([sessionId, ...ownedSessions]);
+      if (!Array.isArray(stopped) || !stopped.length || new Set(stopped).size !== stopped.length
+        || ![...owned].every(id => stopped.includes(id)) || stopped.some(id => !owned.has(id))) {
+        const error = invalid('native_stopped_tree_binding_unproven'); error.details.stopped_session_ids = stopped ?? null; throw error;
+      }
+      return { stopped_session_ids: stopped, trajectory_id: metadata.trajectoryId, method: agyNativeService.stop.path };
+    }
+    const reply = await unary('wait', { conversationId: sessionId, inactivityTimeoutSeconds: Math.max(1, Math.min(2147483647, Math.ceil((deadline - Date.now()) / 1000))), returnOnExecutorError: false });
+    return { idle: reply.timedOut === false, reason: reply.timedOut ? 'native_wait_timed_out' : 'native_wait_fully_idle', method: agyNativeService.wait.path, trajectory_id: metadata.trajectoryId };
+  } finally { signal?.removeEventListener('abort', abort); client.close(); }
+}
+
+export const inspectAgyNative = input => agyNativeRequest(input);
+/** Read-only per-node native state; no execution/readiness grant. */
+export const inspectAgyNativeState = input => agyNativeRequest(input, 'state');
+/** Scoped control, not an idle/physical grant. Caller must verify retirement. */
+export const stopAgyNativeTree = (input, ownedSessions = []) => agyNativeRequest(input, 'stop', ownedSessions);

package/dist/harness-runtime/lib/agy-native-inventory.mjs

@@ -0,0 +1,19 @@
+// A new StreamAgentStateUpdates subscription starts with a full snapshot.
+// An omitted protobuf update is an empty list; a partial indexed list is not.
+export const agyNativeFullList = (update, key) => !update ||
+  Array.isArray(update[key]) && update.totalLength === update[key].length &&
+  update.indices?.length === update.totalLength && update.indices.every((value, offset) => value === offset);
+
+export function agyNativeInventory(snapshot, sessionId) {
+  if (snapshot?.conversationId !== sessionId || !snapshot.trajectoryId || snapshot.error ||
+    snapshot.method !== '/exa.language_server_pb.LanguageServerService/StreamAgentStateUpdates' ||
+    !agyNativeFullList(snapshot.backgroundTasksUpdate, 'backgroundTasks') ||
+    !agyNativeFullList(snapshot.pendingAgentMessagesUpdate, 'pendingAgentMessages'))
+    throw Object.assign(new Error('AGY native task inventory is incomplete or unbound'), { code: 'native_resources_unproven' });
+  const tasks = snapshot.backgroundTasksUpdate?.backgroundTasks?.map(item => item.taskSnapshot) ?? [];
+  if (tasks.some(task => !task || typeof task.taskId !== 'string' || !task.taskId.startsWith(`${sessionId}/task-`) || !/\/task-\d+$/.test(task.taskId) || !task.toolName) ||
+    new Set(tasks.map(task => task.taskId)).size !== tasks.length)
+    throw Object.assign(new Error('AGY native task identity is unproven'), { code: 'native_resources_unproven' });
+  return { tasks, messages: snapshot.pendingAgentMessagesUpdate?.pendingAgentMessages ?? [],
+    idle: snapshot.fullyIdle === true && snapshot.status === 1 && snapshot.executorLoopStatus === 1 && snapshot.hasActiveChildren !== true };
+}

package/dist/harness-runtime/lib/agy-native_pb.js

@@ -0,0 +1,117 @@
+// @generated by protoc-gen-es v2.16.0 with parameter "target=js"
+// @generated from file agy-native.proto (package exa.language_server_pb, syntax proto3)
+/* eslint-disable */
+
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
+
+/**
+ * Describes the file agy-native.proto.
+ */
+export const file_agy_native = /*@__PURE__*/
+  fileDesc("ChBhZ3ktbmF0aXZlLnByb3RvEhZleGEubGFuZ3VhZ2Vfc2VydmVyX3BiIoQBCiNXYWl0Rm9yQ29udmVyc2F0aW9uRnVsbHlJZGxlUmVxdWVzdBIXCg9jb252ZXJzYXRpb25faWQYASABKAkSIgoaaW5hY3Rpdml0eV90aW1lb3V0X3NlY29uZHMYAiABKAUSIAoYcmV0dXJuX29uX2V4ZWN1dG9yX2Vycm9yGAQgASgIIjkKJFdhaXRGb3JDb252ZXJzYXRpb25GdWxseUlkbGVSZXNwb25zZRIRCgl0aW1lZF9vdXQYASABKAgiOQoeR2V0Q29udmVyc2F0aW9uTWV0YWRhdGFSZXF1ZXN0EhcKD2NvbnZlcnNhdGlvbl9pZBgBIAEoCSJsChRDb252ZXJzYXRpb25NZXRhZGF0YRIeChZwYXJlbnRfY29udmVyc2F0aW9uX2lkGAUgASgJEhwKFHJvb3RfY29udmVyc2F0aW9uX2lkGAYgASgJEhYKDndvcmtzcGFjZV91cmlzGAcgAygJIosBCh9HZXRDb252ZXJzYXRpb25NZXRhZGF0YVJlc3BvbnNlEj4KCG1ldGFkYXRhGAEgASgLMiwuZXhhLmxhbmd1YWdlX3NlcnZlcl9wYi5Db252ZXJzYXRpb25NZXRhZGF0YRIRCgludW1fc3RlcHMYAiABKA0SFQoNdHJhamVjdG9yeV9pZBgDIAEoCSI2ChtGb3JjZVN0b3BDYXNjYWRlVHJlZVJlcXVlc3QSFwoPY29udmVyc2F0aW9uX2lkGAEgASgJIkAKHEZvcmNlU3RvcENhc2NhZGVUcmVlUmVzcG9uc2USIAoYc3RvcHBlZF9jb252ZXJzYXRpb25faWRzGAEgAygJIlAKHlN0cmVhbUFnZW50U3RhdGVVcGRhdGVzUmVxdWVzdBIXCg9jb252ZXJzYXRpb25faWQYASABKAkSFQoNc3Vic2NyaWJlcl9pZBgCIAEoCSJOCgxBZ2VudE1lc3NhZ2USCgoCaWQYASABKAkSEQoJcmVjaXBpZW50GAIgASgJEg4KBnNlbmRlchgDIAEoCRIPCgdjb250ZW50GAQgASgJIokBChpQZW5kaW5nQWdlbnRNZXNzYWdlc1VwZGF0ZRIPCgdpbmRpY2VzGAEgAygNEkQKFnBlbmRpbmdfYWdlbnRfbWVzc2FnZXMYAiADKAsyJC5leGEubGFuZ3VhZ2Vfc2VydmVyX3BiLkFnZW50TWVzc2FnZRIUCgx0b3RhbF9sZW5ndGgYAyABKA0iagoMVGFza1NuYXBzaG90Eg8KB3Rhc2tfaWQYASABKAkSEQoJdG9vbF9uYW1lGAIgASgJEhIKCnN0ZXBfaW5kZXgYBiABKA0SDwoHbG9nX3VyaRgHIAEoCRIRCglpc19kYWVtb24YCCABKAgiTQoOQmFja2dyb3VuZFRhc2sSOwoNdGFza19zbmFwc2hvdBgBIAEoCzIkLmV4YS5sYW5ndWFnZV9zZXJ2ZXJfcGIuVGFza1NuYXBzaG90IoABChVCYWNrZ3JvdW5kVGFza3NVcGRhdGUSDwoHaW5kaWNlcxgBIAMoDRJAChBiYWNrZ3JvdW5kX3Rhc2tzGAIgAygLMiYuZXhhLmxhbmd1YWdlX3NlcnZlcl9wYi5CYWNrZ3JvdW5kVGFzaxIUCgx0b3RhbF9sZW5ndGgYAyABKA0i5wIKEEFnZW50U3RhdGVVcGRhdGUSFwoPY29udmVyc2F0aW9uX2lkGAEgASgJEhUKDXRyYWplY3RvcnlfaWQYAiABKAkSDgoGc3RhdHVzGAMgASgFEhkKEWV4ZWN1dGFibGVfc3RhdHVzGAQgASgFEhwKFGV4ZWN1dG9yX2xvb3Bfc3RhdHVzGAUgASgFEhsKE2hhc19hY3RpdmVfY2hpbGRyZW4YDiABKAgSTgoXYmFja2dyb3VuZF90YXNrc191cGRhdGUYESABKAsyLS5leGEubGFuZ3VhZ2Vfc2VydmVyX3BiLkJhY2tncm91bmRUYXNrc1VwZGF0ZRISCgpmdWxseV9pZGxlGBIgASgIElkKHXBlbmRpbmdfYWdlbnRfbWVzc2FnZXNfdXBkYXRlGBQgASgLMjIuZXhhLmxhbmd1YWdlX3NlcnZlcl9wYi5QZW5kaW5nQWdlbnRNZXNzYWdlc1VwZGF0ZSJbCh9TdHJlYW1BZ2VudFN0YXRlVXBkYXRlc1Jlc3BvbnNlEjgKBnVwZGF0ZRgBIAEoCzIoLmV4YS5sYW5ndWFnZV9zZXJ2ZXJfcGIuQWdlbnRTdGF0ZVVwZGF0ZWIGcHJvdG8z");
+
+/**
+ * Describes the message exa.language_server_pb.WaitForConversationFullyIdleRequest.
+ * Use `create(WaitForConversationFullyIdleRequestSchema)` to create a new message.
+ */
+export const WaitForConversationFullyIdleRequestSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 0);
+
+/**
+ * Describes the message exa.language_server_pb.WaitForConversationFullyIdleResponse.
+ * Use `create(WaitForConversationFullyIdleResponseSchema)` to create a new message.
+ */
+export const WaitForConversationFullyIdleResponseSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 1);
+
+/**
+ * Describes the message exa.language_server_pb.GetConversationMetadataRequest.
+ * Use `create(GetConversationMetadataRequestSchema)` to create a new message.
+ */
+export const GetConversationMetadataRequestSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 2);
+
+/**
+ * Describes the message exa.language_server_pb.ConversationMetadata.
+ * Use `create(ConversationMetadataSchema)` to create a new message.
+ */
+export const ConversationMetadataSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 3);
+
+/**
+ * Describes the message exa.language_server_pb.GetConversationMetadataResponse.
+ * Use `create(GetConversationMetadataResponseSchema)` to create a new message.
+ */
+export const GetConversationMetadataResponseSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 4);
+
+/**
+ * Describes the message exa.language_server_pb.ForceStopCascadeTreeRequest.
+ * Use `create(ForceStopCascadeTreeRequestSchema)` to create a new message.
+ */
+export const ForceStopCascadeTreeRequestSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 5);
+
+/**
+ * Describes the message exa.language_server_pb.ForceStopCascadeTreeResponse.
+ * Use `create(ForceStopCascadeTreeResponseSchema)` to create a new message.
+ */
+export const ForceStopCascadeTreeResponseSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 6);
+
+/**
+ * Describes the message exa.language_server_pb.StreamAgentStateUpdatesRequest.
+ * Use `create(StreamAgentStateUpdatesRequestSchema)` to create a new message.
+ */
+export const StreamAgentStateUpdatesRequestSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 7);
+
+/**
+ * Describes the message exa.language_server_pb.AgentMessage.
+ * Use `create(AgentMessageSchema)` to create a new message.
+ */
+export const AgentMessageSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 8);
+
+/**
+ * Describes the message exa.language_server_pb.PendingAgentMessagesUpdate.
+ * Use `create(PendingAgentMessagesUpdateSchema)` to create a new message.
+ */
+export const PendingAgentMessagesUpdateSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 9);
+
+/**
+ * Describes the message exa.language_server_pb.TaskSnapshot.
+ * Use `create(TaskSnapshotSchema)` to create a new message.
+ */
+export const TaskSnapshotSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 10);
+
+/**
+ * Describes the message exa.language_server_pb.BackgroundTask.
+ * Use `create(BackgroundTaskSchema)` to create a new message.
+ */
+export const BackgroundTaskSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 11);
+
+/**
+ * Describes the message exa.language_server_pb.BackgroundTasksUpdate.
+ * Use `create(BackgroundTasksUpdateSchema)` to create a new message.
+ */
+export const BackgroundTasksUpdateSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 12);
+
+/**
+ * Describes the message exa.language_server_pb.AgentStateUpdate.
+ * Use `create(AgentStateUpdateSchema)` to create a new message.
+ */
+export const AgentStateUpdateSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 13);
+
+/**
+ * Describes the message exa.language_server_pb.StreamAgentStateUpdatesResponse.
+ * Use `create(StreamAgentStateUpdatesResponseSchema)` to create a new message.
+ */
+export const StreamAgentStateUpdatesResponseSchema = /*@__PURE__*/
+  messageDesc(file_agy_native, 14);
+

package/dist/harness-runtime/lib/agy-terminal-envelope.mjs

@@ -0,0 +1,74 @@
+import { constants, openSync, closeSync, fstatSync, lstatSync, readSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { StringDecoder } from 'node:string_decoder';
+
+const taskId = '[\\w-]+/task-\\d+';
+
+export function ownedAgyOutput(reference, source, sessionId, ownerTask = null) {
+  let fd;
+  try {
+    const transcript = fileURLToPath(source.locator), file = fileURLToPath(reference);
+    const system = path.dirname(path.dirname(transcript));
+    if (path.basename(path.dirname(system)) !== sessionId || path.basename(system) !== '.system_generated') return null;
+    const relative = path.relative(system, file);
+    if (!/^(?:steps\/\d+\/output\.txt|tasks\/task-\d+\.log)$/.test(relative) || realpathSync(file) !== file || realpathSync(system) !== system) return null;
+    if (ownerTask) {
+      const number = ownerTask.match(new RegExp(`^${sessionId}/task-(\\d+)$`))?.[1];
+      if (!number || ![`steps/${number}/output.txt`, `tasks/task-${number}.log`].includes(relative)) return null;
+    }
+    const before = lstatSync(file);
+    if (!before.isFile()) return null;
+    fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.ino !== before.ino || stat.dev !== before.dev) return null;
+    const bytes = Buffer.allocUnsafe(64 * 1024), decoder = new StringDecoder('utf8'), hash = createHash('sha256');
+    let offset = 0, text = '';
+    while (offset < stat.size) {
+      const count = readSync(fd, bytes, 0, Math.min(bytes.length, stat.size - offset), offset); if (!count) return null;
+      const chunk = bytes.subarray(0, count); hash.update(chunk); text += decoder.write(chunk); offset += count;
+    }
+    text += decoder.end();
+    const after = fstatSync(fd);
+    const finalPath = lstatSync(file);
+    if (!finalPath.isFile() || finalPath.dev !== stat.dev || finalPath.ino !== stat.ino || realpathSync(file) !== file
+      || stat.size !== after.size || stat.mtimeMs !== after.mtimeMs || stat.ctimeMs !== after.ctimeMs) return null;
+    return { text, sha256: hash.digest('hex'), locator: reference };
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+/** Only a native envelope is decoded here; stdout cannot introduce terminal authority. */
+export function agyTerminalEnvelope(row, call = null) {
+  if (row?.status !== 'DONE' || typeof row.content !== 'string') return null;
+  let body = row.content.replaceAll('\r\n', '\n'), id = null, cancelled = false;
+  if (row.source === 'SYSTEM' && row.type === 'SYSTEM_MESSAGE') {
+    const match = body.match(new RegExp(`(?:^|\\n)\\[Message\\] timestamp=[^\\n]+ sender=(${taskId}) priority=MESSAGE_PRIORITY_(?:HIGH|LOW) content=Task id "(${taskId})" (finished with result:|was canceled with result:)\\n`));
+    if (!match || match[1] !== match[2]) return null;
+    id = match[1]; cancelled = match[3].startsWith('was canceled');
+    body = body.slice(match.index + match[0].length).replace(/\n<\/SYSTEM_MESSAGE>\s*$/, '');
+  } else if (row.type !== 'GENERIC' || row.source && row.source !== 'MODEL') return null;
+  else {
+    body = body.replace(/^Created At: [^\n]+\nCompleted At: [^\n]+\n/, '');
+    if (call?.name === 'manage_task') {
+      const decode = value => { try { return JSON.parse(value); } catch { return value; } };
+      id = decode(call.args?.TaskId);
+      const action = decode(call.args?.Action);
+      const status = body.match(new RegExp(`^Task: (${taskId})\\nStatus: (DONE|COMPLETED|FAILED|CANCELLED)(?:\\n|$)`));
+      if (action === 'status' && status?.[1] === id) return { task_id: id, task_terminal: true, exit_code: null, command_outcome: status[2] === 'DONE' ? null : status[2].toLowerCase(), output: null };
+      if (action === 'kill' && body.match(new RegExp(`^Task "(${taskId})" cancelled\\.(?:\\n|$)`))?.[1] === id) return { task_id: id, task_terminal: true, exit_code: null, command_outcome: 'cancelled', output: null };
+      return null;
+    }
+  }
+  // This exact wrapper preserves the beginning of the native result, including its exit header.
+  const wrapper = body.match(/^The tool's output was truncated due to being too long\. You can find the full output in a file at (file:\/\/[^\n]+)\.\n\nHere is a preview with the middle of the output truncated:\n/);
+  if (wrapper) body = body.slice(wrapper[0].length);
+  if (cancelled && /^Tool execution was canceled(?:\n|$)/.test(body)) return { task_id: id, task_terminal: true, exit_code: null, command_outcome: 'cancelled', output: null };
+  const header = body.match(/^Command exited with code (-?\d+)\.(?:\n|$)/);
+  if (!header) return null;
+  const exit = Number(header[1]);
+  if (!Number.isSafeInteger(exit)) return null;
+  return { task_id: id, task_terminal: true, exit_code: exit, command_outcome: exit === 0 ? 'completed' : 'failed', output: wrapper ? null : body.split('Command output:\n')[1] ?? null,
+    ...(wrapper ? { output_reference: wrapper[1] } : {}) };
+}

package/dist/harness-runtime/lib/agy-transcript-stream.mjs

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { StringDecoder } from 'node:string_decoder';
+
+// The caller opens and validates the owned no-symlink handle and must discard
+// tentative callback results if this function rejects. One complete JSONL
+// record, rather than the whole transcript, is the largest retained value.
+export async function readAgyTranscriptSnapshot(handle, { locator, assertIdentity, onRecord, onProgress }) {
+  if (typeof assertIdentity !== 'function' || typeof onRecord !== 'function') throw new TypeError('snapshot requires owner validation and a record consumer');
+  const original = await handle.stat();
+  const unchanged = async () => {
+    const current = await handle.stat();
+    if (!current.isFile() || current.dev !== original.dev || current.ino !== original.ino || current.size !== original.size
+      || current.mtimeMs !== original.mtimeMs || current.ctimeMs !== original.ctimeMs) throw new Error('agy_transcript_snapshot_changed');
+    await assertIdentity(current);
+  };
+  if (!original.isFile()) throw new Error('agy_transcript_snapshot_changed');
+  await unchanged();
+  const buffer = Buffer.allocUnsafe(64 * 1024), digest = createHash('sha256');
+  let offset = 0, complete = 0, completeHash = digest.copy();
+  while (offset < original.size) {
+    const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, original.size - offset), offset);
+    if (!bytesRead) throw new Error('agy_transcript_snapshot_changed');
+    const chunk = buffer.subarray(0, bytesRead), lastNewline = chunk.lastIndexOf(10);
+    if (lastNewline >= 0) {
+      digest.update(chunk.subarray(0, lastNewline + 1));
+      complete = offset + lastNewline + 1; completeHash = digest.copy();
+      digest.update(chunk.subarray(lastNewline + 1));
+    } else digest.update(chunk);
+    offset += bytesRead;
+    await onProgress?.(`digest:${original.dev}:${original.ino}:${original.size}:${original.mtimeMs}:${offset}`);
+  }
+  const source = { locator, byte_start: 0, byte_end: complete, sha256: completeHash.digest('hex') };
+  await unchanged();
+  const decoder = new StringDecoder('utf8'); let pending = '', line = 0;
+  offset = 0;
+  while (offset < complete) {
+    const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, complete - offset), offset);
+    if (!bytesRead) throw new Error('agy_transcript_snapshot_changed');
+    pending += decoder.write(buffer.subarray(0, bytesRead)); offset += bytesRead;
+    await onProgress?.(`records:${source.sha256}:${offset}`);
+    let newline;
+    while ((newline = pending.indexOf('\n')) >= 0) {
+      const text = pending.slice(0, newline); pending = pending.slice(newline + 1); line += 1;
+      if (!text.trim()) continue;
+      let record;
+      try { record = JSON.parse(text); } catch { throw new Error('agy_transcript_invalid_record'); }
+      await onRecord(record, { ...source, line });
+    }
+  }
+  pending += decoder.end();
+  if (pending) throw new Error('agy_transcript_snapshot_changed');
+  await unchanged();
+  return { source, partial_tail: complete !== original.size };
+}

package/dist/harness-runtime/lib/daemon-observation.d.mts

@@ -0,0 +1,3 @@
+export function recoverDaemonReply(root: string, id: string, options?: { timeoutMs?: number | null; signal?: AbortSignal; binding?: Record<string, unknown>; onProgress?: (value: Record<string, unknown>) => void; onOutcome?: (value: Record<string, unknown>) => void; onPendingSettlement?: (value: Record<string, unknown>) => Promise<void>; observationClock?: import("./observation-clock.mjs").ObservationClock }): Promise<Record<string, unknown>>;
+export function retainedDaemonReply(root: string, id: string, binding?: Record<string, unknown>): Promise<{ ready: boolean; outcome: unknown; value?: unknown; settlement?: Record<string, unknown> | null; reason?: string } | null>;
+export function withDaemonProgressObserver<T>(observer: (value: Record<string, unknown>) => void, action: () => Promise<T>): Promise<T>;