@humwick/server 0.0.0-stage → 0.130.0

package/src/project-mcp.ts

@@ -0,0 +1,18 @@
+// Project `.mcp.json` MCP projection (#667) — the relay-owned, OPT-IN path that hands a
+// spawned worker its spawn-cwd's COMMITTED `.mcp.json` servers, sourced from the PROJECT
+// (in-repo, trusted) rather than ambient host MCP. Sibling seam to project-instructions
+// (#409): same opt-in + projection shape, default OFF.
+//
+// PROVENANCE, NOT TYPE: "vanilla/zero-host-bleed" means relay OWNS provisioning and sources
+// it from the project, never the host. A repo's `.mcp.json` is part of the code the agent
+// works in; it should travel with the repo like it does for a human who clones it.
+//
+// DIVISION OF LABOR: relay only carries the OPT-IN DECISION (this module + the spawn
+// param/profile field). The actual file read + `--mcp-config` injection happens RUNNER-side
+// (launch-assembly.ts → resolveProjectMcpServers), which is the filesystem authority for the
+// spawn cwd (relay may run on a different host than the orchestrator). It composes with #662
+// `--strict-mcp-config` — the controlled inject path strict PRESERVES — and deliberately does
+// NOT enable Claude's ambient project-`.mcp.json` discovery, whose trust modal wedges headless
+// agents (the very reason #662 added strict to all managed launches).
+
+export const PROJECT_MCP_POLICY_NAMES = ["all"] as const;

package/src/project-role-assets.ts

