agent-relay-server 0.107.0 → 0.109.0

package/src/services/task-issue-weave.ts

@@ -0,0 +1,558 @@
+// #833 — the Task ↔ GitHub issue weave-through. This is the WRITE-THROUGH lens that
+// the design refinement (weave-in, not duplicate) calls for: a comment on a Task does
+// not land in a relay table that can drift — it writes a structured comment THROUGH to
+// the linked GitHub issue, the backing store for human discussion. GitHub stays the
+// system of record for intent/spec/acceptance/discussion; the Task is the lens + the
+// write-through API.
+//
+// FIELD-OWNERSHIP BOUNDARY (the critical hazard #830/#833 guards against):
+//   - GitHub owns: intent / spec / acceptance / human discussion → write THROUGH here.
+//   - Task owns:   execution telemetry (status, stage, gate ledger, branch, commits,
+//                  attribution) → stays Task-only, in src/db/task-entity.ts.
+//
+// GUARD (required): execution telemetry must NEVER write through to GitHub — a comment
+// per gate-pass / per-position-change is noise + a rate-limit suicide. The guard is
+// structural: the telemetry writers (setTaskStatus/setTaskStage/recordGate/…) live in
+// the db layer and DO NOT import this module, so they have no path to the adapter. The
+// ONE chokepoint that touches the issue tracker is `postThrough` below, reachable only
+// via `commentOnTaskThrough` (human/agent discussion) and
+// `postTaskMilestoneComment` (the single milestone-summary exception). `assertWriteThroughEligible`
+// makes the classification a hard, tested invariant.
+//
+// MILESTONE EXCEPTION: a single structured summary MAY post at a meaningful boundary
+// (e.g. on land). The mechanism is `postTaskMilestoneComment`; the land TRIGGER that
+// calls it is #831's job — left here as a seam, not wired into the land pipeline.
+//
+// CLOSE-BRIDGE: #482/#474 already close the linked issue exactly once on land and record
+// it durably in `issue_lifecycle_actions`. The Task does not duplicate that ledger — it
+// PROJECTS it (`taskCloseBridge`), closing the "I couldn't tell if #482 already closed it"
+// gap by surfacing the canonical record instead of copying it.
+import { errMessage } from "agent-relay-sdk";
+import { getTaskDetail } from "../db/task-entity";
+import { getIssueRef } from "../db/issue-refs";
+import { listSuccessfulCloseActionsForIssueRef } from "../db/issue-lifecycle";
+import { insertTaskEvent, getTaskEvent } from "../db/task-core";
+import { listTaskEvents } from "../db/tasks";
+import {
+  failCommentThrough,
+  finalizeCommentThrough,
+  reserveCommentThrough,
+  type TaskCommentThroughKind,
+  type TaskCommentThroughRecord,
+} from "../db/task-comment-through";
+import { resolveIssueTrackerAdapter, type IssueTrackerAdapter } from "../issue-tracker";
+import { emitTaskChanged } from "../sse";
+import { ValidationError } from "../db/connection";
+import type { IssueRef, TaskDetail, TaskEvent, TaskGateState, TaskIssueLink } from "../types";
+
+type AdapterResolver = (ref: IssueRef) => IssueTrackerAdapter;
+type LogFn = (message: string) => void;
+
+interface WeaveOptions {
+  adapterResolver?: AdapterResolver;
+  log?: LogFn;
+}
+
+let adapterResolverForTests: AdapterResolver | undefined;
+
+export function __setTaskWeaveAdapterResolverForTests(resolver: AdapterResolver | undefined): void {
+  adapterResolverForTests = resolver;
+}
+
+function adapterFor(ref: IssueRef, opts: WeaveOptions): IssueTrackerAdapter {
+  return (opts.adapterResolver ?? adapterResolverForTests ?? resolveIssueTrackerAdapter)(ref);
+}
+
+// --- Structured comment format -------------------------------------------------------
+// A relay-written issue comment carries an HTML-comment marker holding a JSON payload so
+// it is machine-parseable (attributable back to its Task + author + kind) while still
+// rendering as a normal human comment on GitHub. The two kinds are the ONLY things that
+// ever write through — discussion (a comment on the Task) and milestone (the boundary
+// summary). Telemetry has no kind here on purpose.
+export const TASK_COMMENT_MARKER = "agent-relay:task-comment";
+export const TASK_COMMENT_FORMAT_VERSION = 1;
+export type TaskCommentKind = "discussion" | "milestone";
+
+// The event types this module appends to the Task ledger as a RECEIPT of a write-through.
+// Everything else (status:*, stage:*, gate:*, dependency.*, ref.*, agent.*) is telemetry
+// and must never reach the chokepoint.
+export const WRITE_THROUGH_EVENT_TYPES = ["comment.posted", "milestone.posted"] as const;
+const TELEMETRY_EVENT_PREFIXES = ["status:", "stage:", "gate:", "dependency.", "ref.", "agent.", "task."];
+
+// Hard guard for the field-ownership boundary: only discussion/milestone write-throughs
+// are eligible. Anything telemetry-shaped throws — so a future caller cannot accidentally
+// route a gate/position event through the issue tracker.
+export function isWriteThroughEligibleKind(kind: string): kind is TaskCommentKind {
+  return kind === "discussion" || kind === "milestone";
+}
+
+export function isTelemetryEventType(type: string): boolean {
+  return TELEMETRY_EVENT_PREFIXES.some((prefix) => type.startsWith(prefix));
+}
+
+function assertWriteThroughEligible(kind: string): asserts kind is TaskCommentKind {
+  if (!isWriteThroughEligibleKind(kind)) {
+    throw new ValidationError(
+      `task-issue weave: '${kind}' is not write-through eligible — execution telemetry stays Task-only and must never post to GitHub`,
+    );
+  }
+}
+
+interface TaskCommentPayload {
+  v: number;
+  kind: TaskCommentKind;
+  taskId: number;
+  author?: string;
+  milestone?: string;
+  // The idempotency/reservation key (clientId for discussion, `${milestone}:${key}` for
+  // milestone). Embedded so a post-before-finalize crash can be RECONCILED: on reclaiming a
+  // stale reservation, we read the issue's comments and match this `key` to learn whether the
+  // comment already landed — instead of blindly re-posting it.
+  key?: string;
+}
+
+const HEADINGS: Record<TaskCommentKind, (p: TaskCommentPayload) => string> = {
+  discussion: (p) => `💬 **Comment on Task #${p.taskId}**${p.author ? ` — _${p.author}_` : ""}`,
+  milestone: (p) => `🏁 **Task #${p.taskId} — ${p.milestone ?? "milestone"}**`,
+};
+
+// The payload is base64url-encoded inside the marker, NOT raw JSON: a user/route-supplied
+// author or milestone containing `}` or `-->` would otherwise break the greedy `{...}` scan
+// or terminate the HTML comment early. base64url's alphabet ([A-Za-z0-9_-]) cannot contain
+// either, so the marker is always delimiter-safe regardless of payload content.
+const MARKER_RE = new RegExp(`^<!--\\s*${TASK_COMMENT_MARKER}\\s+b64=([A-Za-z0-9_-]+)\\s*-->`);
+
+export function formatTaskComment(payload: TaskCommentPayload, body: string): string {
+  const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+  const marker = `<!-- ${TASK_COMMENT_MARKER} b64=${encoded} -->`;
+  return `${marker}\n${HEADINGS[payload.kind](payload)}\n\n${body.trim()}`;
+}
+
+// Round-trip parser (used by the dashboard lens + tests): pull the relay marker back out
+// of a rendered comment so a relay-written comment is unambiguously identifiable. Parsed
+// only from the leading marker block (anchored `^`), never a greedy scan of the body, and
+// the decoded payload's v/taskId/kind are type-validated before it is trusted.
+export function parseTaskComment(comment: string): TaskCommentPayload | null {
+  const match = comment.match(MARKER_RE);
+  if (!match) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(match[1]!, "base64url").toString("utf8")) as unknown;
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const p = parsed as Record<string, unknown>;
+    if (typeof p.v !== "number" || typeof p.taskId !== "number" || typeof p.kind !== "string") return null;
+    if (!isWriteThroughEligibleKind(p.kind)) return null;
+    return {
+      v: p.v,
+      kind: p.kind,
+      taskId: p.taskId,
+      ...(typeof p.author === "string" ? { author: p.author } : {}),
+      ...(typeof p.milestone === "string" ? { milestone: p.milestone } : {}),
+      ...(typeof p.key === "string" ? { key: p.key } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// --- The single chokepoint that touches the issue tracker ----------------------------
+interface WriteThroughResult {
+  posted: TaskIssueLink[];
+  failed: Array<{ link: TaskIssueLink; error: string }>;
+}
+
+// Writes `body` through to every GitHub-backed issue linked to the Task. This is the ONLY
+// function in the codebase that posts a Task-originated comment to an issue tracker. It is
+// kind-gated (assertWriteThroughEligible) so telemetry can never be smuggled through.
+// Non-GitHub providers are skipped (the design's backing store for discussion is GitHub);
+// a tracker failure on one issue does not abort the others.
+// Posts `body` through to the GitHub-backed links in `links` (a tracker failure on one issue
+// does not abort the others). Callers pass the exact link set: ALL github links on a fresh
+// post, or just the reconcile-confirmed-missing subset on a reclaim (so a link that already
+// has the comment is never double-posted).
+async function postThrough(
+  kind: TaskCommentKind,
+  payload: TaskCommentPayload,
+  body: string,
+  links: TaskIssueLink[],
+  opts: WeaveOptions,
+): Promise<WriteThroughResult> {
+  assertWriteThroughEligible(kind);
+  const formatted = formatTaskComment(payload, body);
+  const result: WriteThroughResult = { posted: [], failed: [] };
+  for (const link of links) {
+    if (link.provider !== "github") continue;
+    const ref = getIssueRef(link.issueRefId);
+    if (!ref) continue;
+    try {
+      await adapterFor(ref, opts).comment(ref, formatted);
+      result.posted.push(link);
+    } catch (e) {
+      const message = errMessage(e);
+      result.failed.push({ link, error: message });
+      if (opts.log) opts.log(`task-issue weave: comment-through failed for ${link.repo}#${link.externalKey}: ${message}`);
+      else console.warn(`task-issue weave: comment-through failed for ${link.repo}#${link.externalKey}: ${message}`);
+    }
+  }
+  return result;
+}
+
+interface ReconcileResult {
+  // Links that ALREADY carry a relay marker for this (taskId, kind, key) — the post landed.
+  matched: TaskIssueLink[];
+  // Links read successfully with NO marker — the post is genuinely missing and must be sent.
+  missing: TaskIssueLink[];
+  // Links whose comments could not be read — state UNKNOWN; we must neither finalize nor post.
+  unreadable: TaskIssueLink[];
+}
+
+// Per-link reconcile of a reclaimed-stale reservation (#833): for each linked GitHub issue,
+// classify it as already-has-the-marker (matched), readable-but-missing (must post), or
+// unreadable (unknown). The caller finalizes ONLY when every link is in a known state — a
+// single unreadable link blocks finalization so a Task with multiple issues can never clear
+// its retry slot while one issue's state is still unknown.
+async function reconcileExistingPost(
+  taskId: number,
+  kind: TaskCommentKind,
+  slotKey: string,
+  links: TaskIssueLink[],
+  opts: WeaveOptions,
+): Promise<ReconcileResult> {
+  const matched: TaskIssueLink[] = [];
+  const missing: TaskIssueLink[] = [];
+  const unreadable: TaskIssueLink[] = [];
+  for (const link of links) {
+    if (link.provider !== "github") continue;
+    const ref = getIssueRef(link.issueRefId);
+    if (!ref) continue;
+    const adapter = adapterFor(ref, opts);
+    if (!adapter.listComments) { unreadable.push(link); continue; }
+    try {
+      const comments = await adapter.listComments(ref);
+      const found = comments.some((c) => {
+        const p = parseTaskComment(c);
+        return p !== null && p.taskId === taskId && p.kind === kind && p.key === slotKey;
+      });
+      (found ? matched : missing).push(link);
+    } catch (e) {
+      unreadable.push(link);
+      if (opts.log) opts.log(`task-issue weave: reconcile read failed for ${link.repo}#${link.externalKey}: ${errMessage(e)}`);
+      else console.warn(`task-issue weave: reconcile read failed for ${link.repo}#${link.externalKey}: ${errMessage(e)}`);
+    }
+  }
+  return { matched, missing, unreadable };
+}
+
+// Shared reclaim handler (discussion + milestone are structurally identical here). Returns the
+// finished result, or throws CommentThroughError to leave the reservation durable. Only called
+// when a stale reservation was reclaimed AND there are GitHub links to reconcile.
+async function reconcileReclaim(params: {
+  taskId: number;
+  kind: TaskCommentKind;
+  slotKey: string;
+  payload: TaskCommentPayload;
+  body: string;
+  githubLinks: TaskIssueLink[];
+  reservation: TaskCommentThroughRecord;
+  recordReceipt: (posted: TaskIssueLink[], failed: Array<{ link: TaskIssueLink; error: string }>) => TaskEvent;
+  opts: WeaveOptions;
+}): Promise<WeaveWriteResult> {
+  const { taskId, kind, slotKey, payload, body, githubLinks, reservation, recordReceipt, opts } = params;
+  const recon = await reconcileExistingPost(taskId, kind, slotKey, githubLinks, opts);
+
+  // ANY unreadable link → state unknown → do not finalize, do not blind-post. Leave the
+  // reservation `reserved` (durable) and surface; a later retry reconciles again.
+  if (recon.unreadable.length > 0) {
+    throw new CommentThroughError(
+      `comment-through reconcile could not read ${recon.unreadable.map((l) => `${l.repo}#${l.externalKey}`).join(", ")}; not finalizing/re-posting to avoid a duplicate`,
+      [],
+    );
+  }
+
+  // Every link readable. Post only the genuinely-missing ones (matched links already have it).
+  let posted = recon.matched;
+  if (recon.missing.length > 0) {
+    const result = await postThrough(kind, payload, body, recon.missing, opts);
+    if (result.failed.length > 0) {
+      // A missing link still couldn't be posted → not every link is satisfied. Keep the slot
+      // reclaimable and surface, rather than finalize with a hole.
+      failCommentThrough(reservation.id, Date.now());
+      throw new CommentThroughError(
+        `comment-through reconcile failed to post missing issue(s): ${result.failed.map((f) => `${f.link.repo}#${f.link.externalKey}: ${f.error}`).join("; ")}`,
+        result.failed,
+      );
+    }
+    posted = [...recon.matched, ...result.posted];
+  }
+
+  // Every link now satisfied (already-present + freshly-posted) → finalize exactly once.
+  const event = recordReceipt(posted, []);
+  finalizeCommentThrough(reservation.id, event.id, Date.now());
+  emitChanged(taskId);
+  return { taskId, posted, failed: [], event, deduped: recon.missing.length === 0 };
+}
+
+interface WeaveWriteResult {
+  taskId: number;
+  posted: TaskIssueLink[];
+  failed: Array<{ link: TaskIssueLink; error: string }>;
+  event: TaskEvent | null;
+  deduped: boolean;
+}
+
+function emitChanged(taskId: number): void {
+  const detail = getTaskDetail(taskId);
+  if (detail) emitTaskChanged(detail, "task.updated");
+}
+
+// --- Comment-on-Task → write-through -------------------------------------------------
+export interface CommentOnTaskInput {
+  taskId: number;
+  body: string;
+  author?: string;
+  /** Optional idempotency key: a re-delivered comment with the same key posts once. */
+  clientId?: string;
+}
+
+export interface CommentOnTaskResult {
+  taskId: number;
+  posted: TaskIssueLink[];
+  failed: Array<{ link: TaskIssueLink; error: string }>;
+  event: TaskEvent | null;
+  deduped: boolean;
+}
+
+// Thrown when every GitHub write-through failed. NOT a ValidationError — the request was
+// well-formed; GitHub was unreachable — so it must NOT leave a posted receipt (finding 1):
+// a clientId retry re-hits GitHub because the reservation was flipped to 'failed'.
+export class CommentThroughError extends Error {
+  constructor(message: string, readonly failures: Array<{ link: TaskIssueLink; error: string }>) {
+    super(message);
+    this.name = "CommentThroughError";
+  }
+}
+
+export async function commentOnTaskThrough(input: CommentOnTaskInput, opts: WeaveOptions = {}): Promise<CommentOnTaskResult> {
+  const taskId = input.taskId;
+  const detail = getTaskDetail(taskId);
+  if (!detail) throw new ValidationError(`task ${taskId} not found`);
+  const body = typeof input.body === "string" ? input.body.trim() : "";
+  if (!body) throw new ValidationError("comment body required");
+
+  // Discussion has no relay backing store — it lives in GitHub. With no GitHub-backed
+  // issue linked, there is nowhere for it to live, so the write-through is rejected rather
+  // than silently dropped into a table that would drift.
+  const githubLinks = detail.issues.filter((link) => link.provider === "github");
+  if (githubLinks.length === 0) {
+    throw new ValidationError("task has no linked GitHub issue to write the comment through to");
+  }
+
+  const clientId = input.clientId?.trim();
+  const author = input.author?.trim() || "agent-relay";
+  const payload: TaskCommentPayload = { v: TASK_COMMENT_FORMAT_VERSION, kind: "discussion", taskId, author, ...(clientId ? { key: clientId } : {}) };
+
+  // The success-scoped receipt writer (shared by the normal-post and reconcile-found paths):
+  // an AUDIT of what actually landed on GitHub (posted only), not a second store of the
+  // discussion. GitHub stays canonical; the Task renders by reading it back.
+  const recordReceipt = (posted: TaskIssueLink[], failed: Array<{ link: TaskIssueLink; error: string }>): TaskEvent =>
+    insertTaskEvent(taskId, {
+      source: author,
+      type: "comment.posted",
+      severity: "info",
+      title: `Comment written through to ${posted.map((l) => `${l.repo}#${l.externalKey}`).join(", ")}`,
+      body,
+      metadata: {
+        kind: "discussion",
+        author,
+        ...(clientId ? { clientId } : {}),
+        posted: posted.map((l) => ({ issueRefId: l.issueRefId, repo: l.repo, externalKey: l.externalKey, url: l.url })),
+        ...(failed.length > 0 ? { failed: failed.map((f) => ({ issueRefId: f.link.issueRefId, error: f.error })) } : {}),
+      },
+    }, Date.now());
+
+  // Idempotency = reserve→post→finalize (NOT scan→post→insert): the (taskId,kind,clientId)
+  // slot is claimed TRANSACTIONALLY before the awaited GitHub append, so concurrent same-key
+  // requests can't both post, and a crash leaves a durable reservation rather than re-posting.
+  let reservation: TaskCommentThroughRecord | undefined;
+  if (clientId) {
+    const reserved = reserveCommentThrough(taskId, "discussion", clientId, Date.now());
+    if (reserved.outcome === "duplicate") {
+      return { taskId, posted: [], failed: [], event: reserved.record.eventId ? getTaskEvent(reserved.record.eventId) : null, deduped: true };
+    }
+    if (reserved.outcome === "in_flight") {
+      return { taskId, posted: [], failed: [], event: null, deduped: true };
+    }
+    reservation = reserved.record;
+    // Stale-`reserved` reclaim is ambiguous (post-before-finalize crash). Reconcile each linked
+    // issue against GitHub before re-posting: finalize only when EVERY link's state is known
+    // (already-posted or freshly-posted); a single unreadable link leaves the slot durable.
+    if (reserved.reconcileNeeded) {
+      return await reconcileReclaim({ taskId, kind: "discussion", slotKey: clientId, payload, body, githubLinks, reservation, recordReceipt, opts });
+    }
+  }
+
+  const result = await postThrough("discussion", payload, body, githubLinks, opts);
+
+  // Finding 1: zero successful GitHub posts → NO receipt. Release the reservation to 'failed'
+  // (reclaimable) and surface the failure so a retry actually re-hits GitHub. The Task never
+  // shows a comment as posted when GitHub never received it.
+  if (result.posted.length === 0) {
+    if (reservation) failCommentThrough(reservation.id, Date.now());
+    throw new CommentThroughError(
+      `comment write-through failed for all linked issue(s): ${result.failed.map((f) => `${f.link.repo}#${f.link.externalKey}: ${f.error}`).join("; ")}`,
+      result.failed,
+    );
+  }
+
+  const event = recordReceipt(result.posted, result.failed);
+  if (reservation) finalizeCommentThrough(reservation.id, event.id, Date.now());
+  emitChanged(taskId);
+  return { taskId, posted: result.posted, failed: result.failed, event, deduped: false };
+}
+
+// --- Milestone summary (the single-comment exception) — SEAM for #831 ----------------
+export interface MilestoneCommentInput {
+  taskId: number;
+  milestone: string;
+  summary: string;
+  /** One comment per boundary: e.g. the land key, so #831 re-firing posts once. */
+  idempotencyKey?: string;
+  commitSha?: string;
+  gates?: TaskGateState[];
+  author?: string;
+}
+
+export interface MilestoneCommentResult {
+  taskId: number;
+  posted: TaskIssueLink[];
+  failed: Array<{ link: TaskIssueLink; error: string }>;
+  event: TaskEvent | null;
+  deduped: boolean;
+}
+
+function gatesLine(gates: TaskGateState[] | undefined): string {
+  if (!gates || gates.length === 0) return "";
+  return `\ngates: ${gates.map((g) => `${g.gate} ${g.status === "pass" ? "✓" : "✗"}`).join(" · ")}`;
+}
+
+// The MECHANISM for the milestone exception. #831's land trigger calls this once at a
+// boundary (land/deploy). Idempotent by (milestone, idempotencyKey) so a retried land
+// surfaces exactly one structured summary. NOT wired into the land pipeline here.
+export async function postTaskMilestoneComment(input: MilestoneCommentInput, opts: WeaveOptions = {}): Promise<MilestoneCommentResult> {
+  const taskId = input.taskId;
+  const detail = getTaskDetail(taskId);
+  if (!detail) throw new ValidationError(`task ${taskId} not found`);
+  const milestone = input.milestone?.trim();
+  if (!milestone) throw new ValidationError("milestone required");
+  const summary = input.summary?.trim();
+  if (!summary) throw new ValidationError("milestone summary required");
+
+  // The milestone slot is the (milestone, idempotencyKey) pair so distinct boundaries don't
+  // collide. The marker embeds that same slotKey so a reclaim can reconcile against GitHub.
+  const idempotencyKey = input.idempotencyKey?.trim();
+  const slotKey = idempotencyKey ? `${milestone}:${idempotencyKey}` : undefined;
+  const author = input.author?.trim() || "agent-relay";
+  const body = `${summary}${input.commitSha ? `\ncommit: \`${input.commitSha.slice(0, 12)}\`` : ""}${gatesLine(input.gates)}`;
+  const payload: TaskCommentPayload = { v: TASK_COMMENT_FORMAT_VERSION, kind: "milestone", taskId, author, milestone, ...(slotKey ? { key: slotKey } : {}) };
+
+  const recordReceipt = (posted: TaskIssueLink[], failed: Array<{ link: TaskIssueLink; error: string }>): TaskEvent =>
+    insertTaskEvent(taskId, {
+      source: author,
+      type: "milestone.posted",
+      severity: "info",
+      title: `Milestone ${milestone}`,
+      body: summary,
+      metadata: {
+        kind: "milestone",
+        milestone,
+        author,
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+        ...(input.commitSha ? { commitSha: input.commitSha } : {}),
+        posted: posted.map((l) => ({ issueRefId: l.issueRefId, repo: l.repo, externalKey: l.externalKey, url: l.url })),
+        ...(failed.length > 0 ? { failed: failed.map((f) => ({ issueRefId: f.link.issueRefId, error: f.error })) } : {}),
+      },
+    }, Date.now());
+
+  // Same reserve→post→finalize + reconcile-on-reclaim discipline as discussion, so a re-fired
+  // land posts at most one summary even across concurrency and post-before-finalize crashes.
+  const githubLinks = detail.issues.filter((link) => link.provider === "github");
+  let reservation: TaskCommentThroughRecord | undefined;
+  if (slotKey) {
+    const reserved = reserveCommentThrough(taskId, "milestone", slotKey, Date.now());
+    if (reserved.outcome === "duplicate") {
+      return { taskId, posted: [], failed: [], event: reserved.record.eventId ? getTaskEvent(reserved.record.eventId) : null, deduped: true };
+    }
+    if (reserved.outcome === "in_flight") {
+      return { taskId, posted: [], failed: [], event: null, deduped: true };
+    }
+    reservation = reserved.record;
+    if (reserved.reconcileNeeded && githubLinks.length > 0 && slotKey) {
+      return await reconcileReclaim({ taskId, kind: "milestone", slotKey, payload, body, githubLinks, reservation, recordReceipt, opts });
+    }
+  }
+
+  // No GitHub-backed issue → nothing to post through, but still leave a local timeline marker.
+  // When there ARE linked issues and EVERY post fails, treat it like a failed write-through
+  // (finding 1): release the reservation and surface the failure so #831 can re-fire.
+  const result = githubLinks.length > 0
+    ? await postThrough("milestone", payload, body, githubLinks, opts)
+    : { posted: [] as TaskIssueLink[], failed: [] as Array<{ link: TaskIssueLink; error: string }> };
+  if (githubLinks.length > 0 && result.posted.length === 0) {
+    if (reservation) failCommentThrough(reservation.id, Date.now());
+    throw new CommentThroughError(
+      `milestone write-through failed for all linked issue(s): ${result.failed.map((f) => `${f.link.repo}#${f.link.externalKey}: ${f.error}`).join("; ")}`,
+      result.failed,
+    );
+  }
+
+  const event = recordReceipt(result.posted, result.failed);
+  if (reservation) finalizeCommentThrough(reservation.id, event.id, Date.now());
+  emitChanged(taskId);
+  return { taskId, posted: result.posted, failed: result.failed, event, deduped: false };
+}
+
+// --- Reads ---------------------------------------------------------------------------
+export function listWriteThroughEvents(taskId: number): TaskEvent[] {
+  return listTaskEvents(taskId).filter((e) => (WRITE_THROUGH_EVENT_TYPES as readonly string[]).includes(e.type));
+}
+
+// --- Close-bridge projection (#482/#474 receipt, not a copy) --------------------------
+export interface TaskCloseBridgeEntry {
+  issueRefId: string;
+  provider: string;
+  repo: string;
+  externalKey: string;
+  url: string;
+  issueStatus: string;
+  /** A successful #482/#474 close action exists for this issue (the canonical record). */
+  closed: boolean;
+  closedAt?: number;
+  commitSha?: string;
+  landKey?: string;
+  source?: string;
+}
+
+// Projects the canonical issue-lifecycle ledger onto the Task's linked issues. This is the
+// answer to "did #482 already close it?" — read, never duplicated. The land WIRING that
+// advances the Task on land is #831; this projection is always accurate regardless, because
+// #474 writes the ledger row the moment it closes the issue.
+export function taskCloseBridge(taskId: number): TaskCloseBridgeEntry[] {
+  const detail = getTaskDetail(taskId);
+  if (!detail) throw new ValidationError(`task ${taskId} not found`);
+  return detail.issues.map((link) => {
+    const actions = listSuccessfulCloseActionsForIssueRef(link.issueRefId);
+    const latest = actions[0];
+    return {
+      issueRefId: link.issueRefId,
+      provider: link.provider,
+      repo: link.repo,
+      externalKey: link.externalKey,
+      url: link.url,
+      issueStatus: link.status,
+      closed: Boolean(latest),
+      ...(latest?.updatedAt ? { closedAt: latest.updatedAt } : {}),
+      ...(latest?.commitSha ? { commitSha: latest.commitSha } : {}),
+      ...(latest?.landKey ? { landKey: latest.landKey } : {}),
+      ...(latest?.source ? { source: latest.source } : {}),
+    };
+  });
+}