agent-relay-server 0.58.0 → 0.59.0

package/src/db/stats.ts

@@ -135,20 +135,35 @@ export const ANALYTICS_PERIODS = {
 
 export type AnalyticsPeriod = keyof typeof ANALYTICS_PERIODS;
 
-// Message → category, the ONE place this mapping lives (server-side SQL). Order is
-// significant: a claimable/system/pair/channel message is classified as such even
-// when it is also a reply; only an otherwise-plain reply counts as "Replies".
-export const ANALYTICS_CATEGORIES = ["Messages", "Replies", "Work items", "System", "Pair", "Channel"] as const;
-export type AnalyticsCategory = (typeof ANALYTICS_CATEGORIES)[number];
-export const ANALYTICS_CATEGORY_SQL = `
+// ─── Analytics taxonomy ─────────────────────────────────────────────────────
+// The relay carries three distinct streams of activity, and analytics keeps them
+// SEPARATE rather than collapsing into one "messages" count (which is ~94%
+// session-mirror noise on a busy relay — see the work layer below):
+//   1. Conversation — real inter-agent / human messaging (chat, replies, channel, pair, work items)
+//   2. Work — session-mirror cognition: tool calls, reasoning, narration, responses
+//   3. Fleet — agent registrations/spawns + per-agent activity (NOT online/offline:
+//      agents start, work, and shut down constantly — point-in-time status is noise here)
+
+// Conversation categories. Order is significant: a claimable/channel/pair message
+// is classified as such even when it is also a reply; only an otherwise-plain reply
+// counts as "Replies". Session/control/system rows are EXCLUDED (they're streams 2/mechanical).
+export const CONVERSATION_CATEGORIES = ["Chat", "Replies", "Channel", "Pair", "Work items"] as const;
+export type ConversationCategory = (typeof CONVERSATION_CATEGORIES)[number];
+const CONVERSATION_CATEGORY_SQL = `
   CASE
     WHEN claimable = 1 THEN 'Work items'
-    WHEN kind = 'system' OR from_agent = 'system' THEN 'System'
-    WHEN kind = 'pair' THEN 'Pair'
     WHEN kind = 'channel.event' THEN 'Channel'
+    WHEN kind = 'pair' THEN 'Pair'
     WHEN reply_to IS NOT NULL THEN 'Replies'
-    ELSE 'Messages'
+    ELSE 'Chat'
   END`;
+// Only real messaging — excludes the session-mirror lane and mechanical/system rows.
+const CONVERSATION_FILTER = `kind NOT IN ('session','control','system') AND from_agent != 'system'`;
+
+// Session-mirror event sub-types we surface as the "agent work" composition. (prompt
+// is counted in the user-interaction stream; notice is mechanical chatter.)
+export const WORK_TYPES = ["tool", "reasoning", "narration", "response"] as const;
+export type WorkType = (typeof WORK_TYPES)[number];
 
 export interface AnalyticsData {
   period: AnalyticsPeriod;
@@ -156,52 +171,196 @@ export interface AnalyticsData {
   now: number;
   bucketMs: number;
   bucketCount: number;
-  // Per-bucket category counts, oldest → newest, length === bucketCount.
-  buckets: Array<{ start: number; counts: Record<AnalyticsCategory, number> }>;
-  // Category totals over the whole period (powers the breakdown donut).
-  categories: Record<AnalyticsCategory, number>;
-  // Busiest-hours grid: heatmap[dayOfWeek 0=Sun][hour 0-23], in server-local time.
+  // 1. Conversation — real messaging volume, per-bucket (oldest→newest) + totals.
+  conversation: {
+    buckets: Array<{ start: number; counts: Record<ConversationCategory, number> }>;
+    totals: Record<ConversationCategory, number>;
+    total: number;
+  };
+  // 2. Work — session-mirror cognition: per-bucket type counts, totals, tool leaderboard, turn count.
+  work: {
+    buckets: Array<{ start: number; counts: Record<WorkType, number> }>;
+    totals: Record<WorkType, number>;
+    topTools: Array<{ name: string; count: number }>;
+    turns: number;
+    toolCalls: number;
+  };
+  // 3. User interaction — human prompts, reply rate, and agent reply latency (median is
+  // the headline; avg is tail-inflated by agents that were away mid-conversation).
+  user: {
+    prompts: number;
+    replied: number;
+    replyRate: number; // 0..1
+    latencyMs: { median: number; avg: number; p90: number } | null;
+    buckets: Array<{ start: number; prompts: number }>;
+  };
+  // 4. Fleet — activity-based, never online/offline. Registrations (spawns) over time,
+  // how many were agent-spawned, distinct active agents, and a per-agent leaderboard.
+  fleet: {
+    activeAgents: number;
+    registrations: number;
+    spawnedByAgent: number;
+    buckets: Array<{ start: number; registrations: number }>;
+    leaderboard: Array<{ id: string; label: string | null; turns: number; toolCalls: number; messages: number }>;
+  };
+  // Busiest-hours grid: heatmap[dayOfWeek 0=Sun][hour 0-23], server-local time, all activity.
   heatmap: number[][];
-  totalMessages: number;
   totalReactions: number;
 }
 
-export function emptyCategoryCounts(): Record<AnalyticsCategory, number> {
-  return { Messages: 0, Replies: 0, "Work items": 0, System: 0, Pair: 0, Channel: 0 };
+function emptyConversationCounts(): Record<ConversationCategory, number> {
+  return { Chat: 0, Replies: 0, Channel: 0, Pair: 0, "Work items": 0 };
+}
+function emptyWorkCounts(): Record<WorkType, number> {
+  return { tool: 0, reasoning: 0, narration: 0, response: 0 };
+}
+
+// Percentile over an unsorted list of numbers (linear interpolation-free nearest-rank).
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+  return sorted[idx] ?? 0;
 }
 
 export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()): AnalyticsData {
   const { ms, buckets: bucketCount } = ANALYTICS_PERIODS[period] ?? ANALYTICS_PERIODS["24h"];
   const start = now - ms;
   const bucketMs = ms / bucketCount;
+  const db = getDb();
+  // created_at in (start, now] keeps the floored bucket index in [0, bucketCount).
+  const clampIdx = (bucket: number) => Math.min(Math.max(bucket, 0), bucketCount - 1);
+  const bucketStarts = Array.from({ length: bucketCount }, (_, i) => start + i * bucketMs);
 
-  const buckets = Array.from({ length: bucketCount }, (_, i) => ({
-    start: start + i * bucketMs,
-    counts: emptyCategoryCounts(),
-  }));
-  const categories = emptyCategoryCounts();
-
-  // One pass: bucket index × category counts. CAST floors toward zero; created_at
-  // in (start, now] keeps the index in [0, bucketCount).
-  const volumeRows = getDb()
+  // ── 1. Conversation: real messaging volume ──
+  const conversationBuckets = bucketStarts.map((s) => ({ start: s, counts: emptyConversationCounts() }));
+  const conversationTotals = emptyConversationCounts();
+  const convRows = db
     .query(
-      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, ${ANALYTICS_CATEGORY_SQL} AS category, COUNT(*) AS c
-       FROM messages WHERE created_at > ? AND created_at <= ? GROUP BY bucket, category`,
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, ${CONVERSATION_CATEGORY_SQL} AS category, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND ${CONVERSATION_FILTER} GROUP BY bucket, category`,
     )
-    .all(start, bucketMs, start, now) as Array<{ bucket: number; category: AnalyticsCategory; c: number }>;
-  for (const row of volumeRows) {
-    const idx = Math.min(Math.max(row.bucket, 0), bucketCount - 1);
-    const bucket = buckets[idx];
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; category: ConversationCategory; c: number }>;
+  for (const row of convRows) {
+    const bucket = conversationBuckets[clampIdx(row.bucket)];
     if (bucket && row.category in bucket.counts) {
       bucket.counts[row.category] += row.c;
-      categories[row.category] += row.c;
+      conversationTotals[row.category] += row.c;
+    }
+  }
+  const conversationTotal = Object.values(conversationTotals).reduce((sum, v) => sum + v, 0);
+
+  // ── 2. Work: session-mirror cognition ──
+  const workBuckets = bucketStarts.map((s) => ({ start: s, counts: emptyWorkCounts() }));
+  const workTotals = emptyWorkCounts();
+  const workRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket,
+              json_extract(payload, '$.session.type') AS wtype, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+         AND json_extract(payload, '$.session.type') IN ('tool','reasoning','narration','response')
+       GROUP BY bucket, wtype`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; wtype: WorkType; c: number }>;
+  for (const row of workRows) {
+    const bucket = workBuckets[clampIdx(row.bucket)];
+    if (bucket && row.wtype in bucket.counts) {
+      bucket.counts[row.wtype] += row.c;
+      workTotals[row.wtype] += row.c;
     }
   }
