@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/domains/dispatch/path-scope.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import {
 	asDirectoryPathBoundary,
 	normalizePathBoundaryEntry,
@@ -14,6 +15,7 @@ const POSIX_ABSOLUTE_TOKEN_RE = /(?:^|[\s("'])((?:\/[\w.~+-]+)+)/gu;
 const WINDOWS_ABSOLUTE_TOKEN_RE = /(?:^|[\s("'])([A-Za-z]:[\\/][^\s"']+)/gu;
 const BACKSLASH_PATH_RE = /\b[A-Za-z_.-][\w.-]*\\(?:(?:[\w.-]+\\)+[\w.-]+|[\w-]+\.[A-Za-z0-9]{1,8})\b/gu;
 const DOUBLE_SEPARATOR_PATH_RE = /\b[\w.-]+\/\/[\w./-]+/gu;
+const PARENT_PREFIX_RE = /^(?:\.\.\/)+/u;
 
 export type DispatchPathProvenanceKind = "declared" | "derived" | "inferred";
 export type DispatchPathConfidence = "certain" | "high" | "medium" | "low";
@@ -49,11 +51,24 @@ export interface DispatchPathScopeProvenance {
 	writeBoundaries: DispatchPathProvenanceEntry[];
 }
 
+/**
+ * A prose token whose leading "../" run inference had to reinterpret, kept so
+ * the notice can name the raw token beside the scope it produced. `resolved` is
+ * the repository path the stripped remainder anchored to, or null when nothing
+ * under the dispatch root carried it and the token took no part in scope.
+ */
+export interface DispatchInferredParentToken {
+	token: string;
+	resolved: string | null;
+	source: "task" | "briefing";
+}
+
 export interface DispatchPathScope {
 	source: "declared" | "inferred";
 	workingContextPaths: ReadonlyArray<string>;
 	writeBoundaries: ReadonlyArray<string>;
 	inferredOnlyPaths: ReadonlyArray<string>;
+	parentTokens: ReadonlyArray<DispatchInferredParentToken>;
 	provenance: DispatchPathScopeProvenance;
 }
 
@@ -64,6 +79,19 @@ export interface DeclaredScopeReplacementNotice {
 	message: string;
 }
 
+export interface InferredScopeParentTokenNotice {
+	code: "legacy_scope_inferred";
+	level: "warning";
+	paths: ReadonlyArray<{
+		path: string;
+		policy: "working-context";
+		provenance: "inferred";
+		source: "task" | "briefing";
+		confidence: "low";
+	}>;
+	message: string;
+}
+
 export type DispatchPathScopeInferenceErrorCode = "legacy_scope_path_absolute" | "legacy_scope_path_malformed";
 
 export class DispatchPathScopeInferenceError extends Error {
@@ -139,19 +167,78 @@ export function declaredIntentPathProvenance(input: {
 	return sortedEntries(entries);
 }
 
-function inferredPaths(req: Pick<DispatchRequest, "task" | "briefing">): string[] {
+/** One prose token read as a repository path, as an anchored "../" quote, or as neither. */
+type InferredPathToken =
+	| { kind: "token"; token: string }
+	| { kind: "anchored"; token: string; resolved: string }
+	| { kind: "dropped"; token: string };
+
+function inferredPaths(
+	req: Pick<DispatchRequest, "task" | "briefing">,
+	root: string,
+): { paths: string[]; droppedTokens: string[] } {
 	const paths = new Set<string>();
+	const droppedTokens = new Set<string>();
 	const text = `${req.task}\n${req.briefing ?? ""}`;
 	for (const match of text.matchAll(DISPATCH_PATH_TOKEN_RE)) {
-		const token = inferredPathToken(match[0]);
+		const inferred = inferredPathToken(match[0], root);
+		if (inferred.kind === "dropped") {
+			droppedTokens.add(inferred.token);
+			continue;
+		}
+		const token = inferred.kind === "anchored" ? inferred.resolved : inferred.token;
 		if (token.startsWith("http://") || token.startsWith("https://")) continue;
 		paths.add(token);
 	}
-	return [...paths];
+	return { paths: [...paths], droppedTokens: [...droppedTokens] };
 }
 
-function inferredPathToken(token: string): string {
-	return token.replace(/\.+$/u, "");
+/**
+ * A leading "./" is how prose quotes an import specifier ("./parser.js"); it
+ * names the same repository path without the prefix, and the boundary grammar
+ * would otherwise refuse the whole dispatch for a dot segment.
+ *
+ * A leading "../" run is that same quote copied out of a file whose location
+ * this function never sees. Both callers, strictInferredPaths and
+ * inferredPaths, are handed the task or briefing text and nothing else, so the
+ * origin the run is measured against is unknowable here and no arithmetic on
+ * the run's length can decide whether it escapes. What is decidable is whether
+ * the remainder names something under the dispatch root, so the run is
+ * stripped and the remainder probed: "../src/store.js" quoted out of
+ * test/store.test.ts anchors to src/store.js, and "../../../etc/passwd"
+ * anchors to nothing in a checkout that holds no etc/passwd.
+ *
+ * That is a deliberate reading of issue #266, recorded here because it is the
+ * one place the choice is made. Criterion 1 ("never rejects the dispatch") and
+ * criterion 2 ("a prose token whose .. segments would leave the repository
+ * root is still refused") ask for opposite answers on a leading run, and only
+ * criterion 1 is decidable without an origin, so a run that names nothing is
+ * dropped rather than refused. Neither outcome widens authority: an inferred
+ * path selects project rules and compiles context but never becomes a write
+ * boundary, and an anchored remainder carries no ".." so path.resolve keeps it
+ * under the root. Both outcomes are named to the operator by
+ * inferredScopeParentTokenNotice, so the reinterpretation is never silent.
+ *
+ * The probe costs one existsSync per "../"-leading token (3 microseconds on a
+ * hit and 2 on a miss over 5,000 warm calls on this checkout) and no stat at
+ * all for the ordinary token, which the grammar matches dozens of per dispatch
+ * (the 27 tokens per task measured for REPORTABLE_OMITTED_PATH_RE below).
+ *
+ * A ".." or "." outside the leading run ("../src/../../b.ts", "../src/./b.ts")
+ * walks back out of a segment it already anchored, which is decidable without
+ * an origin, so it falls through to the boundary grammar and keeps its
+ * refusal, as does a run that leaves no remainder at all ("../..").
+ */
+function inferredPathToken(raw: string, root: string): InferredPathToken {
+	const token = raw.replace(/^\.\//u, "").replace(/\.+$/u, "");
+	const parents = PARENT_PREFIX_RE.exec(token)?.[0];
+	if (parents === undefined) return { kind: "token", token };
+	const rest = token.slice(parents.length);
+	const segments = rest.split("/");
+	if (rest.length === 0 || segments.includes("..") || segments.includes(".")) return { kind: "token", token };
+	return existsSync(resolvePathBoundary(root, rest))
+		? { kind: "anchored", token, resolved: rest }
+		: { kind: "dropped", token };
 }
 
 function failMalformedText(text: string, source: "task" | "briefing"): void {
@@ -188,18 +275,31 @@ function failMalformedText(text: string, source: "task" | "briefing"): void {
 function strictInferredPaths(
 	text: string,
 	source: "task" | "briefing",
-): Array<{ path: string; evidence: DispatchPathProvenanceEvidence }> {
+	root: string,
+): {
+	paths: Array<{ path: string; evidence: DispatchPathProvenanceEvidence }>;
+	parentTokens: DispatchInferredParentToken[];
+} {
 	failMalformedText(text, source);
 	const withoutUrls = text.replace(HTTP_URL_RE, (url) => " ".repeat(url.length));
 	const evidence: DispatchPathProvenanceEvidence =
 		source === "task"
 			? { provenance: "inferred", source, confidence: "medium", reason: "task_path_token" }
 			: { provenance: "inferred", source, confidence: "low", reason: "briefing_path_token" };
-	const result: Array<{ path: string; evidence: DispatchPathProvenanceEvidence }> = [];
+	const paths: Array<{ path: string; evidence: DispatchPathProvenanceEvidence }> = [];
+	const parentTokens: DispatchInferredParentToken[] = [];
 	for (const match of withoutUrls.matchAll(DISPATCH_PATH_TOKEN_RE)) {
-		const token = inferredPathToken(match[0]);
+		const inferred = inferredPathToken(match[0], root);
+		if (inferred.kind === "dropped") {
+			parentTokens.push({ token: inferred.token, resolved: null, source });
+			continue;
+		}
+		if (inferred.kind === "anchored") {
+			parentTokens.push({ token: inferred.token, resolved: inferred.resolved, source });
+		}
+		const token = inferred.kind === "anchored" ? inferred.resolved : inferred.token;
 		try {
-			result.push({ path: normalizePathBoundaryEntry(token), evidence });
+			paths.push({ path: normalizePathBoundaryEntry(token), evidence });
 		} catch (error) {
 			const code =
 				error instanceof PathBoundaryError && error.code === "absolute"
@@ -213,7 +313,7 @@ function strictInferredPaths(
 			);
 		}
 	}
-	return result;
+	return { paths, parentTokens };
 }
 
 function legacyPathScope(req: DispatchRequest, cwd: string): DispatchPathScope {
@@ -229,13 +329,21 @@ function legacyPathScope(req: DispatchRequest, cwd: string): DispatchPathScope {
 		addProvenance(workingEntries, root, writeEvidence);
 		addProvenance(writeEntries, asDirectoryPathBoundary(resolvePathBoundary(cwd, root)), writeEvidence);
 	}
-	for (const candidate of strictInferredPaths(req.task, "task")) {
-		addProvenance(workingEntries, candidate.path, candidate.evidence);
-	}
+	// One map across both fields, first field winning: an orchestrator that
+	// restates the file it is asking about quotes the same specifier in the task
+	// and in the briefing, and the notice must name it once rather than spend two
+	// of its twelve render slots on the same token.
+	const parentTokens = new Map<string, DispatchInferredParentToken>();
+	const recordParentTokens = (entries: ReadonlyArray<DispatchInferredParentToken>): void => {
+		for (const entry of entries) if (!parentTokens.has(entry.token)) parentTokens.set(entry.token, entry);
+	};
+	const taskScope = strictInferredPaths(req.task, "task", cwd);
+	for (const candidate of taskScope.paths) addProvenance(workingEntries, candidate.path, candidate.evidence);
+	recordParentTokens(taskScope.parentTokens);
 	if (req.briefing !== undefined) {
-		for (const candidate of strictInferredPaths(req.briefing, "briefing")) {
-			addProvenance(workingEntries, candidate.path, candidate.evidence);
-		}
+		const briefingScope = strictInferredPaths(req.briefing, "briefing", cwd);
+		for (const candidate of briefingScope.paths) addProvenance(workingEntries, candidate.path, candidate.evidence);
+		recordParentTokens(briefingScope.parentTokens);
 	}
 	const workingContext = [...workingEntries.values()].map((entry) => ({
 		path: entry.path,
@@ -250,6 +358,7 @@ function legacyPathScope(req: DispatchRequest, cwd: string): DispatchPathScope {
 		workingContextPaths: workingContext.map((entry) => entry.path),
 		writeBoundaries: writeBoundaries.map((entry) => entry.path),
 		inferredOnlyPaths: [],
+		parentTokens: [...parentTokens.values()],
 		provenance: {
 			version: 1,
 			mode: "legacy-inferred",
@@ -266,7 +375,15 @@ export function resolveDispatchPathScope(req: DispatchRequest): DispatchPathScop
 
 	const declaredProvenance = declaredIntentPathProvenance(req.intent);
 	const declaredPaths = declaredProvenance.map((entry) => entry.path);
-	const inferredOnlyPaths = inferredPaths(req).filter((candidate) => !pathBoundaryCovers(declaredPaths, candidate));
+	const inferred = inferredPaths(req, cwd);
+	// A dropped token cannot be covered by a declaration, so it is always listed.
+	// An anchored one is listed under the path it anchored to and goes through
+	// the same coverage test the notice has always applied, which is why
+	// "../src/store.js" under a declared "src/" stops reading as an omitted path.
+	const inferredOnlyPaths = [
+		...inferred.paths.filter((candidate) => !pathBoundaryCovers(declaredPaths, candidate)),
+		...inferred.droppedTokens,
+	];
 	const writeEvidence = DECLARED_EVIDENCE.writeRoots;
 	const writeBoundaries = req.intent.writeRoots.map((root) => ({
 		path: resolvePathBoundary(cwd, root),
@@ -277,6 +394,11 @@ export function resolveDispatchPathScope(req: DispatchRequest): DispatchPathScop
 		workingContextPaths: declaredPaths,
 		writeBoundaries: writeBoundaries.map((entry) => entry.path),
 		inferredOnlyPaths,
+		// Empty on purpose: the declaration is the scope here, so no "../" token
+		// changed what the worker sees and there is nothing for the legacy notice
+		// to report. A dropped one still reaches the operator through
+		// inferredOnlyPaths above.
+		parentTokens: [],
 		provenance: {
 			version: 1,
 			mode: "declared",
@@ -286,24 +408,113 @@ export function resolveDispatchPathScope(req: DispatchRequest): DispatchPathScop
 	};
 }
 
+/**
+ * The prose token grammar also matches version numbers, ratios, and Latin
+ * abbreviations ("0.5", "v24.9", "e.g", "dead/raw"). Those never select a rule
+ * or a boundary, so the replacement notice names only tokens that read as
+ * repository paths: a segment with a source or document file extension, or
+ * a trailing directory separator. Method names (`Store.fromText`, `store.set`)
+ * share the dotted shape and are excluded by the extension list. A live three-task dispatch printed 27
+ * "omitted paths" per task, most of them numbers, three times over.
+ */
+const REPORTABLE_OMITTED_PATH_RE =
+	/\.(?:[cm]?[jt]sx?|json|ya?ml|md|txt|py|go|rs|c|h|cc|cpp|hpp|java|rb|sh|toml|css|html|sql|lock)(?:\/|$)|\/$/u;
+const OMITTED_PATH_REPORT_CAP = 12;
+
+/** Omitted prose paths worth telling the operator about, capped for the transcript. */
+function reportableOmittedPaths(scope: DispatchPathScope): string[] {
+	return scope.inferredOnlyPaths.filter((path) => REPORTABLE_OMITTED_PATH_RE.test(path));
+}
+
+function renderOmittedPaths(paths: ReadonlyArray<string>): string {
+	if (paths.length <= OMITTED_PATH_REPORT_CAP) return paths.join(", ");
+	return `${paths.slice(0, OMITTED_PATH_REPORT_CAP).join(", ")} and ${paths.length - OMITTED_PATH_REPORT_CAP} more`;
+}
+
 /** Render the named diagnostic for the declared-scope replacement tradeoff. */
 export function declaredScopeReplacementDiagnostic(scope: DispatchPathScope): string | null {
-	if (scope.source !== "declared" || scope.inferredOnlyPaths.length === 0) return null;
-	return `typed_scope_replaced_inferred_paths: typed intent omitted prose-inferred paths ${scope.inferredOnlyPaths.join(
-		", ",
+	if (scope.source !== "declared") return null;
+	const omitted = reportableOmittedPaths(scope);
+	if (omitted.length === 0) return null;
+	return `typed_scope_replaced_inferred_paths: typed intent omitted prose-inferred paths ${renderOmittedPaths(
+		omitted,
 	)}; those paths did not select project rules or expand worker authority`;
 }
 
 /** Render the interactive warning for the declared-scope replacement tradeoff. */
 export function declaredScopeReplacementNotice(scope: DispatchPathScope): DeclaredScopeReplacementNotice | null {
-	if (scope.source !== "declared" || scope.inferredOnlyPaths.length === 0) return null;
-	const omittedPaths = [...scope.inferredOnlyPaths];
+	if (scope.source !== "declared") return null;
+	const omittedPaths = reportableOmittedPaths(scope);
+	if (omittedPaths.length === 0) return null;
 	return {
 		code: "typed_scope_replaced_inferred_paths",
 		level: "warning",
 		omittedPaths,
-		message: `[dispatch scope] typed intent replaced prose path inference; omitted paths: ${omittedPaths.join(
-			", ",
+		message: `[dispatch scope] typed intent replaced prose path inference; omitted paths: ${renderOmittedPaths(
+			omittedPaths,
 		)}. Those paths did not select project rules or expand worker authority.`,
 	};
 }
+
+/**
+ * A reinterpreted "../" token is the one legacy-mode scope fact worth the
+ * transcript. It fires only where a leading "../" run made inference choose
+ * between a path the prose never literally spelled and no path at all, which
+ * before this release failed the whole dispatch, so unlike a per-dispatch
+ * inference notice it cannot warn on the ordinary case that
+ * `publishDispatchPathScope` deliberately keeps quiet. The anchored token earns
+ * the line more than the dropped one: dropping subtracts from scope, while
+ * anchoring puts "src/store.js" in working context because prose said
+ * "../src/store.js", and a rewrite the operator cannot see is one nobody can
+ * check.
+ *
+ * Declared mode records none. The declaration is the scope there, and a prose
+ * token that never entered it is already the subject of
+ * `declaredScopeReplacementNotice`. That notice filters by
+ * REPORTABLE_OMITTED_PATH_RE, so a declared-mode drop of "../data/blob.bin" or
+ * "../src/helper" is in fact named nowhere; that is the accepted cost of not
+ * spending a second per-dispatch notice on a token that took no part in a scope
+ * the intent had already fixed.
+ *
+ * The legacy list is not filtered by REPORTABLE_OMITTED_PATH_RE, because the
+ * "../" prefix is itself the filter: the version numbers, ratios, and Latin
+ * abbreviations that filter exists for ("0.5", "v24.9", "e.g", "4/10") cannot
+ * carry one.
+ *
+ * Both notices render one `<raw token> -> <anchored path or "dropped">` pair
+ * per entry, under the same twelve-entry cap the replacement notice uses.
+ */
+function renderParentTokens(tokens: ReadonlyArray<DispatchInferredParentToken>): string {
+	return renderOmittedPaths(tokens.map((entry) => `${entry.token} -> ${entry.resolved ?? "dropped"}`));
+}
+
+/** Render the named diagnostic for prose tokens whose leading "../" run was reinterpreted. */
+export function inferredScopeParentTokenDiagnostic(scope: DispatchPathScope): string | null {
+	const tokens = scope.parentTokens;
+	if (tokens.length === 0) return null;
+	return `legacy_scope_inferred: prose inference resolved path tokens carrying a leading '../' run against the dispatch root ${renderParentTokens(
+		tokens,
+	)}; an anchored token selects project rules without expanding worker authority and a dropped one took no part in scope`;
+}
+
+/** Render the interactive warning for prose tokens whose leading "../" run was reinterpreted. */
+export function inferredScopeParentTokenNotice(scope: DispatchPathScope): InferredScopeParentTokenNotice | null {
+	const tokens = scope.parentTokens;
+	if (tokens.length === 0) return null;
+	return {
+		code: "legacy_scope_inferred",
+		level: "warning",
+		// Every entry names the raw prose token, the one spelling both outcomes
+		// share; the message carries what each one resolved to.
+		paths: tokens.map((entry) => ({
+			path: entry.token,
+			policy: "working-context",
+			provenance: "inferred",
+			source: entry.source,
+			confidence: "low",
+		})),
+		message: `[dispatch scope] prose inference resolved path tokens carrying a leading '../' run against the dispatch root: ${renderParentTokens(
+			tokens,
+		)}. An anchored token selects project rules without expanding worker authority; a dropped one took no part in scope.`,
+	};
+}

package/src/domains/dispatch/run-event-journal.ts

@@ -51,9 +51,6 @@ export const RUN_EVENT_JOURNAL_FILE = "events.ndjson";
 export const RUN_EVENT_JOURNAL_CAP_BYTES = 2 * 1024 * 1024;
 /** Pending bytes that trigger a flush of droppable lines. */
 export const RUN_EVENT_JOURNAL_FLUSH_BYTES = 8 * 1024;
-/** Per-process env override, resolved ahead of settings (see runEventJournalEnabled). */
-export const RUN_EVENT_JOURNAL_ENV_VAR = "CLIO_CODER_RUN_JOURNAL";
-
 interface JournalLineBase {
 	seq: number;
 	at: string;
@@ -119,7 +116,7 @@ export interface RunEventJournal extends RunEventJournalSink {
 let configuredEnabled: boolean | undefined;
 
 /**
- * Install the `panes.journal` setting. Called from the composition root beside
+ * Install the `fleet.history.journal` setting. Called from the composition root beside
  * `configureGuardrails` so the journal never reads settings.yaml itself; a
  * settings read on the dispatch event path would be both a cost and a throw
  * site (readSettings rejects an invalid file).
@@ -128,17 +125,9 @@ export function configureRunEventJournal(enabled: boolean | undefined): void {
 	configuredEnabled = enabled;
 }
 
-function parseEnvFlag(raw: string | undefined): boolean | undefined {
-	if (raw === undefined) return undefined;
-	const normalized = raw.trim().toLowerCase();
-	if (normalized === "1" || normalized === "true" || normalized === "on") return true;
-	if (normalized === "0" || normalized === "false" || normalized === "off") return false;
-	return undefined;
-}
-
-/** env override > configured settings > on. */
-function runEventJournalEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
-	return parseEnvFlag(env[RUN_EVENT_JOURNAL_ENV_VAR]) ?? configuredEnabled ?? true;
+/** Effective settings projection, then the shipped default. */
+function runEventJournalEnabled(): boolean {
+	return configuredEnabled ?? true;
 }
 
 // ---------------------------------------------------------------------------

package/src/domains/dispatch/state.ts

@@ -6,8 +6,8 @@
  *   receipts/<runId>.json        per-run RunReceipt
  *
  * The ledger holds an in-memory mirror of runs.json. `create()` and `update()`
- * mutate memory only; `persist()` writes the bounded ring (default 1000, env
- * override `CLIO_CODER_MAX_DISPATCH_RUNS`) atomically via engine.atomicWrite.
+ * mutate memory only; `persist()` writes the settings-bounded ring (default
+ * 1000) atomically via engine.atomicWrite.
  *
  * No worker spawning, no domain wire-up, no SafeEventBus emission yet. Those
  * land in P6S3 and P6S5. This slice is a pure persistence primitive.
@@ -159,7 +159,6 @@ function readRuns(): RunEnvelope[] {
 
 function resolveMaxRuns(opt?: number | undefined): number {
 	if (opt !== undefined && opt > 0) return Math.floor(opt);
-	// env (CLIO_CODER_MAX_DISPATCH_RUNS) > settings guardrails > default; see core/guardrails.ts.
 	return resolveGuardrail("maxDispatchRuns");
 }
 

package/src/domains/dispatch/transport.ts

@@ -10,9 +10,9 @@
  *
  * SSH tier invariants:
  *   - The remote environment is a whitelist, never the orchestrator's
- *     process.env. Remote workers default to CLIO_CODER_RESIDENCY=observe so a
- *     worker on a node that serves models for the operator can never evict a
- *     resident model.
+ *     process.env. Remote workers default to a user-managed target lifecycle
+ *     so a worker on a node that serves models for the operator can never
+ *     evict a resident model.
  *   - The orchestrator cwd is entered on the remote node (shared-filesystem
  *     assumption; path parity is a doctor preflight, and placement refuses
  *     nodes that have not passed it).
@@ -62,9 +62,9 @@ export interface SshNodeEndpoint {
 	 */
 	clioCoderEntry?: string;
 	/**
-	 * Residency posture exported to the remote worker. Defaults to "observe":
-	 * remote workers must never evict models resident on their node. "manage"
-	 * is an explicit per-node opt-in.
+	 * Residency posture projected into the remote worker's target lifecycle.
+	 * Defaults to "observe": remote workers must never evict models resident on
+	 * their node. "manage" is an explicit per-node opt-in.
 	 */
 	residency?: "observe" | "manage";
 	connectTimeoutSec?: number;
@@ -99,14 +99,33 @@ const DEFAULT_REMOTE_CLIO_ENTRY = "clio-coder worker";
  * orchestrator-supplied credential.
  */
 function remoteEnvAssignments(node: SshNodeEndpoint): string {
-	const residency = node.residency ?? "observe";
 	// `$$` is the login shell's pid, and it leads the process group the remote
 	// command runs in. `exec` replaces that shell in place, so the worker
 	// inherits both the pid and the group leadership, and the value it announces
 	// is the group an abort must signal.
 	const labels = (node.labels ?? []).map((label) => label.trim()).filter((label) => label.length > 0);
 	const labelAssignment = labels.length > 0 ? ` CLIO_CODER_WORKER_LABELS=${shellQuote(labels.join(","))}` : "";
-	return `AI_AGENT=${AI_AGENT_NAME} CLIO_CODER_RESIDENCY=${residency} CLIO_CODER_WORKER_PGID=$$${labelAssignment}`;
+	return `AI_AGENT=${AI_AGENT_NAME} CLIO_CODER_WORKER_PGID=$$${labelAssignment}`;
+}
+
+type TargetLifecycle = NonNullable<WorkerSpec["target"]["lifecycle"]>;
+
+export function resolveSshTargetLifecycle(
+	residency: SshNodeEndpoint["residency"],
+	targetLifecycle: WorkerSpec["target"]["lifecycle"],
+): TargetLifecycle {
+	if (targetLifecycle === "user-managed" || residency !== "manage") return "user-managed";
+	return "clio-coder-managed";
+}
+
+function workerSpecForSshNode(node: SshNodeEndpoint, spec: WorkerSpec): WorkerSpec {
+	return {
+		...spec,
+		target: {
+			...spec.target,
+			lifecycle: resolveSshTargetLifecycle(node.residency, spec.target.lifecycle),
+		},
+	};
 }
 
 function buildRemoteWorkerCommand(node: SshNodeEndpoint, cwd: string): string {
@@ -174,20 +193,25 @@ export function createSshWorkerTransport(node: SshNodeEndpoint, opts?: SshTransp
 			// are the transport's own and compose with the caller's rather than
 			// replacing them; every other option is forwarded as handed.
 			const { cwd: _consumedCwd, onAnnounce, onForcedKill, ...forwarded } = spawnOpts ?? {};
-			return spawnWorkerProcess(sshBinary, buildSshArgs(node, buildRemoteWorkerCommand(node, cwd)), spec, {
-				...(opts?.shutdownGraceMs !== undefined ? { shutdownGraceMs: opts.shutdownGraceMs } : {}),
-				...forwarded,
-				env: process.env,
-				onAnnounce: (attestation) => {
-					remote.pid = attestation.pid;
-					remote.processGroupId = attestation.processGroupId;
-					onAnnounce?.(attestation);
-				},
-				onForcedKill: () => {
-					killRemote();
-					onForcedKill?.();
+			return spawnWorkerProcess(
+				sshBinary,
+				buildSshArgs(node, buildRemoteWorkerCommand(node, cwd)),
+				workerSpecForSshNode(node, spec),
+				{
+					...(opts?.shutdownGraceMs !== undefined ? { shutdownGraceMs: opts.shutdownGraceMs } : {}),
+					...forwarded,
+					env: process.env,
+					onAnnounce: (attestation) => {
+						remote.pid = attestation.pid;
+						remote.processGroupId = attestation.processGroupId;
+						onAnnounce?.(attestation);
+					},
+					onForcedKill: () => {
+						killRemote();
+						onForcedKill?.();
+					},
 				},
-			});
+			);
 		},
 	};
 }

package/src/domains/dispatch/types.ts

@@ -6,6 +6,7 @@
  * are pure data: no class methods, no engine refs.
  */
 
+import type { GatewayRoutingObservation } from "../../core/gateway-routing.js";
 import type { ResponseModelIdObservation } from "../../core/response-model-id.js";
 import type { SkillActivation } from "../../core/skill-activation.js";
 import type { ToolProfileName } from "../../tools/profiles.js";
@@ -584,7 +585,7 @@ export interface RunReceiptSafetySummary {
 	 * (reason code `guard_block`); a call that required permission and was denied
 	 * non-interactively is counted under `permissionRequested`, not `blocked`, so
 	 * scripts can tell "approval would have been needed" apart from a policy
-	 * block (see docs/safety-model.md). Such a call still appears in
+	 * block (see docs/architecture/safety-model.md). Such a call still appears in
 	 * `blockedAttempts` because its outcome was blocked, so `decisions.blocked`
 	 * is not a proxy for the number of blocked attempts; use `blockedAttempts`
 	 * or the `toolStats`/`toolActivity` blocked counts for that.
@@ -652,6 +653,8 @@ export interface RunReceiptUpstreamResponse {
 	responseModelIdObservation: ResponseModelIdObservation;
 	differingResponseModelId: string | null;
 	providerResponseId: string | null;
+	/** Physical route and proxy attempts reported by LiteLLM, when this call used that gateway. */
+	gatewayRouting?: GatewayRoutingObservation;
 }
 
 /**
@@ -712,14 +715,66 @@ export interface RunHostVerificationCheck {
 	memo: boolean;
 	outputTail: string;
 	artifactPath?: string;
-	/** Original evidence owner on a memo hit. */
+	/** Run that owns the evidence when it did not come from this run: a memo hit, or the batch member the shared check ran under. */
 	evidenceRunId?: string;
 }
 
+/**
+ * Why a batch-settled failing check was or was not charged to a run. It is a
+ * batch-wide fact and is sealed identically on every receipt in the batch; each
+ * receipt's own `status` is what that run is judged by.
+ */
+export interface RunHostVerificationAttribution {
+	/** Declared check id that failed. */
+	check: string;
+	/**
+	 * Absolute repository paths the check's own output named, capped at 32. The
+	 * paths that decided the charge come first so a truncated list still contains
+	 * the evidence behind the verdict; each group is sorted.
+	 */
+	implicated: string[];
+	/** Run ids the failure is charged to, sorted; empty when every named path belongs to a run that did not declare the check. */
+	charged: string[];
+	/**
+	 * The weakest evidence behind the charge set, never the strongest, so the
+	 * record cannot claim a certainty it does not have.
+	 *
+	 * `write_roots`: every charged run has an implicated path inside its own
+	 * declared write roots. `attributed_elsewhere`: nothing is charged because
+	 * every implicated path falls inside the write roots of a live batch member
+	 * that did not declare this check. `unattributable`: the charge is not backed
+	 * by per-run path evidence, which covers a failure that named no path, one
+	 * that named only paths no member claims, and one charged to a run that
+	 * declared no write roots at all. The first two of those charge every run that
+	 * declared the check: a real failure with no owner is charged to everyone
+	 * rather than excused for everyone.
+	 */
+	basis: "write_roots" | "attributed_elsewhere" | "unattributable";
+}
+
 export interface RunHostVerification {
-	status: "verified" | "rejected" | "skipped";
+	/**
+	 * `verified` states that every declared check passed, which is the claim
+	 * `trust-status.ts:619` turns into "validated by host-verification".
+	 * `not_implicated` is the batch-settled exculpation: a declared check failed
+	 * for the batch and this run's `checks` carries its non-zero exit code, but
+	 * the failure was charged elsewhere, so no validator speaks for this run.
+	 */
+	status: "verified" | "rejected" | "skipped" | "not_implicated";
 	reason?: string;
 	checks: RunHostVerificationCheck[];
+	/**
+	 * How the declared checks were run. Absent means the single-run strategy every
+	 * receipt carried before batch settlement existed: the checks ran for this run
+	 * alone, straight after it finished. `batch-settled` means they ran once for
+	 * the whole parallel batch after every live member had finished. The field is
+	 * omitted rather than stamped `"single"` so a single-task receipt digests
+	 * exactly as it did before (`receipt-integrity.ts:145-147` is the same
+	 * reasoning applied one field over).
+	 */
+	strategy?: "batch-settled";
+	/** Per-failing-check attribution for a batch-settled run; absent when nothing failed. */
+	attribution?: RunHostVerificationAttribution[];
 }
 
 export interface RunReceipt {

package/src/domains/dispatch/worker-model-metadata.ts

@@ -0,0 +1,38 @@
+import type { ProvidersContract } from "../providers/contract.js";
+
+/** Preparation owns its wait; a late HTTP body cannot start an expired worker. */
+export async function prepareWorkerModelMetadata(
+	providers: ProvidersContract,
+	targetId: string,
+	deadlineAt: number,
+	signal?: AbortSignal,
+	now: () => number = Date.now,
+): Promise<void> {
+	signal?.throwIfAborted();
+	const status = providers.list().find((entry) => entry.target.id === targetId);
+	if (status?.target.runtime !== "litellm" || status.health.lastCheckAt !== null) return;
+	const remainingMs = deadlineAt - now();
+	const deadlineError = new Error("dispatch: admission deadline expired during worker model metadata preparation");
+	if (remainingMs <= 0) throw deadlineError;
+	const controller = new AbortController();
+	const abort = (): void => controller.abort(signal?.reason);
+	signal?.addEventListener("abort", abort, { once: true });
+	const timer = setTimeout(() => controller.abort(deadlineError), Math.min(remainingMs, 2_147_483_647));
+	let rejectAborted!: (reason: unknown) => void;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		rejectAborted = reject;
+	});
+	const onAbort = (): void => rejectAborted(controller.signal.reason);
+	controller.signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		// The provider also fences publication after each await. Promise.race
+		// observes the probe's eventual rejection if an HTTP body settles late.
+		await Promise.race([providers.probeTarget(targetId, { reasoning: false, signal: controller.signal }), aborted]);
+		controller.signal.throwIfAborted();
+		if (now() >= deadlineAt) throw deadlineError;
+	} finally {
+		clearTimeout(timer);
+		signal?.removeEventListener("abort", abort);
+		controller.signal.removeEventListener("abort", onAbort);
+	}
+}