pi-crew 0.9.53 → 0.9.55

package/src/extension/rpc-hmac.ts

@@ -0,0 +1,256 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+/**
+ * HMAC-based origin signing for cross-extension RPC.
+ *
+ * Shared secret is distributed via environment variable PI_CREW_RPC_SECRET.
+ * When the secret is configured, all RPC requests must include a valid HMAC
+ * signature. When the secret is NOT configured, HMAC is disabled (backward
+ * compat for setups that don't need it).
+ *
+ * Usage:
+ *   Sender:   signRpcRequest(params, "my-extension", "pi-crew:rpc:ping")
+ *   Receiver: wrap handler with withHmacVerification(handler, channel)
+ */
+
+export const RPC_HMAC_VERSION = 1;
+
+const SECRET_ENV_VAR = "PI_CREW_RPC_SECRET";
+const CLOCK_SKEW_TOLERANCE_MS = 5 * 60 * 1000; // 5 min
+const SIGNATURE_VALIDITY_MS = 10 * 60 * 1000; // 10 min
+
+// --- Secret management -------------------------------------------------------
+
+/** Get the shared secret. Returns undefined if not configured. */
+export function getRpcSecret(): string | undefined {
+	return process.env[SECRET_ENV_VAR];
+}
+
+/** Set the shared secret (for testing or programmatic setup). */
+export function setRpcSecret(secret: string): void {
+	process.env[SECRET_ENV_VAR] = secret;
+}
+
+/** Clear the shared secret. */
+export function clearRpcSecret(): void {
+	delete process.env[SECRET_ENV_VAR];
+}
+
+/** Whether HMAC authentication is currently enabled. */
+export function isHmacEnabled(): boolean {
+	return typeof process.env[SECRET_ENV_VAR] === "string" && process.env[SECRET_ENV_VAR].length > 0;
+}
+
+// --- Types -------------------------------------------------------------------
+
+export interface RpcSignaturePayload {
+	version: number;
+	origin: string;
+	timestamp: number;
+	channel: string;
+	nonce: string;
+}
+
+export type RpcSignedPayload = RpcSignaturePayload & { signature: string };
+
+// Process-latched: emit a soft, non-alarming note once per process when an RPC
+// request is actually processed without HMAC. The previous warning was emitted
+// at extension registration (every pi load) and was considered noisy by users
+// who never wire cross-extension RPC. Opt out with PI_CREW_SUPPRESS_RPC_WARNING=1.
+let _rpcHmacSoftInfoEmitted = false;
+function rpcHmacSoftInfoOnce(): void {
+	if (_rpcHmacSoftInfoEmitted) return;
+	_rpcHmacSoftInfoEmitted = true;
+	console.warn(
+		"[pi-crew] PI_CREW_RPC_SECRET not set; cross-extension RPC requests will be accepted without origin authentication. " +
+			"Operation allowlists and session checks still apply. Set PI_CREW_RPC_SECRET or PI_CREW_SUPPRESS_RPC_WARNING=1 to silence this message.",
+	);
+}
+
+// --- Signing -----------------------------------------------------------------
+
+/**
+ * Create an HMAC signature for an RPC request.
+ *
+ * @throws if no secret is configured
+ */
+export function createRpcSignature(origin: string, channel: string, body: unknown): RpcSignedPayload {
+	const secret = getRpcSecret();
+	if (!secret) {
+		throw new Error(`[pi-crew HMAC] Cannot create signature: ${SECRET_ENV_VAR} not set.`);
+	}
+
+	const payload: RpcSignaturePayload = {
+		version: RPC_HMAC_VERSION,
+		origin,
+		timestamp: Date.now(),
+		channel,
+		nonce: randomBytes(16).toString("hex"),
+	};
+
+	const signature = computeHmac(secret, payload, body);
+	return { ...payload, signature };
+}
+
+// --- Verification ------------------------------------------------------------
+
+/**
+ * Verify an HMAC signature.
+ *
+ * @returns `{ valid: true }` or `{ valid: false, reason: string }`
+ */
+export function verifyRpcSignature(payload: RpcSignedPayload, body: unknown): { valid: true } | { valid: false; reason: string } {
+	const secret = getRpcSecret();
+	if (!secret) {
+		return { valid: false, reason: `[pi-crew HMAC] ${SECRET_ENV_VAR} not configured.` };
+	}
+
+	if (payload.version !== RPC_HMAC_VERSION) {
+		return { valid: false, reason: `HMAC version mismatch: expected ${RPC_HMAC_VERSION}, got ${payload.version}` };
+	}
+
+	const now = Date.now();
+	const age = now - payload.timestamp;
+	if (age < -CLOCK_SKEW_TOLERANCE_MS) {
+		return { valid: false, reason: `HMAC timestamp in the future by ${Math.abs(age)}ms` };
+	}
+	if (age > SIGNATURE_VALIDITY_MS) {
+		return { valid: false, reason: `HMAC signature expired (${age}ms old)` };
+	}
+
+	const expected = computeHmac(secret, payload, body);
+	return timingSafeCompare(payload.signature, expected) ? { valid: true } : { valid: false, reason: "HMAC signature mismatch" };
+}
+
+// --- Middleware --------------------------------------------------------------
+
+/**
+ * Wrap an RPC handler with HMAC verification.
+ *
+ * When HMAC is NOT configured (getRpcSecret() returns undefined), requests
+ * without signatures are passed through (backward compat). When HMAC IS
+ * configured, unsigned or invalid signatures are rejected.
+ */
+export function withHmacVerification<P extends { requestId: string }>(
+	handler: (params: P) => unknown | Promise<unknown>,
+	_channel: string,
+): (params: P) => unknown | Promise<unknown> {
+	return (params: P) => {
+		if (!isHmacEnabled()) {
+			// No secret configured → backward compat: allow unsigned.
+			// Emit a soft info note (once per process) only when an actual RPC
+			// request is being processed — the prior registration-time warning
+			// was too noisy for users who never wire cross-extension RPC.
+			if (process.env.PI_CREW_SUPPRESS_RPC_WARNING !== "1") {
+				rpcHmacSoftInfoOnce();
+			}
+			return handler(params);
+		}
+
+		const sigPayload = extractSignaturePayload(params);
+		if (!sigPayload) {
+			throw new Error("[pi-crew HMAC] Missing HMAC signature in RPC request.");
+		}
+
+		// Strip HMAC fields from body before verification (HMAC was signed over original params)
+		const originalBody = stripHmacFields(params);
+		const verification = verifyRpcSignature(sigPayload, originalBody);
+		if (!verification.valid) {
+			throw new Error(`[pi-crew HMAC] ${verification.reason}`);
+		}
+
+		// Pass original params (with HMAC fields stripped) to handler
+		return handler(originalBody as P);
+	};
+}
+
+// --- Helpers -----------------------------------------------------------------
+
+/**
+ * Attach HMAC signature fields to RPC request params.
+ */
+export function signRpcRequest<P extends Record<string, unknown>>(
+	params: P,
+	origin: string,
+	channel: string,
+): P & {
+	hmacVersion: number;
+	hmacOrigin: string;
+	hmacTimestamp: number;
+	hmacChannel: string;
+	hmacNonce: string;
+	hmacSignature: string;
+} {
+	const signed = createRpcSignature(origin, channel, params);
+	return {
+		...params,
+		hmacVersion: signed.version,
+		hmacOrigin: signed.origin,
+		hmacTimestamp: signed.timestamp,
+		hmacChannel: signed.channel,
+		hmacNonce: signed.nonce,
+		hmacSignature: signed.signature,
+	};
+}
+
+// --- Internal ----------------------------------------------------------------
+
+/** Strip HMAC signature fields from params to get the original body. */
+function stripHmacFields<P extends Record<string, unknown>>(params: P): Partial<P> {
+	const result = { ...params };
+	delete result.hmacVersion;
+	delete result.hmacOrigin;
+	delete result.hmacTimestamp;
+	delete result.hmacChannel;
+	delete result.hmacNonce;
+	delete result.hmacSignature;
+	return result;
+}
+
+function computeHmac(secret: string, payload: RpcSignaturePayload, body: unknown): string {
+	const payloadForHmac = {
+		version: payload.version,
+		origin: payload.origin,
+		timestamp: payload.timestamp,
+		channel: payload.channel,
+		nonce: payload.nonce,
+	};
+	const message = `${JSON.stringify(payloadForHmac)}:${JSON.stringify(body)}`;
+	return createHmac("sha256", secret).update(message).digest("hex");
+}
+
+function timingSafeCompare(a: string, b: string): boolean {
+	const bufA = Buffer.from(a, "hex");
+	const bufB = Buffer.from(b, "hex");
+	const maxLen = Math.max(bufA.length, bufB.length);
+	const safeA = Buffer.alloc(maxLen);
+	const safeB = Buffer.alloc(maxLen);
+	bufA.copy(safeA);
+	bufB.copy(safeB);
+	const equal = timingSafeEqual(safeA, safeB);
+	return equal && bufA.length === bufB.length;
+}
+
+/** Extract HMAC signature payload from request params. */
+export function extractSignaturePayload(params: unknown): RpcSignedPayload | null {
+	if (!params || typeof params !== "object" || Array.isArray(params)) return null;
+	const obj = params as Record<string, unknown>;
+	if (
+		typeof obj.hmacVersion !== "number" ||
+		typeof obj.hmacOrigin !== "string" ||
+		typeof obj.hmacTimestamp !== "number" ||
+		typeof obj.hmacChannel !== "string" ||
+		typeof obj.hmacNonce !== "string" ||
+		typeof obj.hmacSignature !== "string"
+	) {
+		return null;
+	}
+	return {
+		version: obj.hmacVersion,
+		origin: obj.hmacOrigin,
+		timestamp: obj.hmacTimestamp,
+		channel: obj.hmacChannel,
+		nonce: obj.hmacNonce,
+		signature: obj.hmacSignature,
+	};
+}