-  const totalMessages = Object.values(categories).reduce((sum, v) => sum + v, 0);
+  const topTools = db
+    .query(
+      `SELECT json_extract(payload, '$.session.label') AS name, COUNT(*) AS count
+       FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+         AND json_extract(payload, '$.session.type') = 'tool'
+         AND json_extract(payload, '$.session.label') IS NOT NULL
+       GROUP BY name ORDER BY count DESC LIMIT 12`,
+    )
+    .all(start, now) as Array<{ name: string; count: number }>;
+  const turns = (
+    db
+      .query(
+        `SELECT COUNT(DISTINCT json_extract(payload, '$.session.turnId')) AS c
+         FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+           AND json_extract(payload, '$.session.turnId') IS NOT NULL`,
+      )
+      .get(start, now) as { c: number }
+  ).c;
+
+  // ── 3. User interaction: human prompts + agent reply latency ──
+  const userBuckets = bucketStarts.map((s) => ({ start: s, prompts: 0 }));
+  const promptRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND from_agent = 'user' GROUP BY bucket`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; c: number }>;
+  let prompts = 0;
+  for (const row of promptRows) {
+    const bucket = userBuckets[clampIdx(row.bucket)];
+    if (bucket) bucket.prompts += row.c;
+    prompts += row.c;
+  }
+  // Latency = first threaded reply from a non-user agent, in (start, now] by the prompt's time.
+  const latencyRows = db
+    .query(
+      `SELECT (r.created_at - u.created_at) AS delta
+       FROM messages u JOIN messages r ON r.reply_to = u.id
+       WHERE u.from_agent = 'user' AND r.from_agent != 'user'
+         AND u.created_at > ? AND u.created_at <= ? AND r.created_at >= u.created_at`,
+    )
+    .all(start, now) as Array<{ delta: number }>;
+  const deltas = latencyRows.map((r) => r.delta).sort((a, b) => a - b);
+  const replied = deltas.length;
+  const latencyMs =
+    replied > 0
+      ? {
+          median: percentile(deltas, 50),
+          avg: Math.round(deltas.reduce((sum, d) => sum + d, 0) / replied),
+          p90: percentile(deltas, 90),
+        }
+      : null;
+
+  // ── 4. Fleet: registrations (spawns) over time + per-agent leaderboard ──
+  const fleetBuckets = bucketStarts.map((s) => ({ start: s, registrations: 0 }));
+  const regRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, COUNT(*) AS c,
+              SUM(CASE WHEN spawned_by IS NOT NULL THEN 1 ELSE 0 END) AS spawned
+       FROM agents WHERE created_at > ? AND created_at <= ? GROUP BY bucket`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; c: number; spawned: number }>;
+  let registrations = 0;
+  let spawnedByAgent = 0;
+  for (const row of regRows) {
+    const bucket = fleetBuckets[clampIdx(row.bucket)];
+    if (bucket) bucket.registrations += row.c;
+    registrations += row.c;
+    spawnedByAgent += row.spawned ?? 0;
+  }
+  const activeAgents = (
+    db
+      .query(
+        `SELECT COUNT(DISTINCT from_agent) AS c FROM messages
+         WHERE created_at > ? AND created_at <= ? AND from_agent NOT IN ('system','user')`,
+      )
+      .get(start, now) as { c: number }
+  ).c;
+  const leaderboard = db
+    .query(
+      `SELECT m.from_agent AS id, a.label AS label,
+              COUNT(DISTINCT CASE WHEN m.kind = 'session' THEN json_extract(m.payload, '$.session.turnId') END) AS turns,
+              SUM(CASE WHEN m.kind = 'session' AND json_extract(m.payload, '$.session.type') = 'tool' THEN 1 ELSE 0 END) AS toolCalls,
+              SUM(CASE WHEN m.kind != 'session' THEN 1 ELSE 0 END) AS messages
+       FROM messages m LEFT JOIN agents a ON a.id = m.from_agent
+       WHERE m.created_at > ? AND m.created_at <= ? AND m.from_agent NOT IN ('system','user')
+       GROUP BY m.from_agent ORDER BY (toolCalls + messages) DESC LIMIT 10`,
+    )
+    .all(start, now) as Array<{ id: string; label: string | null; turns: number; toolCalls: number; messages: number }>;
 
