@humwick/server 0.0.0-stage → 0.130.0

package/src/issue-tracker/registry.ts

@@ -0,0 +1,26 @@
+import type { IssueProvider, IssueRef } from "../types";
+import type { IssueTrackerAdapter } from "./adapter";
+import { githubIssueTrackerAdapter } from "./github";
+
+export type IssueTrackerAdapterMap = Partial<Record<IssueProvider, IssueTrackerAdapter>>;
+
+export interface IssueTrackerRegistry {
+  get(ref: IssueRef): IssueTrackerAdapter;
+}
+
+export function createIssueTrackerRegistry(adapters: IssueTrackerAdapterMap = {}): IssueTrackerRegistry {
+  const resolved: IssueTrackerAdapterMap = { github: githubIssueTrackerAdapter, ...adapters };
+  return {
+    get(ref: IssueRef): IssueTrackerAdapter {
+      const adapter = resolved[ref.provider];
+      if (!adapter) throw new Error(`No issue tracker adapter registered for provider ${ref.provider}`);
+      return adapter;
+    },
+  };
+}
+
+export const issueTrackerRegistry = createIssueTrackerRegistry();
+
+export function resolveIssueTrackerAdapter(ref: IssueRef): IssueTrackerAdapter {
+  return issueTrackerRegistry.get(ref);
+}

package/src/journal-preamble.ts