package/src/extension/run-bundle-schema.ts

@@ -0,0 +1,104 @@
+import { isTeamRunStatus, isTeamTaskStatus } from "../state/contracts.ts";
+import type { TeamEvent } from "../state/event-log.ts";
+import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { ExportedRunBundle } from "./run-export.ts";
+
+export interface BundleValidationResult {
+	ok: boolean;
+	errors: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateArtifact(value: unknown, index: number, errors: string[]): value is ArtifactDescriptor {
+	if (!isRecord(value)) {
+		errors.push(`manifest.artifacts[${index}] must be an object.`);
+		return false;
+	}
+	const before = errors.length;
+	if (typeof value.kind !== "string") errors.push(`manifest.artifacts[${index}].kind must be a string.`);
+	if (typeof value.path !== "string") errors.push(`manifest.artifacts[${index}].path must be a string.`);
+	if (typeof value.createdAt !== "string") errors.push(`manifest.artifacts[${index}].createdAt must be a string.`);
+	if (typeof value.producer !== "string") errors.push(`manifest.artifacts[${index}].producer must be a string.`);
+	if (value.retention !== "run" && value.retention !== "project" && value.retention !== "temporary")
+		errors.push(`manifest.artifacts[${index}].retention is invalid.`);
+	return errors.length === before;
+}
+
+function validateManifest(value: unknown, errors: string[]): value is TeamRunManifest {
+	if (!isRecord(value)) {
+		errors.push("manifest must be an object.");
+		return false;
+	}
+	const before = errors.length;
+	if (value.schemaVersion !== 1) errors.push("manifest.schemaVersion must be 1.");
+	for (const field of [
+		"runId",
+		"team",
+		"goal",
+		"createdAt",
+		"updatedAt",
+		"cwd",
+		"stateRoot",
+		"artifactsRoot",
+		"tasksPath",
+		"eventsPath",
+	] as const) {
+		if (typeof value[field] !== "string") errors.push(`manifest.${field} must be a string.`);
+	}
+	if (!isTeamRunStatus(value.status)) errors.push("manifest.status is invalid.");
+	if (value.workspaceMode !== "single" && value.workspaceMode !== "worktree")
+		errors.push("manifest.workspaceMode must be single or worktree.");
+	if (!Array.isArray(value.artifacts)) errors.push("manifest.artifacts must be an array.");
+	else value.artifacts.forEach((artifact, index) => validateArtifact(artifact, index, errors));
+	return errors.length === before;
+}
+
+function validateTask(value: unknown, index: number, errors: string[]): value is TeamTaskState {
+	if (!isRecord(value)) {
+		errors.push(`tasks[${index}] must be an object.`);
+		return false;
+	}
+	const before = errors.length;
+	for (const field of ["id", "runId", "role", "agent", "title", "cwd"] as const) {
+		if (typeof value[field] !== "string") errors.push(`tasks[${index}].${field} must be a string.`);
+	}
+	if (!isTeamTaskStatus(value.status)) errors.push(`tasks[${index}].status is invalid.`);
+	if (!Array.isArray(value.dependsOn)) errors.push(`tasks[${index}].dependsOn must be an array.`);
+	return errors.length === before;
+}
+
+function validateEvent(value: unknown, index: number, errors: string[]): value is TeamEvent {
+	if (!isRecord(value)) {
+		errors.push(`events[${index}] must be an object.`);
+		return false;
+	}
+	const before = errors.length;
+	for (const field of ["time", "type", "runId"] as const) {
+		if (typeof value[field] !== "string") errors.push(`events[${index}].${field} must be a string.`);
+	}
+	return errors.length === before;
+}
+
+export function validateRunBundle(value: unknown): BundleValidationResult {
+	const errors: string[] = [];
+	if (!isRecord(value)) return { ok: false, errors: ["bundle must be an object."] };
+	if (value.schemaVersion !== 1) errors.push("schemaVersion must be 1.");
+	if (typeof value.exportedAt !== "string") errors.push("exportedAt must be a string.");
+	validateManifest(value.manifest, errors);
+	if (!Array.isArray(value.tasks)) errors.push("tasks must be an array.");
+	else value.tasks.forEach((task, index) => validateTask(task, index, errors));
+	if (!Array.isArray(value.events)) errors.push("events must be an array.");
+	else value.events.forEach((event, index) => validateEvent(event, index, errors));
+	if (!Array.isArray(value.artifactPaths) || !value.artifactPaths.every((item) => typeof item === "string"))
+		errors.push("artifactPaths must be an array of strings.");
+	return { ok: errors.length === 0, errors };
+}
+
+export function assertRunBundle(value: unknown): asserts value is ExportedRunBundle {
+	const validation = validateRunBundle(value);
+	if (!validation.ok)
+		throw new Error(`File is not a valid pi-crew exported run bundle:\n${validation.errors.map((error) => `- ${error}`).join("\n")}`);
+}

package/src/extension/run-export.ts

@@ -0,0 +1,97 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { writeArtifact } from "../state/artifact-store.ts";
+import { readEvents, type TeamEvent } from "../state/event-log.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { redactSecrets } from "../utils/redaction.ts";
+
+/** Replace absolute paths containing home directory with ~/ */
+/** Escape special regex characters in a string */
+function escapeRegex(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Only redact home directory at path boundaries to avoid corrupting substrings */
+function redactHomePathInString(str: string, home: string): string {
+	return str.replace(new RegExp(`(^|(?<=[:=/]))${escapeRegex(home)}`, "g"), "$1~");
+}
+
+/** Replace absolute paths containing home directory with ~/ at path boundaries only */
+function redactHomePaths<T>(obj: T): T {
+	const home = os.homedir();
+	if (!home) return redactSecrets(obj) as T;
+	const json = JSON.stringify(obj);
+	const safe = redactHomePathInString(json, home);
+	return redactSecrets(JSON.parse(safe)) as T;
+}
+
+export interface ExportedRunBundle {
+	schemaVersion: 1;
+	exportedAt: string;
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	events: TeamEvent[];
+	artifactPaths: string[];
+}
+
+export function exportRunBundle(manifest: TeamRunManifest, tasks: TeamTaskState[]): { jsonPath: string; markdownPath: string } {
+	const events = readEvents(manifest.eventsPath);
+	const safeManifest = redactHomePaths(manifest);
+	const safeTasks = redactHomePaths(tasks);
+	const safeEvents = redactHomePaths(events);
+	const bundle: ExportedRunBundle = {
+		schemaVersion: 1,
+		exportedAt: new Date().toISOString(),
+		manifest: safeManifest as TeamRunManifest,
+		tasks: safeTasks as TeamTaskState[],
+		events: safeEvents as TeamEvent[],
+		artifactPaths: safeManifest.artifacts.map((artifact) => artifact.path),
+	};
+	// Compute SHA-256 integrity hash of the bundle and store in manifest
+	const sha256 = crypto.createHash("sha256").update(JSON.stringify(bundle)).digest("hex");
+	(bundle.manifest as unknown as Record<string, unknown>).sha256 = sha256;
+	const json = writeArtifact(manifest.artifactsRoot, {
+		kind: "metadata",
+		relativePath: "export/run-export.json",
+		producer: "run-export",
+		content: `${JSON.stringify(bundle, null, 2)}\n`,
+	});
+	const markdown = writeArtifact(manifest.artifactsRoot, {
+		kind: "summary",
+		relativePath: "export/run-export.md",
+		producer: "run-export",
+		content: [
+			`# pi-crew export ${safeManifest.runId}`,
+			"",
+			`Exported: ${bundle.exportedAt}`,
+			`Status: ${safeManifest.status}`,
+			`Team: ${safeManifest.team}`,
+			`Workflow: ${safeManifest.workflow ?? "(none)"}`,
+			`Goal: ${safeManifest.goal}`,
+			"",
+			"## Tasks",
+			...safeTasks.map(
+				(task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`,
+			),
+			"",
+			"## Artifacts",
+			...(safeManifest.artifacts.length
+				? safeManifest.artifacts.map((artifact) => `- ${artifact.kind}: ${artifact.path}`)
+				: ["- (none)"]),
+			"",
+			"## Recent Events",
+			...safeEvents
+				.slice(-20)
+				.map(
+					(event) =>
+						`- ${event.time} ${event.type}${event.taskId ? ` ${event.taskId}` : ""}${event.message ? `: ${event.message}` : ""}`,
+				),
+			"",
+		].join("\n"),
+	});
+	// Ensure artifact dirs are materialized before returning paths on filesystems with delayed metadata.
+	fs.statSync(path.dirname(json.path));
+	return { jsonPath: json.path, markdownPath: markdown.path };
+}

package/src/extension/run-import.ts

@@ -0,0 +1,168 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DEFAULT_PATHS } from "../config/defaults.ts";
+import { type ConflictReport, detectImportConflicts } from "../runtime/delta-conflict.ts";
+import { atomicWriteFile } from "../state/atomic-write.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+import { assertSafePathId, resolveContainedRelativePath, resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { assertRunBundle } from "./run-bundle-schema.ts";
+
+export interface ImportedRunBundleInfo {
+	runId: string;
+	importedAt: string;
+	bundlePath: string;
+	summaryPath: string;
+	conflictReport?: ConflictReport;
+}
+
+function importRoot(cwd: string, scope: "project" | "user"): string {
+	const base = scope === "project" ? projectCrewRoot(cwd) : userCrewRoot();
+	// SECURITY NOTE: `DEFAULT_PATHS.state.importsSubdir` is a constant (not user-controlled).
+	// If this constant ever becomes user-influenced, this function could become a path
+	// traversal risk. Always keep `importsSubdir` as a hardcoded constant. Do NOT accept
+	// `importsSubdir` as a parameter or from config.
+	return path.join(base, DEFAULT_PATHS.state.importsSubdir);
+}
+
+export function importRunBundle(cwd: string, bundlePath: string, scope: "project" | "user" = "project"): ImportedRunBundleInfo {
+	const resolvedPath = path.isAbsolute(bundlePath) ? bundlePath : path.resolve(cwd, bundlePath);
+	// Path containment: use resolveRealContainedPath for canonical real-path check
+	// to prevent symlink/../ bypass of the startsWith string comparison.
+	const allowedBases: string[] = [];
+	try {
+		allowedBases.push(userCrewRoot());
+	} catch {
+		/* ignore */
+	}
+	try {
+		allowedBases.push(projectCrewRoot(cwd));
+	} catch {
+		/* ignore */
+	}
+	allowedBases.push(cwd); // always include cwd last (highest priority)
+	let isContained = false;
+	for (const base of allowedBases) {
+		try {
+			resolveRealContainedPath(base, resolvedPath);
+			isContained = true;
+			break;
+		} catch {
+			/* not contained — try next base */
+		}
+	}
+	if (!isContained) throw new Error(`Import path must be within project directory or crew root: ${resolvedPath}`);
+	const raw = JSON.parse(fs.readFileSync(resolvedPath, "utf-8")) as unknown;
+	assertRunBundle(raw);
+
+	// Integrity check: verify SHA-256 hash if present in manifest.
+	// SECURITY NOTE: This SHA-256 is a CORRUPTION-DETECTION hash only — it
+	// detects accidental bit-rot or truncation during transfer. It is NOT an
+	// authenticity or tamper-resistance guarantee: the hash is stored INSIDE the
+	// bundle (self-referential), so an attacker who can modify the bundle file
+	// can also recompute and embed a matching hash. For tamper-evidence, an
+	// external HMAC or detached signature would be needed (out of scope).
+	// Blast radius is bounded: imports write to imports/<runId>/ only, execute
+	// no code, and are validated by isContained + assertSafePathId.
+	const bundleJson = fs.readFileSync(resolvedPath, "utf-8");
+	const parsedForHash = JSON.parse(bundleJson) as {
+		manifest?: { sha256?: string };
+	};
+	if (parsedForHash.manifest?.sha256) {
+		const expectedHash = parsedForHash.manifest.sha256;
+		// Recompute hash by stringifying the bundle without the sha256 field
+		const { sha256: _sha256, ...manifestWithoutHash } = parsedForHash.manifest as Record<string, unknown> & {
+			sha256?: string;
+		};
+		const bundleForHash = {
+			...parsedForHash,
+			manifest: manifestWithoutHash,
+		};
+		const recomputedHash = crypto.createHash("sha256").update(JSON.stringify(bundleForHash)).digest("hex");
+		if (recomputedHash !== expectedHash) {
+			throw new Error(`Integrity check failed: SHA-256 mismatch. Expected ${expectedHash}, got ${recomputedHash}`);
+		}
+	}
+
+	const runId = assertSafePathId("runId", raw.manifest.runId);
+	const importedAt = new Date().toISOString();
+
+	// FIND-11: audit the import for security traceability. The SHA-256 check
+	// above is corruption-detection only (NOT authenticity/tamper-resistance) —
+	// a tampered bundle carries a matching/absent hash. Use "warn" severity so
+	// this ALWAYS emits ("debug" is gated behind PI_TEAMS_DEBUG → no-op in prod).
+	logInternalError(
+		"security.bundle_imported",
+		new Error("bundle imported"),
+		`runId="${runId}" source="${resolvedPath}" scope="${scope}"`,
+		"warn",
+	);
+
+	// Non-blocking conflict detection: compare incoming bundle against any existing state.
+	let conflictReport: ConflictReport | undefined;
+	try {
+		const existingManifestPath = path.join(importRoot(cwd, scope), runId, "run-export.json");
+		if (fs.existsSync(existingManifestPath)) {
+			const existingRaw = JSON.parse(fs.readFileSync(existingManifestPath, "utf-8")) as {
+				manifest?: Record<string, unknown>;
+				tasks?: unknown[];
+			};
+			conflictReport = detectImportConflicts(
+				{
+					manifest: raw.manifest as unknown as Record<string, unknown>,
+					tasks: raw.tasks as unknown[],
+				},
+				{ manifest: existingRaw.manifest, tasks: existingRaw.tasks },
+			);
+		}
+	} catch {
+		// Conflict detection is best-effort; do not block import on failure.
+	}
+
+	const importsRoot = importRoot(cwd, scope);
+	fs.mkdirSync(importsRoot, { recursive: true });
+	if (fs.lstatSync(importsRoot).isSymbolicLink()) throw new Error(`Invalid import root: ${importsRoot}`);
+	resolveRealContainedPath(path.dirname(importsRoot), path.basename(importsRoot));
+	const root = resolveContainedRelativePath(importsRoot, runId, "runId");
+	fs.mkdirSync(root, { recursive: true });
+	// TOCTOU note: mkdirSync would throw EEXIST if a symlink already existed.
+	// The lstatSync check catches a symlink swapped in between mkdirSync and the check
+	// (theoretically possible but requires local attacker with exact timing).
+	// resolveRealContainedPath provides an additional real-path containment barrier.
+	if (fs.lstatSync(root).isSymbolicLink()) throw new Error(`Invalid import directory: ${root}`);
+	resolveRealContainedPath(importsRoot, runId);
+	const targetJson = path.join(root, "run-export.json");
+	const targetSummary = path.join(root, "README.md");
+	for (const target of [targetJson, targetSummary]) {
+		if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) throw new Error(`Invalid import target: ${target}`);
+	}
+	atomicWriteFile(targetJson, `${JSON.stringify({ ...raw, importedAt, importedFrom: resolvedPath }, null, 2)}\n`);
+	atomicWriteFile(
+		targetSummary,
+		[
+			`# Imported pi-crew run ${runId}`,
+			"",
+			`Imported: ${importedAt}`,
+			`Source: ${resolvedPath}`,
+			`Original export: ${raw.exportedAt}`,
+			`Status: ${raw.manifest.status}`,
+			`Team: ${raw.manifest.team}`,
+			`Workflow: ${raw.manifest.workflow ?? "(none)"}`,
+			`Goal: ${raw.manifest.goal}`,
+			"",
+			"## Tasks",
+			...raw.tasks.map(
+				(task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`,
+			),
+			"",
+		].join("\n"),
+	);
+	return {
+		runId,
+		importedAt,
+		bundlePath: targetJson,
+		summaryPath: targetSummary,
+		...(conflictReport?.hasConflicts ? { conflictReport } : {}),
+	};
+}