-  // Busiest-hours heatmap (day-of-week × hour), server-local time.
+  // ── Busiest-hours heatmap (all activity, day-of-week × hour, server-local time) ──
   const heatmap: number[][] = Array.from({ length: 7 }, () => new Array(24).fill(0));
-  const heatRows = getDb()
+  const heatRows = db
     .query(
       `SELECT CAST(strftime('%w', created_at / 1000, 'unixepoch', 'localtime') AS INTEGER) AS dow,
               CAST(strftime('%H', created_at / 1000, 'unixepoch', 'localtime') AS INTEGER) AS hour, COUNT(*) AS c
@@ -214,7 +373,7 @@ export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()):
   }
 
   const totalReactions = (
-    getDb()
+    db
       .query(
         `SELECT COUNT(*) AS c FROM message_reactions r
          JOIN messages m ON m.id = r.message_id WHERE m.created_at > ? AND m.created_at <= ?`,
@@ -222,7 +381,19 @@ export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()):
       .get(start, now) as { c: number }
   ).c;
 
-  return { period, start, now, bucketMs, bucketCount, buckets, categories, heatmap, totalMessages, totalReactions };
+  return {
+    period,
+    start,
+    now,
+    bucketMs,
+    bucketCount,
+    conversation: { buckets: conversationBuckets, totals: conversationTotals, total: conversationTotal },
+    work: { buckets: workBuckets, totals: workTotals, topTools, turns, toolCalls: workTotals.tool },
+    user: { prompts, replied, replyRate: prompts > 0 ? replied / prompts : 0, latencyMs, buckets: userBuckets },
+    fleet: { activeAgents, registrations, spawnedByAgent, buckets: fleetBuckets, leaderboard },
+    heatmap,
+    totalReactions,
+  };
 }
 
 export function getHealth(now: number = Date.now()): HealthReport {

package/src/maintenance.ts

@@ -39,7 +39,7 @@ import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { reconcileLandedWorkspace } from "./branch-landed";
 import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
-import { preparePrCompletionScan } from "./workspace-pr-completion";
+import { preparePrCompletionScan, reconcileLandedPr } from "./workspace-pr-completion";
 import { notifyAgentOffline } from "./agent-lifecycle-events";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
@@ -655,6 +655,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   );
   const flagged: string[] = [], cleared: string[] = [], merged: string[] = [], notifiedStewards: string[] = [];
   const reviewerArmed: string[] = [], reviewerChangesRequested: string[] = [], relayPrMerged: string[] = [], relayPrWaiting: string[] = [];
+  const prRecycled: string[] = [];
 
   for (const ws of candidates) {
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
@@ -687,6 +688,12 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     // branch-landed.ts (#304).
     const landed = p.landed === true || p.prMerged === true;
     if (landed && LANDED_RECONCILE_STATUSES.has(ws.status)) {
+      // A PR-land merges asynchronously on the remote, outside the relay's land path. For a
+      // LIVE owner that means recycle (land-and-continue, #423); for a gone owner, finalize
+      // terminal `merged` (#304). `reconcileLandedPr` owns that split — see workspace-pr-completion.
+      const outcome = reconcileLandedPr(ws, p);
+      if (outcome.kind === "recycle") { emitCommand(outcome.command); prRecycled.push(ws.id); continue; }
+      if (outcome.kind === "wait") { relayPrWaiting.push(`${ws.id}:${outcome.reason}`); continue; }
       reconcileLandedWorkspace(ws, p);
       merged.push(ws.id);
       continue;
@@ -752,7 +759,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     }
   }
 
-  return { scanned: candidates.length, flagged, cleared, merged, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
+  return { scanned: candidates.length, flagged, cleared, merged, prRecycled, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
 }
 
 // Deterministic auto-land (Layer 0, #167/#207/#242): land conflict-free ready

package/src/mcp.ts

@@ -50,6 +50,7 @@ import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
 import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools";
+import { PROJECT_INSTRUCTION_POLICY_NAMES, parseProjectInstructions } from "./project-instructions";
 import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action";
 import type { ActivityKind, AgentLifecycle, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
@@ -310,6 +311,7 @@ const TOOLS: ToolDefinition[] = [
         prompt: { type: "string", description: "Initial task/message delivered to the agent on launch — spawn and hand it its first instruction in one call (no separate follow-up message needed)." },
         expectReply: { type: "boolean", description: "Require the worker to report back: it gets a pending reply obligation to you and CANNOT go idle until it delivers its result (which routes to your inbox and wakes you). Defaults true when you pass a prompt — set false for a true fire-and-forget worker that needn't report (e.g. one that only lands a branch)." },
         systemPromptAppend: { type: "string" },
+        projectInstructions: { type: "object", description: "#409 — project instruction projection (default OFF). When set, relay composes a knowledge preamble from the spawn cwd's resolved project (own + inherited entries) and prepends it to systemPromptAppend, instead of relying on host CLAUDE.md. `policy: \"all\"` includes ingested host content; `\"vanilla\"` excludes it (manual+promoted only). Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_INSTRUCTION_POLICY_NAMES } }, additionalProperties: false },
         profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
@@ -874,6 +876,7 @@ async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknow
     prompt: optionalString(args.prompt, "prompt", 16_000),
     expectReply: typeof args.expectReply === "boolean" ? args.expectReply : undefined,
     systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
+    projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
     tags: optionalStringArray(args.tags, "tags"),
     capabilities: optionalStringArray(args.capabilities, "capabilities"),
     providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),

