@humwick/server 0.0.0-stage → 0.130.1

package/src/project-instructions.ts

@@ -0,0 +1,700 @@
+import { composeMemoryPreambleAsync } from "./memory-preamble-async";
+import { composeHostAwareness } from "./host-awareness";
+import { composeGuideIndex } from "./guides";
+import { profileInstructionBlocks } from "./profile-instruction-blocks";
+// Spawn-time instruction sources (#557) — the relay-owned composer that assembles what a spawned
+// agent's systemPromptAppend says, from declared sources only, never from host CLAUDE.md.
+//
+// ADDITIVE-FROM-EMPTY (#403 decision 4): every block here is built from NOTHING and ADDED. Nothing
+// reads host CLAUDE.md or subtracts from it.
+//
+// PROJECT KNOWLEDGE NO LONGER HAS ITS OWN RENDER PATH (#1565 P5.5, §10.4/§10.5). It used to: a
+// `composeProjectInstructions` composer behind the `projectInstructions` PRESENCE gate, rendering
+// the same `project_entries` table the memory preamble renders, with its own filter, its own byte
+// cap, no token accounting, no re-injection at clear/compact — and, until #1601, no audience/TTL/
+// sensitivity checks at all. Two render paths over one table is how #1601 happened. The project
+// cell now resolves through `composeMemoryPreamble` like every other cell. #2154 narrows lifecycle
+// injection to that project cell, which leaves the selected profile's Project Instructions switch as
+// the one gate: on includes project memory while omitting only an `ingested` mirror whose origin
+// matches a repo instruction file THIS provider loads natively; off excludes the whole cell before
+// resolution, so no project entry can win an override collapse.
+import { stripAgentCore, withAgentCore } from "@humwick/sdk/prompt-template-defaults";
+import { canonicalAgentProfileName, COORDINATOR_PROFILE_NAMES, DEFAULT_USER_ID, errMessage } from "@humwick/sdk";
+import { getManifest } from "@humwick/providers";
+import type { LandGatesConfig } from "@humwick/sdk";
+import type { MemoryIdentity } from "./db";
+import { resolveProjectForCanonicalCwd, resolveProjectForCanonicalCwdAsync } from "./services/project";
+import { projectMemoryEnabledForProfile } from "./config-store";
+import { landGatesConfigForSpawnCwd, landGatesConfigForSpawnCwdAsync } from "./land-gates-source";
+import { boundMemoryInjectionEventDetail, composeMemoryPreamble, describeInstructionTruncation, describeMemoryDemotions, describeMemoryOmissions, memoryInstructionDefects, neutralizeMemoryMarkers, stripMemoryPreamble } from "./memory-preamble";
+import { composeJournalPreamble, journalProfileEnabled, neutralizeJournalMarkers, stripJournalPreamble } from "./journal-preamble";
+import { describeInjectionDrops } from "./memory-inject-filter";
+import type { MemorySeam } from "./memory-seam";
+import { renderTemplate } from "./prompt-resolver";
+import { renderAgentCore } from "./agent-core";
+import { effortSectionForProfile } from "./self-effort-rule";
+import type { AgentProfile, MemoryChainScope, RelayInjectionCategory } from "./types";
+
+interface SpawnInstructionInjectionEvent {
+  category: RelayInjectionCategory;
+  summary: string;
+  detail: Record<string, unknown>;
+}
+
+export interface ComposedSpawnInstructions {
+  systemPromptAppend?: string;
+  relayInjectionEvents: SpawnInstructionInjectionEvent[];
+  /**
+   * #1625 — the durable memory identity used for this composition. Returned so the caller can
+   * stamp it into launch params and later seams can replay the same identity. Project inclusion is
+   * deliberately re-derived from that identity's current profile instead of persisted here.
+   * Absent when no `memoryIdentity` was supplied.
+   */
+  memorySeam?: MemorySeam;
+  /** The profile's rendered core (#3517), so a boundary strips exactly the copy the launch carried. */
+  renderedAgentCore?: string;
+}
+
+export const AGENT_RELAY_IDENTITY_HEADING = "## Agent Relay Identity";
+/** Heading for the #1381 config-sourced validation preamble. Exported so tests (and the
+ *  ambient-injection strip in projection tests) can anchor on the exact string. */
+export const VALIDATION_PREAMBLE_HEADING = "# How to validate in THIS project";
+
+/** Fence a shell command for markdown inline code, escaping any backtick so the fence can't
+ *  be broken by a command that itself contains one. */
+function inlineCommand(command: string): string {
+  return command.includes("`") ? `\`\` ${command} \`\`` : `\`${command}\``;
+}
+
+/** The toolchain-generic inner-loop line (#1373 Phase-2 wording) — used ONLY when a project
+ *  declares no explicit `iterate` command, so we can't name a scoped affected-test command. The
+ *  TEXT lives in the `spawn.validation.iterate.generic` prompt-resolver slug (dashboard-editable),
+ *  NOT as a literal here — a prompt change must not be a code change. */
+export function genericIterateLine(): string {
+  return renderTemplate("spawn.validation.iterate.generic");
+}
+
+/** Build the inner-loop directive for a declared `iterate` command (#1381). Names the literal
+ *  command and steers the worker away from the FULL suite on the inner loop — without discouraging
+ *  the required pre-delivery run (#1388 defect-2 fix: the full suite runs at land/merge, NOT at
+ *  delivery). The prose lives in the `spawn.validation.iterate.imperative` slug; this only supplies
+ *  the (pre-fenced) command var. Language-agnostic: `command` is echoed verbatim. */
+export function imperativeIterateLine(command: string): string {
+  return renderTemplate("spawn.validation.iterate.imperative", { command: inlineCommand(command) });
+}
+
+/** Reserved work-type discriminator for the injected "how to deliver" block (#1389 will branch
+ *  build / review / docs variants). Accepted-but-unused today: #1388 emits only the default
+ *  build/code-worker instruction regardless of value, so extending this stays additive. */
+export type DeliveryWorkType = "build" | "review" | "docs";
+
+export interface DeliveryInstructionInput {
+  /** The project's configured `delivery` command, when declared. Absent → toolchain-generic
+   *  fallback ("run your project's tests…") with no hardcoded tool. */
+  deliveryCommand?: string;
+  /** #1389 seam — role/work-type aware variants. Unused in #1388 (build/default only). */
+  workType?: DeliveryWorkType;
+}
+
+/** The injected "how to deliver branch→main" instruction (#1388). A single specializable seam so
+ *  #1389 can add review/docs variants by branching on `workType` without touching callers. Today
+ *  it emits only the build/code-worker case. The instruction PROSE + the exact `relay_task_deliver`
+ *  call live in the `spawn.validation.delivery` prompt-resolver slug (dashboard-editable); this
+ *  function is only the SELECTOR — it resolves the config-sourced run clause (`{{deliveryRun}}`) and
+ *  renders the slug. Language-agnostic: the command is echoed verbatim, and the fallback names no
+ *  toolchain. */
+export function composeDeliveryInstruction(input: DeliveryInstructionInput): string {
+  const deliveryRun = input.deliveryCommand
+    ? `run ${inlineCommand(input.deliveryCommand)}`
+    : "run your project's tests (and typecheck, if it has one)";
+  return renderTemplate("spawn.validation.delivery", { deliveryRun });
+}
+
+/**
+ * #1381 — "How to validate in THIS project": a concise, LANGUAGE-AGNOSTIC preamble sourced
+ * from the spawn cwd repo's `.agent-relay/land-gates.json`. It echoes whatever the project
+ * declared (`cargo test`, `go test ./...`, `bun run test:affected`, …) — core NEVER assumes a
+ * toolchain. Returns "" when the repo has no land-gates config, or a config with nothing to
+ * say (no gates AND no inner-loop command), so the spawn stays byte-identical.
+ *
+ * Content — the three-tier vocabulary (#1388):
+ *   - the inner-loop directive: IMPERATIVE + PROHIBITIVE naming the literal `iterate` command
+ *     when the project declared one, else the toolchain-generic Phase-2 line,
+ *   - the worker DELIVERY instruction (`composeDeliveryInstruction`): the config-sourced
+ *     `delivery` command (or a generic fallback) + the exact `relay_task_deliver` call,
+ *   - the `gates` land command(s) that run automatically at land/merge (the full authority),
+ *   - an explicit "trust config, not README/CONTRIBUTING" line.
+ *
+ * This makes the toolchain-generic Phase-2 brief line (#1373) concrete + authoritative: a
+ * worker is TOLD the exact affected-test command and forbidden from self-running the full suite,
+ * instead of inferring commands from a doc that may say `bun test`.
+ */
+export function composeProjectValidationPreamble(config: LandGatesConfig): string {
+  // Branch on the EXPLICIT `iterate` field: only then do we know a scoped affected-test command
+  // distinct from the full gate, which is what makes the prohibitive "don't run the full suite"
+  // directive honest. Without it, fall back to the generic line (do NOT name the `test` gate as an
+  // inner loop — it may BE the full suite). The `resolveIterateCommand` fallback stays available
+  // for programmatic consumers via the SDK.
+  const iterate = config.iterate?.trim();
+  const delivery = config.delivery?.trim();
+  const gates = config.gates;
+  if (!iterate && !delivery && gates.length === 0) return "";
+
+  // NOTE: single-`\n`-delimited block (NO internal blank lines) so it is one clean
+  // `\n\n`-separated unit among the composed append blocks. Three-tier vocabulary (#1388):
+  // iterate (inner loop) → delivery (worker delivery gate) → gates/land (authoritative full).
+  const lines: string[] = [
+    VALIDATION_PREAMBLE_HEADING,
+    "These commands come from this repo's `.agent-relay/land-gates.json` and are authoritative. Use these commands — do NOT infer test/build commands from README or CONTRIBUTING.",
+    iterate ? imperativeIterateLine(iterate) : genericIterateLine(),
+    composeDeliveryInstruction(delivery ? { deliveryCommand: delivery } : {}),
+  ];
+  if (gates.length > 0) {
+    lines.push(renderTemplate("spawn.validation.landgates.header"));
+    for (const gate of gates) {
+      const suffix = gate.optional ? " _(optional — warns, does not block)_" : "";
+      lines.push(`  - ${inlineCommand(gate.command)} _(${gate.name})_${suffix}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Resolve + render the validation preamble for a spawn cwd, or "" when the cwd's repo declares
+ * no land-gates config. Resilient by design: a malformed/unreadable `land-gates.json` must NOT
+ * crash a spawn (the land-gate runner is the real validator), so any error degrades to "".
+ *
+ * #2171 — `host` names the machine the spawned agent will RUN on. The config is the agent's own
+ * repo's, so it must come from that machine (`land-gates-source.ts`), never from whatever this
+ * process happens to have at the same absolute path. This synchronous form cannot read a remote
+ * host, so for one it serves only what a previous host-sourced read cached; the async twin below
+ * is what the spawn path uses.
+ */
+export function resolveProjectValidationPreamble(cwd: string | undefined, host?: string): string {
+  if (!cwd?.trim()) return "";
+  try {
+    const found = landGatesConfigForSpawnCwd(cwd, host);
+    return found ? composeProjectValidationPreamble(found.config) : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Async request-path twin of {@link resolveProjectValidationPreamble}. Reads a remote agent
+ *  host's config through that host's orchestrator, so a first launch there still gets the block.
+ *  `agentRuntimeCwd` is the cwd the agent will actually RUN in when that differs from the cwd read
+ *  (an isolated spawn's not-yet-created worktree), so the later synchronous seams — which know the
+ *  agent only by that cwd — find this read instead of composing an empty block. */
+export async function resolveProjectValidationPreambleAsync(cwd: string | undefined, host?: string, agentRuntimeCwd?: string): Promise<string> {
+  if (!cwd?.trim()) return "";
+  try {
+    const found = await landGatesConfigForSpawnCwdAsync(cwd, host, agentRuntimeCwd ? { alsoCacheFor: [agentRuntimeCwd] } : {});
+    return found ? composeProjectValidationPreamble(found.config) : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * #557 — THE instruction-sources half of the launch-assembly contract (the relay-side
+ * composer; the runner-side launch-assembly.ts assembles the provisioned skills/plugins/MCP
+ * + vanilla floor). It composes a spawned agent's systemPromptAppend from declared sources,
+ * in precedence order: project knowledge preamble (#409, the project-scoped channel) →
+ * profile system prompt → profile append entries → transient caller/fork context. Composing
+ * from EMPTY and adding (never reading host CLAUDE.md) is the additive-from-empty invariant.
+ *
+ * Appends the dashboard-editable agent core block after profile/caller text, even when
+ * no profile/project material applies (#2788, #2836) — unless the profile opted out
+ * of Relay context (relay.context false), which also opts out of the core.
+ *
+ * ── #559 scoped memory → #1565 P4 unified memory ───────────────────────────────────────
+ * #559 rendered TWO fixed anchors ("Profile memory" from `profile:<name>`, "Operator memory"
+ * from `user:<operator>`) as separate blocks. P4 replaces both with ONE `memoryIdentity`-driven
+ * block: `composeMemoryPreamble` walks the whole `base → provider → host → project` chain (the
+ * base cell FOLDS IN the legacy `profile:` anchor, so nothing that used to inject stops), and
+ * adds what the fixed anchors could not — audience filtering, injection tiers, TTL, sensitivity,
+ * per-scope token budgets and token accounting. One block, not two, so an agent never pays twice
+ * for the same knowledge. P5.5 folds the PROJECT cell into that same block for the same reason.
+ */
+/** The memory cells every LIFECYCLE boundary walks — spawn/restart (#1565 P4a) and clear/compact
+ * (P4b, `src/memory-injection.ts`). Shared, because the delta gate at compact compares the block
+ * a boundary composes against the block the spawn put in the system prompt: two different cell
+ * sets would make every compact look like a change.
+ *
+ * #2154 retires the inherited base/provider/host injection surface, so the project cell is the only
+ * one left to walk. The selected profile's Project Instructions switch still chooses between the
+ * two sets — it is the SOLE project-memory gate, the one the profile matrix advertises ("off
+ * excludes it before resolution, so nothing project-scoped is injected"). Narrowing the OFF set to
+ * `["project"]` too, as b69851cb did, silently turned that switch into a no-op: the editor promised
+ * an exclusion the runtime no longer performed. OFF is the empty set — nothing injected — which is
+ * what retiring the inherited cells means, not "project regardless". */
+export const BASE_MEMORY_CELLS = [] as const satisfies readonly MemoryChainScope[];
+export const LIFECYCLE_MEMORY_CELLS = ["project"] as const satisfies readonly MemoryChainScope[];
+
+export function lifecycleMemoryCells(projectInstructionsEnabled: boolean): readonly MemoryChainScope[] {
+  return projectInstructionsEnabled ? LIFECYCLE_MEMORY_CELLS : BASE_MEMORY_CELLS;
+}
+
+/** When Project Instructions are ON, return the instruction filenames THIS provider loads through
+ * its native repo cascade. Only ingested mirrors of these files are deduplicated; an AGENTS.md
+ * mirror remains useful to Claude, and a CLAUDE.md mirror remains useful to Codex. */
+export function lifecycleProjectNativeInstructionFiles(
+  projectInstructionsEnabled: boolean,
+  provider: string | undefined,
+): readonly string[] | undefined {
+  if (!projectInstructionsEnabled || !provider) return undefined;
+  // The in-repo providers manifest owns this field; keep the narrow structural read compatible
+  // with an older installed providers declaration while workspace package resolution catches up.
+  const files = (getManifest(provider)?.home as { globalInstructionFiles?: string[] } | undefined)?.globalInstructionFiles;
+  return files?.length ? files : undefined;
+}
+
+export function humwickIdentitySection(identity: Record<string, unknown>): string {
+  return `${AGENT_RELAY_IDENTITY_HEADING}\n${JSON.stringify(identity)}`;
+}
+
+export function stripHumwickIdentitySection(value: string): string {
+  if (!value.includes(AGENT_RELAY_IDENTITY_HEADING)) return value;
+  return value
+    .replace(/(^|\n\n)## Agent Relay Identity\n\{[^\n]*\}(?=\n\n|$)/g, "")
+    .replace(/^\n\n+/, "")
+    .replace(/\n\n+$/, "");
+}
+
+export function composeSpawnInstructionsWithEvents(input: {
+  /** Resolved fact from the selected profile's Project Instructions cell. Absent fails closed. */
+  projectInstructionsEnabled?: boolean;
+  /** #1381 — the spawn cwd. When its repo declares `.agent-relay/land-gates.json`, a concise
+   * config-sourced "How to validate in THIS project" preamble is injected (UNGATED — it is
+   * relay-native operational guidance, not policy-scoped knowledge). Absent config → no block. */
+  cwd?: string;
+  /** #2171 — the host the spawned agent will RUN on, which is the machine whose `cwd` the
+   * land-gates config must be read from. Absent means the caller cannot name it, and the read
+   * falls back to this process's own disk (pre-#2171 behaviour). Distinct from the memory
+   * identity's `host` cell only in that it is required even when no `memoryIdentity` is supplied. */
+  host?: string;
+  /** #2171 F1 — the cwd the spawned agent will actually RUN in, when it differs from `cwd`: the
+   * worktree an isolated spawn is about to create. It cannot be READ (the orchestrator has not made
+   * it yet), but it is the cwd every later seam records and looks this agent up by, so the
+   * host-sourced read is recorded against it too. Async composition only — nothing to record when
+   * the read did not happen. */
+  agentRuntimeCwd?: string;
+  /** #1565 P4 — WHO the spawned agent is, for the unified memory preamble (`base → provider →
+   * host → project`, audience-filtered by `profile`). Absent → no memory block at all, so a
+   * caller that does not know the identity produces a byte-identical pre-#1565 spawn. */
+  memoryIdentity?: MemoryIdentity;
+  profile?: Pick<AgentProfile, "instructions" | "maxSpawnedAgents" | "hostAwareness" | "roleAssets"> & { name?: string; relay?: AgentProfile["relay"] };
+  spawnedBy?: string;
+  /** #3045 — a workflow step agent: its step reporting block replaces the spawned-child report-up. */
+  workflowRunId?: string;
+  /** #2976 — the agent holds a live selfEffort grant, so it gets the shared effort rule. */
+  selfEffort?: boolean;
+  agentRelayIdentity?: Record<string, unknown>;
+  callerSystemPromptAppend?: string;
+  /** Internal async seam: compute the filesystem-backed preamble before entering this pure composer. */
+  validationPreamble?: string;
+  memoryPreamble?: () => ReturnType<typeof composeMemoryPreamble>;
+  /** #3567 — the agent's principal, whose style replaces the core's "To a human" line. Defaults to
+   *  the memory identity's operator, which spawn and restart resolve to the principal. */
+  principalUserId?: string;
+}): ComposedSpawnInstructions {
+  const appendBlocks: string[] = [];
+  const relayInjectionEvents: SpawnInstructionInjectionEvent[] = [];
+  if (input.profile?.hostAwareness === true) {
+    const fleet = composeHostAwareness();
+    if (fleet) {
+      appendBlocks.push(fleet);
+      relayInjectionEvents.push({ category: "instructions", summary: "injected fleet host registry", detail: { source: "host-awareness", content: fleet } });
+    }
+  }
+  // [#1381] config-sourced validation preamble. Ungated: injects
+  // whenever the spawn cwd's repo declares `.agent-relay/land-gates.json`, so every worker is
+  // told the project's OWN validation commands instead of inferring them from README/CONTRIBUTING.
+  const validationPreamble = input.validationPreamble ?? resolveProjectValidationPreamble(input.cwd, input.host);
+  if (validationPreamble.trim()) {
+    appendBlocks.push(validationPreamble);
+    relayInjectionEvents.push({
+      category: "instructions",
+      summary: "injected project validation commands (land-gates.json)",
+      // `host` is part of the record because #2171 makes it part of the ANSWER: the same cwd
+      // resolves to different configs on different machines, so an audit of this block has to say
+      // whose disk it came from.
+      detail: { source: "project-validation-commands", cwd: input.cwd, ...(input.host ? { host: input.host } : {}), content: validationPreamble },
+    });
+  }
+  // [#1565 P4/P5.5] the unified memory preamble — the successor to #559's two fixed-anchor blocks
+  // AND (since P5.5) to the project-knowledge block that used to sit beside it, in the same slot
+  // before the profile system prompt. #2154 limits it to the project cell; the selected profile's
+  // Project Instructions switch alone decides whether that cell is injected at all, and supplies
+  // its native-file deduplication policy.
+  // Provider-agnostic — nothing below branches on who runs the agent.
+  if (input.memoryIdentity) {
+    // Memory composition must not make a spawn fail. Preserve the accounting event, including
+    // shared-filter refusals, whenever composition succeeds.
+    let memory: ReturnType<typeof composeMemoryPreamble> | undefined;
+    try {
+      memory = input.memoryPreamble ? input.memoryPreamble() : composeMemoryPreamble(input.memoryIdentity, {
+        cells: lifecycleMemoryCells(input.projectInstructionsEnabled === true),
+        projectNativeInstructionFiles: lifecycleProjectNativeInstructionFiles(
+          input.projectInstructionsEnabled === true,
+          input.memoryIdentity.provider,
+        ),
+      });
+    } catch (error) {
+      relayInjectionEvents.push({
+        category: "memory",
+        summary: `memory failed to compose, spawning with no memory block: ${errMessage(error)}`,
+        detail: { source: "memory-preamble", identity: input.memoryIdentity, failed: true },
+      });
+    }
+    if (memory) {
+      if (memory.block.trim()) appendBlocks.push(memory.block);
+    // The event fires whenever there is ACCOUNTING to report — which includes the case where the
+    // block is "" because nothing fit. "Every drop is stated in the block AND itemized in the
+    // return, never silent" (§4.3) has to hold hardest exactly when the block is empty: that is
+    // the outcome an operator most needs to see, and it is the one with no block to state it in.
+      const instructionDefects = memoryInstructionDefects(memory.instructionSlugs);
+      if (memory.block.trim()
+        || memory.omitted
+        || memory.demoted
+        || memory.filtered.length
+        || instructionDefects.length
+        || (input.memoryIdentity.projectId !== undefined && input.projectInstructionsEnabled !== true)) {
+        const injectedEntries = memory.entries.filter((entry) => entry.rendered);
+        const injected = injectedEntries.length;
+        relayInjectionEvents.push({
+        category: "memory",
+        // Each cause is NAMED, not flattened (#1602): a demotion to the index (#1979 I1), a true
+        // index-cap omission, an instruction truncation and a filter refusal all have different
+        // fixes, so the summary keeps them apart.
+        summary: `injected memory: ${injected} entr${injected === 1 ? "y" : "ies"}, ${memory.tokens} tokens${memory.instructionTokens ? ` + ${memory.instructionTokens} instruction tokens` : ""}${memory.demoted ? ` (${memory.demoted} demoted to index — ${describeMemoryDemotions(memory.demotedByReason, memory.budgets)})` : ""}${memory.omitted ? ` (${memory.omitted} omitted — ${describeMemoryOmissions(memory.omittedByReason, memory.budgets)})` : ""}${describeInstructionTruncation(memory.omittedByReason, memory.budgets)}${memory.filtered.length ? ` (${memory.filtered.length} not injectable — ${describeInjectionDrops(memory.filteredByReason)})` : ""}${instructionDefects.length ? ` [instruction: ${instructionDefects.map((slug) => `${slug.slug} ${slug.status}`).join(", ")}]` : ""}`,
+        // §4.4 observability — `{ entries, tokens, scopes, omitted }` is the per-spawn memory
+        // cost the dashboard charts, from the SAME estimator the tools report (§4.3(3)).
+        //
+        // #2097 — the detail is TRANSPORT-BOUNDED (`boundMemoryInjectionEventDetail`): the spawn
+        // event is POSTed by the runner and the `entries`/`filtered` arrays grow with the whole
+        // store (#1979), so an unbounded detail exceeds the 64 KiB `cleanParams` cap and the visible
+        // entry is dropped. The authoritative counts below (`injectedCount`, `pinnedTokens`,
+        // `indexedTokens`, `filteredCount`, `entriesTotal`) are attached BEFORE bounding so the
+        // dashboard panel's headline numbers stay exact even when the arrays are trimmed to a head.
+        detail: boundMemoryInjectionEventDetail({
+          source: "memory-preamble",
+          identity: input.memoryIdentity,
+          injectedCount: injected,
+          pinnedTokens: injectedEntries.filter((entry) => entry.tier === "pinned").reduce((sum, entry) => sum + entry.tokens, 0),
+          indexedTokens: injectedEntries.filter((entry) => entry.tier === "indexed").reduce((sum, entry) => sum + entry.tokens, 0),
+          filteredCount: memory.filtered.length,
+          entriesTotal: memory.entries.length,
+          projectMemoryEnabled: input.projectInstructionsEnabled === true,
+          tokens: memory.tokens,
+          omitted: memory.omitted,
+          // …with the CAUSE split and the limits it ran under (#1565 F3). The dashboard's cost
+          // panel renders these for every memory injection, spawn included, so leaving them off
+          // here degraded a spawn's "Omitted" to a bare count with no cause and hid the block cap.
+          omittedByReason: memory.omittedByReason,
+          // …and the demotions (#1979 I1): pinned entries that landed in the index instead of a
+          // full body. The index growing is otherwise unexplained on the cost panel.
+          demoted: memory.demoted,
+          demotedByReason: memory.demotedByReason,
+          budgets: memory.budgets,
+          // …and how the INSTRUCTION preface resolved (#1565 P5.1, §10.1): a missing, blank,
+          // failed or truncated slug is invisible in the block by definition — the block is
+          // exactly what it did NOT produce — so the event is the only place it can be reported.
+          instructionTokens: memory.instructionTokens,
+          instructionSlugs: memory.instructionSlugs,
+          scopes: memory.scopes,
+          entries: memory.entries,
+          // …and what the SHARED filter refused before any of that, itemized with reasons (#1565
+          // P5.4). Same shape the project-knowledge event above carries, from the same predicate.
+          filtered: memory.filtered,
+          filteredByReason: memory.filteredByReason,
+          // #3409 — entries held for on-touch delivery, and what the block would have cost without that.
+          areaDeferredCount: memory.areaDeferredCount,
+          counterfactualTokens: memory.counterfactualTokens,
+          content: memory.block,
+        }),
+        });
+      }
+    }
+  }
+  // [#2591] the project journal block — the coordinator's overwrite-by-field current-state
+  // record, its OWN block immediately AFTER the memory block (never inside it). Gated by the
+  // journal profile list (Phase 1: coordinator), NOT by the Project Instructions switch —
+  // it is a separate subsystem with its own budget. Empty journal composes to "" and the
+  // spawn stays byte-identical. Every restart recomposes through this same seam, so a
+  // relaunched agent is byte-identical to a fresh spawn.
+  if (input.memoryIdentity?.projectId && journalProfileEnabled(input.memoryIdentity.profile)) {
+    try {
+      const journal = composeJournalPreamble({
+        projectId: input.memoryIdentity.projectId,
+        profile: input.memoryIdentity.profile,
+      });
+      if (journal.block.trim()) {
+        appendBlocks.push(journal.block);
+        relayInjectionEvents.push({
+          category: "memory",
+          summary: `injected project journal: ${journal.fields.length} field${journal.fields.length === 1 ? "" : "s"}, ${journal.tokens} tokens${journal.trimmed ? ` (${journal.trimmed} value(s) trimmed to the block cap)` : ""}`,
+          detail: {
+            source: "journal-preamble",
+            projectId: input.memoryIdentity.projectId,
+            profile: input.memoryIdentity.profile,
+            fields: journal.fields.map((field) => field.field),
+            tokens: journal.tokens,
+            contentHash: journal.contentHash,
+            content: journal.block,
+          },
+        });
+      }
+    } catch (error) {
+      // A journal failure must never fail a spawn — degrade to no journal block, reported.
+      relayInjectionEvents.push({
+        category: "memory",
+        summary: `project journal failed to compose, spawning without it: ${errMessage(error)}`,
+        detail: { source: "journal-preamble", failed: true, projectId: input.memoryIdentity.projectId, profile: input.memoryIdentity.profile },
+      });
+    }
+  }
+  if (input.spawnedBy && !input.workflowRunId) {
+    const instruction = renderTemplate("spawn.reportup.child");
+    appendBlocks.push(instruction);
+    relayInjectionEvents.push({
+      category: "instructions",
+      summary: "injected spawned-child report-up instructions",
+      detail: { source: "spawned-child-report-up", spawnedBy: input.spawnedBy, content: instruction },
+    });
+  }
+  if ((input.profile?.maxSpawnedAgents ?? 0) > 0) {
+    const instruction = renderTemplate("spawn.reportup.coordinator");
+    appendBlocks.push(instruction);
+    relayInjectionEvents.push({
+      category: "instructions",
+      summary: "injected coordinator child-response instructions",
+      detail: { source: "coordinator-child-report-up", content: instruction },
+    });
+  }
+  const { system: profileSystem, append: profileAppend } = profileInstructionBlocks(input.profile, input.memoryIdentity?.provider);
+  if (profileSystem) appendBlocks.push(profileSystem);
+  appendBlocks.push(...profileAppend);
+  // After the profile, so the step rule is the last word over a charter's report-to-spawner text.
+  if (input.workflowRunId) {
+    const instruction = renderTemplate("spawn.reportup.workflow-step", { runId: input.workflowRunId });
+    appendBlocks.push(instruction);
+    relayInjectionEvents.push({ category: "instructions", summary: "injected workflow step reporting instructions", detail: { source: "workflow-step-report", workflowRunId: input.workflowRunId, content: instruction } });
+  }
+  if (profileSystem || profileAppend.length) {
+    relayInjectionEvents.push({
+      category: "instructions",
+      summary: `injected profile instructions (${profileAppend.length + (profileSystem ? 1 : 0)} block${profileAppend.length + (profileSystem ? 1 : 0) === 1 ? "" : "s"})`,
+      detail: {
+        source: "agent-profile",
+        ...(profileSystem ? { system: profileSystem } : {}),
+        append: profileAppend,
+      },
+    });
+  }
+  // #2976 — one effort section for a coordinator's charter and for any agent with a grant, from one
+  // source, composed at read time so the DB-owned charter is never rewritten.
+  const profileName = canonicalAgentProfileName(input.profile?.name ?? input.memoryIdentity?.profile);
+  if (profileName === "sub-coordinator" || COORDINATOR_PROFILE_NAMES.some(name => name === profileName)) appendBlocks.push(composeGuideIndex());
+  const effort = effortSectionForProfile(input.profile, input.selfEffort === true);
+  if (effort) {
+    appendBlocks.push(effort.content);
+    relayInjectionEvents.push({
+      category: "instructions",
+      summary: "injected effort rule",
+      detail: { source: effort.source, content: effort.content },
+    });
+  }
+  if (input.agentRelayIdentity) {
+    const block = humwickIdentitySection(input.agentRelayIdentity);
+    appendBlocks.push(block);
+    relayInjectionEvents.push({
+      category: "context",
+      summary: "injected default identity",
+      detail: { source: "agent-relay-identity", content: block },
+    });
+  }
+  // Strip BOTH relay-owned marked sections a previous generation's append may carry: the identity
+  // block, and (#1565 P4) the memory block. Recompose-never-replay — a restart must re-derive the
+  // memory from the DB, not stack last generation's copy of it. #2591 adds the journal block to
+  // the same strip+defuse pass: a parent's carried-forward append may hold either block.
+  // …and then DEFUSE whatever markers the caller's own text still carries (#1565 F2): stripping is
+  // strict about what it removes, so a brief that merely mentions a marker survives intact — and
+  // neutralizing what survives keeps it from being read as this prompt's memory/journal block later.
+  const callerSystemPromptAppend = input.callerSystemPromptAppend
+    ? neutralizeJournalMarkers(neutralizeMemoryMarkers(stripJournalPreamble(stripMemoryPreamble(stripHumwickIdentitySection(input.callerSystemPromptAppend)))))
+    : undefined;
+  if (callerSystemPromptAppend?.trim()) {
+    appendBlocks.push(callerSystemPromptAppend);
+    relayInjectionEvents.push({
+      category: "context",
+      summary: "injected caller context",
+      detail: { source: "caller-system-prompt-append", content: callerSystemPromptAppend },
+    });
+  }
+  // #2836 — the one agent core block, dashboard-editable via the prompt-template
+  // registry. Rendered (not code-owned) so an operator edit lands fleet-wide. Gated
+  // on the profile's relay.context switch: vanilla/minimal/isolated-research opted
+  // out of the Relay prompt surface and must not get the core either.
+  const renderedCore = renderAgentCore(profileName, input.principalUserId ?? input.memoryIdentity?.operator);
+  const agentCore = input.profile?.relay?.context === false ? "" : renderedCore;
+  // Withheld does not mean kept: strip stale copies (shipped or customized) even when the
+  // profile opted out — a pure function cannot strip an unknown custom text from "" alone,
+  // so the rendered text is passed for stripping while appending stays disabled.
+  const systemPromptAppend = agentCore.trim()
+    ? withAgentCore(appendBlocks.join("\n\n"), agentCore)
+    : stripAgentCore(appendBlocks.join("\n\n"), renderedCore);
+  if (agentCore.trim()) {
+    relayInjectionEvents.push({
+      category: "instructions",
+      summary: "injected agent core block",
+      detail: { source: "relay-agent-core", content: agentCore },
+    });
+  }
+  return {
+    systemPromptAppend,
+    relayInjectionEvents,
+    renderedAgentCore: renderedCore,
+    // Project inclusion is re-derived from the selected profile at every later boundary. The
+    // launch-time value is stamped only as an agreement witness for the supersede notice: a
+    // profile-switch flip must not be described as a project-rule retraction.
+    ...(input.memoryIdentity
+      ? { memorySeam: { identity: input.memoryIdentity, projectMemoryEnabled: input.projectInstructionsEnabled === true } }
+      : {}),
+  };
+}
+
+/** Async request-path twin of {@link composeSpawnInstructionsWithEvents}. */
+export async function composeSpawnInstructionsWithEventsAsync(input: Parameters<typeof composeSpawnInstructionsWithEvents>[0]): Promise<ComposedSpawnInstructions> {
+  let memoryPreamble: (() => ReturnType<typeof composeMemoryPreamble>) | undefined;
+  if (input.memoryIdentity) {
+    try {
+      const memory = await composeMemoryPreambleAsync(input.memoryIdentity, {
+        cells: lifecycleMemoryCells(input.projectInstructionsEnabled === true),
+        projectNativeInstructionFiles: lifecycleProjectNativeInstructionFiles(input.projectInstructionsEnabled === true, input.memoryIdentity.provider),
+      });
+      memoryPreamble = () => memory;
+    } catch (error) {
+      memoryPreamble = () => { throw error; };
+    }
+  }
+  return composeSpawnInstructionsWithEvents({
+    ...input,
+    memoryPreamble,
+    validationPreamble: await resolveProjectValidationPreambleAsync(input.cwd, input.host, input.agentRuntimeCwd),
+  });
+}
+
+/**
+ * #1052 — the SINGLE home that resolves a profile's spawn-time knowledge world (project
+ * preamble for the cwd + scoped {profile|user} memory anchors) and runs
+ * `composeSpawnInstructionsWithEvents`. Every path that (re)builds a profile-bearing spawn —
+ * fresh managed spawn, managed-policy restart, AND the dashboard "restart Runner/Agent" relaunch
+ * for a NON-policy agent — must call this so a restarted agent is onboarded byte-identically to
+ * its first launch (role charter + project knowledge + scoped memory). Before #1052-v2 the
+ * dashboard-restart path for a dashboard-spawned (non-policy) coordinator called
+ * `buildSpawnCommand` WITHOUT this projection, so the relaunched process came back with EMPTY
+ * injection logs and silently reverted to provider-default IC behavior.
+ */
+export function composeProfileSpawnInstructions(input: {
+  cwd?: string;
+  profileName?: string;
+  profile?: Pick<AgentProfile, "instructions" | "maxSpawnedAgents" | "hostAwareness" | "roleAssets"> & { name?: string; relay?: AgentProfile["relay"] };
+  callerSystemPromptAppend?: string;
+  agentRelayIdentity?: Record<string, unknown>;
+  /** #1951 — authoritative parent lineage, for the spawned-child report-up block (§ block 2).
+   *  Restart used to omit this, so a restarted (and, before P4b's sibling, a compacted) child
+   *  silently lost its "you are a spawned child, report up" instruction. Forwarded verbatim to
+   *  {@link composeSpawnInstructionsWithEvents}, which is what actually gates the block. */
+  spawnedBy?: string;
+  /** #3045 — forwarded to the composer's workflow step block. */
+  workflowRunId?: string;
+  /** #2976 — forwarded to the composer's effort rule gate. */
+  selfEffort?: boolean;
+  /** Operator/user anchor key; defaults to the single-operator default store. */
+  operatorId?: string;
+  /** #1565 P4 — the spawned agent's provider (`claude`, `codex`, …), for the `provider` memory
+   * cell. Absent simply skips that cell; it is NEVER a behavior branch. */
+  provider?: string;
+  /** #1565 P4 — the HOSTNAME the agent will run on (D9), for the `host` memory cell. #1608:
+   * absent/empty means "unresolvable", not "the relay's own host" — every caller must resolve
+   * its own canonical value (`resolveCanonicalHost`) or omit the field; this composer never
+   * guesses via `os.hostname()`, which would misattribute a remote spawn to wherever the relay
+   * process happens to run. */
+  host?: string;
+  /**
+   * #1625 — replay a launch-recorded identity instead of deriving a fresh one. It is authoritative
+   * for identity only: Project memory inclusion is derived from `profileName`'s current Project
+   * Instructions cell. `cwd` still drives the #1381 validation preamble.
+   */
+  memorySeam?: MemorySeam;
+}): ComposedSpawnInstructions {
+  // Canonicalized (#1597): a worktree/steward spawn inherits the REAL project's instructions
+  // instead of a branch-named phantom's (or, once the phantoms were archived, none at all).
+  // Resolved lazily: a replayed seam (#1625) already carries the projectId, and this probe can
+  // reach the filesystem/git for a worktree cwd.
+  const seam: MemorySeam = input.memorySeam ?? (() => {
+    const callerProject = input.cwd ? resolveProjectForCanonicalCwd(input.cwd).project ?? undefined : undefined;
+    return {
+      identity: {
+        operator: input.operatorId ?? DEFAULT_USER_ID,
+        ...(input.host?.trim() ? { host: input.host.trim() } : {}),
+        ...(input.provider ? { provider: input.provider } : {}),
+        ...(callerProject ? { projectId: callerProject.id } : {}),
+        ...(input.profileName ? { profile: input.profileName } : {}),
+      },
+    };
+  })();
+  const host = landGatesHost(input);
+  return composeSpawnInstructionsWithEvents({
+    // Resolve from the config store, rather than a caller-supplied partial projection. That keeps
+    // the named profile's Project Instructions cell the single source of truth for this gate.
+    projectInstructionsEnabled: projectMemoryEnabledForProfile(seam.identity.profile),
+    ...(input.cwd ? { cwd: input.cwd } : {}),
+    // #2171 — the land-gates read follows the agent's host, not the relay's. A replayed seam keeps
+    // its recorded host authoritative for that too, so a restart reads the same machine its spawn did.
+    ...(host ? { host } : {}),
+    memoryIdentity: seam.identity,
+    ...(input.profile ? { profile: input.profile } : {}),
+    ...(input.spawnedBy ? { spawnedBy: input.spawnedBy } : {}),
+    ...(input.workflowRunId ? { workflowRunId: input.workflowRunId } : {}),
+    ...(input.selfEffort ? { selfEffort: true } : {}),
+    ...(input.agentRelayIdentity ? { agentRelayIdentity: input.agentRelayIdentity } : {}),
+    ...(input.callerSystemPromptAppend ? { callerSystemPromptAppend: input.callerSystemPromptAppend } : {}),
+  });
+}
+
+/** The machine whose disk holds this spawn's `land-gates.json` (#2171): the caller's explicit
+ *  `host` when it named one, else the host the replayed launch identity recorded. */
+function landGatesHost(input: { host?: string; memorySeam?: MemorySeam }): string | undefined {
+  return input.host?.trim() || input.memorySeam?.identity.host?.trim() || undefined;
+}
+
+/** Async request-path twin. Use this when deriving a cwd's project identity can touch disk. */
+export async function composeProfileSpawnInstructionsAsync(input: Parameters<typeof composeProfileSpawnInstructions>[0]): Promise<ComposedSpawnInstructions> {
+  const callerProject = !input.memorySeam && input.cwd
+    ? (await resolveProjectForCanonicalCwdAsync(input.cwd)).project ?? undefined
+    : undefined;
+  const seam: MemorySeam = input.memorySeam ?? (() => ({
+    identity: {
+      operator: input.operatorId ?? DEFAULT_USER_ID,
+      ...(input.host?.trim() ? { host: input.host.trim() } : {}),
+      ...(input.provider ? { provider: input.provider } : {}),
+      ...(callerProject ? { projectId: callerProject.id } : {}),
+      ...(input.profileName ? { profile: input.profileName } : {}),
+    },
+  }))();
+  const host = landGatesHost(input);
+  return composeSpawnInstructionsWithEventsAsync({
+    projectInstructionsEnabled: projectMemoryEnabledForProfile(seam.identity.profile),
+    ...(input.cwd ? { cwd: input.cwd } : {}),
+    ...(host ? { host } : {}),
+    memoryIdentity: seam.identity,
+    ...(input.profile ? { profile: input.profile } : {}),
+    ...(input.spawnedBy ? { spawnedBy: input.spawnedBy } : {}),
+    ...(input.workflowRunId ? { workflowRunId: input.workflowRunId } : {}),
+    ...(input.selfEffort ? { selfEffort: true } : {}),
+    ...(input.agentRelayIdentity ? { agentRelayIdentity: input.agentRelayIdentity } : {}),
+    ...(input.callerSystemPromptAppend ? { callerSystemPromptAppend: input.callerSystemPromptAppend } : {}),
+  });
+}