@gajae-code/coding-agent 0.11.7 → 0.11.8

package/src/eval/py/tool-bridge.ts

@@ -19,7 +19,10 @@ export interface PyToolBridgeEntry {
 
 export interface PyToolBridgeInfo {
 	url: string;
-	token: string;
+}
+
+interface PyToolBridgeRegistration extends PyToolBridgeEntry {
+	sessionId: string;
 }
 
 interface BridgeServer {
@@ -27,11 +30,20 @@ interface BridgeServer {
 	stop: () => Promise<void>;
 }
 
-const registrations = new Map<string, PyToolBridgeEntry>();
+const registrations = new Map<string, PyToolBridgeRegistration>();
 let serverPromise: Promise<BridgeServer> | null = null;
 
+function isCanonicalCapability(capability: string): boolean {
+	return capability.length > 0 && !/\s/.test(capability);
+}
+
+function parseBearerCapability(authorization: string | null): string | null {
+	if (!authorization?.startsWith("Bearer ")) return null;
+	const capability = authorization.slice("Bearer ".length);
+	return isCanonicalCapability(capability) ? capability : null;
+}
+
 async function startServer(): Promise<BridgeServer> {
-	const token = crypto.randomUUID();
 	const server = Bun.serve({
 		hostname: "127.0.0.1",
 		port: 0,
@@ -40,7 +52,12 @@ async function startServer(): Promise<BridgeServer> {
 			if (req.method !== "POST" || url.pathname !== "/v1/tool") {
 				return new Response("Not Found", { status: 404 });
 			}
-			if (req.headers.get("authorization") !== `Bearer ${token}`) {
+			const capability = parseBearerCapability(req.headers.get("authorization"));
+			if (!capability) {
+				return new Response("Forbidden", { status: 403 });
+			}
+			const registration = registrations.get(capability);
+			if (!registration) {
 				return new Response("Forbidden", { status: 403 });
 			}
 
@@ -55,19 +72,15 @@ async function startServer(): Promise<BridgeServer> {
 			if (!sessionId || !name) {
 				return Response.json({ ok: false, error: "Missing session/name" }, { status: 400 });
 			}
-			const entry = registrations.get(sessionId);
-			if (!entry) {
-				return Response.json(
-					{ ok: false, error: `No active Python tool bridge session: ${sessionId}` },
-					{ status: 200 },
-				);
+			if (sessionId !== registration.sessionId) {
+				return new Response("Forbidden", { status: 403 });
 			}
 
 			try {
 				const value = await callSessionTool(name, body.args, {
-					session: entry.toolSession,
-					signal: entry.signal,
-					emitStatus: entry.emitStatus,
+					session: registration.toolSession,
+					signal: registration.signal,
+					emitStatus: registration.emitStatus,
 				});
 				return Response.json({ ok: true, value });
 			} catch (err) {
@@ -81,7 +94,6 @@ async function startServer(): Promise<BridgeServer> {
 
 	const info: PyToolBridgeInfo = {
 		url: `http://${server.hostname}:${server.port}`,
-		token,
 	};
 	logger.debug("Python tool bridge listening", { url: info.url });
 
@@ -111,11 +123,15 @@ export async function ensurePyToolBridge(): Promise<PyToolBridgeInfo> {
  * Register a tool session for the duration of one execution. The returned
  * function MUST be called to remove the entry once execution finishes.
  */
-export function registerPyToolBridge(sessionId: string, entry: PyToolBridgeEntry): () => void {
-	registrations.set(sessionId, entry);
+export function registerPyToolBridge(sessionId: string, capability: string, entry: PyToolBridgeEntry): () => void {
+	if (!isCanonicalCapability(capability)) {
+		throw new Error("Python tool bridge capability must be a non-empty canonical bearer token");
+	}
+	const registration = { ...entry, sessionId };
+	registrations.set(capability, registration);
 	return () => {
-		if (registrations.get(sessionId) === entry) {
-			registrations.delete(sessionId);
+		if (registrations.get(capability) === registration) {
+			registrations.delete(capability);
 		}
 	};
 }

package/src/extensibility/gjc-plugins/runtime-adapters.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { bindPluginMcpToPublicNetwork } from "../../runtime-mcp/plugin-network-boundary";
 import { loadCustomTools } from "../custom-tools/loader";
 import type { CustomTool } from "../custom-tools/types";
 import { loadEffectiveGjcPluginRegistry, registryPathForScope } from "./registry";
@@ -330,7 +331,7 @@ export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
 					// resolution path expands ${env:...}/shell templates, which would let
 					// a third-party bundle exfiltrate host secrets. Plugin-bundle MCP
 					// servers connect without bundle-declared headers.
-					configs[m.name] = { type: cfg.transport, url: cfg.url };
+					configs[m.name] = bindPluginMcpToPublicNetwork({ type: cfg.transport, url: url.toString() });
 				}
 			} catch (error) {
 				quarantine.push({

package/src/gjc-runtime/launch-tmux.ts

@@ -705,7 +705,7 @@ function applyGjcTmuxRootTerminalTitleProfile(context: {
 }
 
 function shouldSetGjcTmuxRootTerminalTitle(parsed: Args, env: NodeJS.ProcessEnv): boolean {
-	return !parsed.noTitle && !env.PI_NO_TITLE;
+	return !parsed.noTitle && !(env.GJC_NO_TITLE || env.PI_NO_TITLE);
 }
 
 function buildTmuxRenameWindowArgs(title: string, target?: string): string[] {

package/src/gjc-runtime/managed-owner-supervisor.ts

@@ -1,9 +1,11 @@
 import * as crypto from "node:crypto";
+import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { Process } from "@gajae-code/natives";
 import { readLinuxProcStartTime } from "./linux-proc";
 import { assertSafePathComponent } from "./session-layout";
-import { lifecyclePaths } from "./tmux-owner-isolation";
+import { lifecyclePaths, type OwnerIntent, observeOwnerTerminal } from "./tmux-owner-isolation";
 
 export const MANAGED_OWNER_SUPERVISOR_ARG = "--internal-managed-owner-supervisor";
 export const MANAGED_OWNER_CHILD_TOKEN_ENV = "GJC_MANAGED_OWNER_CHILD_TOKEN";
@@ -14,6 +16,15 @@ export const MANAGED_OWNER_STATE_DIR_ENV = "GJC_TMUX_OWNER_STATE_DIR";
 export const MANAGED_OWNER_RUN_ID_ENV = "GJC_MANAGED_OWNER_RUN_ID";
 export const MANAGED_OWNER_INCARNATION_ENV = "GJC_MANAGED_OWNER_INCARNATION";
 
+let bootstrapSigtermPending = false;
+const captureBootstrapSigterm = () => {
+	bootstrapSigtermPending = true;
+};
+if (process.argv.includes(MANAGED_OWNER_SUPERVISOR_ARG)) {
+	process.removeAllListeners("SIGTERM");
+	process.on("SIGTERM", captureBootstrapSigterm);
+}
+
 export interface ManagedOwnerBinding {
 	schema_version: 2;
 	generation: string;
@@ -52,7 +63,14 @@ function requiredEnvironment(name: string): string {
 	return value;
 }
 
-function lifecycleRoot(): { root: string; generation: string; sessionId: string; runId: string; incarnation: string } {
+function lifecycleRoot(): {
+	root: string;
+	stateDir: string;
+	generation: string;
+	sessionId: string;
+	runId: string;
+	incarnation: string;
+} {
 	const stateDir = requiredEnvironment(MANAGED_OWNER_STATE_DIR_ENV);
 	const sessionId = requiredEnvironment(MANAGED_OWNER_SESSION_ID_ENV);
 	const generation = requiredEnvironment(MANAGED_OWNER_GENERATION_ENV);
@@ -68,7 +86,7 @@ function lifecycleRoot(): { root: string; generation: string; sessionId: string;
 	if (!path.isAbsolute(stateDir)) throw new Error("managed_owner_lifecycle_path_unsafe");
 	const root = lifecyclePaths(stateDir, sessionId, generation).root;
 	if (!root.startsWith(`${path.resolve(stateDir)}${path.sep}`)) throw new Error("managed_owner_lifecycle_path_unsafe");
-	return { root, generation, sessionId, runId, incarnation };
+	return { root, stateDir, generation, sessionId, runId, incarnation };
 }
 
 function commandDigest(command: readonly string[]): string {
@@ -106,8 +124,14 @@ export function isManagedOwnerSupervisorArgv(args: readonly string[]): boolean {
 
 /** Runs one exact child and publishes authority only for a directly observed Linux signal 6. */
 export async function runManagedOwnerSupervisor(): Promise<void> {
-	const { root, generation, sessionId, runId, incarnation } = lifecycleRoot();
+	const { root, stateDir, generation, sessionId, runId, incarnation } = lifecycleRoot();
 	const command = childCommand();
+	let sigtermPending = bootstrapSigtermPending;
+	const captureEarlySigterm = () => {
+		sigtermPending = true;
+	};
+	process.removeAllListeners("SIGTERM");
+	process.on("SIGTERM", captureEarlySigterm);
 	const supervisorStartTime = await readLinuxProcStartTime(process.pid);
 	if (!supervisorStartTime) throw new Error("managed_owner_supervisor_start_time_unavailable");
 	await fs.mkdir(root, { recursive: true, mode: 0o700 });
@@ -135,7 +159,62 @@ export async function runManagedOwnerSupervisor(): Promise<void> {
 	});
 	const childStartTime = await readLinuxProcStartTime(child.pid);
 	if (!childStartTime) throw new Error("managed_owner_child_start_time_unavailable");
+	const childProcess = Process.fromPid(child.pid);
+	if (!childProcess) throw new Error("managed_owner_child_reference_unavailable");
+	if (process.platform === "linux" && childProcess.incarnation !== `linux:${childStartTime}`)
+		throw new Error("managed_owner_child_incarnation_mismatch");
+	let childExited = false;
+	let sigtermRelayed = false;
+	let relayedIntent: OwnerIntent | null = null;
+	let relayedAt: string | null = null;
+	const relaySigterm = () => {
+		if (childExited || sigtermRelayed) return;
+		let candidateIntent: OwnerIntent | null = null;
+		try {
+			const candidate = JSON.parse(
+				fsSync.readFileSync(lifecyclePaths(stateDir, sessionId, generation).intentFile, "utf8"),
+			) as Partial<OwnerIntent>;
+			candidateIntent = typeof candidate.dispatch_id === "string" ? (candidate as OwnerIntent) : null;
+		} catch {
+			candidateIntent = null;
+		}
+		try {
+			if (!childProcess.signalRoot(15)) return;
+		} catch {
+			// The child exited between intent capture and delivery.
+			return;
+		}
+		sigtermRelayed = true;
+		relayedAt = new Date().toISOString();
+		relayedIntent = candidateIntent;
+	};
+	sigtermPending ||= bootstrapSigtermPending;
+	process.removeListener("SIGTERM", captureBootstrapSigterm);
+	process.removeListener("SIGTERM", captureEarlySigterm);
+	process.on("SIGTERM", relaySigterm);
+	if (sigtermPending) relaySigterm();
 	const exitCode = await child.exited;
+	childExited = true;
+	process.removeListener("SIGTERM", relaySigterm);
+	const terminalIntent = relayedIntent as OwnerIntent | null;
+	const terminalObservedAt = relayedAt as string | null;
+	if (sigtermRelayed && terminalObservedAt && terminalIntent) {
+		await observeOwnerTerminal({
+			schema_version: 1,
+			op: "observe_terminal",
+			session_id: sessionId,
+			owner_generation: generation,
+			state_dir: stateDir,
+			socket_key: process.env.GJC_TMUX_OWNER_SERVER_KEY ?? "",
+			observer: "raw_monitor",
+			observed_at: terminalObservedAt,
+			signal: "SIGTERM",
+			exit_code: exitCode,
+			exit_kind: "supervisor_child_exit",
+			reason: "managed_owner_supervisor_exit",
+			operator_dispatch_id: terminalIntent.dispatch_id,
+		});
+	}
 	if (child.signalCode === "SIGABRT") {
 		const receipt: ManagedOwnerSigabrtReceipt = {
 			schema_version: 2,

package/src/gjc-runtime/ralplan-runtime.ts

@@ -11,6 +11,15 @@ import {
 	type RalplanIndexRow,
 	summarizeRalplanIndex,
 } from "./ledger-event-renderer";
+import {
+	assertCwdMatchesRepositoryBinding,
+	assertPathUnderRepositoryBinding,
+	captureRepositoryBinding,
+	parseRepositoryBinding,
+	publicRepositoryBinding,
+	type RepositoryBinding,
+	RepositoryBindingError,
+} from "./repository-binding";
 import { GJC_RALPLAN_ARTIFACT_ENV, isRestrictedRoleAgentBash } from "./restricted-role-agent-bash";
 import { modeStatePath, sessionPlansDir } from "./session-layout";
 import { resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session-resolution";
@@ -179,6 +188,43 @@ async function readActiveRunId(cwd: string, sessionId: string): Promise<string |
 	return candidate;
 }
 
+/**
+ * Read the authoritative repository binding from ralplan run state and fail closed
+ * when the active cwd no longer matches (handoff / QA / stage write) (#2901).
+ */
+async function enforceRalplanRepositoryBinding(cwd: string, sessionId: string): Promise<RepositoryBinding> {
+	const statePath = ralplanStatePath(cwd, sessionId);
+	const existingRead = await readExistingStateForMutation(statePath);
+	if (existingRead.kind === "corrupt") {
+		throw new RalplanCommandError(
+			2,
+			`existing ralplan state is corrupt or tampered (${existingRead.error}); refusing to proceed at ${statePath}`,
+		);
+	}
+	if (existingRead.kind === "absent") {
+		// No prior seed — capture live authority so subsequent handoffs still have a stamp.
+		return publicRepositoryBinding(await captureRepositoryBinding(cwd, { displayPath: cwd }));
+	}
+	const raw = existingRead.value.repository_binding ?? existingRead.value.repositoryBinding;
+	try {
+		if (raw === undefined) {
+			// Legacy seeds without a field: stamp current cwd and require future writes match it.
+			return publicRepositoryBinding(await captureRepositoryBinding(cwd, { displayPath: cwd }));
+		}
+		const binding = parseRepositoryBinding(raw);
+		await assertCwdMatchesRepositoryBinding(cwd, binding);
+		return publicRepositoryBinding(binding);
+	} catch (error) {
+		if (error instanceof RepositoryBindingError) {
+			throw new RalplanCommandError(2, `ralplan repository binding rejected: ${error.message}`);
+		}
+		throw new RalplanCommandError(
+			2,
+			`ralplan repository binding rejected: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
 /**
  * Run-state phases that an artifact write must never reopen. Once ralplan has
  * reached a terminal/handed-off phase, a stray `--write` must not regress
@@ -651,6 +697,24 @@ async function buildRalplanHud(options: {
 async function handleArtifactWrite(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
 	const plannerState = parsePlannerStateArgs(args);
 	const resolved = await resolveArtifactArgs(args, cwd);
+	// Fail closed before stage persistence / path writes when cwd drifted to a sibling repo.
+	const repositoryBinding = await enforceRalplanRepositoryBinding(cwd, resolved.sessionId);
+	// Artifact file paths (when --artifact points at a file) must stay under the bound root.
+	const rawArtifact = flagValue(args, "--artifact");
+	if (rawArtifact && !isRestrictedRoleAgentBash()) {
+		const candidate = path.isAbsolute(rawArtifact) ? rawArtifact : path.resolve(cwd, rawArtifact);
+		try {
+			const stat = await fs.stat(candidate);
+			if (stat.isFile()) {
+				assertPathUnderRepositoryBinding(repositoryBinding, candidate);
+			}
+		} catch (error) {
+			if (error instanceof RepositoryBindingError) {
+				throw new RalplanCommandError(2, `ralplan repository binding rejected: ${error.message}`);
+			}
+			// Non-file / missing path is inline content; resolveArtifactContent already handled it.
+		}
+	}
 	const content = resolved.artifact.endsWith("\n") ? resolved.artifact : `${resolved.artifact}\n`;
 	const sha256 = createHash("sha256").update(content).digest("hex");
 
@@ -696,6 +760,7 @@ async function handleArtifactWrite(args: readonly string[], cwd: string): Promis
 		stage: persisted.stage,
 		stage_n: persisted.stageN,
 		sha256: persisted.sha256,
+		repository_binding: repositoryBinding,
 		created_at: persisted.createdAt,
 	};
 	if (persisted.pendingApprovalPath) payload.pending_approval_path = persisted.pendingApprovalPath;
@@ -809,7 +874,7 @@ function resolveConsensusArgs(args: readonly string[], cwd: string): ConsensusHa
 async function seedRalplanState(
 	cwd: string,
 	resolved: ConsensusHandoffArgs,
-): Promise<{ statePath: string; runId: string }> {
+): Promise<{ statePath: string; runId: string; repositoryBinding: RepositoryBinding }> {
 	const statePath = ralplanStatePath(cwd, resolved.sessionId);
 	// Reuse an existing run id when present so a re-invocation of `gjc ralplan "task"` doesn't
 	// orphan in-progress artifacts under a fresh run id.
@@ -817,6 +882,11 @@ async function seedRalplanState(
 	const runId = existingRunId ?? resolved.sessionId ?? defaultRunId();
 	assertSafePathComponent(runId, "run-id");
 	const now = new Date().toISOString();
+	// When an active seed already carries authority, re-entry must match it (fail closed).
+	// Otherwise stamp the current cwd as the durable binding for this run.
+	const repositoryBinding = existingRunId
+		? await enforceRalplanRepositoryBinding(cwd, resolved.sessionId)
+		: publicRepositoryBinding(await captureRepositoryBinding(cwd, { displayPath: cwd }));
 	const payload: Record<string, unknown> = {
 		active: true,
 		current_phase: "planner",
@@ -827,6 +897,7 @@ async function seedRalplanState(
 		task: resolved.task,
 		run_id: runId,
 		updated_at: now,
+		repository_binding: repositoryBinding,
 	};
 	if (resolved.architectKind) payload.architect_kind = resolved.architectKind;
 	if (resolved.criticKind) payload.critic_kind = resolved.criticKind;
@@ -849,7 +920,7 @@ async function seedRalplanState(
 		},
 	});
 	await writeSessionActivityMarker(cwd, resolved.sessionId, { writer: "ralplan-runtime", path: statePath });
-	return { statePath, runId };
+	return { statePath, runId, repositoryBinding };
 }
 
 async function handleConsensusHandoff(args: readonly string[], cwd: string): Promise<RalplanCommandResult> {
@@ -857,7 +928,7 @@ async function handleConsensusHandoff(args: readonly string[], cwd: string): Pro
 	if (!resolved.task) {
 		throw new RalplanCommandError(2, 'gjc ralplan requires a task description, e.g. `gjc ralplan "<task>"`.');
 	}
-	const { statePath, runId } = await seedRalplanState(cwd, resolved);
+	const { statePath, runId, repositoryBinding } = await seedRalplanState(cwd, resolved);
 	const mode = resolved.deliberate ? "deliberate" : "short";
 	await syncRalplanHud({
 		cwd,
@@ -875,6 +946,7 @@ async function handleConsensusHandoff(args: readonly string[], cwd: string): Pro
 		state_path: statePath,
 		run_id: runId,
 		handoff: "/skill:ralplan",
+		repository_binding: repositoryBinding,
 	};
 	const stdout = resolved.json
 		? renderCliWriteReceipt({ ok: true, ...summary })

package/src/gjc-runtime/repository-binding.ts

@@ -0,0 +1,267 @@
+/**
+ * Authoritative repository/worktree binding for plans and delegated tasks (#2901).
+ *
+ * Multi-repo parent directories must not let QA/review lanes infer a sibling repo
+ * from prose. Bindings carry a validated worktree root + git common-dir identity
+ * so spawn/handoff can fail closed on mismatch.
+ */
+import * as fssync from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { type GitRepository, head, repo } from "../utils/git";
+
+export const REPOSITORY_BINDING_SCHEMA = "gjc.repository_binding.v1" as const;
+
+export interface RepositoryBinding {
+	schema: typeof REPOSITORY_BINDING_SCHEMA;
+	/** Canonical realpath of the git worktree root (or resolved cwd root). */
+	worktreeRoot: string;
+	/** Git common dir realpath when available; null outside a git checkout. */
+	commonDir: string | null;
+	/** Optional repo-relative subdirectory the lane should operate under. */
+	relativeSubdir?: string;
+	/** Optional display path (may be non-canonical); never used for authority. */
+	displayPath?: string;
+	/** Optional baseline HEAD at capture time. */
+	head?: string;
+	/** Optional branch name at capture time (when not detached). */
+	branch?: string;
+}
+
+export type RepositoryBindingErrorCode =
+	| "not_a_repository"
+	| "identity_mismatch"
+	| "path_outside_root"
+	| "invalid_binding";
+
+export class RepositoryBindingError extends Error {
+	readonly code: RepositoryBindingErrorCode;
+
+	constructor(code: RepositoryBindingErrorCode, message: string) {
+		super(message);
+		this.name = "RepositoryBindingError";
+		this.code = code;
+	}
+}
+
+async function realpathOrResolve(target: string): Promise<string> {
+	try {
+		return await fs.realpath(target);
+	} catch {
+		return path.resolve(target);
+	}
+}
+
+/** Sync realpath for path-under-root checks (handles macOS /var → /private/var). */
+function realpathSyncOrResolve(target: string): string {
+	try {
+		return fssync.realpathSync(target);
+	} catch {
+		return path.resolve(target);
+	}
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+
+/** Capture a durable binding from the active cwd/worktree. */
+export async function captureRepositoryBinding(
+	cwd: string,
+	options: { relativeSubdir?: string; displayPath?: string } = {},
+): Promise<RepositoryBinding> {
+	const resolvedCwd = await realpathOrResolve(cwd);
+	const repository = await repo.resolve(resolvedCwd);
+	const worktreeRoot = repository ? await realpathOrResolve(repository.repoRoot) : resolvedCwd;
+	const commonDir = repository ? await realpathOrResolve(repository.commonDir) : null;
+
+	let headSha: string | undefined;
+	let branch: string | undefined;
+	if (repository) {
+		const headState = await head.resolve(resolvedCwd);
+		if (headState) {
+			headSha = headState.commit || undefined;
+			branch = headState.kind === "ref" ? headState.branchName || undefined : undefined;
+		}
+	}
+
+	const binding: RepositoryBinding = {
+		schema: REPOSITORY_BINDING_SCHEMA,
+		worktreeRoot,
+		commonDir,
+		...(options.relativeSubdir ? { relativeSubdir: normalizeRelativeSubdir(options.relativeSubdir) } : {}),
+		...(options.displayPath ? { displayPath: options.displayPath } : {}),
+		...(headSha ? { head: headSha } : {}),
+		...(branch ? { branch } : {}),
+	};
+	return binding;
+}
+
+function normalizeRelativeSubdir(relative: string): string {
+	const normalized = relative
+		.replaceAll("\\", "/")
+		.replace(/^\.\/+/u, "")
+		.replace(/\/+$/u, "");
+	if (normalized === "" || normalized === ".") {
+		throw new RepositoryBindingError("invalid_binding", "relativeSubdir must be a non-empty relative path");
+	}
+	if (path.isAbsolute(normalized) || normalized.split("/").includes("..")) {
+		throw new RepositoryBindingError("invalid_binding", "relativeSubdir must be repo-relative without '..' segments");
+	}
+	return normalized;
+}
+
+/** Parse a binding from JSON/plan payload; fail closed on malformed shapes. */
+export function parseRepositoryBinding(value: unknown): RepositoryBinding {
+	if (!isObject(value)) {
+		throw new RepositoryBindingError("invalid_binding", "repository binding must be an object");
+	}
+	const schema = nonEmptyString(value.schema);
+	if (schema !== REPOSITORY_BINDING_SCHEMA) {
+		throw new RepositoryBindingError(
+			"invalid_binding",
+			`repository binding schema must be ${REPOSITORY_BINDING_SCHEMA}`,
+		);
+	}
+	const worktreeRoot = nonEmptyString(value.worktreeRoot ?? value.worktree_root);
+	if (!worktreeRoot) {
+		throw new RepositoryBindingError("invalid_binding", "repository binding requires worktreeRoot");
+	}
+	const commonDirRaw = value.commonDir ?? value.common_dir;
+	const commonDir =
+		commonDirRaw === null || commonDirRaw === undefined
+			? null
+			: (nonEmptyString(commonDirRaw) ??
+				(() => {
+					throw new RepositoryBindingError("invalid_binding", "commonDir must be a string or null");
+				})());
+	const relativeSubdirRaw = value.relativeSubdir ?? value.relative_subdir;
+	const relativeSubdir =
+		relativeSubdirRaw === undefined ? undefined : normalizeRelativeSubdir(String(relativeSubdirRaw));
+	const displayPath = nonEmptyString(value.displayPath ?? value.display_path);
+	const head = nonEmptyString(value.head);
+	const branch = nonEmptyString(value.branch);
+	return {
+		schema: REPOSITORY_BINDING_SCHEMA,
+		worktreeRoot: path.resolve(worktreeRoot),
+		commonDir: commonDir === null ? null : path.resolve(commonDir),
+		...(relativeSubdir ? { relativeSubdir } : {}),
+		...(displayPath ? { displayPath } : {}),
+		...(head ? { head } : {}),
+		...(branch ? { branch } : {}),
+	};
+}
+
+/** True when two bindings refer to the same repository identity (linked worktrees ok). */
+export function repositoryBindingsMatch(left: RepositoryBinding, right: RepositoryBinding): boolean {
+	if (left.commonDir && right.commonDir) {
+		return path.resolve(left.commonDir) === path.resolve(right.commonDir);
+	}
+	// Non-git workspaces: require exact worktree root match.
+	return path.resolve(left.worktreeRoot) === path.resolve(right.worktreeRoot);
+}
+
+/**
+ * Ensure `cwd` is inside the bound repository (or the same linked worktree family).
+ * Fails closed on sibling-repo drift.
+ */
+export async function assertCwdMatchesRepositoryBinding(
+	cwd: string,
+	binding: RepositoryBinding,
+): Promise<RepositoryBinding> {
+	const active = await captureRepositoryBinding(cwd);
+	if (!repositoryBindingsMatch(active, binding)) {
+		throw new RepositoryBindingError(
+			"identity_mismatch",
+			`Active worktree does not match plan/task repository binding. active=${active.worktreeRoot} (commonDir=${active.commonDir ?? "none"}) bound=${binding.worktreeRoot} (commonDir=${binding.commonDir ?? "none"}).`,
+		);
+	}
+	return active;
+}
+
+/** Ensure a declared target path resolves under the bound worktree root. */
+export function assertPathUnderRepositoryBinding(binding: RepositoryBinding, targetPath: string): string {
+	const root = realpathSyncOrResolve(binding.worktreeRoot);
+	const base = binding.relativeSubdir ? realpathSyncOrResolve(path.resolve(root, binding.relativeSubdir)) : root;
+	const candidate = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
+	// Prefer realpath when the path exists so macOS /var ↔ /private/var aliases match.
+	const resolved = realpathSyncOrResolve(candidate);
+	const relative = path.relative(root, resolved);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) {
+		throw new RepositoryBindingError(
+			"path_outside_root",
+			`Path escapes bound repository root: ${targetPath} (root=${root})`,
+		);
+	}
+	return resolved;
+}
+
+/**
+ * Public identity snapshot for receipts/handoffs (no display-only fields required).
+ * Always includes the schema + durable roots so downstream lanes can re-verify.
+ */
+export function publicRepositoryBinding(binding: RepositoryBinding): RepositoryBinding {
+	return {
+		schema: REPOSITORY_BINDING_SCHEMA,
+		worktreeRoot: path.resolve(binding.worktreeRoot),
+		commonDir: binding.commonDir === null ? null : path.resolve(binding.commonDir),
+		...(binding.relativeSubdir ? { relativeSubdir: binding.relativeSubdir } : {}),
+		...(binding.displayPath ? { displayPath: binding.displayPath } : {}),
+		...(binding.head ? { head: binding.head } : {}),
+		...(binding.branch ? { branch: binding.branch } : {}),
+	};
+}
+
+/**
+ * Resolve the authoritative binding for a delegated task before discovery/spawn.
+ *
+ * - Missing declaration → stamp from session cwd (never leave authority implicit).
+ * - Declared binding → parse + fail closed unless it matches the active session worktree.
+ * - relativeSubdir (when present) must resolve under the bound root.
+ */
+export async function resolveTaskRepositoryBinding(
+	sessionCwd: string,
+	declared: unknown | undefined,
+): Promise<RepositoryBinding> {
+	const sessionBinding = await captureRepositoryBinding(sessionCwd, { displayPath: sessionCwd });
+	if (declared === undefined || declared === null) {
+		return publicRepositoryBinding(sessionBinding);
+	}
+	const taskBinding = parseRepositoryBinding(declared);
+	await assertCwdMatchesRepositoryBinding(sessionCwd, taskBinding);
+	if (taskBinding.relativeSubdir) {
+		assertPathUnderRepositoryBinding(taskBinding, ".");
+	}
+	return publicRepositoryBinding(taskBinding);
+}
+
+/**
+ * Ensure an execution/isolation root (cwd or worktree) still matches the bound identity.
+ * Used after isolation workspace creation so linked worktrees keep the source repository.
+ */
+export async function assertExecutionRootMatchesRepositoryBinding(
+	executionRoot: string,
+	binding: RepositoryBinding,
+): Promise<RepositoryBinding> {
+	return await assertCwdMatchesRepositoryBinding(executionRoot, binding);
+}
+
+/** Optional helper for tests and diagnostics. */
+export function bindingFromGitRepository(
+	repository: GitRepository,
+	options: { relativeSubdir?: string; displayPath?: string; head?: string; branch?: string } = {},
+): RepositoryBinding {
+	return {
+		schema: REPOSITORY_BINDING_SCHEMA,
+		worktreeRoot: path.resolve(repository.repoRoot),
+		commonDir: path.resolve(repository.commonDir),
+		...(options.relativeSubdir ? { relativeSubdir: normalizeRelativeSubdir(options.relativeSubdir) } : {}),
+		...(options.displayPath ? { displayPath: options.displayPath } : {}),
+		...(options.head ? { head: options.head } : {}),
+		...(options.branch ? { branch: options.branch } : {}),
+	};
+}