package/src/project-instructions.ts

@@ -0,0 +1,176 @@
+// Project instruction projection (#409) — the relay-owned replacement for host
+// CLAUDE.md bleed-in. Given a resolved project, render its `rule`/`fact` entries
+// (own + inherited `contains`-ancestor entries from #406's cascade) into a compact,
+// DETERMINISTIC, size-bounded instruction block that can be prepended to a spawned
+// agent's systemPromptAppend.
+//
+// ADDITIVE-FROM-EMPTY (#403 decision 4): this composer builds the instruction world
+// from NOTHING and ADDS project knowledge. It NEVER reads host CLAUDE.md or subtracts
+// from it. Going fully vanilla later = simply not including host-derived (`ingested`)
+// content — a policy switch here, zero schema/composer change. `project_entries.source`
+// is that lever: the included-source set is a policy PARAMETER, and the `vanilla`
+// policy includes `manual`+`promoted` while excluding `ingested`.
+import { resolveProjectEntries } from "./db";
+import { PROJECT_ENTRY_SOURCES, type Project, type ProjectEntryKind, type ProjectEntrySource, type ResolvedProjectEntry } from "./types";
+
+/** Named source policies — THE additive-from-empty lever (#403 decision 4).
+ *   `all`     — every source (manual + promoted + ingested host-CLAUDE.md content).
+ *   `vanilla` — manual + promoted only; EXCLUDES `ingested`, so a vanilla agent gets
+ *               zero host-CLAUDE.md bleed-in while still receiving relay-native knowledge. */
+export const PROJECT_INSTRUCTION_SOURCE_SETS = {
+  all: PROJECT_ENTRY_SOURCES,
+  vanilla: ["manual", "promoted"],
+} as const satisfies Record<string, readonly ProjectEntrySource[]>;
+
+export const PROJECT_INSTRUCTION_POLICY_NAMES = ["all", "vanilla"] as const;
+export type ProjectInstructionPolicyName = (typeof PROJECT_INSTRUCTION_POLICY_NAMES)[number];
+
+/** Per-spawn projection request. Presence (a non-undefined value on the spawn input)
+ * means "project the preamble"; absence means OFF. `policy` selects the source set. */
+export interface ProjectInstructionPolicy {
+  policy?: ProjectInstructionPolicyName;
+}
+
+export interface ComposeProjectInstructionsOptions {
+  /** Named policy selecting the included source set. Default `all`. */
+  policy?: ProjectInstructionPolicyName;
+  /** Explicit source set; overrides `policy` when given (the low-level lever). */
+  includeSources?: readonly ProjectEntrySource[];
+  /** Entry kinds rendered, in this order. Default `["rule", "fact"]` (the directive +
+   * truth kinds; `decision`/`memory` are log/scratch, not preamble material). */
+  includeKinds?: readonly ProjectEntryKind[];
+  /** Merge transitive `contains`-ancestor entries (#406 cascade). Default true. */
+  includeInherited?: boolean;
+  /** Hard byte cap on the rendered block (UTF-8). Default 8192. The block is truncated
+   * deterministically (lowest-priority entries dropped first) to stay within it. */
+  maxBytes?: number;
+}
+
+const DEFAULT_KINDS: readonly ProjectEntryKind[] = ["rule", "fact"];
+const DEFAULT_MAX_BYTES = 8192;
+const TRUNCATION_NOTICE = "_(… additional project entries omitted to fit the instruction budget.)_";
+
+const KIND_HEADINGS: Record<ProjectEntryKind, string> = {
+  rule: "Rules",
+  fact: "Facts",
+  decision: "Decisions",
+  memory: "Memory",
+};
+
+function byteLen(value: string): number {
+  return Buffer.byteLength(value, "utf8");
+}
+
+/** Stable dedup key — same kind + same (trimmed) title + body collapses to one entry.
+ * Uses NUL separators so distinct fields can't collide by concatenation. */
+function dedupKey(entry: ResolvedProjectEntry): string {
+  return `${entry.kind}\u0000${entry.title.trim()}\u0000${(entry.body ?? "").trim()}`;
+}
+
+function entryLine(entry: ResolvedProjectEntry): string {
+  const body = entry.body?.trim();
+  const tag = entry.inherited ? " _(inherited)_" : "";
+  return body ? `- ${entry.title.trim()}: ${body}${tag}` : `- ${entry.title.trim()}${tag}`;
+}
+
+/**
+ * Render a project's instruction block. Deterministic: ordering is by kind (in
+ * `includeKinds` order), then own-before-inherited, then title (code-point), then id —
+ * fully independent of DB row timestamps. Output is deduped and hard-bounded to
+ * `maxBytes`. Returns "" when no entry survives the source/kind filter (the caller then
+ * leaves systemPromptAppend untouched, so the spawn stays byte-identical).
+ */
+export function composeProjectInstructions(
+  project: Pick<Project, "id" | "slug" | "title">,
+  opts: ComposeProjectInstructionsOptions = {},
+): string {
+  const kinds = opts.includeKinds ?? DEFAULT_KINDS;
+  const kindRank = new Map<ProjectEntryKind, number>(kinds.map((kind, index) => [kind, index]));
+  const sources = new Set<ProjectEntrySource>(
+    opts.includeSources ?? PROJECT_INSTRUCTION_SOURCE_SETS[opts.policy ?? "all"],
+  );
+  const includeInherited = opts.includeInherited !== false;
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+
+  const resolved = resolveProjectEntries(project.id, { includeInherited });
+  const filtered = resolved.filter((entry) => kindRank.has(entry.kind) && sources.has(entry.source));
+
+  // Deterministic ordering, independent of DB row order/timestamps.
+  filtered.sort((a, b) => {
+    const byKind = (kindRank.get(a.kind) ?? 0) - (kindRank.get(b.kind) ?? 0);
+    if (byKind !== 0) return byKind;
+    const byInherited = Number(a.inherited) - Number(b.inherited); // own (false) first
+    if (byInherited !== 0) return byInherited;
+    const ta = a.title.trim();
+    const tb = b.title.trim();
+    if (ta !== tb) return ta < tb ? -1 : 1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+
+  // Dedup, own-wins (own sorts before inherited above).
+  const seen = new Set<string>();
+  const deduped: ResolvedProjectEntry[] = [];
+  for (const entry of filtered) {
+    const key = dedupKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(entry);
+  }
+  if (deduped.length === 0) return "";
+
+  // Greedy size-bounded render. Entries are contiguous by kind (primary sort key), so a
+  // per-kind `## heading` is emitted once when the first entry of that kind is included.
+  const header = `# Project knowledge: ${project.title?.trim() || project.slug}`;
+  const budget = maxBytes - byteLen(`\n\n${TRUNCATION_NOTICE}`);
+  const lines: string[] = [header];
+  let bytes = byteLen(header);
+  let lastKind: ProjectEntryKind | null = null;
+  let truncated = false;
+
+  for (const entry of deduped) {
+    const segments: string[] = [];
+    if (entry.kind !== lastKind) segments.push("", `## ${KIND_HEADINGS[entry.kind]}`);
+    segments.push(entryLine(entry));
+    const addition = `\n${segments.join("\n")}`;
+    if (bytes + byteLen(addition) > budget) {
+      truncated = true;
+      break;
+    }
+    lines.push(...segments);
+    bytes += byteLen(addition);
+    lastKind = entry.kind;
+  }
+
+  if (truncated) lines.push("", TRUNCATION_NOTICE);
+  let out = lines.join("\n");
+  // Safety net: guarantee the hard byte cap even if the header + first entry overshoot.
+  if (byteLen(out) > maxBytes) {
+    out = Buffer.from(out, "utf8").subarray(0, maxBytes).toString("utf8");
+  }
+  return out;
+}
+
+/**
+ * Parse a spawn-transport's `projectInstructions` wire value into the normalized policy
+ * (or undefined = OFF). Shared by the MCP and HTTP spawn paths so they cannot drift.
+ *   - undefined / null / false → undefined (OFF)
+ *   - true                     → {} (ON, default policy)
+ *   - { policy }               → validated policy
+ * Throws `onInvalid(message)` for a malformed shape or unknown policy name.
+ */
+export function parseProjectInstructions(
+  value: unknown,
+  onInvalid: (message: string) => Error,
+): ProjectInstructionPolicy | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (typeof value !== "object") {
+    throw onInvalid("projectInstructions must be a boolean or { policy } object");
+  }
+  const policy = (value as Record<string, unknown>).policy;
+  if (policy === undefined) return {};
+  if (typeof policy !== "string" || !PROJECT_INSTRUCTION_POLICY_NAMES.includes(policy as ProjectInstructionPolicyName)) {
+    throw onInvalid(`projectInstructions.policy must be one of: ${PROJECT_INSTRUCTION_POLICY_NAMES.join(", ")}`);
+  }
+  return { policy: policy as ProjectInstructionPolicyName };
+}

package/src/routes/agents-spawn.ts

@@ -6,6 +6,7 @@ import { ValidationError, listAgents } from "../db";
 import { cleanMeta, cleanNullableString, cleanString, cleanStringArray, optionalEnum } from "../validation";
 import { registerAgent } from "../services/register-agent";
 import { spawnAgent, type SpawnAgentInput } from "../services/spawn-agent";
+import { parseProjectInstructions } from "../project-instructions";
 import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
@@ -116,6 +117,7 @@ export const postAgentSpawn: Handler = async (req) => {
       profile: cleanString(parsed.body.profile, "profile", { max: 120 }),
       prompt: cleanString(parsed.body.prompt, "prompt", { max: 16000 }),
       systemPromptAppend: cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 }),
