@themoltnet/pi-runtime 0.7.3 → 0.9.0

package/dist/index.d.ts

@@ -49,10 +49,24 @@ export declare interface AllowedToolsClient {
                 argvPrefix: string[];
             }>;
             runtimeKind: string;
+            policySnapshotHash?: string;
+            runtimeProfileRevision?: number;
         }>;
     };
 }
 
+export declare function assertGuestEnvironmentBoundary(options: {
+    guestCredentialMode: GuestCredentialMode;
+    forwardEnv?: readonly string[];
+    sandboxEnv?: Readonly<Record<string, string>>;
+}): void;
+
+/** @deprecated Prefer assertGuestEnvironmentBoundary for mode-aware checks. */
+export declare function assertHostAuthenticatedGuestEnvironment(options: {
+    forwardEnv?: readonly string[];
+    sandboxEnv?: Readonly<Record<string, string>>;
+}): void;
+
 /**
  * Construct an `AgentSession`. By default it is in-memory; callers may opt
  * parent sessions into daemon-owned file persistence via `sessionPersistence`.
@@ -390,6 +404,10 @@ export declare function executePiTask(claimedTask: ClaimedTask, reporter: TaskRe
 export declare interface ExecutePiTaskOptions {
     /** MoltNet agent whose credentials the VM boots with. */
     agentName: string;
+    /** Already-authenticated host-side Agent. Daemon callers always supply it. */
+    moltnetAgent?: Agent;
+    /** Explicit trust boundary for MoltNet credentials inside the guest. */
+    guestCredentialMode?: GuestCredentialMode;
     /**
      * Host root that owns `.moltnet/<agentName>/`.
      *
@@ -430,8 +448,8 @@ export declare interface ExecutePiTaskOptions {
     runtimeProfileContext?: readonly ContextRef[];
     /**
      * Runtime profile id, used to resolve the tool-policy allow-set at session
-     * start. Required together with a non-`off` `toolEnforcement` for the
-     * `tool_call` gate to run.
+     * start. Required with `toolEnforcement`; the resolved mode determines
+     * whether a `tool_call` gate is installed.
      */
     runtimeProfileId?: string;
     /** Tool-policy enforcement mode for the selected runtime profile. */
