@humwick/server 0.0.0-stage → 0.130.0

package/src/profile-effective-survey.ts

@@ -0,0 +1,121 @@
+// #1963 N3 — the effective-profile survey (the G1 fix the Opus-5 review demanded). It reports each
+// profile's disposition from its EFFECTIVE merged-override shape (seed + persisted
+// `agent-profile-override` row), NOT from the seed alone — because a prod override that sets
+// `projectSkills`/`projectSettings` silently forces an isolated home and drops the ambient project
+// scope (repo hooks OFF). Reading the seed misses that flip; §3.2's old table did exactly that and
+// mislabelled `worker`/`reviewer`. This is the measurement that must exist BEFORE any behaviour
+// moves, so the migration's effect is observed rather than asserted (see #1963 R1).
+//
+// The disposition predicates mirror the runner's launch mechanism and MUST stay in step with it:
+//   - `projectConfigProjectionOn`      → runner/src/profile-home.ts:35-37
+//   - managed home: always for a profiled launch (#3387, runner/src/profile-home.ts)
+//   - the `--setting-sources` arg → runner/src/launch-assembly.ts (Project cells)
+// `projectConfigProjectionOn` is re-derived here (not imported) because the runner cannot be
+// imported into the relay-side config layer; the parity is locked by
+// profile-effective-survey.test.ts. `projectSettingSourcesOn`, however, IS shared — it lives in
+// @humwick/sdk (`projectSettingSourcesOn`, #2084) so this survey, the runner, and the v2 cell
+// deriver (src/profile-cells.ts) can never drift out of step again. The base-derivation refactor
+// that would UNIFY the remaining predicates lives in the heavy nodes (N5/N10), out of this
+// increment's scope.
+
+import { projectInstructionsOn, projectSettingSourcesOn as sdkProjectSettingSourcesOn, type AgentProfile, type AgentProfileBase, type AgentProfileProvider, type SpawnProvider } from "@humwick/sdk";
+import { getManifest } from "@humwick/providers";
+import { listAgentProfiles } from "./config-store.ts";
+
+export type EffectiveProjectHooks = "off" | "ambient" | "n/a";
+/** Repo CLAUDE.md/AGENTS.md disposition: `ambient` loaded via the native project scope,
+ *  `reinjected` honored through Relay's controlled channel after the scope was dropped to gate
+ *  ambient hooks (#2086), `off` not loaded, `n/a` for a provider with no `--setting-sources`. */
+export type EffectiveProjectInstructions = "off" | "ambient" | "reinjected" | "n/a";
+
+export interface EffectiveProfileDisposition {
+  /** True when the profile sets `projectSkills` or `projectSettings` — the trigger that forces an
+   *  isolated home even on `base:"host"` and emits `--setting-sources user` (Claude). */
+  projectConfigProjectionOn: boolean;
+  /** True when any Project instructions, hooks, or settings cell enables the native project scope. */
+  projectSettingSourcesOn: boolean;
+  /** The provider config home the launch actually uses: `isolated` (managed) or `host`. */
+  derivedHome: "isolated" | "host";
+  /** The effective Claude `--setting-sources`, or `"default"` when the flag is absent (loads every
+   *  scope: empirically `user,project,local` — the measured, undocumented CLI default; see #1963). */
+  settingSources: string[] | "default";
+  /** Ambient repo `.claude/settings.json` hook disposition: `off` when the project scope is dropped,
+   *  `ambient` when it loads ungoverned, `n/a` for a provider with no `.claude` surface (Codex). */
+  projectHooks: EffectiveProjectHooks;
+  /** Repo CLAUDE.md/AGENTS.md disposition. Surfaces the #2086 interference explicitly: when P.hooks
+   *  drops the native scope while P.instructions is on, this reads `reinjected` (honored via the
+   *  controlled channel) rather than being silently omitted. */
+  projectInstructions: EffectiveProjectInstructions;
+}
+
+export interface EffectiveProfileSurveyRow extends EffectiveProfileDisposition {
+  name: string;
+  provider: AgentProfileProvider;
+  /** The effective (merged) base. N3 does not recompute `base` — that is the heavy-node D-A change. */
+  base: AgentProfileBase;
+  /** True when a persisted `agent-profile-override` row contributed to this effective shape. */
+  overridden: boolean;
+}
+
+function projectConfigProjectionOn(profile: AgentProfile): boolean {
+  return Boolean(profile.projectSkills);
+}
+
+/** Whether P.instructions is explicitly enabled (a persisted v2 sources cell). The runner
+ *  re-injects the repo docs only for this explicit cell, never the v1 `repoInstructions` fallback. */
+function projectInstructionsExplicitlyOn(profile: AgentProfile): boolean {
+  return profile.sources?.project?.instructions?.enabled === true;
+}
+
+/** The `--setting-sources` / `.claude` scope surface is the plugin-capable (Claude) provider; Codex
+ *  has none. Read as a manifest CAPABILITY (the same `bundledPlugin` discriminator the reporter's
+ *  projectSkills/projectSettings entries use), never a provider-identity branch. */
+function hasSettingSourceSurface(provider: SpawnProvider): boolean {
+  return Boolean(getManifest(provider)?.provisioning?.bundledPlugin);
+}
+
+/** Disposition depends on the RUN provider (an `any`/unscoped profile is surveyed against the given
+ *  provider — default Claude, the fleet's provider and the surface the #1963 survey cares about). */
+export function computeEffectiveProfileDisposition(profile: AgentProfile, provider: SpawnProvider = "claude"): EffectiveProfileDisposition {
+  const projection = projectConfigProjectionOn(profile);
+  const settingSourcesProjection = sdkProjectSettingSourcesOn(profile);
+  // #3387 — every runner-managed profiled launch runs in a Relay-owned home.
+  const isolated = true;
+  const claudeSurface = hasSettingSourceSurface(provider);
+  // Claude emits `--setting-sources user,project` when a Project instructions, hooks, or settings
+  // cell is enabled. Codex has no such flag (it suppresses the project doc via
+  // `project_doc_max_bytes=0` on a vanilla base only), so it never carries `settingSources`.
+  const settingSourcesUser = claudeSurface && settingSourcesProjection;
+  const settingSources = !claudeSurface ? "default" : settingSourcesUser ? ["user", "project"] : ["user"];
+  // #2086 — repo instructions load ambiently when the native scope is present; when P.hooks drops
+  // that scope, an explicit P.instructions cell is re-injected through the controlled channel.
+  const repoInstructionsEnabled = projectInstructionsOn(profile);
+  const projectInstructions: EffectiveProjectInstructions = !claudeSurface
+    ? "n/a"
+    : settingSourcesUser
+      ? (repoInstructionsEnabled ? "ambient" : "off")
+      : projectInstructionsExplicitlyOn(profile) ? "reinjected" : "off";
+  return {
+    projectConfigProjectionOn: projection,
+    projectSettingSourcesOn: settingSourcesProjection,
+    derivedHome: isolated ? "isolated" : "host",
+    settingSources,
+    projectHooks: !claudeSurface ? "n/a" : settingSourcesUser ? "ambient" : "off",
+    projectInstructions,
+  };
+}
+
+/** Survey every built-in + custom profile's EFFECTIVE merged-override disposition. This is the
+ *  per-persisted-row dump the review requires before D-T is answered (#1963 R1.2/R1.3). */
+export function effectiveProfileSurvey(provider: SpawnProvider = "claude"): EffectiveProfileSurveyRow[] {
+  return listAgentProfiles().map((entry) => {
+    const profile = entry.value;
+    return {
+      name: profile.name,
+      provider: profile.provider ?? "any",
+      base: profile.base,
+      overridden: Boolean(profile.overridden),
+      ...computeEffectiveProfileDisposition(profile, provider),
+    };
+  });
+}