+      projectInstructions: parseProjectInstructions(parsed.body.projectInstructions, (m) => new ValidationError(m)),
       tags: cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }),
       capabilities: cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }),
       providerArgs: cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }),

package/src/routes/commands.ts

@@ -229,15 +229,21 @@ export const patchCommand: Handler = async (req, params) => {
           if (newBranch) {
             setWorkspaceBranch(workspaceId, newBranch, baseSha ?? mergedSha);
           }
-          // #239 — push the author a "your branch landed" notice (no polling). Only on a
+          // #239 — push the author a "your branch landed" notice (no polling). Fires on a
           // real land; a no-op resolution (#230) merged nothing, so it earns no notice.
-          if (command.result.merged === true && landedWorkspace) {
+          // #423 — a PR-land RECYCLE is a no-op merge (`merged:false`) but a land DID happen
+          // on the remote: the relay carries that ground truth in `params.prLanded`, so the
+          // notice fires from it with the recycled `newBranch` — full rebase-ff parity.
+          const prLanded = isRecord(command.params.prLanded) ? command.params.prLanded : undefined;
+          if ((command.result.merged === true || prLanded) && landedWorkspace) {
             notifyBranchLanded({
               workspace: landedWorkspace,
-              mergedSha,
-              subject: cleanString(command.result.subject, "result.subject", { max: 200 }),
+              mergedSha: prLanded ? cleanString(prLanded.sha, "params.prLanded.sha", { max: 64 }) ?? mergedSha : mergedSha,
+              subject: prLanded
+                ? cleanString(prLanded.subject, "params.prLanded.subject", { max: 200 })
+                : cleanString(command.result.subject, "result.subject", { max: 200 }),
               newBranch,
-              pushed: typeof command.result.pushed === "boolean" ? command.result.pushed : undefined,
+              pushed: prLanded ? true : typeof command.result.pushed === "boolean" ? command.result.pushed : undefined,
             });
           }
         }

package/src/services/spawn-agent.ts

@@ -32,6 +32,7 @@ import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } fr
 import { runnerRuntimeTokenEnv } from "../runtime-tokens";
 import { selectSpawnOrchestrator } from "../spawn-targets";
 import { getAgentProfile } from "../config-store";