@@ -0,0 +1,109 @@
+// #3587 — pinned role assets share native provisioning and the existing first-turn composer.
+import { getManifest } from "@humwick/providers";
+import { isProjectFilePath, isProjectRoleName, isRecord, stripControlBytes, type ProjectFilesSnapshot, type ProjectFilesRequest, type ProjectRoleAssets } from "@humwick/sdk";
+import { ValidationError } from "./db";
+import { estimateTextTokens } from "./memory-tokens";
+import { splitFrontmatter } from "./markdown-frontmatter";
+
+export const DEFAULT_ROLE_CONTEXT_TOKEN_CAP = 24_000;
+
+function list(value: unknown, field: string, where: string): string[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.some(item => typeof item !== "string" || !item.trim())) {
+    throw new ValidationError(`${where}: ${field} must be a list of non-empty strings`);
+  }
+  const entries = [...new Set((value as string[]).map(item => item.trim()))];
+  for (const entry of entries) {
+    if (!(field === "skills" ? isProjectRoleName(entry) : isProjectFilePath(entry))) {
+      throw new ValidationError(`${where}: invalid ${field} entry ${JSON.stringify(entry)}`);
+    }
+  }
+  return entries;
+}
+
+function declarations(frontmatter: Record<string, unknown>, where: string) {
+  const cap = frontmatter.contextTokenCap ?? DEFAULT_ROLE_CONTEXT_TOKEN_CAP;
+  if (!Number.isSafeInteger(cap) || (cap as number) <= 0) throw new ValidationError(`${where}: contextTokenCap must be a positive integer`);
+  return { skills: list(frontmatter.skills, "skills", where), context: list(frontmatter.context, "context", where), cap: cap as number };
+}
+
+/** Expand only declared assets, with every follow-up read pinned to the initial snapshot. */
+export async function hydrateRoleAssets(snapshot: ProjectFilesSnapshot, read: (request: ProjectFilesRequest) => Promise<ProjectFilesSnapshot>): Promise<ProjectFilesSnapshot> {
+  const context = new Set<string>();
+  const skills = new Set<string>();
+  for (const [path, text] of Object.entries(snapshot.files)) {
+    if (!/^\.agent-relay\/roles\/[^/]+\.md$/.test(path) || text === null) continue;
+    try {
+      const { frontmatter } = splitFrontmatter(text, path);
+      if (!isRecord(frontmatter)) continue;
+      const declared = declarations(frontmatter, path);
+      declared.context.forEach(file => context.add(file));
+      declared.skills.forEach(name => skills.add(name));
+    } catch { /* The role parser reports malformed declarations, including in catalog entries. */ }
+  }
+  if (!context.size && !skills.size) return snapshot;
+  const files = { ...snapshot.files };
+  const merge = async (request: ProjectFilesRequest) => {
+    const extra = await read({ ...request, sha: snapshot.sha });
+    if (extra.sha !== snapshot.sha) throw new ValidationError(`role assets were read at ${extra.sha}, expected ${snapshot.sha}`);
+    Object.assign(files, extra.files);
+  };
+  const paths = [...context].filter(path => files[path] === undefined);
+  for (let i = 0; i < paths.length; i += 32) await merge({ paths: paths.slice(i, i + 32) });
+  for (const name of skills) {
+    const dir = `.claude/skills/${name}`;
+    await merge({ paths: [`${dir}/SKILL.md`], dir });
+  }
+  return { ...snapshot, files };
+}
+
+export function parseRoleAssets(name: string, frontmatter: Record<string, unknown>, snapshot: ProjectFilesSnapshot, where: string): ProjectRoleAssets | undefined {
+  const declared = declarations(frontmatter, where);
+  if (!declared.context.length && !declared.skills.length) return undefined;
+  const content = (path: string, kind: string): string => {
+    const text = snapshot.files[path];
+    if (text === undefined || text === null) throw new ValidationError(`${where}: ${kind} ${JSON.stringify(path)} does not exist at ${snapshot.sha}`);
+    const clean = stripControlBytes(text);
+    if (clean !== text) console.warn(`${where}: stripped control bytes from ${path}`);
+    return clean;
+  };
+  const assets: ProjectRoleAssets = {
+    role: name, sha: snapshot.sha, contextTokenCap: declared.cap,
+    context: declared.context.map(path => ({ path, content: content(path, "context file") })),
+    skills: declared.skills.map(skill => {
+      const dir = `.claude/skills/${skill}/`;
+      content(`${dir}SKILL.md`, `unknown skill "${skill}": skill file`);
+      return { kind: "skill", name: skill, files: Object.keys(snapshot.files).filter(path => path.startsWith(dir) && snapshot.files[path] !== null)
+        .map(path => ({ path: path.slice(dir.length), content: content(path, "skill file") })) };
+    }),
+  };
+  const warning = roleAssetBudgetWarning(assets);
+  // #3587: validation refuses overflow; compiled launches only warn (docs/specs/3587-role-assets.md).
+  if (warning) throw new ValidationError(warning);
+  return assets;
+}
+
+/** Re-check compiled content at launch without dropping or truncating stored assets. */
+export function roleAssetBudgetWarning(assets: ProjectRoleAssets | undefined): string | undefined {
+  if (!assets) return undefined;
+  const counts = [...assets.context, ...assets.skills.flatMap(skill => (skill.files ?? []).map(file => ({ ...file, path: `.claude/skills/${skill.name}/${file.path}` })))]
+    .map(file => ({ path: file.path, tokens: estimateTextTokens(file.content) }));
+  const total = counts.reduce((sum, file) => sum + file.tokens, 0);
+  return total > assets.contextTokenCap
+    ? `project role "${assets.role}" at ${assets.sha}: ${total} estimated tokens exceeds contextTokenCap ${assets.contextTokenCap}; ${counts.map(file => `${file.path}: ${file.tokens} tokens`).join("; ")}`
+    : undefined;
+}
+
+export function composeRoleAssets(assets: ProjectRoleAssets | undefined, provider: string | undefined): string | undefined {
+  if (!assets) return undefined;
+  const blocks: string[] = [];
+  if (assets.context.length) blocks.push(`# Role context (${assets.role}, ${assets.sha})\n\n${assets.context.map(file => `## ${file.path}\n\n${file.content}`).join("\n\n")}`);
+  if (assets.skills.length) {
+    const kind = provider && getManifest(provider)?.shim?.kind;
+    const native = kind === "codex-relay" || kind === "claude-relay";
+    blocks.push(native
+      ? `# Required project skills\n\nUse ${assets.skills.map(skill => `\`${skill.name}\``).join(", ")} before starting work.`
+      : `# Required project skills\n\n${assets.skills.flatMap(skill => (skill.files ?? []).map(file => `## ${skill.name}/${file.path}\n\n${file.content}`)).join("\n\n")}`);
+  }
+  return blocks.join("\n\n") || undefined;
+}

package/src/project-roles-validate.ts

