@gajae-code/coding-agent 0.3.0 → 0.3.1

package/src/harness-control-plane/control-endpoint.ts

@@ -88,13 +88,16 @@ export class ControlServer {
 }
 
 export class EndpointUnreachableError extends Error {
-	constructor(readonly socketPath: string) {
-		super(`endpoint_unreachable:${socketPath}`);
+	constructor(
+		readonly socketPath: string,
+		readonly reason = "unreachable",
+	) {
+		super(`endpoint_${reason}:${socketPath}`);
 		this.name = "EndpointUnreachableError";
 	}
 }
 
-/** Call the owner's control endpoint. Rejects with {@link EndpointUnreachableError} when no owner listens. */
+/** Call the owner's control endpoint. Rejects with {@link EndpointUnreachableError} when no owner listens or responds. */
 export function callEndpoint(socketPath: string, req: EndpointRequest, timeoutMs = 5_000): Promise<unknown> {
 	return new Promise((resolve, reject) => {
 		const socket = net.connect(socketPath);
@@ -107,7 +110,10 @@ export function callEndpoint(socketPath: string, req: EndpointRequest, timeoutMs
 			socket.destroy();
 			fn();
 		};
-		const timer = setTimeout(() => done(() => reject(new Error(`endpoint_timeout:${socketPath}`))), timeoutMs);
+		const timer = setTimeout(
+			() => done(() => reject(new EndpointUnreachableError(socketPath, "timeout"))),
+			timeoutMs,
+		);
 		socket.setEncoding("utf8");
 		socket.on("connect", () => socket.write(frame(req)));
 		socket.on("data", (chunk: string) => {
@@ -118,16 +124,21 @@ export function callEndpoint(socketPath: string, req: EndpointRequest, timeoutMs
 				done(() => {
 					try {
 						resolve(JSON.parse(line));
-					} catch (error) {
-						reject(error instanceof Error ? error : new Error(String(error)));
+					} catch {
+						reject(new EndpointUnreachableError(socketPath, "bad_frame"));
 					}
 				});
 			}
 		});
 		socket.on("error", (error: NodeJS.ErrnoException) => {
 			done(() => {
-				if (error.code === "ENOENT" || error.code === "ECONNREFUSED") {
-					reject(new EndpointUnreachableError(socketPath));
+				if (
+					error.code === "ENOENT" ||
+					error.code === "ECONNREFUSED" ||
+					error.code === "ECONNRESET" ||
+					error.code === "EPIPE"
+				) {
+					reject(new EndpointUnreachableError(socketPath, error.code.toLowerCase()));
 				} else {
 					reject(error);
 				}

package/src/harness-control-plane/owner.ts

@@ -52,6 +52,31 @@ import {
 import type { EventEnvelope, GitDelta, Observation, PrimitiveResponse, SessionState, Severity } from "./types";
 import { DEFAULT_RETRY_BUDGET, OBSERVED_SIGNALS } from "./types";
 
+function isStartupLivenessBlocker(blocker: string): boolean {
+	return blocker === "detached-owner-not-live";
+}
+
+function isOwnerVanishedBlocker(blocker: string): boolean {
+	return blocker.startsWith("owner-vanished:");
+}
+
+function reconcileLiveOwnerState(state: SessionState): { state: SessionState; reconciled: boolean } {
+	const blockers = state.blockers.filter(blocker => !isStartupLivenessBlocker(blocker));
+	const hadLivenessBlocker = blockers.length !== state.blockers.length;
+	const lifecycle =
+		hadLivenessBlocker && state.lifecycle === "blocked" && blockers.length === 0 ? "observing" : state.lifecycle;
+	if (!hadLivenessBlocker && lifecycle === state.lifecycle) return { state, reconciled: false };
+	return {
+		state: {
+			...state,
+			lifecycle,
+			blockers,
+			updatedAt: new Date().toISOString(),
+		},
+		reconciled: true,
+	};
+}
+
 export interface OwnerOptions {
 	root: string;
 	sessionId: string;
@@ -139,6 +164,11 @@ export class RuntimeOwner {
 	async #loadState(): Promise<SessionState> {
 		const state = await readSessionState(this.#opts.root, this.#opts.sessionId);
 		if (!state) throw new Error(`session_not_found:${this.#opts.sessionId}`);
+		const reconciled = reconcileLiveOwnerState(state);
+		if (reconciled.reconciled) {
+			await writeSessionState(this.#opts.root, reconciled.state);
+			return reconciled.state;
+		}
 		return state;
 	}
 
@@ -369,17 +399,22 @@ export class RuntimeOwner {
 
 	async #recover(): Promise<PrimitiveResponse> {
 		const obs = await this.#observeGit();
-		const decision = classifyRecovery({ observation: obs, retryBudget: { ...DEFAULT_RETRY_BUDGET } });
+		const state = await this.#loadState();
+		const recoveringPriorVanish = state.blockers.some(isOwnerVanishedBlocker);
+		const recoveryObservation: Observation = recoveringPriorVanish
+			? { ...obs, ownerLive: false, risk: obs.gitDelta === "dirty" ? "vanished-dirty" : obs.risk }
+			: obs;
+		const decision = classifyRecovery({ observation: recoveryObservation, retryBudget: { ...DEFAULT_RETRY_BUDGET } });
 		let vanishReceiptId: string | null = null;
 		if (requiresVanishBeforeAction(decision.classification)) {
-			const dirty = obs.gitDelta === "dirty" || obs.gitDelta === "unknown";
-			const p = dirty ? preserveDirtyWorktree(obs.cwd) : null;
+			const dirty = recoveryObservation.gitDelta === "dirty" || recoveryObservation.gitDelta === "unknown";
+			const p = dirty ? preserveDirtyWorktree(recoveryObservation.cwd) : null;
 			const evidence: VanishEvidence = {
 				classification: decision.classification,
-				gitDelta: obs.gitDelta,
+				gitDelta: recoveryObservation.gitDelta,
 				gitStatusPorcelain: p
 					? `tracked:${p.trackedDiffSha256};untracked:${p.untrackedManifest.length}`
-					: obs.observedSignals.join(","),
+					: recoveryObservation.observedSignals.join(","),
 				untrackedManifest: p?.untrackedManifest ?? [],
 				preservation: p?.stashRef ? "stash" : "snapshot",
 				stashRef: p?.stashRef ?? null,
@@ -391,15 +426,25 @@ export class RuntimeOwner {
 				sessionId: this.#opts.sessionId,
 				family: "vanish",
 				source: "owner",
-				subject: { workspace: obs.cwd, branch: obs.branch, head: null, commit: null },
+				subject: {
+					workspace: recoveryObservation.cwd,
+					branch: recoveryObservation.branch,
+					head: null,
+					commit: null,
+				},
 				evidence,
 			});
 			await writeReceiptImmutable(this.#opts.root, this.#opts.sessionId, "vanish", receipt.receiptId, receipt);
 			vanishReceiptId = receipt.receiptId;
 		}
-		const state = await this.#loadState();
+		if (vanishReceiptId) {
+			state.blockers = state.blockers.filter(blocker => !isOwnerVanishedBlocker(blocker));
+			state.lifecycle = state.blockers.length === 0 ? "observing" : state.lifecycle;
+			state.updatedAt = new Date(this.#opts.clock ? this.#opts.clock() : Date.now()).toISOString();
+			await writeSessionState(this.#opts.root, state);
+		}
 		await this.#emit(decision.severity, "recover_classified", { classification: decision.classification });
-		return this.#response(state, { decision, observation: obs, vanishReceiptId });
+		return this.#response(state, { decision, observation: recoveryObservation, vanishReceiptId });
 	}
 
 	async #operate(input: Record<string, unknown>): Promise<PrimitiveResponse> {
@@ -475,12 +520,14 @@ export class RuntimeOwner {
 
 	async #submit(input: Record<string, unknown>): Promise<PrimitiveResponse> {
 		const prompt = typeof input.prompt === "string" ? input.prompt : "";
+		const state = await this.#loadState();
 		if (!prompt) {
-			const state = await this.#loadState();
 			return this.#response(state, { accepted: false, reason: "empty-prompt" }, false);
 		}
+		if (state.lifecycle === "blocked") {
+			return this.#response(state, { accepted: false, reason: "lifecycle-blocked" }, false);
+		}
 		const result = await singleFlightAccept(this.#opts.rpc, prompt, this.#opts.acceptanceTimeoutMs);
-		const state = await this.#loadState();
 		if (result.accepted) {
 			state.lifecycle = "observing";
 			state.updatedAt = new Date(this.#opts.clock ? this.#opts.clock() : Date.now()).toISOString();

package/src/harness-control-plane/state-machine.ts

@@ -57,8 +57,9 @@ export function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boole
 	// `start` creates a new session; never re-applicable to an existing record.
 	add("start", false, "session-already-exists");
 
-	// `submit` is owner-routed: it requires a live owner and a non-terminal lifecycle.
+	// `submit` is owner-routed: it requires a live owner and a non-blocked, non-terminal lifecycle.
 	if (terminal) add("submit", false, `lifecycle-terminal:${lifecycle}`);
+	else if (lifecycle === "blocked") add("submit", false, "lifecycle-blocked");
 	else if (!ownerLive) add("submit", false, "owner-not-live");
 	else add("submit", true);
 

package/src/hooks/skill-state.ts

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
-import { writeJsonAtomic } from "../gjc-runtime/state-writer";
+import { ModeStateSchema, SkillActiveStateSchema } from "../gjc-runtime/state-schema";
+import { writeJsonAtomic, writeWorkflowEnvelopeAtomic } from "../gjc-runtime/state-writer";
 import { isUltragoalBypassPrompt, readUltragoalVerificationState } from "../gjc-runtime/ultragoal-guard";
 import { buildSessionContext, loadEntriesFromFile, type SessionEntry } from "../session/session-manager";
 import {
@@ -8,6 +9,7 @@ import {
 	type SkillActiveEntry,
 	type SkillActiveState,
 } from "../skill-state/active-state";
+import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
 import {
 	compareSkillKeywordMatches,
 	GJC_SKILL_KEYWORD_DEFINITIONS,
@@ -218,14 +220,36 @@ function skillStatePath(stateDir: string, sessionId?: string): string {
 	return path.join(stateDir, SKILL_ACTIVE_STATE_FILE);
 }
 
-async function readJsonFile<T>(filePath: string): Promise<T | null> {
+function warnInvalidState(kind: string, filePath: string, error: string): void {
+	console.warn(`gjc skill-state: invalid ${kind} at ${filePath}: ${error}`);
+}
+
+async function readValidatedJsonFile<T>(
+	filePath: string,
+	kind: string,
+	schema: { safeParse: (value: unknown) => { success: true } | { success: false; error: { message: string } } },
+): Promise<T | null> {
+	let raw: string;
 	try {
-		const raw = await Bun.file(filePath).text();
-		return JSON.parse(raw) as T;
+		raw = await Bun.file(filePath).text();
 	} catch (error) {
 		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return null;
+		warnInvalidState(kind, filePath, `read error: ${(error as Error).message}`);
 		return null;
 	}
+	let value: T;
+	try {
+		value = JSON.parse(raw) as T;
+	} catch (error) {
+		warnInvalidState(kind, filePath, `invalid JSON: ${(error as Error).message}`);
+		return null;
+	}
+	const parsed = schema.safeParse(value);
+	if (!parsed.success) {
+		warnInvalidState(kind, filePath, parsed.error.message);
+		return null;
+	}
+	return value;
 }
 
 async function writeJsonFile(filePath: string, value: unknown, cwd: string): Promise<void> {
@@ -265,22 +289,41 @@ export async function readVisibleSkillActiveState(
 	if (!stateDir) return await readCanonicalVisibleSkillActiveState(cwd, sessionId);
 	const resolvedStateDir = resolveGjcStateDir(cwd, stateDir);
 	if (sessionId) {
-		const sessionState = await readJsonFile<SkillActiveState>(skillStatePath(resolvedStateDir, sessionId));
+		const sessionState = await readValidatedJsonFile<SkillActiveState>(
+			skillStatePath(resolvedStateDir, sessionId),
+			"skill-active-state",
+			SkillActiveStateSchema,
+		);
 		if (sessionState) return sessionState;
 	}
-	return await readJsonFile<SkillActiveState>(skillStatePath(resolvedStateDir));
+	return await readValidatedJsonFile<SkillActiveState>(
+		skillStatePath(resolvedStateDir),
+		"skill-active-state",
+		SkillActiveStateSchema,
+	);
 }
 
-export async function recordSkillActivation(input: RecordSkillActivationInput): Promise<SkillActiveState | null> {
-	const match = detectPrimarySkillKeyword(input.text);
-	if (!match) return null;
+interface SeedSkillActivationStateInput {
+	cwd: string;
+	sessionId?: string;
+	threadId?: string;
+	turnId?: string;
+	nowIso?: string;
+	stateDir?: string;
+}
 
+async function seedSkillActivationState(
+	skill: GjcWorkflowSkill,
+	keyword: string,
+	source: string,
+	input: SeedSkillActivationStateInput,
+): Promise<SkillActiveState> {
 	const resolvedStateDir = resolveGjcStateDir(input.cwd, input.stateDir);
 	const nowIso = input.nowIso ?? new Date().toISOString();
-	const phase = initialPhaseForSkill(match.skill);
-	const initializedStatePath = modeStatePath(resolvedStateDir, match.skill, input.sessionId);
+	const phase = initialPhaseForSkill(skill);
+	const initializedStatePath = modeStatePath(resolvedStateDir, skill, input.sessionId);
 	const entry: SkillActiveEntry = {
-		skill: match.skill,
+		skill,
 		phase,
 		active: true,
 		activated_at: nowIso,
@@ -292,41 +335,102 @@ export async function recordSkillActivation(input: RecordSkillActivationInput):
 	const state: SkillActiveState = {
 		version: 1,
 		active: true,
-		skill: match.skill,
-		keyword: match.keyword,
+		skill,
+		keyword,
 		phase,
 		activated_at: nowIso,
 		updated_at: nowIso,
-		source: "gjc-skill-state-hook",
+		source,
 		...(input.sessionId ? { session_id: input.sessionId } : {}),
 		...(input.threadId ? { thread_id: input.threadId } : {}),
 		...(input.turnId ? { turn_id: input.turnId } : {}),
-		initialized_mode: match.skill,
+		initialized_mode: skill,
 		initialized_state_path: initializedStatePath,
 		active_skills: [entry],
 	};
 	const modeState: ModeState = {
 		active: true,
+		version: WORKFLOW_STATE_VERSION,
 		current_phase: phase,
-		skill: match.skill,
+		skill,
 		cwd: input.cwd,
 		updated_at: nowIso,
 		...(input.sessionId ? { session_id: input.sessionId } : {}),
 		...(input.threadId ? { thread_id: input.threadId } : {}),
 		...(input.turnId ? { turn_id: input.turnId } : {}),
 	};
-	if (match.skill === "deep-interview") {
+	if (skill === "deep-interview") {
 		modeState.threshold = DEFAULT_DEEP_INTERVIEW_AMBIGUITY_THRESHOLD;
 		modeState.threshold_source = "default";
 	}
 
-	await writeJsonFile(initializedStatePath, modeState, input.cwd);
+	await writeWorkflowEnvelopeAtomic(initializedStatePath, modeState, {
+		cwd: input.cwd,
+		receipt: {
+			cwd: input.cwd,
+			skill,
+			owner: "gjc-hook",
+			command: source,
+			sessionId: input.sessionId,
+		},
+		audit: { category: "state", verb: "write", owner: "gjc-hook", skill },
+	});
 	await writeJsonFile(skillStatePath(resolvedStateDir, input.sessionId), state, input.cwd);
-	if (!input.sessionId) return state;
-	await writeJsonFile(skillStatePath(resolvedStateDir), state, input.cwd);
+	if (input.sessionId) {
+		await writeJsonFile(skillStatePath(resolvedStateDir), state, input.cwd);
+	}
 	return state;
 }
 
+export async function recordSkillActivation(input: RecordSkillActivationInput): Promise<SkillActiveState | null> {
+	const match = detectPrimarySkillKeyword(input.text);
+	if (!match) return null;
+	return await seedSkillActivationState(match.skill, match.keyword, "gjc-skill-state-hook", input);
+}
+
+export interface EnsureWorkflowSkillActivationInput {
+	cwd: string;
+	skill: string;
+	sessionId?: string;
+	threadId?: string;
+	turnId?: string;
+	nowIso?: string;
+	stateDir?: string;
+}
+
+/**
+ * Idempotently seed `.gjc/state` for a workflow skill that was invoked directly
+ * (e.g. via `/skill:<name>`) rather than through keyword detection. This ensures
+ * the mutation guard and Stop hook engage the moment a workflow skill becomes
+ * active, instead of relying on the skill prompt to run its own state-init steps.
+ *
+ * The seed is non-destructive: if an active entry for this skill already exists
+ * (for example after a `gjc state handoff` promotion that carries
+ * `handoff_from`/`handoff_at` lineage), nothing is written so lineage is
+ * preserved. Non-workflow skills are ignored.
+ */
+export async function ensureWorkflowSkillActivationState(
+	input: EnsureWorkflowSkillActivationInput,
+): Promise<SkillActiveState | null> {
+	const skill = input.skill.trim();
+	if (!isGjcWorkflowSkill(skill)) return null;
+	const existing = await readVisibleSkillActiveState(input.cwd, input.sessionId, input.stateDir);
+	const alreadyActive = listActiveSkills(existing).some(
+		entry =>
+			entry.skill === skill &&
+			(existing ? entryMatchesContext(entry, existing, input.sessionId, input.threadId) : true),
+	);
+	if (alreadyActive) return existing;
+	return await seedSkillActivationState(skill, `/skill:${skill}`, "gjc-skill-invocation", {
+		cwd: input.cwd,
+		sessionId: input.sessionId,
+		threadId: input.threadId,
+		turnId: input.turnId,
+		nowIso: input.nowIso,
+		stateDir: input.stateDir,
+	});
+}
+
 function isTerminalModeState(state: ModeState | null): boolean {
 	if (state?.active !== true) return true;
 	const phase = String(state.current_phase ?? "")
@@ -335,6 +439,45 @@ function isTerminalModeState(state: ModeState | null): boolean {
 	return ["complete", "completed", "handoff", "failed", "cancelled", "canceled", "inactive"].includes(phase);
 }
 
+/**
+ * Phases that genuinely finish a skill and release the Stop block. Note that
+ * "handoff" is intentionally absent: a skill sitting in the handoff phase has
+ * declared it is ready to chain but has not yet been demoted/cleared, so it
+ * must keep blocking until the chain (or an explicit clear) removes it.
+ */
+const STOP_RELEASING_PHASES = ["complete", "completed", "failed", "cancelled", "canceled", "inactive"] as const;
+
+/**
+ * Handoff workflows must never stop silently — they always have to offer the
+ * user a next step (refine, hand off, or finish) via the ask tool. The Stop
+ * hook keeps blocking these even in the "handoff" phase until they are demoted
+ * (active:false) or cleared.
+ */
+function isHandoffRequiredSkill(skill: GjcWorkflowSkill): boolean {
+	return skill === "deep-interview" || skill === "ralplan";
+}
+
+/**
+ * Decide whether an active-state entry's mode-state releases the Stop block.
+ *
+ * For handoff-required skills a missing or unreadable mode-state does NOT
+ * release the block: those workflows must always end by offering the user a
+ * next step, so the `skill-active-state.json` entry stays authoritative until
+ * the skill is demoted or cleared. For other skills a missing/corrupt
+ * mode-state preserves the historical fail-open behavior so a broken state file
+ * cannot lock a session.
+ */
+function modeStateReleasesStop(state: ModeState | null, handoffRequired: boolean): boolean {
+	if (!state) return !handoffRequired;
+	if (state.active !== true) return true;
+	const phase = String(state.current_phase ?? "")
+		.trim()
+		.toLowerCase();
+	if ((STOP_RELEASING_PHASES as readonly string[]).includes(phase)) return true;
+	if (!handoffRequired && phase === "handoff") return true;
+	return false;
+}
+
 async function readVisibleModeState(
 	cwd: string,
 	skill: GjcWorkflowSkill,
@@ -344,11 +487,11 @@ async function readVisibleModeState(
 	const resolvedStateDir = resolveGjcStateDir(cwd, stateDir);
 	if (sessionId) {
 		const sessionStatePath = modeStatePath(resolvedStateDir, skill, sessionId);
-		const sessionState = await readJsonFile<ModeState>(sessionStatePath);
+		const sessionState = await readValidatedJsonFile<ModeState>(sessionStatePath, "mode-state", ModeStateSchema);
 		if (sessionState) return { state: sessionState, statePath: sessionStatePath };
 	}
 	const rootStatePath = modeStatePath(resolvedStateDir, skill);
-	const rootState = await readJsonFile<ModeState>(rootStatePath);
+	const rootState = await readValidatedJsonFile<ModeState>(rootStatePath, "mode-state", ModeStateSchema);
 	if (!rootState) return null;
 	return { state: rootState, statePath: rootStatePath };
 }
@@ -421,8 +564,13 @@ export async function buildSkillStopOutput(input: StopHookInput): Promise<Record
 	if (!skillState || activeEntries.length === 0) return null;
 
 	for (const entry of activeEntries) {
-		const modeState = await readJsonFile<ModeState>(modeStatePath(resolvedStateDir, entry.skill, input.sessionId));
-		if (isTerminalModeState(modeState)) continue;
+		const modeState = await readValidatedJsonFile<ModeState>(
+			modeStatePath(resolvedStateDir, entry.skill, input.sessionId),
+			"mode-state",
+			ModeStateSchema,
+		);
+		const handoffRequired = isHandoffRequiredSkill(entry.skill);
+		if (modeStateReleasesStop(modeState, handoffRequired)) continue;
 		const phase = String(modeState?.current_phase ?? entry.phase ?? skillState.phase ?? "active");
 		const statePath = modeStatePath(resolvedStateDir, entry.skill, input.sessionId);
 		if (entry.skill === "ultragoal") {
@@ -450,7 +598,9 @@ export async function buildSkillStopOutput(input: StopHookInput): Promise<Record
 				}
 			}
 		}
-		const systemMessage = `GJC skill "${entry.skill}" is still active (phase: ${phase}; state: ${statePath}). Continue or explicitly finish/cancel the skill before stopping.`;
+		const systemMessage = handoffRequired
+			? `GJC handoff skill "${entry.skill}" must not stop without offering a next step (phase: ${phase}; state: ${statePath}). Use the ask tool to present the next handoff step — e.g. refine further, hand off to ralplan/team/ultragoal, or finish — then chain or explicitly clear the skill before stopping.`
+			: `GJC skill "${entry.skill}" is still active (phase: ${phase}; state: ${statePath}). Continue or explicitly finish/cancel the skill before stopping.`;
 		return {
 			decision: "block",
 			reason: systemMessage,

package/src/internal-urls/agent-protocol.ts

@@ -1,23 +1,72 @@
 /**
  * Protocol handler for agent:// URLs.
  *
- * Resolves agent output IDs against the artifacts directories of every active
- * session. Parents and subagents share outputs via this registry: a subagent
- * can read its parent's output IDs because both sessions are registered in
- * the shared context.
+ * Resolves agent output IDs only against artifacts directories explicitly
+ * authorized by the caller's ResolveContext. Parents and subagents can share
+ * outputs by passing their tree's artifacts dir at that API boundary.
  *
  * URL forms:
  * - agent://<id> - Full output content
  * - agent://<id>/<path> - JSON extraction via path form
  * - agent://<id>?q=<query> - JSON extraction via query form
  */
+import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isEnoent } from "@gajae-code/utils";
 import { applyQuery, pathToQuery } from "./json-query";
-import { artifactsDirsFromRegistry } from "./registry-helpers";
-import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+import { authorizedArtifactsDirsFromContext } from "./registry-helpers";
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext } from "./types";
 
+interface AgentOutputMetadata {
+	id: string;
+	kind: "agent-output";
+	sizeBytes: number;
+	lineCount: number;
+	sha256: string;
+	createdAt: string;
+}
+
+function isAgentOutputMetadata(value: unknown, outputId: string): value is AgentOutputMetadata {
+	if (!value || typeof value !== "object") return false;
+	const meta = value as Record<string, unknown>;
+	return (
+		meta.id === outputId &&
+		meta.kind === "agent-output" &&
+		typeof meta.sizeBytes === "number" &&
+		typeof meta.lineCount === "number" &&
+		typeof meta.sha256 === "string" &&
+		typeof meta.createdAt === "string"
+	);
+}
+
+async function verifyAgentOutputMetadata(outputId: string, foundPath: string, bytes: Buffer): Promise<void> {
+	const metaPath = `${foundPath}.meta.json`;
+	let metaRaw: string;
+	try {
+		metaRaw = await Bun.file(metaPath).text();
+	} catch (err) {
+		if (isEnoent(err)) throw new Error(`agent://${outputId} missing metadata`);
+		throw err;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(metaRaw);
+	} catch {
+		throw new Error(`agent://${outputId} malformed metadata`);
+	}
+	if (!isAgentOutputMetadata(parsed, outputId)) {
+		throw new Error(`agent://${outputId} malformed metadata`);
+	}
+	const stat = await fs.stat(foundPath);
+	if (stat.size !== parsed.sizeBytes || bytes.byteLength !== parsed.sizeBytes) {
+		throw new Error(`agent://${outputId} size mismatch`);
+	}
+	const sha256 = createHash("sha256").update(bytes).digest("hex");
+	if (sha256 !== parsed.sha256) {
+		throw new Error(`agent://${outputId} hash mismatch`);
+	}
+}
 /**
  * Handler for agent:// URLs.
  *
@@ -28,11 +77,17 @@ export class AgentProtocolHandler implements ProtocolHandler {
 	readonly scheme = "agent";
 	readonly immutable = true;
 
-	async resolve(url: InternalUrl): Promise<InternalResource> {
+	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
 		const outputId = url.rawHost || url.hostname;
 		if (!outputId) {
 			throw new Error("agent:// URL requires an output ID: agent://<id>");
 		}
+		// Output IDs address a single file inside a session artifacts dir. Reject
+		// path separators / traversal so a crafted id cannot escape the dir via
+		// path.join(dir, `${outputId}.md`).
+		if (outputId.includes("/") || outputId.includes("\\") || outputId.includes("..")) {
+			throw new Error(`agent://${outputId} invalid id: path separators are not allowed`);
+		}
 
 		const urlPath = url.pathname;
 		const queryParam = url.searchParams.get("q");
@@ -43,7 +98,7 @@ export class AgentProtocolHandler implements ProtocolHandler {
 			throw new Error("agent:// URL cannot combine path extraction with ?q=");
 		}
 
-		const dirs = artifactsDirsFromRegistry();
+		const dirs = authorizedArtifactsDirsFromContext(context);
 
 		if (dirs.length === 0) {
 			throw new Error("No session - agent outputs unavailable");
@@ -51,7 +106,6 @@ export class AgentProtocolHandler implements ProtocolHandler {
 
 		let foundPath: string | undefined;
 		let anyDirExists = false;
-		const availableIds = new Set<string>();
 
 		for (const dir of dirs) {
 			try {
@@ -64,18 +118,10 @@ export class AgentProtocolHandler implements ProtocolHandler {
 			const candidate = path.join(dir, `${outputId}.md`);
 			try {
 				await fs.stat(candidate);
+				if (foundPath) throw new Error(`agent://${outputId} ambiguous id in authorized artifacts`);
 				foundPath = candidate;
-				break;
 			} catch (err) {
 				if (!isEnoent(err)) throw err;
-				try {
-					const files = await fs.readdir(dir);
-					for (const f of files) {
-						if (f.endsWith(".md")) availableIds.add(f.replace(/\.md$/, ""));
-					}
-				} catch {
-					// Listing failures are non-fatal; continue searching.
-				}
 			}
 		}
 
@@ -84,11 +130,12 @@ export class AgentProtocolHandler implements ProtocolHandler {
 		}
 
 		if (!foundPath) {
-			const availableStr = availableIds.size > 0 ? [...availableIds].join(", ") : "none";
-			throw new Error(`Not found: ${outputId}\nAvailable: ${availableStr}`);
+			throw new Error(`agent://${outputId} not found`);
 		}
 
-		const rawContent = await Bun.file(foundPath).text();
+		const rawBytes = Buffer.from(await Bun.file(foundPath).arrayBuffer());
+		await verifyAgentOutputMetadata(outputId, foundPath, rawBytes);
+		const rawContent = rawBytes.toString("utf8");
 		const notes: string[] = [];
 		let content = rawContent;
 		let contentType: InternalResource["contentType"] = "text/markdown";