@@ -0,0 +1,350 @@
+// #2591 — the project-journal spawn/boundary preamble, the sibling of
+// `composeMemoryPreamble` (src/memory-preamble.ts). Where the memory block renders an
+// append-only ENTRY ledger, this renders the journal's CURRENT field values — the
+// overwrite-by-field record a coordinator keeps for its (project, profile).
+//
+// Same three disciplines the memory composer holds:
+//   • DETERMINISTIC — field render order comes from the fixed field catalog
+//     (PROJECT_JOURNAL_FIELDS), never from a row timestamp, so the same DB renders the same
+//     block. The rendered-at and `_updated …_` lines are wall-clock-derived by design (staleness is the
+//     point), so the DELTA-GATE hash (`contentHash`) is computed over the stable content —
+//     field keys + values — never over the rendered times, or every compact would look like a
+//     change.
+//   • SIZE-BOUNDED — per-field caps are enforced at write (4000 chars); the whole block has
+//     its own token ceiling (JOURNAL_TOKEN_CAP) with a deterministic, visible trim order:
+//     the longest value is shortened first, marked with an ellipsis and named in the footer.
+//   • EMPTY IS "" — no fields, or a profile outside the Phase-1 gate, compose to "" and the
+//     caller leaves `systemPromptAppend` untouched (byte-identical spawn).
+//
+// Anti-forgery mirrors the memory block: marker-shaped comments in field values are
+// neutralized on render, and strip/extract only recognize composer-SHAPED blocks (an opener
+// at line start followed immediately by this block's own `# Project Journal` header).
+
+import { createHash } from "node:crypto";
+import { getProject, listProjectJournal, PROJECT_JOURNAL_FIELD_LABELS, PROJECT_JOURNAL_FIELDS, type ProjectJournalField, type ProjectJournalRow } from "./db";
+import { contextRenderNow, formatUtcMinute, renderedAtLine } from "./context-block-rendered-at";
+import { formatRelativeTime } from "./mcp/presentation";
+import { cutToTokens, estimateTextTokens } from "./memory-tokens";
+
+/** The stable open marker. Versioned so a future render shape can be recognized. */
+export const JOURNAL_PREAMBLE_MARKER = "<!-- relay:journal v1 -->";
+/** The close marker — makes strip exact (the block legitimately contains blank lines). */
+export const JOURNAL_PREAMBLE_END_MARKER = "<!-- /relay:journal -->";
+
+/** Marker-SHAPED comments in field content. The boundary is only a boundary if a value
+ *  cannot forge it — a journal field that quotes the closer would orphan the block tail and
+ *  stack a fresh copy on the next restart. The trailing `journal-state:` hash line gets the
+ *  same treatment: a value quoting it could otherwise shadow the state read the compact
+ *  delta-gate trusts (the composer appends the real line AFTER neutralization, so only a
+ *  forgery can ever match). Neutralized on render, same as memory. */
+const MARKER_SHAPED = /<!--\s*\/?\s*(?:relay:journal\b|journal-state:)[\s\S]*?-->/g;
+
+/** Whole-block token ceiling (≈2500, #2591). Per-field caps already bound each value
+ *  (4000 chars ≈ 1000t), but five saturated fields would still overrun the prompt; the trim
+ *  order is deterministic — longest value first — and every cut is visible in the block. */
+export const JOURNAL_TOKEN_CAP = 2500;
+
+/**
+ * The profiles whose spawns/boundaries compose a journal block. Phase 1 (#2591) is the
+ * coordinator only. This is the ONE gate every composer caller reads — spawn, restart and
+ * the clear/compact boundaries — so a profile cannot get the block at one lifecycle point
+ * and not another. Phase 2 generalizes by widening this list; nothing else hard-codes a
+ * profile name (the store and the MCP tools are profile-parameterized throughout).
+ */
+export const PROJECT_JOURNAL_PROFILES: readonly string[] = ["coordinator"];
+
+export function journalProfileEnabled(profile: string | undefined): boolean {
+  return !!profile?.trim() && PROJECT_JOURNAL_PROFILES.includes(profile.trim());
+}
+
+/** The header line the composer ALWAYS writes immediately after the opener — part of what
+ *  makes an opener composer-shaped rather than a prose mention of the marker. */
+const JOURNAL_HEADER_PREFIX = "# Project Journal";
+
+/** The fetch/update reflex, stated in the block: a journal field is only worth its tokens if
+ *  the coordinator knows it can UPDATE it in place. Only names tools the journal-enabled
+ *  profile actually carries (the `project-journal` group ships with exactly these). */
+const JOURNAL_DIRECTIVE = "_Current structured journal for this project and profile — fields are OVERWRITTEN in place (they do not stack like memory entries). Keep them current with `relay_project_journal_update`; read the change history with `relay_project_journal_get`._";
+
+export interface ComposedJournalField {
+  field: ProjectJournalField;
+  label: string;
+  /** The value as rendered (already neutralized; possibly trimmed by the block cap). */
+  renderedValue: string;
+  tokens: number;
+  /** Set when the whole-block cap shortened this field's value. */
+  truncated?: boolean;
+  updatedAt: number;
+  updatedBy: string;
+}
+
+export interface ComposedJournalPreamble {
+  /** The markdown block, or "" when nothing applies (no fields, or profile not gated in). */
+  block: string;
+  /** Estimated token cost of the whole rendered block (chars/4, from the shared estimator). */
+  tokens: number;
+  /** Hash of the STABLE content (field keys + values, never the rendered relative times) —
+   *  the delta-gate token. "" when the journal is empty or not applicable, so "nothing" is a
+   *  first-class state exactly like `memoryBlockHash("")`. */
+  contentHash: string;
+  /** The fields that rendered, in catalog order. */
+  fields: ComposedJournalField[];
+  /** How many fields the whole-block cap shortened. */
+  trimmed: number;
+  /** False when the profile is outside PROJECT_JOURNAL_PROFILES — nothing applies at all. */
+  applicable: boolean;
+}
+
+/** Stable content hash over the journal's field→value state (NOT the rendered block). Same
+ *  shape as `memoryBlockHash`: short, an equality token; "" hashes to "". */
+export function journalContentHash(rows: readonly ProjectJournalRow[]): string {
+  if (!rows.length) return "";
+  const canonical = rows.map((row) => `${row.field}=${row.value}`).join("\n");
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+
+function neutralizeMarkers(text: string): string {
+  return text.replace(MARKER_SHAPED, (match) => `&lt;${match.slice(1)}`);
+}
+
+/** The same defusing, for text relay did not compose — applied to the caller brief AFTER
+ *  `stripJournalPreamble` removed any real block from it (mirrors
+ *  `neutralizeMemoryMarkers`). */
+export function neutralizeJournalMarkers(text: string): string {
+  return neutralizeMarkers(text);
+}
+
+function projectLabel(projectId: string): string {
+  const project = getProject(projectId);
+  return project?.title?.trim() || project?.slug?.trim() || projectId;
+}
+
+/** `_updated <UTC> (<age> as of render) by …_` — #3698: the absolute time stays true however late
+ *  the block is read; the age is pinned to the block's one rendered-at line, never to "now". */
+function updatedLine(updatedAt: number, updatedBy: string, now: number): string {
+  const age = formatRelativeTime(updatedAt, now, { dayDecimal: true }).relative;
+  return `_updated ${formatUtcMinute(updatedAt)} (${age} as of render) by ${updatedBy}_`;
+}
+
+/** The `## Label` + value + updated-line segment one field renders as. The value is
+ *  already neutralized (see the composer's working copies). */
+function renderFieldSegment(field: ComposedJournalField, now: number): string {
+  return [`## ${field.label}`, field.renderedValue, updatedLine(field.updatedAt, field.updatedBy, now)].join("\n");
+}
+
+/**
+ * Compose the journal block for a (project, profile).
+ *
+ * Reads the CURRENT rows (recompose, never replay), renders them in fixed catalog order with
+ * their `updated` staleness, and enforces the whole-block token cap by repeatedly trimming
+ * the LONGEST value — the deterministic order — with an ellipsis and a footer naming what was
+ * cut. Field values are marker-neutralized on render. Empty journal or a profile outside the
+ * Phase-1 gate composes to "" with `applicable:false` respectively — the caller omits the
+ * block and the spawn stays byte-identical.
+ */
+export function composeJournalPreamble(input: {
+  projectId: string;
+  /** Accepts `undefined` so callers can pass an identity's optional profile straight through —
+   *  the profile gate inside composes to "" (applicable:false) for anything not enabled. */
+  profile: string | undefined;
+  now?: number;
+  tokenBudget?: number;
+}): ComposedJournalPreamble {
+  const applicable = journalProfileEnabled(input.profile);
+  const empty: ComposedJournalPreamble = { block: "", tokens: 0, contentHash: "", fields: [], trimmed: 0, applicable };
+  if (!applicable) return empty;
+
+  const now = input.now ?? contextRenderNow();
+  // Narrowed by journalProfileEnabled above — a profile that reaches here is non-empty.
+  const profile = input.profile as string;
+  const rows: ProjectJournalRow[] = listProjectJournal(input.projectId, profile);
+  const contentHash = journalContentHash(rows);
+  if (!rows.length) return { ...empty, contentHash };
+
+  const cap = Math.max(0, input.tokenBudget ?? JOURNAL_TOKEN_CAP);
+  // Working copies for the trim loop; values are marker-NEUTRALIZED up front so the trim
+  // arithmetic and the render see the same bytes (neutralization expands "<!--" to "&lt;!--",
+  // and a cut measured against the raw text could overshoot the cap after expansion).
+  // Render order is the fixed catalog order of the rows.
+  const working: Array<{ row: ProjectJournalRow; value: string; truncated: boolean }> =
+    rows.map((row) => ({ row, value: neutralizeMarkers(row.value), truncated: false }));
+
+  const headerBlock = [
+    JOURNAL_PREAMBLE_MARKER,
+    `${JOURNAL_HEADER_PREFIX} — ${projectLabel(input.projectId)} (${profile})`,
+    renderedAtLine(now),
+    "",
+    JOURNAL_DIRECTIVE,
+  ].join("\n");
+  const overhead = estimateTextTokens(headerBlock) + estimateTextTokens(JOURNAL_PREAMBLE_END_MARKER) + 4; // + separators/footer slack
+
+  const cost = (): number =>
+    overhead + working.reduce(
+      (sum, item) => sum + estimateTextTokens(`## Label\n${item.value}\n${updatedLine(item.row.updatedAt, item.row.updatedBy, now)}`),
+      0,
+    );
+
+  // Deterministic trim: while over cap, shorten the LONGEST value by the deficit. A field
+  // reduced to "" still renders its heading + staleness line (the field exists), only its
+  // value is gone — the footer names it, so the loss is never silent.
+  let trimmed = 0;
+  let total = cost();
+  while (total > cap) {
+    const deficit = total - cap;
+    let target: (typeof working)[number] | undefined;
+    for (const item of working) {
+      if (!item.value) continue;
+      if (!target || item.value.length > target.value.length) target = item;
+    }
+    if (!target) break; // nothing left to trim (all values empty); over-cap only via overhead
+    const allowance = Math.max(0, Math.floor(target.value.length / 4) - deficit - 1);
+    const cut = allowance > 0 ? cutToTokens(target.value, allowance) : "";
+    target.value = cut;
+    if (!target.truncated) {
+      target.truncated = true;
+      trimmed += 1;
+    }
+    total = cost();
+  }
+
+  const fields: ComposedJournalField[] = working.map((item) => ({
+    field: item.row.field,
+    label: PROJECT_JOURNAL_FIELD_LABELS[item.row.field],
+    renderedValue: item.value,
+    tokens: estimateTextTokens(item.value),
+    ...(item.truncated ? { truncated: true } : {}),
+    updatedAt: item.row.updatedAt,
+    updatedBy: item.row.updatedBy,
+  }));
+
+  const lines = [headerBlock];
+  for (const field of fields) {
+    lines.push("", renderFieldSegment(field, now));
+  }
+  if (trimmed) {
+    lines.push("", `_journal budget: ${trimmed} field value(s) shortened to fit the ${cap}-token block cap — relay_project_journal_get returns the full text_`);
+  }
+  // The state line carries the contentHash INSIDE the block, so the compact delta-gate can
+  // read the journal state a LAUNCHED prompt carries straight out of its bytes (derived,
+  // never bookkept — the same philosophy as memory's extract-from-prompt read). Without it,
+  // the rendered relative times would make hash-of-block useless as an equality token.
+  if (contentHash) lines.push(`<!-- journal-state: ${contentHash} -->`);
+  lines.push(JOURNAL_PREAMBLE_END_MARKER);
+
+  const block = lines.join("\n");
+  return { block, tokens: estimateTextTokens(block), contentHash, fields, trimmed, applicable };
+}
+
+// ── strip / extract (mirrors memory-preamble's strict, composed-shape scan) ──────────────
+
+interface JournalPreambleSpan {
+  open: number;
+  from: number;
+  end: number;
+}
+
+const OPENER_HEADER_LINE = /^\r?\n# Project Journal\b/;
+
+function isComposedOpener(value: string, at: number): boolean {
+  if (at > 0 && value[at - 1] !== "\n") return false;
+  return OPENER_HEADER_LINE.test(value.slice(at + JOURNAL_PREAMBLE_MARKER.length));
+}
+
+function isComposedCloser(value: string, at: number): boolean {
+  if (at > 0 && value[at - 1] !== "\n") return false;
+  const after = at + JOURNAL_PREAMBLE_END_MARKER.length;
+  return after === value.length || value[after] === "\n" || value[after] === "\r";
+}
+
+function nextComposedOpener(value: string, from: number): number {
+  for (let at = value.indexOf(JOURNAL_PREAMBLE_MARKER, from); at >= 0; at = value.indexOf(JOURNAL_PREAMBLE_MARKER, at + 1)) {
+    if (isComposedOpener(value, at)) return at;
+  }
+  return -1;
+}
+
+function lastComposedCloser(value: string, from: number, until: number): number {
+  let found = -1;
+  for (let at = value.indexOf(JOURNAL_PREAMBLE_END_MARKER, from); at >= 0 && at < until; at = value.indexOf(JOURNAL_PREAMBLE_END_MARKER, at + 1)) {
+    if (isComposedCloser(value, at)) found = at;
+  }
+  return found;
+}
+
+function journalPreambleSpans(value: string): JournalPreambleSpan[] {
+  if (!value.includes(JOURNAL_PREAMBLE_MARKER)) return [];
+  const spans: JournalPreambleSpan[] = [];
+  let cursor = 0;
+  for (;;) {
+    const open = nextComposedOpener(value, cursor);
+    if (open < 0) break;
+    const openEnd = open + JOURNAL_PREAMBLE_MARKER.length;
+    const nextOpen = nextComposedOpener(value, openEnd);
+    const closeAt = lastComposedCloser(value, openEnd, nextOpen < 0 ? value.length : nextOpen);
+    const end = closeAt < 0 ? openEnd : closeAt + JOURNAL_PREAMBLE_END_MARKER.length;
+    spans.push({ open, from: value.slice(open - 2, open) === "\n\n" ? open - 2 : open, end });
+    cursor = end;
+  }
+  return spans;
+}
+
+/** Remove a previously injected journal block (marker to marker), so a restart/re-inject
+ *  REPLACES it instead of stacking a second copy. Strict about what it removes — only a
+ *  composer-shaped opener/closer pair — exactly like `stripMemoryPreamble`. */
+export function stripJournalPreamble(value: string): string {
+  const spans = journalPreambleSpans(value);
+  if (!spans.length) return value;
+  let out = "";
+  let last = 0;
+  for (const { from, end } of spans) {
+    out += value.slice(last, from);
+    last = end;
+  }
+  out += value.slice(last);
+  return out.replace(/^\n\n+/, "").replace(/\n\n+$/, "");
+}
+
+/** The journal block a prompt CARRIES, marker to marker, or null when it carries none — what
+ *  the boundary delta-gate reads out of the launched prompt (last block wins, as with
+ *  memory). */
+export function extractJournalPreamble(value: string): string | null {
+  const span = journalPreambleSpans(value).at(-1);
+  return span ? value.slice(span.open, span.end) : null;
+}
+
+/** The journal CONTENT-STATE a prompt carries: the `journal-state:` hash inside its journal
+ *  block. "" when it carries a block with no state line (an empty-journal retraction); null
+ *  when it carries no journal block at all — the same three states the memory gate reads
+ *  (hash / empty / absent). */
+export function extractJournalStateHash(value: string): string | null {
+  const block = extractJournalPreamble(value);
+  if (block === null) return null;
+  // LAST occurrence wins — the composer appends the real state line at block END, after all
+  // field content, so a journal-state-shaped string inside a field value can never shadow
+  // the state the delta gate reads (belt to MARKER_SHAPED neutralization).
+  const match = [...block.matchAll(/<!-- journal-state: ([0-9a-f]{16}) -->/g)].at(-1);
+  return match?.[1] ?? "";
+}
+
+/** What the re-injected copy says about the copy already in context — the journal twin of
+ *  `MEMORY_SUPERSEDE_NOTICE`. The journal is keyed DIRECTLY by (project, profile) — there is
+ *  no cell-chain derivation to diverge — so unlike memory (#1625) no seam-verification
+ *  qualifier is needed: the later copy is current, unconditionally. */
+export const JOURNAL_SUPERSEDE_NOTICE = "_This journal block SUPERSEDES any earlier relay journal block in this context (a clear/compact does not rewrite the system prompt, so an older copy may still be above). Where they differ, THIS one is current — a field absent here was cleared._";
+
+/** The delivered form: the composed block with the notice on the line after its header,
+ *  inside the markers so a later strip takes it with the block. "" stays "". */
+export function withJournalSupersedeNotice(block: string): string {
+  if (!block.trim()) return block;
+  const lines = block.split("\n");
+  // [0] is the opener, [1] the header line; the notice reads as the block's own subtitle.
+  const at = lines.length > 1 ? 2 : 1;
+  return [...lines.slice(0, at), "", JOURNAL_SUPERSEDE_NOTICE, ...lines.slice(at)].join("\n");
+}
+
+/** An EMPTY block that still carries the supersede notice — the retraction payload for a
+ *  boundary that composed nothing while the agent's prompt is still carrying an earlier copy
+ *  (every field was cleared). Marker-wrapped so strip/extract take it like any other block. */
+export function journalRetractionBlock(): string {
+  return [JOURNAL_PREAMBLE_MARKER, "", JOURNAL_SUPERSEDE_NOTICE, JOURNAL_PREAMBLE_END_MARKER].join("\n");
+}

package/src/kernel-correlation.ts

@@ -0,0 +1,28 @@
+// Kernel Phase-2 (#1409) — the reserved kernel correlation-id namespace (R2).
+//
+// This is the LOW-LEVEL home for the `kcmd:` reservation so the single command-write choke point
+// (`createCommand`, `commands-db.ts`) can enforce it WITHOUT importing the service-layer
+// `kernel-command-bridge.ts` (which itself imports `commands-db`, so a bridge-side home would be a
+// cycle). The bridge re-exports these for its public API; `commands-db` and the HTTP command ingress
+// import them from here.
+//
+// ── SECURITY — R2 (checkpoint C2 residual #2) ────────────────────────────────────────────────────
+// Every kernel-issued command's `correlation_id` is stamped under the `kcmd:` prefix (the bridge's
+// collision-proof dedup key, `correlationKeyFor`). An EXTERNAL / client-influenced caller must NEVER
+// be able to write a `kcmd:`-namespaced `correlation_id`, or it could pre-seed a row that cross-maps a
+// kernel command — `findCommandByCorrelationId` would return the attacker's row as the kernel
+// command's dispatch (leak its status/result, or suppress the real dispatch via dedup). The reservation
+// is enforced at the SINGLE write choke point (`createCommand`), which rejects a reserved
+// correlation_id unless the trusted kernel-bridge path explicitly opts in — so every ingress
+// (`POST /api/commands`, spawn `spawnRequestId`, the WS bus, audit branch/approval/request ids, …) is
+// covered by construction.
+
+/** The reserved correlation-id namespace for EVERY kernel-issued command. Changing this constant is a
+ *  wire-format change — keep it stable. */
+export const KERNEL_CORRELATION_PREFIX = "kcmd:";
+
+/** True if `correlationId` falls in the reserved kernel namespace. The external command ingress + the
+ *  `createCommand` choke point call this to fail-closed on a forged/cross-mapping `correlation_id`. */
+export function isReservedKernelCorrelationId(correlationId: string | undefined | null): boolean {
+  return typeof correlationId === "string" && correlationId.startsWith(KERNEL_CORRELATION_PREFIX);
+}

package/src/land-authorization.ts

@@ -0,0 +1,73 @@
+// Delivery-authorization land guardrail (#1473). SINGLE home for "may this workspace be picked up for
+// landing by an AUTOMATIC sweep (auto-merge, PR-completion, or steward hand-off)?" — the sibling of
+// land-block.ts (#1482).
+//
+// The incident (#1473): a workspace was treated as an auto-merge / steward LAND candidate merely by
+// having a pushed `agent/*` branch in a ready-to-land status — with NO requirement that its owner had
+// DELIVERED / authorized the land. A "HOLD" is coordinator convention only, so a never-delivered,
+// explicitly-held worker branch (round-13, not GO'd) was swept and handed to a steward "to land or
+// escalate", and long-reaped reviewer scratch branches flooded the same steward.
+//
+// THE INVARIANT (round-2, after adversarial review reproduced two bypasses): a workspace is
+// auto-merge / steward / PR-completion eligible ONLY IF a Task bound to THAT EXACT workspace has
+// recorded a land-authorizing delivery (`land.requested === true` on a deliverable event whose
+// `workspaceId` is this workspace — set only by a `complete` relay_task_deliver whose acceptance
+// lands). Everything else — held, never-delivered, AND taskless/utility spawns — is EXCLUDED,
+// FAIL-CLOSED.
+//
+//   - P1a (cross-task authorization bleed): the authorization is bound to the exact workspaceId, NOT
+//     to "any Task sharing the owning agent or the branch name". So a delivered Task A owned by an
+//     agent can NEVER authorize that agent's DISTINCT never-delivered Task B on a different held
+//     workspace. (workspaceLandAuthorization in db/task-deliverables.ts does the exact match.)
+//   - P1b (taskless fail-open): a taskless/utility isolated spawn is never-delivered by definition, so
+//     it records no authorizing delivery and is excluded from the AUTO sweep — fail-closed, not
+//     fail-open. This does NOT touch the EXPLICIT land path: `humwick workspace land` issues a
+//     `merge` action directly and never enters this sweep, and relay_task_deliver is itself the
+//     authorization. Only the automatic main-move sweep / PR-completion / steward candidacy is gated.
+//   - Head-pinning (round-3 F3, order-free + format-tolerant in round-4): authorization is pinned to the
+//     DELIVERED commit SHAs (the whole `commits[]` set of each authorizing delivery, matched
+//     case-insensitively with abbreviation tolerance), so a branch that walked its land back
+//     (merge_planned → review_requested) and then re-pushed UNREVIEWED commits is NOT re-landed on the
+//     stale authorization. Enforced only where the live branch head is known (the
+//     dispatch/scan loops pass `currentHead`); the candidacy filter, which has no head, does the
+//     existence check and the dispatch loop rejects a moved head.
+
+import { workspaceLandAuthorization } from "./db";
+import type { WorkspaceRecord } from "./types";
+
+// THE read predicate every automatic land-candidacy chokepoint consults. Truthy means EXCLUDE this
+// workspace from the auto sweep (auto-merge dispatch, PR auto-merge, and conflict/protected-tip
+// steward hand-off). FAIL-CLOSED: a workspace with no authorizing delivery bound to its exact id —
+// which includes every held/never-delivered branch and every taskless/utility spawn — is awaiting
+// authorization and is not a candidate. A workspace delivered before this change already carries the
+// `land.requested` event with its workspaceId, so no migration/backfill is needed.
+//
+// `opts.currentHead` (round-3 F3): when the caller knows the branch's live head (from a merge
+// preview), authorization is additionally head-pinned — a delivered head that no longer matches the
+// live head is stale and the workspace is treated as awaiting authorization. Omit it (candidacy
+// filter, no preview yet) for an existence-only check. A commit-less authorizing delivery cannot be
+// pinned, so it falls back to existence-only rather than stranding a legitimate delivery.
+export function workspaceAwaitingLandAuthorization(
+  ws: Pick<WorkspaceRecord, "id"> | null | undefined,
+  opts: { currentHead?: string } = {},
+): boolean {
+  if (!ws?.id) return true;
+  const auth = workspaceLandAuthorization(ws.id);
+  if (!auth.authorized) return true;
+  const head = opts.currentHead?.trim();
+  if (!head || auth.unpinned) return false;
+  // Head-pin match (round-4 P1): case-insensitive with abbreviation tolerance in BOTH directions. The
+  // delivered SHAs come from caller-supplied `commits[].sha` (relay_task_deliver validates length only —
+  // not format, case, or ordering), so a worker may deliver short (`git rev-parse --short`) or uppercased
+  // SHAs while the live head from the merge preview is a full lowercase 40-char OID. An exact `includes`
+  // stranded those as staleAuthorization; prefix-either-way + lowercasing kills both the abbreviation and
+  // case strands WITHOUT loosening the pin — a genuinely-new unreviewed commit shares no prefix with any
+  // delivered SHA (git guarantees short-SHA uniqueness at delivery time). `head` and every `heads` entry
+  // are trimmed-non-empty here, so neither startsWith degenerates to an empty-prefix match. (Precedent:
+  // services/review-ref-reconcile.ts compares OIDs case-insensitively.)
+  const h = head.toLowerCase();
+  return !auth.heads.some((candidate) => {
+    const c = candidate.toLowerCase();
+    return c.startsWith(h) || h.startsWith(c);
+  });
+}

package/src/land-block.ts

@@ -0,0 +1,59 @@
+// Landing authority is explicit at spawn. Task types and profiles never imply a block (#2770).
+import type { WorkspaceRecord } from "./types";
+
+const LEGACY_DERIVED_BLOCK_REASONS = new Set([
+  "review-task", "research-task", "reviewer-profile", "isolated-research-profile",
+]);
+
+// Reserved metadata keys owned by trusted authority writers: upsertWorkspace stamps the immutable
+// spawn-derived land block, and clearTaskReviewHoldBody atomically stamps the reviewed-head pin.
+// They are NEVER writable through a caller-supplied metadata patch. Stripping them at every
+// external write chokepoint closes both the #1482 self-clear hole and #2518 pin forgery.
+export const RESERVED_WORKSPACE_METADATA_KEYS = [
+  "stewardCancellation",
+  "mergeHold",
+  "landBlocked",
+  "landBlockedReason",
+  // #2518 — coordinator-approved reviewed-head authority. Only the clear transaction may stamp
+  // this; accepting it through an action metadata patch lets a worker replace H1 with H2 and
+  // makes the next explicit merge land an unreviewed head.
+  "reviewHoldPromotedHeadSha",
+  "rekeyCommandId",
+] as const;
+
+// Strip the guardrail-owned keys from a caller-supplied metadata patch. Returns a NEW object (never
+// mutates the input) so callers can pass it straight through. A no-op for every legitimate patch —
+// internal authority writers use their dedicated paths rather than a generic metadata patch.
+export function stripReservedWorkspaceMetadataKeys<T extends Record<string, unknown>>(metadata: T): T {
+  let stripped: Record<string, unknown> | undefined;
+  for (const key of RESERVED_WORKSPACE_METADATA_KEYS) {
+    if (key in metadata) {
+      if (!stripped) stripped = { ...metadata };
+      delete stripped[key];
+    }
+  }
+  return (stripped ?? metadata) as T;
+}
+
+// Read-time migration: ignore retired derived stamps, including immutable old spawn commands.
+// Unknown/missing provenance still fails closed; external writers cannot forge a legacy reason.
+export function workspaceLandBlocked(
+  workspace: Pick<WorkspaceRecord, "metadata"> | null | undefined,
+): boolean {
+  const metadata = workspace?.metadata;
+  return Boolean(metadata?.landBlocked) && !LEGACY_DERIVED_BLOCK_REASONS.has(typeof metadata?.landBlockedReason === "string" ? metadata.landBlockedReason.trim() : "");
+}
+
+// User-facing rejection for a blocked land attempt. One string so every surface says the same thing.
+export const LAND_BLOCK_REJECT_MESSAGE =
+  "workspace was explicitly land-blocked at spawn and cannot land to main; the block is permanent and cannot be cleared or overridden";
+
+export function resolveSpawnLandBlocked(input: {
+  explicit?: boolean;
+  /** Only an isolated workspace carries the block (a shared one has nothing to stamp it on); defaults to true. */
+  isolated?: boolean;
+}): { landBlocked: boolean; reason?: string } {
+  return input.isolated !== false && input.explicit === true
+    ? { landBlocked: true, reason: "explicit-spawn-flag" }
+    : { landBlocked: false };
+}

package/src/land-failure-event-key.ts

@@ -0,0 +1,8 @@
+import type { WorkspaceRecord } from "./types";
+import { getWorkspace } from "./db/workspaces";
+
+/** One terminal wake per handed-off land, including retries and escalation (#2777). */
+export function landFailureEventKey(workspace: Pick<WorkspaceRecord, "id"> & Partial<Pick<WorkspaceRecord, "metadata">>, commandId?: string): string {
+  const meta = workspace.metadata ?? getWorkspace(workspace.id)?.metadata ?? {};
+  return `land-failure:${workspace.id}:${meta.landRequestAttemptAt ?? meta.mergeCommandId ?? commandId ?? "unarmed"}`;
+}

package/src/land-gate-failure-routing.ts

@@ -0,0 +1,69 @@
+import { isAgentOnline } from "./agent-ref";
+import { getAgent, getWorkspace, patchWorkspaceMetadataAsync } from "./db";
+import { notificationEnabledFor } from "./notification-settings-store";
+import { withWorkspaceTaskOwnerRoles } from "./task-owner-notices";
+
+/** A third failed required gate means the author is likely stuck and needs coordinator help. */
+export const LAND_GATE_FAILURE_ESCALATION_THRESHOLD = 3;
+
+interface LandGateFailureRoutingInput {
+  workspaceId: string;
+  branch?: string;
+  failedAt?: number;
+  gateName?: string;
+  owner?: string;
+  coordinator?: string | null;
+  fallback?: string;
+}
+
+export interface LandGateFailureRouting {
+  recipients: string[];
+  parent?: string;
+  forceDelivery?: boolean;
+  consecutiveFailures: number;
+  escalationReason?: "author-unavailable" | "author-suppressed" | "repeated-failures";
+  stale?: boolean;
+}
+
+function positiveInteger(value: unknown): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+/** Terminal failures always wake both ends; reject stale deferred artifact completions (#2777). */
+export async function routeLandGateFailure(input: LandGateFailureRoutingInput): Promise<LandGateFailureRouting> {
+  const workspace = getWorkspace(input.workspaceId);
+  if (!workspace || workspace.branch !== input.branch || (input.failedAt !== undefined && (workspace.landedAt ?? 0) >= input.failedAt)) {
+    return { recipients: [], consecutiveFailures: 0, stale: true };
+  }
+  const prior = workspace.metadata.landGateFailure;
+  const sameBranch = prior && typeof prior === "object" && (prior as Record<string, unknown>).branch === input.branch;
+  const consecutiveFailures = (sameBranch ? positiveInteger(workspace.metadata.landGateFailureCount) : 0) + 1;
+  const notifiedAt = Date.now();
+  await patchWorkspaceMetadataAsync(workspace.id, {
+    landGateFailureCount: consecutiveFailures,
+    landGateFailure: { branch: input.branch, failedAt: input.failedAt ?? notifiedAt, notifiedAt, gateName: input.gateName },
+    landGateFailureEscalatedAt: undefined,
+  });
+
+  const owner = input.owner ? getAgent(input.owner) : undefined;
+  const ownerActionable = Boolean(owner && isAgentOnline(owner) && notificationEnabledFor("workspace.land_gate_failed", { agentId: owner.id, teamId: owner.teamId }));
+  const escalationReason = !owner || !isAgentOnline(owner)
+    ? "author-unavailable"
+    : !ownerActionable
+      ? "author-suppressed"
+      : consecutiveFailures >= LAND_GATE_FAILURE_ESCALATION_THRESHOLD
+        ? "repeated-failures"
+        : undefined;
+  const escalationTarget = input.coordinator ?? input.fallback;
+  // #2862 — the bound Tasks' owner roles too, so a failure before a claim reaches the replacement.
+  const recipients = withWorkspaceTaskOwnerRoles([input.owner, escalationTarget], workspace);
+  const forceDelivery = true;
+  if (forceDelivery && recipients.length === 0 && input.owner) recipients.push(input.owner);
+  return {
+    recipients,
+    ...(input.coordinator ? { parent: input.coordinator } : {}),
+    ...(forceDelivery ? { forceDelivery } : {}),
+    consecutiveFailures,
+    ...(escalationReason ? { escalationReason } : {}),
+  };
+}