+import { composeProjectInstructions, type ProjectInstructionPolicy } from "../project-instructions";
 import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
@@ -62,6 +63,16 @@ export interface SpawnAgentInput {
   profile?: string;
   prompt?: string;
   systemPromptAppend?: string;
+  /**
+   * #409 — project instruction projection. When set, relay composes an instruction
+   * preamble from the spawn's resolved project (own entries + inherited `contains`-
+   * ancestors) and PREPENDS it to systemPromptAppend. Additive-from-empty (#403
+   * decision 4): the block is built only from `project_entries`, never from host
+   * CLAUDE.md. Absent (undefined) = OFF → the spawn command is byte-identical to today.
+   * `policy` selects the included source set: `all` (manual+promoted+ingested) or
+   * `vanilla` (manual+promoted; excludes `ingested` host-CLAUDE.md content).
+   */
+  projectInstructions?: ProjectInstructionPolicy;
   /**
    * #413 — does this spawn carry a report-back contract? When true, relay seeds a pending
    * reply obligation from the spawner to the child at registration, so the child can't go
@@ -197,6 +208,20 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // resolves it. Absent (graceful) when the cwd is inside no registered root.
   const callerProject = resolveProjectForCwd(resolvedCwd);
 
+  // #409 — instruction projection (default OFF). Only when the caller opts in AND the
+  // spawn cwd resolves to a project do we compose a knowledge preamble and PREPEND it to
+  // systemPromptAppend. Absent flag / no project / empty block ⇒ systemPromptAppend is
+  // left exactly as the caller passed it, so the spawn command stays byte-identical.
+  let systemPromptAppend = input.systemPromptAppend;
+  if (input.projectInstructions && callerProject) {
+    const block = composeProjectInstructions(callerProject, {
+      ...(input.projectInstructions.policy ? { policy: input.projectInstructions.policy } : {}),
+    });
+    if (block) {
+      systemPromptAppend = systemPromptAppend ? `${block}\n\n${systemPromptAppend}` : block;
+    }
+  }
+
   // Child runner token. `agentInitiated` (set whenever an agent is the caller) forces a
   // non-spawn-capable child (no grandchildren); `spawnedBy` stamps authoritative lineage the
   // child can't forge (it registers with spawnedBy = caller, read from the signed token).
@@ -244,7 +269,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       permissionMode: approvalMode,
       providerArgs: input.providerArgs ?? [],
       prompt: input.prompt,
-      systemPromptAppend: input.systemPromptAppend,
+      systemPromptAppend,
       ...(expectReply ? { expectReply } : {}),
       policyName: input.policyName,
       spawnRequestId,