@@ -0,0 +1,53 @@
+// #3043 — one validator for every file under `.agent-relay/roles/` at one commit. Pure: the
+// `roles validate` land gate, relay_spawn_targets discovery and (#3045) the workflow loader share it.
+
+import { isProjectRoleName, PROJECT_ROLES_DIR, SPAWN_PROVIDERS, type AgentProfile, type ProjectFilesSnapshot, type SpawnProvider } from "@humwick/sdk";
+import { parseProjectRole, projectRoleProfile } from "./project-roles";
+
+export interface ProjectRoleReport {
+  name: string;
+  path: string;
+  description?: string;
+  /** The base profile the role names (default worker). Absent when the file did not parse. */
+  base?: string;
+  /** Providers the role can run on; empty when it has errors. */
+  providers: SpawnProvider[];
+  errors: string[];
+}
+
+function roleFileName(path: string): string | undefined {
+  const prefix = `${PROJECT_ROLES_DIR}/`;
+  return path.startsWith(prefix) && path.endsWith(".md") && !path.slice(prefix.length).includes("/") ? path.slice(prefix.length, -".md".length) : undefined;
+}
+
+/** Validate every role file in `snapshot` (read with `dir: PROJECT_ROLES_DIR` plus `.mcp.json`): one
+ *  report per file, sorted, each with the parser's first error. With `profiles` (lowercase name to
+ *  profile) the base is resolved and compiled too, so a bad `extends` fails here, not at first spawn. */
+export function validateProjectRoles(snapshot: ProjectFilesSnapshot, options: { profiles?: ReadonlyMap<string, AgentProfile> } = {}): ProjectRoleReport[] {
+  const reports: ProjectRoleReport[] = [];
+  for (const [path, text] of Object.entries(snapshot.files)) {
+    const name = roleFileName(path);
+    if (name === undefined || text === null) continue;
+    const report: ProjectRoleReport = { name, path, providers: [], errors: [] };
+    reports.push(report);
+    if (!isProjectRoleName(name)) {
+      report.errors.push(`${path}: "${name}" is not a valid role name (letters, digits, "." "_" "-"; at most 64 characters)`);
+      continue;
+    }
+    try {
+      const role = parseProjectRole(name, snapshot);
+      report.base = role.extends;
+      if (role.description) report.description = role.description;
+      if (options.profiles) {
+        const base = options.profiles.get(role.extends.toLowerCase());
+        if (!base) throw new Error(`${path}: project role "${name}" extends unknown profile "${role.extends}"`);
+        projectRoleProfile(base, role);
+      }
+      report.providers = [...SPAWN_PROVIDERS];
+    } catch (error) {
+      const message = (error as Error).message;
+      report.errors.push(message.includes(path) ? message : `${path}: ${message}`);
+    }
+  }
+  return reports.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/project-roles.ts

@@ -0,0 +1,364 @@
+import { splitFrontmatter } from "./markdown-frontmatter";
+import { hydrateRoleAssets, parseRoleAssets } from "./project-role-assets";
+// #3043 — project roles: `.agent-relay/roles/<name>.md` in the spawn's repo, read at ONE landed
+// default-branch commit on a host that owns the checkout, compiled into an in-flight
+// AgentProfile overlay. Never persisted. A role may append instructions, select named `.mcp.json`
+// entries, choose dispatch/model/effort and narrow workspace policy; every other field is refused.
+
+import { isAbsolute, resolve } from "node:path";
+import {
+  coerceProjectMcpServer,
+  isFullCommitSha,
+  isProjectRoleName,
+  isRecord,
+  isAgentLifecycle,
+  isSpawnProvider,
+  PROJECT_FETCH_TIMEOUT_MS,
+  PROJECT_MCP_FILE,
+  profileProjectSourceEnabled,
+  projectGitOutputCap,
+  projectRoleFiles,
+  projectRolePath,
+  readProjectFiles,
+  VALID_WORKSPACE_MODES,
+  type AgentLifecycle,
+  type AgentProfile,
+  type Orchestrator,
+  type ProjectFilesRequest,
+  type ProjectFilesSnapshot,
+  type ProjectGit,
+  type ProjectRoleProvenance,
+  type ProvisioningMcpServer,
+  type SpawnProvider,
+  type TaskDispatch,
+  type WorkspaceMode,
+} from "@humwick/sdk";
+import type { BuiltInProfileSpawnDefaults } from "./agent-profile-catalog";
+import { bundledRoleText } from "./bundled-workflows";
+import { isTrustedOrchestratorApiUrl } from "./config";
+import { mergeProfileOverride } from "./config-store";
+import { cleanTaskDispatch } from "./db/task-entity";
+import { ValidationError } from "./db";
+import { McpNotFoundError } from "./mcp-errors";
+import { projectTrustFix } from "./project-trust";
+import { runGit, toProjectGitResult } from "./services/git-process";
+import { isOrchestratorLocalToRelay } from "./utils";
+import { fetchHostJson } from "./workspace-host-client";
+
+const RELAY_MCP_SERVER_NAME = "agent-relay";
+const DEFAULT_ROLE_BASE = "worker";
+export const ROLE_FIELDS = ["description", "extends", "mcp", "dispatch", "models", "effort", "workspace", "skills", "context", "contextTokenCap"] as const;
+export const WORKSPACE_FIELDS = ["mode", "landBlocked", "lifecycle"] as const;
+export const DISPATCH_FIELDS = ["type", "complexity", "contextFootprint", "criticality"] as const;
+const READ_TIMEOUT_MS = 5_000;
+/** The host's refresh fetch plus its local reads must finish inside the relay's wait. */
+const HOST_READ_TIMEOUT_MS = PROJECT_FETCH_TIMEOUT_MS + 10_000;
+
+export interface ProjectRole {
+  assets?: AgentProfile["roleAssets"];
+  name: string;
+  description?: string;
+  extends: string;
+  dispatch?: TaskDispatch;
+  models?: Partial<Record<SpawnProvider, string>>;
+  effort?: string;
+  workspace?: { mode?: WorkspaceMode; landBlocked?: true; lifecycle?: AgentLifecycle };
+  body: string;
+  source: Pick<ProjectFilesSnapshot, "ref" | "sha" | "fetched" | "fetchError">;
+  /** The selected `.mcp.json` entries at `source.sha`, before the cwd check. */
+  mcpServers: Record<string, ProvisioningMcpServer & { cwd?: string }>;
+  /** #3120 — the repo has no role of this name at `source.sha`, so this is Relay's bundled one. */
+  bundled?: true;
+  /** #3091 — `extends` is a workflow step's profile pin, not the role file's own. */
+  profilePinned?: true;
+}
+
+function at(name: string, snapshot: Pick<ProjectFilesSnapshot, "ref" | "sha">): string {
+  return `project role "${name}" (${projectRolePath(name)} at ${snapshot.ref} ${snapshot.sha.slice(0, 12)})`;
+}
+
+function rejectUnknownFields(value: Record<string, unknown>, allowed: readonly string[], where: string): void {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw new ValidationError(`${where}: unknown field${unknown.length > 1 ? "s" : ""} ${unknown.map((key) => `"${key}"`).join(", ")}; allowed: ${allowed.join(", ")}`);
+}
+
+
+function optionalString(value: unknown, field: string, where: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError(`${where}: ${field} must be a non-empty string`);
+  return value.trim();
+}
+
+function parseDispatch(value: unknown, where: string): TaskDispatch | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError(`${where}: dispatch must be an object`);
+  rejectUnknownFields(value, DISPATCH_FIELDS, `${where} dispatch`);
+  try {
+    return cleanTaskDispatch(value);
+  } catch (error) {
+    throw new ValidationError(`${where}: ${(error as Error).message}`);
+  }
+}
+
+function parseModels(value: unknown, where: string): ProjectRole["models"] {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError(`${where}: models must map a provider to a model`);
+  const out: Partial<Record<SpawnProvider, string>> = {};
+  for (const [provider, model] of Object.entries(value)) {
+    if (!isSpawnProvider(provider)) throw new ValidationError(`${where}: models names unknown provider "${provider}"`);
+    out[provider] = optionalString(model, `models.${provider}`, where);
+  }
+  return out;
+}
+
+function parseWorkspace(value: unknown, where: string): ProjectRole["workspace"] {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError(`${where}: workspace must be an object`);
+  rejectUnknownFields(value, WORKSPACE_FIELDS, `${where} workspace`);
+  const out: NonNullable<ProjectRole["workspace"]> = {};
+  if (value.mode !== undefined) {
+    if (!(VALID_WORKSPACE_MODES as readonly unknown[]).includes(value.mode)) throw new ValidationError(`${where}: workspace.mode must be one of ${VALID_WORKSPACE_MODES.join(", ")}`);
+    out.mode = value.mode as WorkspaceMode;
+  }
+  if (value.landBlocked !== undefined) {
+    // A role can only add a land block; lifting one is never its call.
+    if (value.landBlocked !== true) throw new ValidationError(`${where}: workspace.landBlocked can only be true`);
+    out.landBlocked = true;
+  }
+  if (value.lifecycle !== undefined) {
+    if (!isAgentLifecycle(value.lifecycle)) throw new ValidationError(`${where}: workspace.lifecycle must be persistent or transient`);
+    out.lifecycle = value.lifecycle;
+  }
+  return out;
+}
+
+function parseMcpNames(value: unknown, where: string): string[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new ValidationError(`${where}: mcp must be a list of ${PROJECT_MCP_FILE} server names`);
+  const names = value.map((entry) => {
+    if (typeof entry !== "string" || !entry.trim()) throw new ValidationError(`${where}: mcp entries must be ${PROJECT_MCP_FILE} server names; scoped entries are not supported`);
+    const name = entry.trim();
+    if (name === RELAY_MCP_SERVER_NAME) throw new ValidationError(`${where}: "${RELAY_MCP_SERVER_NAME}" is Relay's own MCP and is always present; do not select it`);
+    return name;
+  });
+  return [...new Set(names)];
+}
+
+/** A file the snapshot read; asking for one it did not read is a caller bug, not a missing file. */
+function fileAt(snapshot: ProjectFilesSnapshot, path: string): string | null {
+  const text = snapshot.files[path];
+  if (text === undefined) throw new Error(`${path} was not read at ${snapshot.sha}`);
+  return text;
+}
+
+function selectMcpServers(names: string[], snapshot: ProjectFilesSnapshot, where: string): ProjectRole["mcpServers"] {
+  if (!names.length) return {};
+  const mcpJson = fileAt(snapshot, PROJECT_MCP_FILE);
+  let declared: Record<string, unknown> = {};
+  if (mcpJson !== null) {
+    try {
+      const parsed = JSON.parse(mcpJson) as unknown;
+      declared = isRecord(parsed) && isRecord(parsed.mcpServers) ? parsed.mcpServers : {};
+    } catch (error) {
+      throw new ValidationError(`${where}: ${PROJECT_MCP_FILE} at that commit is not valid JSON: ${(error as Error).message}`);
+    }
+  }
+  const out: ProjectRole["mcpServers"] = {};
+  for (const name of names) {
+    const raw = declared[name];
+    if (raw === undefined) {
+      throw new ValidationError(`${where} names MCP server "${name}", which is not in ${PROJECT_MCP_FILE} at that commit${mcpJson === null ? " (the file does not exist there)" : ""}`);
+    }
+    const server = coerceProjectMcpServer(raw);
+    if (!server) throw new ValidationError(`${where}: ${PROJECT_MCP_FILE} entry "${name}" has neither a command nor a url`);
+    const cwd = isRecord(raw) && typeof raw.cwd === "string" ? raw.cwd : undefined;
+    out[name] = cwd === undefined ? server : { ...server, cwd };
+  }
+  return out;
+}
+
+/** Validate a role snapshot. Unknown role and unknown MCP names fail with the file and commit. */
+export function parseProjectRole(name: string, snapshot: ProjectFilesSnapshot): ProjectRole {
+  const where = at(name, snapshot);
+  const text = fileAt(snapshot, projectRolePath(name));
+  if (text === null) {
+    throw new McpNotFoundError(`project role "${name}" not found: ${projectRolePath(name)} does not exist at ${snapshot.ref} ${snapshot.sha.slice(0, 12)}`);
+  }
+  const { frontmatter, body } = splitFrontmatter(text, where);
+  if (!isRecord(frontmatter)) throw new ValidationError(`${where}: frontmatter must be a YAML mapping`);
+  rejectUnknownFields(frontmatter, ROLE_FIELDS, where);
+  if (!body) throw new ValidationError(`${where}: the role body (instructions after the frontmatter) is empty`);
+  const description = optionalString(frontmatter.description, "description", where);
+  const dispatch = parseDispatch(frontmatter.dispatch, where);
+  const models = parseModels(frontmatter.models, where);
+  const effort = optionalString(frontmatter.effort, "effort", where);
+  const workspace = parseWorkspace(frontmatter.workspace, where);
+  const assets = parseRoleAssets(name, frontmatter, snapshot, where);
+  return {
+    name,
+    ...(assets ? { assets } : {}),
+    ...(description ? { description } : {}),
+    extends: optionalString(frontmatter.extends, "extends", where) ?? DEFAULT_ROLE_BASE,
+    ...(dispatch && Object.keys(dispatch).length ? { dispatch } : {}),
+    ...(models && Object.keys(models).length ? { models } : {}),
+    ...(effort ? { effort } : {}),
+    ...(workspace && Object.keys(workspace).length ? { workspace } : {}),
+    body,
+    source: { ref: snapshot.ref, sha: snapshot.sha, fetched: snapshot.fetched, ...(snapshot.fetchError ? { fetchError: snapshot.fetchError } : {}) },
+    mcpServers: selectMcpServers(parseMcpNames(frontmatter.mcp, where), snapshot, where),
+  };
+}
+
+/** #3120 — the repo's role at the snapshot's commit, else Relay's bundled role of that name. The one
+ *  resolution every role read uses: a spawn, a restart and a workflow step. */
+export function resolveProjectRole(name: string, snapshot: ProjectFilesSnapshot): ProjectRole {
+  const path = projectRolePath(name);
+  const bundled = fileAt(snapshot, path) === null ? bundledRoleText(name) : undefined;
+  if (bundled === undefined) return parseProjectRole(name, snapshot);
+  return { ...parseProjectRole(name, { ...snapshot, files: { ...snapshot.files, [path]: bundled } }), bundled: true };
+}
+
+/** The host's answer must be exactly what was asked: every requested path, at the requested commit. */
+function checkSnapshot(value: unknown, request: ProjectFilesRequest): { ok: true; value: ProjectFilesSnapshot } | { ok: false; reason: string } {
+  if (!isRecord(value) || typeof value.ref !== "string" || !isFullCommitSha(value.sha) || typeof value.fetched !== "boolean"
+    || (value.fetchError !== undefined && typeof value.fetchError !== "string") || !isRecord(value.files)) return { ok: false, reason: "invalid project-files response" };
+  const files = value.files;
+  if (!request.paths.every((path) => files[path] === null || typeof files[path] === "string") || !Object.values(files).every((text) => text === null || typeof text === "string")) return { ok: false, reason: "the response is missing requested files" };
+  if (request.dir !== undefined && value.dir !== request.dir) return { ok: false, reason: "the orchestrator did not list the requested directory (upgrade it)" };
+  // #3120 — an orchestrator that predates `dirExt` lists `*.md` instead: an empty listing that looks real.
+  if (request.dirExt !== undefined && value.dirExt !== request.dirExt) return { ok: false, reason: `the orchestrator cannot list ${request.dirExt} files (upgrade it)` };
+  if (request.sha !== undefined && value.sha !== request.sha) return { ok: false, reason: `the orchestrator answered at ${value.sha}, not the requested commit (upgrade it)` };
+  return { ok: true, value: value as unknown as ProjectFilesSnapshot };
+}
+
+export function localProjectGit(cwd: string): ProjectGit {
+  return async (args, options) => {
+    const result = options?.network
+      ? await runGit(["-C", cwd, ...args], PROJECT_FETCH_TIMEOUT_MS, 256 * 1024)
+      : await runGit(["-C", cwd, ...args], READ_TIMEOUT_MS, projectGitOutputCap(256 * 1024, options), options?.input);
+    return toProjectGitResult(result);
+  };
+}
+
+/** Read project files where the agent will run: this process's git for its own host, otherwise
+ *  the target orchestrator's route. Never this process's disk for another host. */
+export async function readHostProjectFiles(host: Orchestrator, cwd: string, request: ProjectFilesRequest, subject: string): Promise<ProjectFilesSnapshot> {
+  const where = `${subject} on ${host.id}`;
+  const target = request.sha === undefined ? cwd : `${cwd} at ${request.sha}`;
+  if (host.apiUrl) {
+    if (!isTrustedOrchestratorApiUrl(host.apiUrl)) throw new ValidationError(`${where}: the orchestrator API URL is not trusted`);
+    const query = new URLSearchParams({ path: cwd });
+    for (const path of request.paths) query.append("file", path);
+    if (request.sha !== undefined) query.set("sha", request.sha);
+    if (request.dir !== undefined) query.set("dir", request.dir);
+    if (request.dirExt !== undefined) query.set("dirExt", request.dirExt);
+    const result = await fetchHostJson<{ snapshot?: ProjectFilesSnapshot; error?: string }>(host.apiUrl, "/api/repo/project-files", {
+      query,
+      timeoutMs: HOST_READ_TIMEOUT_MS,
+      validate: (body) => {
+        if (!isRecord(body)) return { ok: false, reason: "invalid project-files response" };
+        if (body.snapshot === undefined && typeof body.error === "string") return { ok: true, value: { error: body.error } };
+        const checked = checkSnapshot(body.snapshot, request);
+        return checked.ok ? { ok: true, value: { snapshot: checked.value } } : checked;
+      },
+    });
+    if (!result.ok) {
+      const failure = result.failure;
+      const detail = failure.stage === "http"
+        ? failure.status === 404 ? "the orchestrator is too old to read project files at a landed commit (upgrade it)" : `HTTP ${failure.status}`
+        : failure.stage === "validate" ? failure.reason : failure.error;
+      throw new ValidationError(`${where}: cannot read ${target}: ${detail}`);
+    }
+    if (!result.value.snapshot) throw new ValidationError(`${where}: cannot read ${target}: ${result.value.error}`);
+    return result.value.snapshot;
+  }
+  if (!isOrchestratorLocalToRelay(host)) throw new ValidationError(`${where}: the host has no API URL, so its checkout cannot be read`);
+  try {
+    return await readProjectFiles(request, localProjectGit(cwd));
+  } catch (error) {
+    throw new ValidationError(`${where}: cannot read ${target}: ${(error as Error).message}`);
+  }
+}
+
+/** The role at the default branch's tip (refreshed first), or at `sha` when it is landed; else the bundled one. */
+export async function readProjectRole(host: Orchestrator, cwd: string, name: string, sha?: string): Promise<ProjectRole> {
+  if (!isProjectRoleName(name)) throw new ValidationError(`invalid project role name ${JSON.stringify(name)}`);
+  const request = { paths: projectRoleFiles(name), ...(sha !== undefined ? { sha } : {}) };
+  const read = (request: ProjectFilesRequest) => readHostProjectFiles(host, cwd, request, `project role "${name}"`);
+  return resolveProjectRole(name, await hydrateRoleAssets(await read(request), read));
+}
+
+/**
+ * The in-flight profile a role spawns with. The base profile's appended instructions are kept and
+ * the role body follows them. MCP is narrowed to Relay's own endpoint plus the selected entries:
+ * provisioned, host and shared-bridge servers are off, and the runner never reads cwd `.mcp.json`.
+ */
+export function projectRoleProfile(base: AgentProfile, role: ProjectRole): AgentProfile {
+  const where = `project role "${role.name}"`;
+  const selected = Object.keys(role.mcpServers);
+  if (selected.length && !profileProjectSourceEnabled(base, "mcp")) {
+    throw new ValidationError(`${where} selects MCP servers, but its base profile "${base.name}" does not enable project MCP; extend a profile that does (for example QA)`);
+  }
+  const merged = mergeProfileOverride(base, {
+    instructions: { append: [...(base.instructions?.append ?? []), role.body] },
+  });
+  delete merged.sharedMcp;
+  merged.mcp = { ...merged.mcp, mode: "none" };
+  if (merged.provisioning) merged.provisioning = { ...merged.provisioning, mcpServers: {} };
+  if (merged.sources) merged.sources = { ...merged.sources, host: { ...merged.sources.host, mcp: { ...merged.sources.host.mcp, enabled: false } } };
+  merged.pinnedProjectMcp = {
+    sha: role.source.sha,
+    servers: Object.fromEntries(Object.entries(role.mcpServers).map(([name, { cwd: _cwd, ...server }]) => [name, server])),
+  };
+  if (role.assets) {
+    merged.roleAssets = role.assets;
+    const provisioning = merged.provisioning ?? { skills: [], plugins: [], hooks: [], mcpServers: {} };
+    const selected = new Set(role.assets.skills.map(skill => skill.name));
+    merged.provisioning = { ...provisioning, skills: [...provisioning.skills.filter(skill => !selected.has(skill.name)), ...role.assets.skills] };
+  }
+  return merged;
+}
+
+/** Q2 — a selected entry may only name the agent's own workspace as its cwd. */
+export function assertProjectRoleMcpCwd(role: ProjectRole, workspaceCwd: string): void {
+  for (const [name, server] of Object.entries(role.mcpServers)) {
+    if (server.cwd === undefined) continue;
+    const cwd = isAbsolute(server.cwd) ? resolve(server.cwd) : resolve(workspaceCwd, server.cwd);
+    if (cwd !== resolve(workspaceCwd)) {
+      throw new ValidationError(`project role "${role.name}": ${PROJECT_MCP_FILE} entry "${name}" sets cwd ${server.cwd}, but the agent runs in ${workspaceCwd}; remove cwd from the entry so it runs in the agent's workspace`);
+    }
+  }
+}
+
+export function projectRoleProvenance(role: ProjectRole): ProjectRoleProvenance {
+  return {
+    name: role.name, ref: role.source.ref, sha: role.source.sha, fetched: role.source.fetched,
+    ...(role.bundled ? { bundled: true as const } : {}), ...(role.profilePinned ? { profile: role.extends } : {}),
+  };
+}
+
+/** #3091 — the role on a workflow step's pinned base profile instead of the one its file extends. */
+export function withRoleProfile(role: ProjectRole, profile: string | undefined): ProjectRole {
+  return profile && profile !== role.extends ? { ...role, extends: profile, profilePinned: true } : role;
+}
+
+/** The base profile's code-owned spawn defaults with the role's work shape and lifecycle. A role
+ *  can add a land block to its base's, never remove one. */
+export function projectRoleSpawnDefaults(defaults: BuiltInProfileSpawnDefaults, role: ProjectRole | undefined): BuiltInProfileSpawnDefaults {
+  if (!role) return defaults;
+  return {
+    ...defaults,
+    ...(role.dispatch ? { dispatch: role.dispatch } : {}),
+    ...(role.workspace?.lifecycle ? { lifecycle: role.workspace.lifecycle } : {}),
+    ...(role.workspace?.landBlocked ? { landBlocked: true } : {}),
+  };
+}
+
+/** A role names its MCP servers explicitly, so a trust gate that drops them fails the spawn. */
+export function assertProjectRoleMcpTrusted(role: ProjectRole, profile: AgentProfile): void {
+  const gate = profile.projectGates?.mcp;
+  if (!Object.keys(role.mcpServers).length || !profile.sources?.project || gate?.allowed) return;
+  const fix = gate && projectTrustFix(profile.name, "mcp", gate);
+  throw new ValidationError(`project role "${role.name}": its MCP servers are not trusted for this spawn (${gate?.detail ?? "no trust decision"}); `
+    + `base profile "${profile.name}", sources.project.mcp${fix ? `; fix: ${fix}` : ""}`);
+}