package/src/profile-host-sources.ts

@@ -0,0 +1,73 @@
+// #3387 — the v1 Host fields (instructions.globalInstructions, mcp.mode, hooks.mode, hostAssets.*)
+// are the canonical stored inputs; `sources.host` is their write-synchronized projection. Matrix
+// writes are translated onto the v1 fields, and a write naming both sides with different values is
+// refused instead of picking one.
+import { effectiveHostSources, hostAssetPresetDefault, isRecord, type AgentProfile, type ProfileHostCells } from "@humwick/sdk";
+import { ValidationError } from "./db/connection.ts";
+
+type MatrixHostClass = keyof ProfileHostCells;
+const MATRIX_HOST_CLASSES: readonly MatrixHostClass[] = ["instructions", "mcp", "hooks", "skills", "plugins"];
+
+/** The `sources.host` projection of a profile's canonical Host fields (asset-cell refs kept). */
+export function hostCellsFromProfile(profile: Pick<AgentProfile, "base" | "instructions" | "mcp" | "hooks" | "hostAssets" | "sources">): ProfileHostCells {
+  const effective = effectiveHostSources(profile);
+  const stored = profile.sources?.host;
+  return {
+    instructions: { enabled: effective.instructions },
+    mcp: { enabled: effective.mcp },
+    hooks: { enabled: effective.hooks, refs: stored?.hooks.refs ?? [] },
+    skills: { enabled: effective.skills, refs: stored?.skills.refs ?? [] },
+    plugins: { enabled: effective.plugins, refs: stored?.plugins.refs ?? [] },
+  };
+}
+
+/** Re-project `sources.host` from the canonical fields; a profile without a matrix stays without one. */
+export function withSyncedHostCells<T extends AgentProfile>(profile: T): T {
+  if (!profile.sources) return profile;
+  return { ...profile, sources: { ...profile.sources, host: hostCellsFromProfile(profile) } };
+}
+
+function v1Value(body: Record<string, unknown>, hostClass: MatrixHostClass): boolean | undefined {
+  const section = (key: string) => isRecord(body[key]) ? body[key] as Record<string, unknown> : undefined;
+  if (hostClass === "instructions") {
+    const value = section("instructions")?.globalInstructions;
+    return value === undefined ? undefined : value === "allow";
+  }
+  if (hostClass === "mcp" || hostClass === "hooks") {
+    const value = section(hostClass)?.mode;
+    return value === undefined ? undefined : value === "host";
+  }
+  const value = section("hostAssets")?.[hostClass];
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function writeV1(body: Record<string, unknown>, hostClass: MatrixHostClass, enabled: boolean): void {
+  const section = (key: string) => (isRecord(body[key]) ? { ...body[key] as Record<string, unknown> } : {});
+  if (hostClass === "instructions") body.instructions = { ...section("instructions"), globalInstructions: enabled ? "allow" : "ignore" };
+  else if (hostClass === "mcp" || hostClass === "hooks") body[hostClass] = { ...section(hostClass), mode: enabled ? "host" : "none" };
+  else body.hostAssets = { ...section("hostAssets"), [hostClass]: enabled };
+}
+
+/**
+ * Apply the Host cells a write body names onto its canonical v1 fields. An omitted asset field
+ * resolves to the built-in seed's value (`seedAssets`), else the preset of `base`; a cell that only
+ * restates that stays an omission, anything else is written explicitly.
+ */
+export function reconcileHostCellInputs(body: Record<string, unknown>, base: AgentProfile["base"], seedAssets?: AgentProfile["hostAssets"]): Record<string, unknown> {
+  const sources = isRecord(body.sources) ? body.sources : undefined;
+  const host = sources && isRecord(sources.host) ? sources.host : undefined;
+  if (!host) return body;
+  const next = { ...body };
+  for (const hostClass of MATRIX_HOST_CLASSES) {
+    const cell = isRecord(host[hostClass]) ? (host[hostClass] as Record<string, unknown>).enabled : undefined;
+    if (typeof cell !== "boolean") continue;
+    const stored = v1Value(next, hostClass);
+    if (stored !== undefined) {
+      if (stored !== cell) throw new ValidationError(`sources.host.${hostClass}.enabled contradicts the profile's Host ${hostClass} setting`);
+      continue;
+    }
+    if ((hostClass === "skills" || hostClass === "plugins") && cell === (seedAssets?.[hostClass] ?? hostAssetPresetDefault(base))) continue;
+    writeV1(next, hostClass, cell);
+  }
+  return next;
+}

package/src/profile-instruction-blocks.ts

@@ -0,0 +1,11 @@
+import type { AgentProfile } from "@humwick/sdk";
+import { composeRoleAssets } from "./project-role-assets";
+
+/** #3587 — resolve the profile's blocks once for the first-turn text and injection report. */
+export function profileInstructionBlocks(profile: Pick<AgentProfile, "instructions" | "roleAssets"> | undefined, provider: string | undefined) {
+  const system = profile?.instructions.system?.trim();
+  const append = profile?.instructions.append.filter(entry => entry.trim()) ?? [];
+  const roleAssets = composeRoleAssets(profile?.roleAssets, provider);
+  if (roleAssets) append.push(roleAssets);
+  return { system, append };
+}

package/src/profile-project-validation.ts

@@ -0,0 +1,23 @@
+import { isRecord, type ProfileProjectAck, type ProfileProjectTrust } from "@humwick/sdk";
+import { cleanEnum, cleanString } from "./validation";
+import { ValidationError } from "./db/connection";
+
+export function cleanProfileProjectAck(value: unknown, field: string): ProfileProjectAck {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  const at = typeof value.at === "number" && Number.isFinite(value.at) && value.at >= 0 && value.at <= Number.MAX_SAFE_INTEGER ? value.at : (() => { throw new ValidationError(`${field}.at must be a finite number between 0 and ${Number.MAX_SAFE_INTEGER}`); })();
+  return { by: cleanString(value.by, `${field}.by`, { required: true, max: 200 })!, at, cellsHash: cleanString(value.cellsHash, `${field}.cellsHash`, { required: true, max: 128 })! };
+}
+
+export function cleanProfileProjectTrust(value: unknown, field: string): ProfileProjectTrust {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  return {
+    scope: cleanEnum(value.scope, `${field}.scope`, ["roots", "pinned", "any"] as const) as ProfileProjectTrust["scope"],
+    // Bug fix (#2068 N12 review): this previously dropped `review` on every write, so a profile's
+    // stored trust block could never carry anything but the implicit "fingerprint" default —
+    // `reviewModeOf` (src/project-trust.ts) always fell back regardless of what was requested. Any
+    // dashboard/API caller that sets `review` had it silently discarded before persistence.
+    ...(value.review === undefined || value.review === null
+      ? {}
+      : { review: cleanEnum(value.review, `${field}.review`, ["fingerprint", "commit", "none"] as const) as ProfileProjectTrust["review"] }),
+  };
+}

package/src/profile-provider-options.ts

@@ -0,0 +1,59 @@
+// Validation for AgentProfile.providerOptions: per-provider launch switches the runner reads.
+import { ValidationError } from "./db/connection.ts";
+import { cleanEnum, cleanStringArray } from "./validation";
+import { isRecord, type AgentProfileProviderOptions } from "@humwick/sdk";
+
+type ClaudeAgentTypes = NonNullable<NonNullable<AgentProfileProviderOptions["claude"]>["agentTypes"]>;
+const CLAUDE_AGENT_TYPES = ["all", "general-purpose", "none"] as const satisfies readonly ClaudeAgentTypes[];
+type SectionCleaner = (section: Record<string, unknown>, field: (key: string) => string) => void;
+
+// Each known provider section: its #3171 harness-trim booleans (null clears a key back to the
+// runner default) and any further field checks.
+const SECTIONS: Record<string, { booleans: readonly string[]; clean?: SectionCleaner }> = {
+  claude: {
+    booleans: ["artifacts", "workflows", "bundledSkills", "interactiveTools"],
+    clean: (section, field) => {
+      if ("disallowedTools" in section && section.disallowedTools !== null) {
+        section.disallowedTools = cleanStringArray(section.disallowedTools, field("disallowedTools"), { itemMax: 120, maxItems: 64 });
+      }
+      if (section.subagentModel !== undefined && section.subagentModel !== null) section.subagentModel = cleanEnum(section.subagentModel, field("subagentModel"), ["sonnet", "haiku", "opus"] as const);
+      if (section.subagentMaxEffort === null) delete section.subagentMaxEffort;
+      else if (section.subagentMaxEffort !== undefined) section.subagentMaxEffort = cleanEnum(section.subagentMaxEffort, field("subagentMaxEffort"), ["low", "medium", "high", "xhigh", "max"] as const);
+      if (section.subagentContextTokens === null) delete section.subagentContextTokens;
+      else if (section.subagentContextTokens !== undefined && (typeof section.subagentContextTokens !== "number" || !Number.isSafeInteger(section.subagentContextTokens) || section.subagentContextTokens < 100_000 || section.subagentContextTokens > 1_000_000)) throw new ValidationError(`${field("subagentContextTokens")} must be an integer between 100000 and 1000000`);
+      if (section.agentTypes === null) delete section.agentTypes;
+      else if (section.agentTypes !== undefined) section.agentTypes = cleanEnum(section.agentTypes, field("agentTypes"), CLAUDE_AGENT_TYPES);
+    },
+  },
+  codex: {
+    booleans: ["multiAgent", "imageGeneration"],
+    clean: (section, field) => {
+      if (!("toolOutputTokenLimit" in section) || section.toolOutputTokenLimit === null) return;
+      const limit = section.toolOutputTokenLimit;
+      if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1_000 || limit > 200_000) {
+        throw new ValidationError(`${field("toolOutputTokenLimit")} must be an integer between 1000 and 200000`);
+      }
+    },
+  },
+  opencode: { booleans: ["task"] },
+};
+
+export function cleanAgentProfileProviderOptions(value: unknown): Record<string, unknown> {
+  if (value === undefined || value === null) return {};
+  if (!isRecord(value)) throw new ValidationError("providerOptions must be an object");
+  const cleaned: Record<string, unknown> = { ...value };
+  for (const [name, spec] of Object.entries(SECTIONS)) {
+    const raw = value[name];
+    if (raw === undefined || raw === null) continue;
+    if (!isRecord(raw)) throw new ValidationError(`providerOptions.${name} must be an object`);
+    const section = { ...raw };
+    const field = (key: string) => `providerOptions.${name}.${key}`;
+    for (const key of spec.booleans) {
+      if (section[key] === null) delete section[key];
+      else if (section[key] !== undefined && typeof section[key] !== "boolean") throw new ValidationError(`${field(key)} must be a boolean`);
+    }
+    spec.clean?.(section, field);
+    cleaned[name] = section;
+  }
+  return cleaned;
+}