@@ -447,6 +465,8 @@ export declare interface ExecutePiTaskOptions {
     promptExtras?: Record<string, unknown>;
     /** Snapshot progress callback; defaults to stderr logging. */
     onSnapshotProgress?: (message: string) => void;
+    /** Structured VM credential-boundary diagnostics. */
+    onVmDiagnostic?: (diagnostic: VmDiagnostic) => void;
     /**
      * Optional pre-resolved checkpoint path. If omitted, `ensureSnapshot` is
      * invoked. Useful for batch execution where the caller wants to cache
@@ -586,21 +606,18 @@ export declare function filterModelVisibleTools(tools: readonly ToolDefinition[]
  */
 export declare function findMainWorktree(startPath?: string): string;
 
-/**
- * The gate's verdict:
- * - `{ allow: true }` — let the tool run.
- * - `{ allow: false, reason }` — block it (enforce mode).
- * - `{ audit, ... }` — would-block, but proceed and record it (watch mode).
- */
 export declare type GateDecision = {
     allow: true;
+    reasonCode: ToolPolicyDecisionReason;
     matchedShellCommands?: MatchedShellCommand[];
 } | {
     allow: false;
+    reasonCode: ToolPolicyDecisionReason;
     reason: string;
     missing?: string[];
     missingShellCommands?: MissingShellCommand[];
 } | {
+    reasonCode: ToolPolicyDecisionReason;
     audit: string;
     missing?: string[];
     missingShellCommands?: MissingShellCommand[];
@@ -642,6 +659,13 @@ export declare interface GondolinTemplateResolveContext {
     onProgress?: (message: string) => void;
 }
 
+export declare type GuestCredentialMode = 'guest-config' | 'host-authenticated';
+
+export declare class GuestEnvironmentBoundaryError extends Error {
+    readonly refusedNames: readonly string[];
+    constructor(refusedNames: readonly string[]);
+}
+
 /**
  * Baseline env keys forwarded to host-exec child processes.
  * Callers can extend this set at sandbox startup via `MoltNetToolsConfig.hostExecBaseEnv`.
@@ -703,7 +727,7 @@ export declare function isResolvedPathInsideRoot(path: string, root: string): bo
 
 export declare function isToolVisible(name: string, policy?: ModelVisibleToolPolicy): boolean;
 
-export declare function loadCredentials(agentDir: string): VmCredentials;
+export declare function loadCredentials(agentDir: string, mode?: GuestCredentialMode, onDiagnostic?: (diagnostic: VmDiagnostic) => void): VmCredentials;
 
 export declare interface ManagedVm {
     vm: VM;
@@ -1076,11 +1100,14 @@ export declare interface ResolvedGondolinTemplate {
     resumeCommands: readonly ResumeCommand[];
 }
 
+export declare function resolveHostExecBaseEnv(guestCredentialMode: GuestCredentialMode, agentEnv: Readonly<Record<string, string | undefined>>): Set<string>;
+
 /**
  * Resolve the session's tool policy at start-up.
  *
- * `off` short-circuits without a network call. Otherwise the allowed-tool set
- * is fetched from the API. If that fetch fails, the mode decides the fallback:
+ * The latest allowed-tool set and enforcement mode are fetched from the API,
+ * including when the daemon's cached profile says `off`. If that fetch fails,
+ * the cached mode decides the fallback:
  * `enforce` **fails closed** (empty allow-set → every non-`off` tool is
  * blocked); `watch` fails open (empty allow-set → every tool is audited but
  * allowed).
@@ -1264,6 +1291,10 @@ export declare interface SessionToolPolicy {
     enforcement: ToolEnforcement;
     allowedTools: ReadonlySet<string>;
     allowedShellCommands: readonly ShellCommandRule[];
+    /** Latest effective policy hash resolved for this Pi session. */
+    executionPolicySnapshotHash?: string;
+    /** Latest runtime profile revision resolved with the session policy. */
+    executionRuntimeProfileRevision?: number;
     /**
      * `true` when the allow-set is a **degraded fallback** — the allowed-tools
      * fetch failed or timed out and this policy is the fail-closed/fail-open
@@ -1271,7 +1302,7 @@ export declare interface SessionToolPolicy {
      * empty-but-resolved policy (e.g. a profile with no bound tools) has
      * `degraded: false`. Surfaced in every audit/block log so an operator can tell
      * "blocked because the policy is empty" from "blocked because we couldn't read
-     * the policy". `off` and successful resolutions are never degraded.
+     * the policy". Successful resolutions are never degraded.
      */
     degraded: boolean;
 }
@@ -1327,10 +1358,35 @@ declare const ToolEnforcementSchema = Type.Union(toolEnforcementLiterals, {
     'Runtime tool-policy enforcement mode: off (inert), watch (audit only), enforce (block disallowed tools, fail-closed).',
 });
 
+/** Correlation and claim evidence repeated on every tool-policy decision. */
+export declare interface ToolPolicyDecisionContext {
+    taskId: string;
+    attemptN: number;
+    teamId: string;
+    claimantAgentId?: string;
+    leaseId?: string;
+    proposerKind?: 'agent' | 'human';
+    proposerId?: string;
+    claimRuntimeProfileId?: string;
+    executionRuntimeProfileId?: string;
+    claimRuntimeProfileRevision?: number;
+    claimPolicySnapshotHash?: string;
+    claimedExecutorFingerprint?: string;
+}
+
+/**
+ * The gate's verdict:
+ * - `{ allow: true }` — let the tool run.
+ * - `{ allow: false, reason }` — block it (enforce mode).
+ * - `{ audit, ... }` — would-block, but proceed and record it (watch mode).
+ */
+export declare type ToolPolicyDecisionReason = 'policy_off' | 'executor_protocol_tool' | 'policy_allowed' | 'shell_command_prefix_allowed' | 'shell_command_unresolvable' | 'arbitrary_code_interpreter' | 'shell_output_redirection_requires_broad_permission' | 'tool_not_permitted';
+
 export declare interface ToolPolicyExtensionDeps {
     policy: SessionToolPolicy;
     analyzer: ShellCommandAnalyzer;
     logger: ToolPolicyLogger;
+    context?: ToolPolicyDecisionContext;
 }
 
 /**
@@ -1366,6 +1422,12 @@ export declare interface VmConfig {
     checkpointPath: string;
     /** MoltNet agent name (used to resolve credentials). */
     agentName: string;
+    /**
+     * Trust boundary for guest credentials. `guest-config` injects the complete
+     * legacy agent directory. `host-authenticated` never reads or injects it and
+     * relies exclusively on the supplied host-side Agent for MoltNet operations.
+     */
+    guestCredentialMode?: GuestCredentialMode;
     /**
      * Host root that owns `.moltnet/<agentName>/`.
      *
@@ -1389,12 +1451,16 @@ export declare interface VmConfig {
      * into the guest without storing secret values in the profile.
      */
     forwardEnv?: string[];
+    /** Structured credential-boundary diagnostics for daemon loggers. */
+    onDiagnostic?: (diagnostic: VmDiagnostic) => void;
     /** Abort resume/setup work, closing any live VM owned by resumeVm. */
     signal?: AbortSignal;
 }
 
 export declare interface VmCredentials {
+    /** Empty in host-authenticated mode; retained as strings for API stability. */
     moltnetJson: string;
+    /** Empty in host-authenticated mode; retained as strings for API stability. */
     agentEnvRaw: string;
     /**
      * Pi OAuth/API-key auth blob. Null when neither `~/.pi/agent/auth.json`
@@ -1415,6 +1481,13 @@ export declare interface VmCredentials {
     githubAppPemFilename: string | null;
 }
 
+export declare interface VmDiagnostic {
+    event: 'vm.credentials.mode' | 'vm.credentials.github_key_missing';
+    level: 'info' | 'warning';
+    message: string;
+    credentialMode: GuestCredentialMode;
+}
+
 /**
  * Subset of `@earendil-works/gondolin`'s `VmFs` we actually use. We
  * narrow the dependency surface so unit tests can hand in a

package/dist/index.js

@@ -1925,6 +1925,11 @@ Type$1.Object({ id: UuidSchema });
 Type$1.Object({
 	publicKey: PublicKeySchema,
 	fingerprint: FingerprintSchema,
+	proof: Type$1.String({
+		minLength: 1,
+		maxLength: 256
+	}),
+	credentialType: Type$1.Literal("oauth2"),
 	agentName: Type$1.String({
 		minLength: 1,
 		maxLength: 34
@@ -2198,7 +2203,6 @@ var ProblemCodeSchema = Type$1.Union([
 	Type$1.Literal("VALIDATION_FAILED"),
 	Type$1.Literal("INVALID_CHALLENGE"),
 	Type$1.Literal("INVALID_SIGNATURE"),
-	Type$1.Literal("VOUCHER_LIMIT"),
 	Type$1.Literal("RATE_LIMIT_EXCEEDED"),
 	Type$1.Literal("SERIALIZATION_EXHAUSTED"),
 	Type$1.Literal("SIGNING_REQUEST_EXPIRED"),
@@ -4532,12 +4536,30 @@ function resolveVmAgentDir(config) {
 	const rootDir = config.agentRootDir ?? findMainWorktree();
 	return path.join(rootDir, ".moltnet", config.agentName);
 }
-function loadCredentials(agentDir) {
-	const moltnetJson = readFileSync(path.join(agentDir, "moltnet.json"), "utf8");
-	const agentEnvRaw = readFileSync(path.join(agentDir, "env"), "utf8");
+function loadCredentials(agentDir, mode = "guest-config", onDiagnostic) {
+	const moltnetPath = path.join(agentDir, "moltnet.json");
+	const agentEnvPath = path.join(agentDir, "env");
 	const piAgentDir = resolvePiCodingAgentDir();
 	const piAuthPath = path.join(piAgentDir, "auth.json");
 	const piAuthJson = existsSync(piAuthPath) ? readFileSync(piAuthPath, "utf8") : null;
+	if (mode === "host-authenticated") return {
+		moltnetJson: "",
+		agentEnvRaw: "",
+		piAuthJson,
+		agentEnv: {},
+		gitconfig: null,
+		sshPrivateKey: null,
+		sshPublicKey: null,
+		allowedSigners: null,
+		githubAppPem: null,
+		githubAppPemFilename: null
+	};
+	const hasMoltnetJson = existsSync(moltnetPath);
+	const hasAgentEnv = existsSync(agentEnvPath);
+	if (!hasMoltnetJson || !hasAgentEnv) throw new Error(`Guest credential mode requires both ${moltnetPath} and ${agentEnvPath}`);
+	const moltnetJson = readFileSync(moltnetPath, "utf8");
+	const agentEnvRaw = readFileSync(agentEnvPath, "utf8");
+	if (moltnetJson.trim() === "") throw new Error(`Agent configuration is empty: ${moltnetPath}`);
 	const gitconfigPath = path.join(agentDir, "gitconfig");
 	const gitconfig = existsSync(gitconfigPath) ? readFileSync(gitconfigPath, "utf8") : null;
 	const sshDir = path.join(agentDir, "ssh");
@@ -4546,9 +4568,13 @@ function loadCredentials(agentDir) {
 	const allowedSigners = existsSync(path.join(sshDir, "allowed_signers")) ? readFileSync(path.join(sshDir, "allowed_signers"), "utf8") : null;
 	let githubAppPem = null;
 	let githubAppPemFilename = null;
-	const pemPath = JSON.parse(moltnetJson).github?.private_key_path;
-	if (pemPath) if (!existsSync(pemPath)) process.stderr.write(`[pi-extension] Warning: github.private_key_path not found at ${pemPath} — moltnet github token will fail inside the guest
-`);
+	const pemPath = (moltnetJson ? JSON.parse(moltnetJson) : null)?.github?.private_key_path;
+	if (pemPath) if (!existsSync(pemPath)) onDiagnostic?.({
+		event: "vm.credentials.github_key_missing",
+		level: "warning",
+		credentialMode: mode,
+		message: `github.private_key_path not found at ${pemPath}; moltnet github token will fail inside the guest`
+	});
 	else {
 		githubAppPem = readFileSync(pemPath, "utf8");
 		githubAppPemFilename = path.basename(pemPath);
@@ -4594,6 +4620,70 @@ var BASE_ALLOWED_HOSTS = [
 	"storage.googleapis.com",
 	"*.googlesource.com"
 ];
+var DEFAULT_MOLTNET_API_URL = "https://api.themolt.net";
+/**
+* Host environment names that may intentionally cross into a
+* host-authenticated guest. This local list is the authority boundary;
+* server-supplied runtime-profile `requiredEnv` cannot widen it.
+*/
+var HOST_AUTHENTICATED_GUEST_ENV_ALLOWLIST = new Set([
+	"ANTHROPIC_API_KEY",
+	"OPENAI_API_KEY",
+	"OPENAI_BASE_URL",
+	"AZURE_OPENAI_API_KEY",
+	"AZURE_OPENAI_ENDPOINT",
+	"AZURE_OPENAI_API_VERSION",
+	"GOOGLE_API_KEY",
+	"GEMINI_API_KEY",
+	"MISTRAL_API_KEY",
+	"GROQ_API_KEY",
+	"OPENROUTER_API_KEY",
+	"XAI_API_KEY",
+	"CEREBRAS_API_KEY",
+	"DEEPSEEK_API_KEY",
+	"OLLAMA_API_KEY",
+	"OLLAMA_BASE_URL",
+	"AWS_ACCESS_KEY_ID",
+	"AWS_SECRET_ACCESS_KEY",
+	"AWS_SESSION_TOKEN",
+	"AWS_REGION",
+	"AWS_DEFAULT_REGION",
+	"GITHUB_TOKEN",
+	"GH_TOKEN",
+	"LINEAR_API_KEY"
+]);
+var RESERVED_GUEST_ENVIRONMENT_NAMES = new Set([
+	"PATH",
+	"HOME",
+	"NODE_EXTRA_CA_CERTS",
+	"MOLTNET_GUEST_WORKSPACE",
+	"GIT_SSH",
+	"GIT_SSH_COMMAND",
+	"SSH_AUTH_SOCK"
+]);
+function isReservedGuestEnvironmentName(name) {
+	return name.startsWith("MOLTNET_") || name.startsWith("GIT_CONFIG_") || RESERVED_GUEST_ENVIRONMENT_NAMES.has(name);
+}
+var GuestEnvironmentBoundaryError = class extends Error {
+	constructor(refusedNames) {
+		super(`Guest credential boundary refuses runtime-controlled environment variables: ${refusedNames.join(", ")}. Remove them from the runtime profile; MoltNet operations use the trusted host-side Agent.`);
+		this.refusedNames = refusedNames;
+		this.name = "GuestEnvironmentBoundaryError";
+	}
+};
+function assertGuestEnvironmentBoundary(options) {
+	const refusedForwardEnv = (options.forwardEnv ?? []).filter((name) => isReservedGuestEnvironmentName(name) || options.guestCredentialMode === "host-authenticated" && !HOST_AUTHENTICATED_GUEST_ENV_ALLOWLIST.has(name));
+	const refusedSandboxEnv = Object.keys(options.sandboxEnv ?? {}).filter(isReservedGuestEnvironmentName);
+	const refused = [...new Set([...refusedForwardEnv, ...refusedSandboxEnv])].sort();
+	if (refused.length > 0) throw new GuestEnvironmentBoundaryError(refused);
+}
+/** @deprecated Prefer assertGuestEnvironmentBoundary for mode-aware checks. */
+function assertHostAuthenticatedGuestEnvironment(options) {
+	assertGuestEnvironmentBoundary({
+		guestCredentialMode: "host-authenticated",
+		...options
+	});
+}
 /**
 * Return whether two Gondolin hostname globs can match at least one common
 * string. Each `*` is an arbitrary substring, so this walks the product of the
@@ -4665,10 +4755,22 @@ async function resumeVm(config) {
 	throwIfAborted(config.signal, "VM resume");
 	const agentDir = resolveVmAgentDir(config);
 	const guestWorkspace = path.resolve(config.mountPath);
-	if (!existsSync(agentDir)) throw new Error(`Agent directory not found: ${agentDir}. Run: moltnet register --name ${config.agentName}`);
-	const creds = loadCredentials(agentDir);
-	const moltnetConfig = JSON.parse(creds.moltnetJson);
-	const apiHost = new URL(moltnetConfig.endpoints.api).hostname;
+	const guestCredentialMode = config.guestCredentialMode ?? "guest-config";
+	if (guestCredentialMode === "guest-config" && !existsSync(agentDir)) throw new Error(`Agent directory not found: ${agentDir}. Run: moltnet register --name ${config.agentName}`);
+	assertGuestEnvironmentBoundary({
+		guestCredentialMode,
+		forwardEnv: config.forwardEnv,
+		sandboxEnv: config.sandboxConfig?.env
+	});
+	config.onDiagnostic?.({
+		event: "vm.credentials.mode",
+		level: "info",
+		credentialMode: guestCredentialMode,
+		message: guestCredentialMode === "host-authenticated" ? "MoltNet agent files and non-allowlisted host environment variables are withheld from the guest" : "The complete MoltNet agent configuration is available to the guest"
+	});
+	const creds = loadCredentials(agentDir, guestCredentialMode, config.onDiagnostic);
+	const configuredApiUrl = creds.moltnetJson ? JSON.parse(creds.moltnetJson).endpoints.api : void 0;
+	const apiHost = new URL(configuredApiUrl ?? process.env.MOLTNET_API_URL ?? DEFAULT_MOLTNET_API_URL).hostname;
 	const runtimeAllowedHosts = config.sandboxConfig?.network?.allowedHosts ?? [];
 	const runtimeAllowedInternalHosts = config.sandboxConfig?.network?.allowedInternalHosts ?? [];
 	const protectedExternalHosts = [...new Set([
@@ -4689,7 +4791,7 @@ async function resumeVm(config) {
 		else if (k.endsWith("_PRIVATE_KEY_PATH")) vmAgentEnv[k] = `${vmAgentDir}/${path.basename(v)}`;
 		else vmAgentEnv[k] = v;
 	}
-	vmAgentEnv.MOLTNET_CREDENTIALS_PATH = `${vmAgentDir}/moltnet.json`;
+	if (creds.moltnetJson) vmAgentEnv.MOLTNET_CREDENTIALS_PATH = `${vmAgentDir}/moltnet.json`;
 	const vfsConfig = resolveVfsShadowConfig(config.sandboxConfig);
 	let workspaceProvider = new RealFSProvider(config.mountPath);
 	workspaceProvider = new ShadowProvider(workspaceProvider, {
@@ -4705,6 +4807,11 @@ async function resumeVm(config) {
 			writeMode: vfsConfig.mode
 		});
 	}
+	if (guestCredentialMode === "host-authenticated") workspaceProvider = new ShadowProvider(workspaceProvider, {
+		shouldShadow: ({ path: shadowPath }) => shadowPath.split("/").includes(".moltnet"),
+		denySymlinkBypass: true,
+		writeMode: "deny"
+	});
 	const forwardedEnv = {};
 	for (const name of config.forwardEnv ?? []) {
 		const value = process.env[name];
@@ -4777,44 +4884,47 @@ async function resumeVm(config) {
 			if (lastErr) throw lastErr instanceof Error ? lastErr : new Error(nonErrorMessage(lastErr));
 		}
 		const vmSshDir = `${vmAgentDir}/ssh`;
-		await vm.exec(`mkdir -p ${vmAgentDir}/ssh /home/agent/.pi/agent`, { signal: config.signal });
+		const hasAgentFiles = guestCredentialMode === "guest-config";
+		await vm.exec(hasAgentFiles ? `mkdir -p ${vmAgentDir}/ssh /home/agent/.pi/agent` : "mkdir -p /home/agent/.pi/agent", { signal: config.signal });
 		if (creds.piAuthJson !== null) await vm.fs.writeFile("/home/agent/.pi/agent/auth.json", creds.piAuthJson, {
 			mode: 384,
 			signal: config.signal
 		});
-		const vmMoltnetJson = rewriteMoltnetJsonPaths(creds.moltnetJson, vmAgentDir, vmSshDir, creds.githubAppPemFilename);
-		await vm.fs.writeFile(`${vmAgentDir}/moltnet.json`, vmMoltnetJson, {
-			mode: 384,
-			signal: config.signal
-		});
-		await vm.fs.writeFile(`${vmAgentDir}/env`, creds.agentEnvRaw, {
-			mode: 384,
-			signal: config.signal
-		});
-		if (creds.gitconfig) {
-			const vmGitconfig = rewriteGitconfigPaths(creds.gitconfig, vmSshDir, vmAgentDir);
-			await vm.fs.writeFile(`${vmAgentDir}/gitconfig`, vmGitconfig, {
+		if (hasAgentFiles) {
+			const vmMoltnetJson = rewriteMoltnetJsonPaths(creds.moltnetJson, vmAgentDir, vmSshDir, creds.githubAppPemFilename);
+			await vm.fs.writeFile(`${vmAgentDir}/moltnet.json`, vmMoltnetJson, {
+				mode: 384,
+				signal: config.signal
+			});
+			await vm.fs.writeFile(`${vmAgentDir}/env`, creds.agentEnvRaw, {
+				mode: 384,
+				signal: config.signal
+			});
+			if (creds.gitconfig) {
+				const vmGitconfig = rewriteGitconfigPaths(creds.gitconfig, vmSshDir, vmAgentDir);
+				await vm.fs.writeFile(`${vmAgentDir}/gitconfig`, vmGitconfig, {
+					mode: 420,
+					signal: config.signal
+				});
+			}
+			if (creds.sshPrivateKey) await vm.fs.writeFile(`${vmSshDir}/id_ed25519`, creds.sshPrivateKey, {
+				mode: 384,
+				signal: config.signal
+			});
+			if (creds.sshPublicKey) await vm.fs.writeFile(`${vmSshDir}/id_ed25519.pub`, creds.sshPublicKey, {
 				mode: 420,
 				signal: config.signal
 			});
+			if (creds.allowedSigners) await vm.fs.writeFile(`${vmSshDir}/allowed_signers`, creds.allowedSigners, {
+				mode: 420,
+				signal: config.signal
+			});
+			if (creds.githubAppPem && creds.githubAppPemFilename) await vm.fs.writeFile(`${vmAgentDir}/${creds.githubAppPemFilename}`, creds.githubAppPem, {
+				mode: 384,
+				signal: config.signal
+			});
 		}
-		if (creds.sshPrivateKey) await vm.fs.writeFile(`${vmSshDir}/id_ed25519`, creds.sshPrivateKey, {
-			mode: 384,
-			signal: config.signal
-		});
-		if (creds.sshPublicKey) await vm.fs.writeFile(`${vmSshDir}/id_ed25519.pub`, creds.sshPublicKey, {
-			mode: 420,
-			signal: config.signal
-		});
-		if (creds.allowedSigners) await vm.fs.writeFile(`${vmSshDir}/allowed_signers`, creds.allowedSigners, {
-			mode: 420,
-			signal: config.signal
-		});
-		if (creds.githubAppPem && creds.githubAppPemFilename) await vm.fs.writeFile(`${vmAgentDir}/${creds.githubAppPemFilename}`, creds.githubAppPem, {
-			mode: 384,
-			signal: config.signal
-		});
-		await vm.exec("chown -R agent:agent /home/agent/.pi /home/agent/.moltnet", { signal: config.signal });
+		await vm.exec(hasAgentFiles ? "chown -R agent:agent /home/agent/.pi /home/agent/.moltnet" : "chown -R agent:agent /home/agent/.pi", { signal: config.signal });
 		return {
 			vm,
 			credentials: creds,
@@ -5314,16 +5424,25 @@ function createGondolinBashOps(vm, localCwd, guestWorkspace) {
 * capability-aware allow-set) is tracked as future work.
 */
 function decideToolCall(input) {
-	if (input.enforcement === "off") return { allow: true };
-	if (input.toolName.startsWith("submit_") || input.toolName === "subagent") return { allow: true };
+	if (input.enforcement === "off") return {
+		allow: true,
+		reasonCode: "policy_off"
+	};
+	if (input.toolName.startsWith("submit_") || input.toolName === "subagent") return {
+		allow: true,
+		reasonCode: "executor_protocol_tool"
+	};
 	const resolved = resolveNames(input);
-	if (resolved.kind === "unresolvable") return fenced(input.enforcement, "shell command could not be statically authorized", "unresolvable shell command (watch)");
+	if (resolved.kind === "unresolvable") return fenced(input.enforcement, "shell_command_unresolvable", "shell command could not be statically authorized", "unresolvable shell command (watch)");
 	const arbitraryCode = [...new Set(resolved.tools.filter((tool) => tool.risk === "arbitrary-code").map((tool) => tool.name))];
-	if (arbitraryCode.length > 0) return fenced(input.enforcement, `arbitrary-code interpreter not authorizable by tool policy: ${arbitraryCode.join(", ")}`, `would block — arbitrary-code interpreter (watch): ${arbitraryCode.join(", ")}`, arbitraryCode);
+	if (arbitraryCode.length > 0) return fenced(input.enforcement, "arbitrary_code_interpreter", `arbitrary-code interpreter not authorizable by tool policy: ${arbitraryCode.join(", ")}`, `would block — arbitrary-code interpreter (watch): ${arbitraryCode.join(", ")}`, arbitraryCode);
 	if (input.toolName !== "bash") {
 		const missing = resolved.tools.map((tool) => tool.name).filter((name) => !input.allowedTools.has(name));
-		if (missing.length === 0) return { allow: true };
-		return fenced(input.enforcement, `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing);
+		if (missing.length === 0) return {
+			allow: true,
+			reasonCode: "policy_allowed"
+		};
+		return fenced(input.enforcement, "tool_not_permitted", `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing);
 	}
 	const matchedShellCommands = [];
 	const missingShellCommands = resolved.tools.filter((tool) => {
@@ -5333,7 +5452,7 @@ function decideToolCall(input) {
 		matchedShellCommands.push(toMatchedShellCommand(tool.name, matched.argvPrefix));
 		return false;
 	}).map(toMissingShellCommand);
-	if (missingShellCommands.length === 0 && resolved.hasOutputRedirection && matchedShellCommands.length > 0) return fenced(input.enforcement, "shell output redirection requires broad executable permission", "would block shell output redirection under scoped command policy", [...new Set(matchedShellCommands.map(({ executable }) => executable))], matchedShellCommands.map(({ executable, argvPrefixFingerprint, argvPrefixLength }) => ({
+	if (missingShellCommands.length === 0 && resolved.hasOutputRedirection && matchedShellCommands.length > 0) return fenced(input.enforcement, "shell_output_redirection_requires_broad_permission", "shell output redirection requires broad executable permission", "would block shell output redirection under scoped command policy", [...new Set(matchedShellCommands.map(({ executable }) => executable))], matchedShellCommands.map(({ executable, argvPrefixFingerprint, argvPrefixLength }) => ({
 		executable,
 		argvFingerprint: argvPrefixFingerprint,
 		argvLength: argvPrefixLength,
@@ -5341,10 +5460,14 @@ function decideToolCall(input) {
 	})));
 	if (missingShellCommands.length === 0) return matchedShellCommands.length > 0 ? {
 		allow: true,
+		reasonCode: "shell_command_prefix_allowed",
 		matchedShellCommands
-	} : { allow: true };
+	} : {
+		allow: true,
+		reasonCode: "policy_allowed"
+	};
 	const missing = [...new Set(missingShellCommands.map(({ executable }) => executable))];
-	return fenced(input.enforcement, `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing, missingShellCommands);
+	return fenced(input.enforcement, "tool_not_permitted", `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing, missingShellCommands);
 }
 function fingerprintArgv(argv) {
 	return `sha256:${createHash$1("sha256").update(JSON.stringify(argv.map((token) => token === null ? { dynamic: true } : token))).digest("hex").slice(0, 16)}`;
@@ -5371,14 +5494,16 @@ function matchesArgvPrefix(argv, prefix) {
 * Shared enforce/watch branch: block in `enforce`, audit-and-allow in `watch`.
 * `enforcement` is never `off` here (short-circuited by the caller).
 */
-function fenced(enforcement, blockReason, auditReason, missing, missingShellCommands) {
+function fenced(enforcement, reasonCode, blockReason, auditReason, missing, missingShellCommands) {
 	if (enforcement === "enforce") return {
 		allow: false,
+		reasonCode,
 		reason: blockReason,
 		...missing ? { missing } : {},
 		...missingShellCommands?.length ? { missingShellCommands } : {}
 	};
 	return {
+		reasonCode,
 		audit: auditReason,
 		...missing ? { missing } : {},
 		...missingShellCommands?.length ? { missingShellCommands } : {}
@@ -5421,8 +5546,9 @@ function resolveNames(input) {
 /**
 * Resolve the session's tool policy at start-up.
 *
-* `off` short-circuits without a network call. Otherwise the allowed-tool set
-* is fetched from the API. If that fetch fails, the mode decides the fallback:
+* The latest allowed-tool set and enforcement mode are fetched from the API,
+* including when the daemon's cached profile says `off`. If that fetch fails,
+* the cached mode decides the fallback:
 * `enforce` **fails closed** (empty allow-set → every non-`off` tool is
 * blocked); `watch` fails open (empty allow-set → every tool is audited but
 * allowed).
@@ -5433,12 +5559,6 @@ function resolveNames(input) {
 * session, stable enforcement for the run) accepted over re-fetching per call.
 */
 async function resolveSessionToolPolicy(input) {
-	if (input.enforcement === "off") return {
-		enforcement: "off",
-		allowedTools: /* @__PURE__ */ new Set(),
-		allowedShellCommands: [],
-		degraded: false
-	};
 	const timeoutMs = input.timeoutMs ?? 5e3;
 	try {
 		const resolved = await withTimeout$1(input.agent.runtimeProfiles.allowedTools(input.profileId, { teamId: input.teamId }), timeoutMs);
@@ -5454,6 +5574,8 @@ async function resolveSessionToolPolicy(input) {
 				if (rule.argvPrefix.length < 2 || rule.argvPrefix.length > 8 || rule.argvPrefix.some((token) => !token)) throw new Error("runtime returned an invalid shell command rule");
 				return { argvPrefix: rule.argvPrefix };
 			}),
+			executionPolicySnapshotHash: resolved.policySnapshotHash,
+			executionRuntimeProfileRevision: resolved.runtimeProfileRevision,
 			degraded: false
 		};
 	} catch (err) {
@@ -5526,34 +5648,46 @@ function decideForEvent(event, policy, analyze) {
 * `off`. Register it in a session's `extensionFactories`.
 */
 function createToolPolicyExtension(deps) {
+	if (deps.context?.claimPolicySnapshotHash && deps.policy.executionPolicySnapshotHash && deps.context.claimPolicySnapshotHash !== deps.policy.executionPolicySnapshotHash) deps.logger.info({
+		...decisionContext(deps),
+		decision: "continue",
+		reason: "claim_execution_policy_drift"
+	}, "tool_policy.snapshot_drift");
 	return (pi) => {
 		if (deps.policy.enforcement === "off") return;
 		pi.on("tool_call", (event) => {
 			const decision = decideForEvent(event, deps.policy, (command) => deps.analyzer.analyze(command));
 			if ("allow" in decision && decision.allow) {
-				if (decision.matchedShellCommands?.length) deps.logger.debug({
+				deps.logger.info({
+					...decisionContext(deps),
 					toolName: event.toolName,
 					toolCallId: event.toolCallId,
-					matchedShellCommands: decision.matchedShellCommands
-				}, "tool_policy.shell_command_allowed");
+					decision: "allowed",
+					reason: decision.reasonCode,
+					...decision.matchedShellCommands?.length ? { shellFingerprints: decision.matchedShellCommands } : {}
+				}, "tool_policy.allowed");
 				return;
 			}
 			if ("audit" in decision) {
 				deps.logger.info({
+					...decisionContext(deps),
 					toolName: event.toolName,
 					toolCallId: event.toolCallId,
-					degraded: deps.policy.degraded,
-					decision
+					decision: "audit",
+					reason: decision.reasonCode,
+					...decision.missing?.length ? { missingExecutables: decision.missing } : {},
+					...decision.missingShellCommands?.length ? { shellFingerprints: decision.missingShellCommands } : {}
 				}, "tool_policy.audit");
 				return;
 			}
 			deps.logger.warn({
+				...decisionContext(deps),
 				toolName: event.toolName,
 				toolCallId: event.toolCallId,
-				degraded: deps.policy.degraded,
-				reason: decision.reason,
-				missingExecutables: decision.missing,
-				missingShellCommands: decision.missingShellCommands
+				decision: "blocked",
+				reason: decision.reasonCode,
+				...decision.missing?.length ? { missingExecutables: decision.missing } : {},
+				...decision.missingShellCommands?.length ? { shellFingerprints: decision.missingShellCommands } : {}
 			}, "tool_policy.blocked");
 			return {
 				block: true,
@@ -5562,6 +5696,15 @@ function createToolPolicyExtension(deps) {
 		});
 	};
 }
+function decisionContext(deps) {
+	return {
+		...deps.context ?? {},
+		enforcement: deps.policy.enforcement,
+		degraded: deps.policy.degraded,
+		executionPolicySnapshotHash: deps.policy.executionPolicySnapshotHash,
+		executionRuntimeProfileRevision: deps.policy.executionRuntimeProfileRevision
+	};
+}
 //#endregion
 //#region src/runtime/capability-discovery.ts
 var GuestExecutableProbeError = class extends Error {
@@ -7104,6 +7247,19 @@ var GONDOLIN_TOOL_NAMES = [
 	"find",
 	"grep"
 ];
+var HOST_AUTHENTICATED_HOST_EXEC_REFUSED_ENV = new Set([
+	"GIT_CONFIG_GLOBAL",
+	"MOLTNET_CREDENTIALS_PATH",
+	"SSH_AUTH_SOCK"
+]);
+function resolveHostExecBaseEnv(guestCredentialMode, agentEnv) {
+	const names = new Set([...HOST_EXEC_DEFAULT_BASE_ENV, ...Object.keys(agentEnv)]);
+	if (guestCredentialMode === "host-authenticated") {
+		for (const name of HOST_AUTHENTICATED_HOST_EXEC_REFUSED_ENV) names.delete(name);
+		for (const name of names) if (name.startsWith("MOLTNET_")) names.delete(name);
+	}
+	return names;
+}
 var noopTurnEventHandler = () => {};
 async function openVmWorkspaceFileForRead(config) {
 	const localPath = isAbsolute(config.filePath) ? config.filePath : resolve(config.cwdPath, config.filePath);
@@ -7135,6 +7291,16 @@ function createGondolinToolDefinitions(config) {
 		}
 	];
 }
+function createMoltNetAgentResolver(input) {
+	let resolved;
+	return () => {
+		if (!resolved) resolved = (input.moltnetAgent ? Promise.resolve(input.moltnetAgent) : (input.connectAgent ?? ((configDir) => connect({ configDir })))(input.configDir)).catch((error) => {
+			resolved = void 0;
+			throw error;
+		});
+		return resolved;
+	};
+}
 /**
 * Factory that builds a pi-specific `executeTask` function suitable for
 * injection into `AgentRuntime`. The returned function caches the resolved
@@ -7318,11 +7484,13 @@ async function executePiTask(claimedTask, reporter, opts) {
 				checkpointPath,
 				agentName: opts.agentName,
 				agentRootDir,
+				guestCredentialMode: opts.guestCredentialMode,
 				mountPath,
 				workspaceMode: preparedWorkspace.mode,
 				extraAllowedHosts: opts.extraAllowedHosts,
 				sandboxConfig: effectiveSandboxConfig,
 				forwardEnv: opts.forwardEnv,
+				onDiagnostic: opts.onVmDiagnostic,
 				signal: reporter.cancelSignal
 			}));
 		} catch (err) {
@@ -7339,6 +7507,10 @@ async function executePiTask(claimedTask, reporter, opts) {
 		activateAgentEnv(managed.credentials.agentEnv, agentRootDir);
 		const activeWorkspace = preparedWorkspace;
 		const activeManaged = managed;
+		const getMoltNetAgent = createMoltNetAgentResolver({
+			moltnetAgent: opts.moltnetAgent,
+			configDir: managed.agentDir
+		});
 		await emit("info", {
 			event: "execute_start",
 			correlationId: task.correlationId ?? null,
@@ -7353,7 +7525,7 @@ async function executePiTask(claimedTask, reporter, opts) {
 		let resolvedPriorContext;
 		const continueFrom = task.input?.continueFrom;
 		if (task.taskType === FREEFORM_TYPE && continueFrom) try {
-			const resolved = await resolvePriorContext(await connect({ configDir: managed.agentDir }), continueFrom);
+			const resolved = await resolvePriorContext(await getMoltNetAgent(), continueFrom);
 			if (resolved) {
 				resolvedPriorContext = resolved;
 				await emit("info", {
@@ -7468,7 +7640,7 @@ async function executePiTask(claimedTask, reporter, opts) {
 		});
 		const submitTools = submitToolDefs;
 		try {
-			const moltnetAgent = await connect({ configDir: managed.agentDir });
+			const moltnetAgent = await getMoltNetAgent();
 			const moltnetTools = createMoltNetTools({
 				getAgent: () => moltnetAgent,
 				getDiaryId: () => diaryId,
@@ -7482,7 +7654,7 @@ async function executePiTask(claimedTask, reporter, opts) {
 					guestWorkspace: activeManaged.guestWorkspace,
 					filePath
 				}),
-				hostExecBaseEnv: new Set([...HOST_EXEC_DEFAULT_BASE_ENV, ...Object.keys(managed.credentials.agentEnv)]),
+				hostExecBaseEnv: resolveHostExecBaseEnv(opts.guestCredentialMode ?? "guest-config", managed.credentials.agentEnv),
 				hostExecAutoApprove: opts.hostExecAutoApprove ?? opts.sandboxConfig?.hostExec?.autoApprove ?? false,
 				getTaskContext: () => ({
 					taskId: task.id,
@@ -7512,28 +7684,34 @@ async function executePiTask(claimedTask, reporter, opts) {
 					...obj
 				}))
 			};
-			if (opts.runtimeProfileId && opts.toolEnforcement && opts.toolEnforcement !== "off") {
-				const [analyzer, policy] = await Promise.all([ShellCommandAnalyzer.create(), resolveSessionToolPolicy({
+			const toolPolicyDecisionContext = buildToolPolicyDecisionContext(claimedTask, opts.runtimeProfileId);
+			if (opts.runtimeProfileId && opts.toolEnforcement) {
+				const policy = await resolveSessionToolPolicy({
 					agent: moltnetAgent,
 					profileId: opts.runtimeProfileId,
 					teamId: taskTeamId,
 					runtimeKind: opts.runtimeDefinition?.runtimeKind ?? "gondolin_pi",
 					enforcement: opts.toolEnforcement,
 					logger: toolPolicyLogger
-				})]);
-				verifiedGuestExecutables = (await discoverGuestExecutables(managed.vm, [...policy.allowedShellCommands.map(({ argvPrefix }) => argvPrefix[0]), ...policy.enforcement === "watch" ? resolvedVmTemplate?.executables ?? [] : []], { signal: reporter.cancelSignal })).available;
-				const availableExecutables = new Set(verifiedGuestExecutables);
-				const allowedShellCommands = policy.allowedShellCommands.filter(({ argvPrefix }) => availableExecutables.has(argvPrefix[0]));
-				unavailableRuntimeShellCommands = policy.allowedShellCommands.filter(({ argvPrefix }) => !availableExecutables.has(argvPrefix[0]));
-				resolvedToolPolicy = {
-					...policy,
-					allowedShellCommands
-				};
-				toolPolicyExtensions.push(createToolPolicyExtension({
-					policy: resolvedToolPolicy,
-					analyzer,
-					logger: toolPolicyLogger
-				}));
+				});
+				resolvedToolPolicy = policy;
+				if (policy.enforcement !== "off") {
+					const analyzer = await ShellCommandAnalyzer.create();
+					verifiedGuestExecutables = (await discoverGuestExecutables(managed.vm, [...policy.allowedShellCommands.map(({ argvPrefix }) => argvPrefix[0]), ...policy.enforcement === "watch" ? resolvedVmTemplate?.executables ?? [] : []], { signal: reporter.cancelSignal })).available;
+					const availableExecutables = new Set(verifiedGuestExecutables);
+					const allowedShellCommands = policy.allowedShellCommands.filter(({ argvPrefix }) => availableExecutables.has(argvPrefix[0]));
+					unavailableRuntimeShellCommands = policy.allowedShellCommands.filter(({ argvPrefix }) => !availableExecutables.has(argvPrefix[0]));
+					resolvedToolPolicy = {
+						...policy,
+						allowedShellCommands
+					};
+					toolPolicyExtensions.push(createToolPolicyExtension({
+						policy: resolvedToolPolicy,
+						analyzer,
+						logger: toolPolicyLogger,
+						context: toolPolicyDecisionContext
+					}));
+				}
 			}
 			const runtimeToolContext = {
 				agent: moltnetAgent,
@@ -7913,6 +8091,29 @@ async function executePiTask(claimedTask, reporter, opts) {
 		});
 	}
 }
+function buildToolPolicyDecisionContext(claimedTask, executionRuntimeProfileId) {
+	const { task, attemptN, claimAuthority } = claimedTask;
+	const proposer = task.proposedByAgentId ? {
+		proposerKind: "agent",
+		proposerId: task.proposedByAgentId
+	} : task.proposedByHumanId ? {
+		proposerKind: "human",
+		proposerId: task.proposedByHumanId
+	} : {};
+	return {
+		taskId: task.id,
+		attemptN,
+		teamId: task.teamId,
+		...proposer,
+		...claimAuthority?.claimantAgentId ? { claimantAgentId: claimAuthority.claimantAgentId } : {},
+		...claimAuthority?.leaseId ? { leaseId: claimAuthority.leaseId } : {},
+		...claimAuthority?.runtimeProfileId ? { claimRuntimeProfileId: claimAuthority.runtimeProfileId } : {},
+		...executionRuntimeProfileId ? { executionRuntimeProfileId } : {},
+		...typeof claimAuthority?.runtimeProfileRevision === "number" ? { claimRuntimeProfileRevision: claimAuthority.runtimeProfileRevision } : {},
+		...claimAuthority?.policySnapshotHash ? { claimPolicySnapshotHash: claimAuthority.policySnapshotHash } : {},
+		...claimAuthority?.executorFingerprint ? { claimedExecutorFingerprint: claimAuthority.executorFingerprint } : {}
+	};
+}
 function createSessionTurnState() {
 	return {
 		assistantText: "",
@@ -8564,4 +8765,4 @@ function describeToolErrorMessage(result) {
 	}
 }
 //#endregion
-export { GONDOLIN_BASE_EXECUTABLES, GONDOLIN_TOOL_NAMES, HOST_EXEC_DEFAULT_BASE_ENV, MOLTNET_TOOL_NAMES, PI_EXECUTOR_MANIFEST_VERSION, PI_RUNTIME_DEFINITION_VERSION, activateAgentEnv, buildAgentSession, buildPiExecutorManifest, buildRuntimeKernel, buildWorkspaceMountInstructions, createGondolinBashOps, createGondolinEditOps, createGondolinFindOps, createGondolinLsOps, createGondolinReadOps, createGondolinToolDefinitions, createGondolinWriteOps, createMoltNetTools, createPiOtelExtension, createPiRetryTriage, createPiTaskExecutor, createSubagentTool, createToolPolicyExtension, decideForEvent, decideToolCall, defineGondolinTemplate, definePiExtension, definePiRuntime, definePiTool, enabledPiToolNames, ensureSnapshot, executeGondolinGrep, executePiTask, filterModelVisibleTools, findMainWorktree, injectRuntimeContext as injectTaskContext, isKernelTool, isResolvedPathInsideRoot, isToolVisible, loadCredentials, materializePiExtensions, materializePiTools, normalizeRetryTriageResult, redactRetryTriageSecrets, resolveSessionToolPolicy, resolveTaskWorktreePath, resumeVm, toGuestPath };
+export { GONDOLIN_BASE_EXECUTABLES, GONDOLIN_TOOL_NAMES, GuestEnvironmentBoundaryError, HOST_EXEC_DEFAULT_BASE_ENV, MOLTNET_TOOL_NAMES, PI_EXECUTOR_MANIFEST_VERSION, PI_RUNTIME_DEFINITION_VERSION, activateAgentEnv, assertGuestEnvironmentBoundary, assertHostAuthenticatedGuestEnvironment, buildAgentSession, buildPiExecutorManifest, buildRuntimeKernel, buildWorkspaceMountInstructions, createGondolinBashOps, createGondolinEditOps, createGondolinFindOps, createGondolinLsOps, createGondolinReadOps, createGondolinToolDefinitions, createGondolinWriteOps, createMoltNetTools, createPiOtelExtension, createPiRetryTriage, createPiTaskExecutor, createSubagentTool, createToolPolicyExtension, decideForEvent, decideToolCall, defineGondolinTemplate, definePiExtension, definePiRuntime, definePiTool, enabledPiToolNames, ensureSnapshot, executeGondolinGrep, executePiTask, filterModelVisibleTools, findMainWorktree, injectRuntimeContext as injectTaskContext, isKernelTool, isResolvedPathInsideRoot, isToolVisible, loadCredentials, materializePiExtensions, materializePiTools, normalizeRetryTriageResult, redactRetryTriageSecrets, resolveHostExecBaseEnv, resolveSessionToolPolicy, resolveTaskWorktreePath, resumeVm, toGuestPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/pi-runtime",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "license": "MIT",
   "type": "module",
   "description": "Composable MoltNet runtime kernel for Pi agents in Gondolin VMs",
@@ -31,10 +31,10 @@
     "@opentelemetry/api": "^1.9.0",
     "multiformats": "^13.3.0",
     "typebox": "^1.2.8",
-    "@themoltnet/agent-runtime": "0.41.2",
-    "@themoltnet/sdk": "0.131.0",
-    "@themoltnet/shell-command-analyzer": "0.3.0",
-    "@themoltnet/os-keyring": "0.2.0"
+    "@themoltnet/agent-runtime": "0.42.0",
+    "@themoltnet/os-keyring": "0.2.0",
+    "@themoltnet/sdk": "0.133.0",
+    "@themoltnet/shell-command-analyzer": "0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.79.4",
@@ -51,9 +51,9 @@
     "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.0.0",
-    "@moltnet/crypto-service": "0.1.0",
     "@moltnet/models": "0.1.0",
-    "@moltnet/tasks": "0.1.0"
+    "@moltnet/tasks": "0.1.0",
+    "@moltnet/crypto-service": "0.1.0"
   },
   "engines": {
     "node": ">=24"