package/src/project-settings.ts

@@ -0,0 +1,5 @@
+// Project `.claude/settings.json` projection (#669) — sibling to projectMcp (#667).
+// Relay carries only the opt-in decision; the runner reads/sanitizes the project settings
+// and injects them through the controlled Claude `--settings` path.
+
+export const PROJECT_SETTINGS_POLICY_NAMES = ["all"] as const;

package/src/project-skills.ts

@@ -0,0 +1,5 @@
+// Project `.claude/skills` projection (#668) — sibling to projectMcp (#667).
+// Relay carries only the opt-in decision; the runner reads the spawn cwd and materializes
+// project-committed skills into the managed Claude config home.
+
+export const PROJECT_SKILLS_POLICY_NAMES = ["all"] as const;

package/src/project-toolchain.ts

@@ -0,0 +1,58 @@
+// #2947 — the toolchain facts the orchestrator's resolver produced, validated here and read by the agent,
+// spawn-receipt and host surfaces. An agent's come from its own registration, a host's from its roster.
+import { isRecord, type HostProjectToolchainStatus, type HostView, type Orchestrator, type ProjectTool, type ProjectToolchain } from "@humwick/sdk";
+import type { AgentCard } from "./types";
+
+const MAX_TOOLS = 16;
+const MAX_OVERRIDES = 8;
+const MAX_TEXT = 500;
+
+const text = (value: unknown): string | undefined => typeof value === "string" && value.trim() ? value.trim().slice(0, MAX_TEXT) : undefined;
+
+/** Lenient on purpose: a malformed toolchain is dropped, never a reason to reject the whole roster. */
+export function cleanProjectToolchain(value: unknown): ProjectToolchain | undefined {
+  const project = isRecord(value) ? text(value.project) : undefined;
+  if (!project || !isRecord(value) || !Array.isArray(value.tools)) return undefined;
+  const tools = value.tools.slice(0, MAX_TOOLS).flatMap((entry): ProjectTool[] => {
+    if (!isRecord(entry)) return [];
+    const tool = text(entry.tool);
+    const version = text(entry.version);
+    const source = text(entry.source);
+    if (!tool || !version || !source) return [];
+    const overrides = Array.isArray(entry.overrides) ? entry.overrides.slice(0, MAX_OVERRIDES).map(text).filter((path): path is string => !!path) : [];
+    return [{ tool, version, source, ...(overrides.length ? { overrides } : {}) }];
+  });
+  return { project, tools };
+}
+
+export function cleanHostProjectToolchainStatus(value: unknown): HostProjectToolchainStatus | undefined {
+  if (!isRecord(value) || value.resolver !== "mise") return undefined;
+  const miseBin = text(value.miseBin);
+  const miseVersion = text(value.miseVersion);
+  const error = text(value.error);
+  return { resolver: "mise", ...(miseBin ? { miseBin } : {}), ...(miseVersion ? { miseVersion } : {}), ...(error ? { error } : {}) };
+}
+
+/** The toolchain the agent registered with: written in the same event that makes it "registered". */
+export function agentToolchain(agent: Pick<AgentCard, "meta">): ProjectToolchain | undefined {
+  return cleanProjectToolchain(agent.meta?.toolchain);
+}
+
+export function attachToolchain(agent: AgentCard): AgentCard {
+  const toolchain = agentToolchain(agent);
+  return toolchain ? { ...agent, toolchain } : agent;
+}
+
+/** A host's resolver (from its newest live generation) and one entry per project its live agents run, newest first. */
+export function hostProjectToolchain(liveGenerations: Orchestrator[]): HostView["projectToolchain"] {
+  const newestFirst = [...liveGenerations].sort((a, b) => b.lastSeen - a.lastSeen);
+  const resolver = cleanHostProjectToolchainStatus(newestFirst[0]?.meta?.projectToolchain);
+  const projects = new Map<string, ProjectToolchain>();
+  for (const orch of newestFirst) {
+    for (const agent of [...orch.managedAgents].sort((a, b) => b.startedAt - a.startedAt)) {
+      if (agent.toolchain && !projects.has(agent.toolchain.project)) projects.set(agent.toolchain.project, agent.toolchain);
+    }
+  }
+  if (!resolver && projects.size === 0) return undefined;
+  return { ...(resolver ? { resolver } : {}), projects: [...projects.values()] };
+}