package/src/profile-role-templates.ts

@@ -0,0 +1,26 @@
+// Built-in role prompts for the #2982 catalog. Dashboard-editable like every prompt template; the
+// four promoted roles start from the charters their live custom profiles carried. The text is the
+// bundled Markdown seed in both flag modes (#3517).
+import type { SeedTemplate } from "./db/prompt-templates";
+import { bundledPrompt } from "./versioned-prompts";
+
+function profileTemplate(slug: string, title: string, description: string): SeedTemplate {
+  const text = bundledPrompt(slug).template;
+  return { slug, category: "profile", title, description, template: text, defaultTemplate: text, variables: [] };
+}
+
+export const PROFILE_ROLE_TEMPLATES: SeedTemplate[] = [
+  profileTemplate("profile.sec-ops.system", "Security Operations System Prompt", "Built-in sec-ops defensive security charter (#3173)."),
+  profileTemplate("skill.security-code-review", "Security Code Review Skill", "Bundled sec-ops security code review checklist (#3173)."),
+  profileTemplate("skill.security-host-audit", "Security Host Audit Skill", "Bundled sec-ops host audit runbook (#3173)."),
+  profileTemplate("skill.security-hardening", "Security Hardening Skill", "Bundled sec-ops reviewed hardening runbook (#3173)."),
+  profileTemplate("profile.sub-coordinator.charter", "Sub-coordinator Charter", "Built-in sub-coordinator charter (#3375)."),
+  profileTemplate("profile.software-design.system", "Software Design System Prompt", "Built-in software-design system prompt (#2982)."),
+  profileTemplate("profile.qa.system", "QA System Prompt", "Built-in QA system prompt (#2982)."),
+  profileTemplate("profile.worker-gui.system", "GUI Worker System Prompt", "Built-in worker-gui system prompt (#2982)."),
+  profileTemplate("profile.social-media.system", "Social Media System Prompt", "Built-in social-media system prompt (#2982)."),
+  profileTemplate("profile.device-qa.system", "Device QA System Prompt", "Built-in device-qa system prompt (#2982)."),
+  profileTemplate("profile.debugger.system", "Debugger System Prompt", "Built-in debugger system prompt (#2982)."),
+  profileTemplate("profile.probe.system", "Probe System Prompt", "Built-in probe system prompt (#2982): minimal on purpose, no role charter."),
+  profileTemplate("skill.device-lane", "Device Lane Skill", "SKILL.md of the device-qa profile's inline device-lane skill (#2982)."),
+];

