@deksden-com/dd-flow-cli 0.9.0-beta.145 → 0.9.0-beta.149

package/dist/domain/diagnostic-aspects.js

@@ -0,0 +1,103 @@
+/** Registered baseline coverage; applicability remains agent-owned. */
+export const diagnosticAspects = {
+    "mb-audit": [
+        {
+            "id": "01",
+            "question": "Structure, indexes and reachability of active memory"
+        },
+        {
+            "id": "02",
+            "question": "Links, frontmatter and durable traceability"
+        },
+        {
+            "id": "03",
+            "question": "Source of truth, duplicates, freshness and factual contradictions"
+        },
+        {
+            "id": "04",
+            "question": "Delivery docs, epics/features, protocols and verification matrices"
+        },
+        {
+            "id": "05",
+            "question": "System boundaries, C4, ADRs and contracts"
+        },
+        {
+            "id": "06",
+            "question": "Scenarios, fixtures, evidence and runners"
+        },
+        {
+            "id": "07",
+            "question": "UI contracts and user guides"
+        },
+        {
+            "id": "08",
+            "question": "Engineering standards and code contracts"
+        },
+        {
+            "id": "09",
+            "question": "Operations, release policy and active named deferrals"
+        },
+        {
+            "id": "10",
+            "question": "Memory lifecycle, archives and durable promotion"
+        },
+        {
+            "id": "11",
+            "question": "Code-to-memory traceability"
+        },
+        {
+            "id": "12",
+            "question": "Project agent skills, prompts and execution guidance"
+        }
+    ],
+    "project-review": [
+        {
+            "id": "structure_navigation_review",
+            "question": "Can readers locate system truth and delivery evidence?"
+        },
+        {
+            "id": "feature_epic_layer_review",
+            "question": "Are durable capabilities and delivery layers coherent?"
+        },
+        {
+            "id": "spec_conformance_review",
+            "question": "Does actual project behavior conform to its normative specs?"
+        },
+        {
+            "id": "architecture_harmonization_review",
+            "question": "Are architecture and boundaries coherent top-down?"
+        },
+        {
+            "id": "adr_decision_review",
+            "question": "Are significant decisions, alternatives and consequences recorded?"
+        },
+        {
+            "id": "scenario_evidence_review",
+            "question": "Do actual scenarios, fixtures, checks and evidence cover capabilities?"
+        },
+        {
+            "id": "contract_traceability_review",
+            "question": "Are public contracts traced through implementation and tests?"
+        },
+        {
+            "id": "frontmatter_crosslink_review",
+            "question": "Are metadata and cross-links factual and current?"
+        },
+        {
+            "id": "engineering_standards_review",
+            "question": "Does actual code follow applicable engineering standards?"
+        },
+        {
+            "id": "operations_policy_review",
+            "question": "Are applicable Git, environment and delivery policies followed?"
+        },
+        {
+            "id": "protocol_delivery_trace_review",
+            "question": "Do protocols and RUNs factually establish delivery and closure?"
+        },
+        {
+            "id": "def_followup_review",
+            "question": "Are active DEFs visible, deduplicated and bound to future gates?"
+        }
+    ]
+};

package/dist/domain/diagnostic-flows.js

@@ -0,0 +1,8 @@
+/** Only the accepted E5 read-only slice, not a registry of future workflows. */
+export const diagnosticFlowStages = Object.freeze({
+    "mb-audit": ["preflight", "audit", "review", "report"],
+    "project-review": ["preflight", "analyze", "review", "report"]
+});
+export function isDiagnosticFlow(id) {
+    return typeof id === "string" && Object.hasOwn(diagnosticFlowStages, id);
+}

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

@@ -0,0 +1,216 @@
+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': 1024 * 1024, '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();
+  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(invalid(`grpc_${error.code ?? 'unknown'}`)) : 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(invalid(`grpc_${error.code ?? 'unknown'}`)); } });
+        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_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/daemon-operations.d.mts

@@ -1 +1,2 @@
 export function inspectDaemonOperation(root: string, id: string): Promise<Record<string, unknown>>;
+export function validateNativeLaunchEnvironment(value: unknown): Record<string, string | null>;

package/dist/harness-runtime/lib/daemon-operations.mjs

@@ -5,7 +5,9 @@ import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { hashJson, writeJsonAtomic } from "./runner-events.mjs";
 import { errorRecord, isObservationLoss, isProvenShellCorrection, reportedError } from "./operation-errors.mjs";