package/src/profile-workflow-policy.ts

@@ -0,0 +1,14 @@
+import { isRecord, ValidationError, type AgentProfile } from "@humwick/sdk";
+import { cleanStringArray } from "./validation";
+
+export function cleanProfileWorkflows(value: unknown): NonNullable<AgentProfile["workflows"]> {
+  if (!isRecord(value)) throw new ValidationError("workflows must be an object");
+  const result: NonNullable<AgentProfile["workflows"]> = {};
+  if (value.allowed !== undefined) result.allowed = cleanStringArray(value.allowed, "workflows.allowed", { itemMax: 64, maxItems: 100 }) ?? [];
+  for (const field of ["maxConcurrentRuns", "maxLiveAgents"] as const) {
+    if (value[field] === undefined) continue;
+    if (!Number.isInteger(value[field]) || Number(value[field]) < 0 || Number(value[field]) > 100) throw new ValidationError(`workflows.${field} must be an integer from 0 to 100`);
+    result[field] = Number(value[field]);
+  }
+  return result;
+}

package/src/project-claudemd-sweep.ts

@@ -0,0 +1,176 @@
+// #1939 — periodic CLAUDE.md re-ingest + backfill + found:false surfacing.
+//
+// `ingestClaudeMd` (project-ingest.ts) was only ever called from two spots: the MCP tool
+// (on-demand, human/agent-triggered) and `autoSeedProjectForCwdAsync` (once, the moment a brand
+// new project/root is first registered). Nothing re-ran it afterwards, so an ingested project's
+// knowledge silently drifted from its CLAUDE.md as the file was edited, and any project that
+// existed BEFORE the ingest feature shipped (source:'ingested' count of zero, forever) was never
+// backfilled at all — both symptoms observed by hand across the fleet (#1939).
+//
+// This sweep is the fix for both, as ONE job rather than two: `ingestClaudeMd` is already fully
+// idempotent (see its own header) and cheap (one stat + one read per root), so running it against
+// EVERY registered project on a standing interval both (a) keeps already-ingested projects fresh
+// and (b) IS the backfill for a project with zero ingested entries — its first sweep pass is
+// indistinguishable from a one-off backfill migration, so a separate migration script would just
+// be this same loop run once by hand. `runOnStart:true` means a fresh deploy backfills immediately
+// rather than waiting out the interval.
+//
+// found:false (a registered root with no CLAUDE.md on disk) was previously silent — visible only
+// by reading `ingestClaudeMd`'s return value directly. This sweep tracks it as a project-health
+// signal: a `project.claudemd-not-found` event on the transition INTO missing, and a `recovered:true`
+// follow-up the moment it's found again — the same "only speak on state change" discipline
+// `memory-store-health-sweep.ts` uses, so a healthy fleet doesn't bury the signal under daily
+// reaffirmations.
+
+import { DEFAULT_USER_ID, errMessage } from "@humwick/sdk";
+import { CLAUDEMD_REINGEST_INTERVAL_MS } from "./config";
+import { listProjects } from "./db";
+import { emitRelayEvent } from "./events";
+import { ingestClaudeMd } from "./project-ingest";
+import type { Project } from "./types";
+
+/** Per-project outcome, including which roots (if any) had no CLAUDE.md this pass. */
+export interface ClaudeMdSweepEntry {
+  projectId: string;
+  slug: string;
+  created: number;
+  updated: number;
+  unchanged: number;
+  retracted: number;
+  /** Root paths with no CLAUDE.md found this pass — empty when every registered root has one. */
+  missingRoots: string[];
+  error?: string;
+}
+
+export interface ClaudeMdSweepResult extends Record<string, unknown> {
+  projects: number;
+  created: number;
+  updated: number;
+  unchanged: number;
+  retracted: number;
+  errors: number;
+  /** Projects with at least one root missing CLAUDE.md this pass, worst (most missing roots) first. */
+  missing: Array<{ projectId: string; slug: string; missingRoots: string[] }>;
+  entries: ClaudeMdSweepEntry[];
+}
+
+/** Project ids currently flagged (>=1 root missing CLAUDE.md) as of the last sweep that emitted for
+ *  them — lets the sweep tell "already known missing" (re-affirm, no event) apart from "newly missing"
+ *  or "just recovered" (both emit exactly once). Module-level, process-lifetime, in-memory only: a
+ *  restart clearing it is harmless the same way it is for the memory sweep's identical map — every
+ *  still-missing project re-flags on the very next pass regardless. */
+const flaggedMissingProjects = new Set<string>();
+
+/** Test-only reset, mirroring `resetMemoryStoreHealthRecommendationTrackingForTests`. */
+export function resetClaudeMdSweepTrackingForTests(): void {
+  flaggedMissingProjects.clear();
+}
+
+function yieldToEventLoop(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+function emitFoundStateEvent(project: Project, missingRoots: string[], recovered: boolean): void {
+  try {
+    emitRelayEvent({
+      type: "project.claudemd-not-found",
+      source: "project-claudemd-sweep",
+      subject: project.id,
+      data: {
+        projectId: project.id,
+        slug: project.slug,
+        missingRoots,
+        ...(recovered ? { recovered: true } : {}),
+      },
+    });
+  } catch (err) {
+    console.warn(`[relay] project-claudemd-sweep: failed to record claudemd-not-found event for ${project.slug} (self-heals next tick): ${errMessage(err)}`);
+  }
+}
+
+/**
+ * Re-ingest CLAUDE.md for every registered project. Never throws — a sweep is a maintenance
+ * pass, and one project's ingest failure (a permissions error, a malformed root) must not cost
+ * every other project's result.
+ */
+export async function runClaudeMdReingestSweep(opts: { signal?: AbortSignal } = {}): Promise<ClaudeMdSweepResult> {
+  const projects = listProjects();
+  const entries: ClaudeMdSweepEntry[] = [];
+  let created = 0;
+  let updated = 0;
+  let unchanged = 0;
+  let retracted = 0;
+  let errors = 0;
+
+  for (const project of projects) {
+    if (opts.signal?.aborted) break;
+
+    let entry: ClaudeMdSweepEntry;
+    try {
+      const result = await ingestClaudeMd(project.id, DEFAULT_USER_ID);
+      const missingRoots = result.roots.filter((r) => !r.found).map((r) => r.rootPath);
+      entry = {
+        projectId: project.id,
+        slug: project.slug,
+        created: result.created,
+        updated: result.updated,
+        unchanged: result.unchanged,
+        retracted: result.retracted,
+        missingRoots,
+      };
+      created += result.created;
+      updated += result.updated;
+      unchanged += result.unchanged;
+      retracted += result.retracted;
+
+      const wasFlagged = flaggedMissingProjects.has(project.id);
+      if (missingRoots.length) {
+        if (!wasFlagged) emitFoundStateEvent(project, missingRoots, false);
+        flaggedMissingProjects.add(project.id);
+      } else if (wasFlagged) {
+        emitFoundStateEvent(project, missingRoots, true);
+        flaggedMissingProjects.delete(project.id);
+      }
+    } catch (err) {
+      errors += 1;
+      entry = { projectId: project.id, slug: project.slug, created: 0, updated: 0, unchanged: 0, retracted: 0, missingRoots: [], error: errMessage(err) };
+    }
+    entries.push(entry);
+
+    // Yield between projects (#1725/#1835 pattern) so a large fleet's sweep can't block the event
+    // loop as one contiguous synchronous block, and so `signal` gets a real chance to land mid-run.
+    await yieldToEventLoop();
+  }
+
+  const missing = entries
+    .filter((e) => e.missingRoots.length > 0)
+    .sort((a, b) => b.missingRoots.length - a.missingRoots.length)
+    .map((e) => ({ projectId: e.projectId, slug: e.slug, missingRoots: e.missingRoots }));
+
+  return {
+    projects: projects.length,
+    ...(opts.signal?.aborted ? { aborted: true, projectsUnprocessed: projects.length - entries.length } : {}),
+    created,
+    updated,
+    unchanged,
+    retracted,
+    errors,
+    missing,
+    entries,
+  };
+}
+
+/** Registered in `src/maintenance/jobs.ts`. Daily by default; `runOnStart` so a fresh deploy (or a
+ *  project that pre-dates the ingest feature) backfills immediately instead of waiting out the
+ *  interval — see the module header for why this one job covers both re-ingest and backfill. */
+export const CLAUDEMD_REINGEST_JOB = {
+  id: "claudemd-reingest",
+  critical: false,
+  title: "CLAUDE.md re-ingest",
+  description: "Re-ingest CLAUDE.md for every registered project (idempotent) so ingested project knowledge tracks the file, backfills any project with zero ingested entries, and surfaces a missing CLAUDE.md as a project-health event (#1939).",
+  intervalMs: CLAUDEMD_REINGEST_INTERVAL_MS,
+  runOnStart: true,
+  async handler(context: { signal?: AbortSignal }) {
+    return runClaudeMdReingestSweep({ signal: context.signal });
+  },
+};

package/src/project-file-source.ts

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isRecord, type ProjectRoot } from "@humwick/sdk";
+import { isTrustedOrchestratorApiUrl } from "./config";
+import { getOrchestrator, listOrchestrators, projectCheckoutCommandsAsync } from "./db";
+import { hostIsRelayHost } from "./relay-host-locality";
+import { resolveSpawnHostAnchor } from "./spawn-placement";
+import { isPathWithinBase } from "./utils";
+import { fetchHostJson } from "./workspace-host-client";
+
+/** File consumers share one source per path; checkout ownership is resolved below. */
+export function projectFileRoots(roots: ProjectRoot[]): ProjectRoot[] {
+  const byPath = new Map<string, ProjectRoot>();
+  for (const root of roots) if (!byPath.has(root.rootPath)) byPath.set(root.rootPath, root);
+  return [...byPath.values()];
+}
+
+/** Checkout reads share host selection. A remote failure must never fall back to hub disk. */
+export async function readProjectRootFile(root: ProjectRoot, filename: string): Promise<string | null> {
+  const path = join(root.rootPath, filename);
+  const states = (await projectCheckoutCommandsAsync(root.projectId, { confirmedOnly: true })).filter((state) => state.rootPath === root.rootPath);
+  const present = states.filter((state) => state.type === "project.checkout.ensure");
+  const removed = new Set(states.filter((state) => state.type === "project.checkout.remove").map((state) => state.orchestratorId));
+  if (removed.size && !present.length) throw new Error(`${filename}: no confirmed checkout host owns ${root.rootPath}`);
+  const confirmedOwner = present.find((state) => state.orchestratorId === root.orchestratorId) ?? present[0];
+  const ownerId = confirmedOwner?.orchestratorId ?? root.orchestratorId;
+  const candidates = listOrchestrators().filter((item) => isPathWithinBase(root.rootPath, item.baseDir) && !removed.has(item.id));
+  const host = ownerId && !removed.has(ownerId) ? getOrchestrator(ownerId)
+    : candidates.length ? resolveSpawnHostAnchor({ cwd: root.rootPath, allowedOrchestratorIds: candidates.map((item) => item.id) }) : undefined;
+  if (ownerId && !host) throw new Error(`${filename}: owning host ${ownerId} not found`);
+  if (!host && candidates.length) throw new Error(`${filename}: no online host owns ${root.rootPath}`);
+  if (!host || hostIsRelayHost(host.id)) {
+    try { return await readFile(path, "utf8"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  }
+  if (host.status !== "online" || !host.apiUrl || !isTrustedOrchestratorApiUrl(host.apiUrl)) {
+    throw new Error(`${filename}: owning host ${host.id} is unavailable`);
+  }
+  const result = await fetchHostJson<string>(host.apiUrl, "/api/files/read", {
+    query: new URLSearchParams({ path }), timeoutMs: 3_000,
+    validate: (body) => isRecord(body) && body.encoding === "utf8" && body.truncated === false && typeof body.content === "string"
+      ? { ok: true, value: body.content }
+      : { ok: false, reason: "incomplete or non-text file" },
+  });
+  if (result.ok) return result.value;
+  const failure = result.failure;
+  // Older orchestrators return 400 for missing files, so use their explicit missing-path error.
+  if (failure.stage === "http" && [400, 404].includes(failure.status) && isRecord(failure.body)
+    && failure.body.error === `Path does not exist: ${path}`) return null;
+  throw new Error(`${filename} on ${host.id}: ${JSON.stringify(failure)}`);
+}