-import { assertDaemonOwnership, budgetObservationScope, releaseBudgetObservation, completeBudgetOperation } from "./managed-daemon.mjs";
+import { assertDaemonOwnership, budgetObservationScope, releaseBudgetObservation, completeBudgetOperation, stopProcessGroup } from "./managed-daemon.mjs";
+import { processSnapshot } from "./process-snapshot.mjs";
+import { NATIVE_SHUTDOWN_CONTRACT, NATIVE_SHUTDOWN_PHASES } from "./native-children.mjs";
 import { readModelObservations, modelAttribution } from "./model-observations.mjs";
 import { publishOperationProgress, publishOperationWaiting, withOperationProgress } from './operation-progress.mjs';
 import { prepareDaemonRequest } from "./native-request-proof.mjs";
@@ -16,6 +18,20 @@ const dispatchGenerations = new Map();
 const shutdowns = new Map();
 const settlements = new Map();
 
+// Configuration locations only: credentials and arbitrary process env are not
+// replay inputs. The browser cache is additive for historical five-key launches.
+const nativeLaunchEnvironmentKeys = ["CODEX_HOME", "DD_FLOW_CONFIG_HOME", "DD_FLOW_HOME", "DD_FLOW_BIN", "DD_FLOW_RESOURCE_HOME"];
+export function validateNativeLaunchEnvironment(value) {
+  const cache = value?.PLAYWRIGHT_BROWSERS_PATH;
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).some(key => ![...nativeLaunchEnvironmentKeys, "PLAYWRIGHT_BROWSERS_PATH"].includes(key))
+    || nativeLaunchEnvironmentKeys.some(key => value[key] !== null && typeof value[key] !== "string")
+    || Object.hasOwn(value, "PLAYWRIGHT_BROWSERS_PATH") && cache !== null
+      && (typeof cache !== "string" || !cache || cache.length > 4096 || cache.includes("\0") || !path.isAbsolute(cache)))
+    throw Object.assign(new Error("Native launch requires explicit configuration locations and an absolute browser cache"), { code: "runtime_scope_native_launch_required" });
+  return value;
+}
+
 // Progress is not outcome authority. Once native effect is retained, a failed
 // diagnostic write must keep its identity and prohibit redispatch.
 async function publishRetainedProgress(root, id, phase, result, metadata) {
@@ -41,28 +57,84 @@ export function commitDaemonShutdown(root) {
   fence.committed = true; shutdowns.set(root, fence);
 }
 
+function ownedSnapshot(snapshot, rootPid) {
+  const owned = new Set([rootPid]); let size;
+  do { size = owned.size; for (const item of snapshot) if (owned.has(item.ppid)) owned.add(item.pid); } while (size !== owned.size);
+  return snapshot.filter(item => item.pid !== rootPid && owned.has(item.pid) && !item.zombie);
+}
+const mergeProcesses = (...snapshots) => [...new Map(snapshots.flat().map(item => [`${item.pid}:${item.started}`, item])).values()];
+
 /** The same incarnation may retry remaining cleanup, never a native Turn. */
 export async function completeDaemonShutdown(root, state, persist, prepare, phases) {
   const daemonId = state.daemon_id ?? state.config?.daemonId;
   let shutdown = state.shutdown;
-  if (!shutdown || shutdown.daemon_id !== daemonId) shutdown = { schema_id: "dd-flow/daemon-shutdown@1", daemon_id: daemonId, generation: dispatchGenerations.get(root) ?? 0, phases: {} };
-  shutdown = { ...shutdown, required_phases: ["tree", ...phases.map(([phase]) => phase)] };
+  if (shutdown && shutdown.schema_id !== NATIVE_SHUTDOWN_CONTRACT) throw Object.assign(new Error("shutdown contract mismatch; retain historical owner evidence"), { code: "native_contract_mismatch" });
+  if (!shutdown || shutdown.daemon_id !== daemonId) shutdown = { schema_id: NATIVE_SHUTDOWN_CONTRACT, daemon_id: daemonId, generation: dispatchGenerations.get(root) ?? 0, phases: {} };
+  shutdown = { ...shutdown, required_phases: [...new Set([...NATIVE_SHUTDOWN_PHASES, ...phases.map(([phase]) => phase)])] };
   try {
-    if (!shutdown.phases.tree) {
+    if (!shutdown.phases.execution) {
+      // Some native adapters close their provider inside prepare(). Observe
+      // ownership first, before that close can reparent a support process.
+      const before = ownedSnapshot(await processSnapshot(), state.pid);
+      shutdown = { ...shutdown, generation: dispatchGenerations.get(root) ?? shutdown.generation,
+        owned_processes: mergeProcesses(shutdown.owned_processes ?? [], before), inventory_complete: state.pid === process.pid };
+      await persist({ shutdown });
       const result = await prepare();
-      shutdown = { ...shutdown, phases: { tree: true }, tree_observed_at: new Date().toISOString(), result: result ?? { clean: true } };
       commitDaemonShutdown(root);
-      await persist({ shutdown, shutdown_state: "stopping", active_tree: false });
+      // Compute ancestry within each snapshot, not across recycled parent PIDs.
+      const resources = mergeProcesses(shutdown.owned_processes, ownedSnapshot(await processSnapshot(), state.pid));
+      shutdown = { ...shutdown, phases: { execution: true }, owned_processes: resources,
+        inventory_complete: state.pid === process.pid, tree_observed_at: new Date().toISOString(), result: result ?? {} };
+      await persist({ shutdown, shutdown_state: "stopping" });
     }
     commitDaemonShutdown(root);
     for (const [phase, action] of phases) {
+      if (phase === "daemon_resource" && !shutdown.phases.owned_resources) {
+        if (!shutdown.inventory_complete) throw Object.assign(new Error("owned resource coverage is unknown"), { code: "native_resources_unproven" });
+        for (const retained of shutdown.owned_processes ?? []) {
+          const current = (await processSnapshot()).find(item => item.pid === retained.pid);
+          if (!current || current.started !== retained.started || current.zombie) continue;
+          await stopProcessGroup({ pid: retained.pid, started: retained.started }, 1000, { detached: false });
+        }
+        const remaining = await processSnapshot();
+        if ((shutdown.owned_processes ?? []).some(retained => remaining.some(item => item.pid === retained.pid && item.started === retained.started && !item.zombie))) throw Object.assign(new Error("owned resources remain live"), { code: "native_resources_unproven" });
+        const nativeResources = shutdown.result?.native_resources;
+        const resourceGap = nativeResources?.entries?.some(resource => resource.state !== "stopped"
+          && !(resource.classification === "required_work" && shutdown.result?.native_settled === true && shutdown.result?.settled === true)
+          && !(shutdown.owned_processes ?? []).some(item => resource.pid === item.pid && resource.started === item.started));
+        shutdown = { ...shutdown, phases: { ...shutdown.phases, owned_resources: !resourceGap },
+          resource_retirement: { confirmed: !resourceGap, reason: resourceGap ? "native_resource_identity_unproven" : "owned_processes_retired" } };
+        await persist({ shutdown });
+      }
       if (shutdown.phases[phase]) continue;
       await action();
       shutdown = { ...shutdown, phases: { ...shutdown.phases, [phase]: true } };
       await persist({ shutdown });
     }
-    const result = { ...shutdown.result, daemon_id: daemonId, stopped: true, settled: true, shutdown_contract: "dd-flow/daemon-shutdown@1", _shutdown: true };
-    await persist({ shutdown, shutdown_state: result.clean === true ? "clean" : "unclean", active_tree: false, stopped_at: new Date().toISOString(), cleanup_error: null });
+    const publishedRevision = state.native_execution_revision;
+    const sameRevision = publishedRevision === undefined || publishedRevision === shutdown.result?.native_settlement?.revision;
+    const nativeSettled = sameRevision && state.active_tree === false && !state.unclaimed_activity && shutdown.result?.settled === true && shutdown.result?.native_settled === true && shutdown.result?.native_settlement?.confirmed !== false;
+    const physicalStopped = shutdown.required_phases.every(phase => shutdown.phases[phase] === true);
+    // Cleanup retries/joining controls advance the control fence, not the old
+    // native Turn. Publish the current control generation with retained phases.
+    shutdown = { ...shutdown, generation: dispatchGenerations.get(root) ?? shutdown.generation };
+    const { result: ignored, ...proof } = shutdown; void ignored;
+    let result = { ...shutdown.result, daemon_id: daemonId, stopped: true, physical_stopped: physicalStopped,
+      settled: nativeSettled, native_settled: nativeSettled, clean: shutdown.result?.clean !== false && nativeSettled && physicalStopped,
+      resource_retirement: shutdown.resource_retirement,
+      shutdown_contract: NATIVE_SHUTDOWN_CONTRACT, shutdown_proof: proof, _shutdown: true };
+    shutdown = { ...shutdown, result };
+    // prepare() owns execution quiescence. A stale publication must not clear
+    // activity that arrives while its durable write is in flight.
+    await persist({ shutdown, shutdown_state: result.clean === true ? "clean" : "unclean", stopped_at: new Date().toISOString(), cleanup_error: null });
+    if (nativeSettled && (state.native_execution_revision !== publishedRevision || state.active_tree !== false || state.unclaimed_activity)) {
+      shutdown = { ...shutdown, phases: { ...shutdown.phases, execution: false } };
+      result = { ...result, clean: false, settled: false, native_settled: false,
+        native_settlement: { ...result.native_settlement, confirmed: false, reason: "late_activity_during_shutdown_publication" },
+        shutdown_proof: { ...proof, phases: shutdown.phases } };
+      shutdown = { ...shutdown, result };
+      await persist({ shutdown, shutdown_state: "unclean" });
+    }
     return result;
   } catch (error) {
     if (error.code === "tree_not_settled" && !shutdowns.get(root)?.committed) throw error;
@@ -255,7 +327,9 @@ export async function durableDaemonDispatch(root, request, action, observe) {
   const control = ["daemon.stop", "session.cancel"].includes(request.operation);
   if (!productive.has(request.operation) && !control) return await action();
   const generation = dispatchGenerations.get(root) ?? 0;
-  if (control) { dispatchGenerations.set(root, generation + 1); const state = await read(path.join(root,'daemon.json')); await writeJsonAtomic(path.join(root,'operation-fence.json'), { generation: generation + 1, daemon_id: state?.daemon_id ?? state?.config?.daemonId ?? null }); }
+  // Once retirement is committed there is no productive dispatch to cancel.
+  // Retrying/joining cleanup must not stale its own durable generation proof.
+  if (control && !(request.operation === "daemon.stop" && shutdowns.get(root)?.committed)) { dispatchGenerations.set(root, generation + 1); const state = await read(path.join(root,'daemon.json')); await writeJsonAtomic(path.join(root,'operation-fence.json'), { generation: generation + 1, daemon_id: state?.daemon_id ?? state?.config?.daemonId ?? null }); }
   const assertCurrent = () => { assertDaemonDispatch(root); if (generation !== (dispatchGenerations.get(root) ?? 0)) throw Object.assign(new Error("control cancelled a queued productive dispatch"), { code: "operation_cancelled" }); };
   const stop = request.operation === "daemon.stop" ? (shutdowns.get(root) ?? { pending: 0, committed: false }) : null;
   if (stop) { stop.pending++; shutdowns.set(root, stop); }
@@ -301,7 +375,7 @@ export async function durableDaemonStart(options, action) {
   // Keep only configuration locations, never inherited credentials. The owned
   // scope can reuse this exact adapter launch after retiring the old daemon.
   const launch = { schema_id: "dd-flow/native-launch@1", executable: options.entryPath ?? null, args: process.argv.slice(2), cwd: process.cwd(), runtime_owner: process.env.DD_FLOW_RUNTIME_OWNER ?? null,
-    env: Object.fromEntries(["CODEX_HOME", "DD_FLOW_CONFIG_HOME", "DD_FLOW_HOME", "DD_FLOW_BIN", "DD_FLOW_RESOURCE_HOME"].map(key => [key, process.env[key] ?? null])) };
+    env: validateNativeLaunchEnvironment(Object.fromEntries([...nativeLaunchEnvironmentKeys, ...(process.env.PLAYWRIGHT_BROWSERS_PATH === undefined ? [] : ["PLAYWRIGHT_BROWSERS_PATH"])].map(key => [key, process.env[key] ?? null]))) };
   const request = prepareDaemonRequest({ id: process.env.DD_EVAL_OPERATION_ID ?? randomUUID(), operation: "daemon.start", params: { ...options, runtimeOwner: process.env.DD_FLOW_RUNTIME_OWNER ?? null, resourceHome: process.env.DD_FLOW_RESOURCE_HOME ?? null, launch } });
   return await journalDispatch(root, request, () => action(options));
 }