@staix/agent-hub 0.30.0 → 0.31.0

package/src/hub/board.ts

@@ -1,5 +1,7 @@
 import { parseAttemptReceipt, parseResearchRunners, verifyAttemptReceipt, type AttemptReceiptV1 } from "./research-runner.ts";
 import { canonicalJson } from "./packs.ts";
+import { parseEvidenceLink, evidenceLinkCanonical, MAX_EVIDENCE_RECORD_BYTES, type EvidenceLinkV1 } from "./research-evidence.ts";
+import { parseStoredReviewComment, reviewCommentIds, emptyReviewCommentCounts, REVIEW_COMMENT_LIMIT, type ReviewCommentRecord, type ReviewCommentFence, type ReviewCommentCounts, type ReviewCommentPackage, type ReviewCommentPackageView } from "./review-comments.ts";
 import { parseComparisonPlan, comparisonPlanHash, evaluatorIdentityHash, parseExperimentProtocol, protocolHash, parseExperimentAttempt, parseExperimentEvent, parseExperimentHostEvidence, experimentStatus, projectExperimentWithObservations, declaredExperimentEvents,
   type ComparisonPlanV1, type ExperimentProtocolRecord, type ExperimentAttemptRecord, type ExperimentEventRecord, type ExperimentWriteFence, type DeclaredExperimentEventInput, type ExperimentHostEvidence, type ExperimentStatus } from "./research-experiments.ts";
 import type { InvocationRow } from "./invocations.ts";
@@ -249,6 +251,7 @@ export interface HistoryEntry {
   /** Opaque artifact identity captured by the host at the queue-held role write. */
   queueReviewBinding?: string;
   reviewerFailure?: { peer: string; head?: string; cause: "start_failed" | "quota" | "no_verdict" };
+  resolvedReviewComments?: string[];
   planning?: { revision: number; fields: (keyof PlanningFields)[]; previous: PlanningFields; pull?: true; split?: { children: { id: number; revision: number; history: number }[] } };
 }
 /** #901: one person verdict on a plan claim, with the model label the person says produced the claim. All closed or bounded; nothing here is claim text. */
@@ -259,6 +262,14 @@ export interface ClaimVerdict { slot: number; verdict: (typeof CLAIM_VERDICTS)[n
 export function claimListId(claims: readonly string[] | undefined): string {
   return createHash("sha256").update(planFingerprint({ claims: [...(claims ?? [])] })).digest("hex").slice(0, 16);
 }
+/** #901's one claim identity boundary, shared by person verdicts and declared passage links. */
+export function taskClaimIdentity(task: Pick<Task, "id" | "created" | "plan">, slot: number): { claimId: string; claimRevision: string; slot: number } {
+  if (!Number.isSafeInteger(task.id) || task.id < 1 || !Number.isSafeInteger(task.created) || task.created < 0
+    || !Number.isSafeInteger(slot) || slot < 1 || slot > Math.min(50, task.plan?.claims?.length ?? 0)) throw new Error("claim slot is unavailable; refresh ahub task show and use a current declared claim slot");
+  // ponytail: revision binds the whole ordered list, so another claim's edit invalidates every link.
+  // Upgrade to shared per-claim revision bindings at this #901 boundary, preserving exact-list restoration of existing verdicts.
+  return { claimId: `claim:${task.id}:${task.created}:${slot}`, claimRevision: claimListId(task.plan?.claims), slot };
+}
 /** A claim slot is a position in the plan's claim list (at most 50, as the scorecard's own bound); a model label is a bounded token, never prose. */
 export function parseClaimVerdict(value: unknown, slots: number): ClaimVerdict {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("claim verdict must be an object");
@@ -320,9 +331,12 @@ function plannerMetadata(planner: unknown, reason?: PlannerReason): Pick<History
   return { planner: plannerValue(planner), ...(reason === undefined ? {} : { plannerReason: reason }) };
 }
 /** #604: what this project handed to another project, and the last state that project reported (agent-hub#1030 design 4). */
-export interface HandoffOutboundRow { remoteProject: string; remoteTask: number; originPeer: string; localTask: number | null; title: string; state: string; pr: number | null; head: string | null; updatedAt: number }
+export interface HandoffOutboundRow { remoteProject: string; remoteTask: number; originPeer: string; localTask: number | null; title: string; state: string; pr: number | null; head: string | null; updatedAt: number;
+  /** #733: the target task's flow revision at the last event applied; null for a row from before sequences or from a target that sends none. */
+  seq: number | null }
+const OUTBOUND_COLUMNS = "remote_project, remote_task, origin_peer, local_task, title, last_state, pr, head, updated_at, seq";
 const handoffOutboundFromRow = (row: Record<string, unknown>): HandoffOutboundRow => ({ remoteProject: String(row.remote_project), remoteTask: Number(row.remote_task), originPeer: String(row.origin_peer),
-  localTask: row.local_task === null ? null : Number(row.local_task), title: String(row.title), state: String(row.last_state), pr: row.pr === null ? null : Number(row.pr), head: row.head === null ? null : String(row.head), updatedAt: Number(row.updated_at) });
+  localTask: row.local_task === null ? null : Number(row.local_task), title: String(row.title), state: String(row.last_state), pr: row.pr === null ? null : Number(row.pr), head: row.head === null ? null : String(row.head), updatedAt: Number(row.updated_at), seq: row.seq === null || row.seq === undefined ? null : Number(row.seq) });
 
 export interface Task extends PlanningFields {
   offer?: TaskOffer;
@@ -355,6 +369,8 @@ export interface Task extends PlanningFields {
   deps?: number[];
   /** Who routing offers the task first once nothing is left to wait for (issue #207); null when nobody was named. */
   reserved?: PeerId | null;
+  /** #1176: only the person can run this leg. Present (true) only when set; no agent is ever offered it, and it counts toward no planner's WIP. */
+  needsPerson?: true;
   signals: string[];
   /** consecutive changes_requested verdicts */
   rejections: number;
@@ -407,6 +423,8 @@ const TASK_SELECT = "SELECT tasks.*, (SELECT CASE WHEN length(CAST(payload AS BL
 /** Task board in `.agenthub/state/hub.db`. It outlives the hub process: `ahub kill` leaves the file. */
 export class Board {
   private readonly db: Database;
+  private reviewObserverCacheStamp = "";
+  private readonly reviewObserverScopeCache = new Map<string, boolean>();
   private pendingChanges: { task: Task; entry: HistoryEntry }[] | undefined;
   /** Every recorded change, as it lands (telemetry, issue #40). */
   onChange?: (task: Task, entry: HistoryEntry) => void;
@@ -494,6 +512,8 @@ export class Board {
       if (!have.has(col)) this.db.run(`ALTER TABLE tasks ADD COLUMN "${col}" INTEGER`);
     }
     if (!have.has("pinned")) this.db.run("ALTER TABLE tasks ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0");
+    // #1176: additive, like `pinned`; an older hub ignores the column.
+    if (!have.has("needs_person")) this.db.run("ALTER TABLE tasks ADD COLUMN needs_person INTEGER NOT NULL DEFAULT 0");
     if (!have.has("draft")) this.db.run("ALTER TABLE tasks ADD COLUMN draft INTEGER NOT NULL DEFAULT 0");
     if (!have.has("planning_revision")) this.db.run("ALTER TABLE tasks ADD COLUMN planning_revision INTEGER NOT NULL DEFAULT 0");
     this.db.run(`CREATE TABLE IF NOT EXISTS releases (
@@ -524,12 +544,28 @@ export class Board {
     // is the ORIGIN's record of what it handed to another project and the last state that project reported. Both are additive: a daemon without `task_handoff` never reads them, so a target
     // lacking the feature is refused at recovery while either holds a row.
     this.db.run("CREATE TABLE IF NOT EXISTS task_handoff_origin (task_id INTEGER PRIMARY KEY, project_id TEXT NOT NULL, peer TEXT NOT NULL, origin_task INTEGER, at INTEGER NOT NULL)");
+    // #731 (agent-hub#1203): the origin's idempotency key and a digest of what it asked for. A key is unique per origin project, so a replay can never file a second task. Rows from before keep NULL.
+    for (const [column, type] of [["handoff_key", "TEXT"], ["request_digest", "TEXT"]] as const)
+      if (!(this.db.query("PRAGMA table_info(task_handoff_origin)").all() as { name: string }[]).some(c => c.name === column)) this.db.run(`ALTER TABLE task_handoff_origin ADD COLUMN ${column} ${type}`);
+    this.db.run("CREATE UNIQUE INDEX IF NOT EXISTS task_handoff_origin_key ON task_handoff_origin(project_id, handoff_key) WHERE handoff_key IS NOT NULL");
     this.db.run(`CREATE TABLE IF NOT EXISTS task_handoff_outbound (remote_project TEXT NOT NULL, remote_task INTEGER NOT NULL, origin_peer TEXT NOT NULL, local_task INTEGER,
       title TEXT NOT NULL, last_state TEXT NOT NULL, pr INTEGER, head TEXT, updated_at INTEGER NOT NULL, PRIMARY KEY(remote_project, remote_task))`);
+    // #733: the sequence of the last applied event, so an event that arrives late cannot move a row backwards. Rows from before keep NULL and accept any event.
+    if (!(this.db.query("PRAGMA table_info(task_handoff_outbound)").all() as { name: string }[]).some(c => c.name === "seq")) this.db.run("ALTER TABLE task_handoff_outbound ADD COLUMN seq INTEGER");
     this.db.run(`CREATE TABLE IF NOT EXISTS research_handoffs (
       campaign_id TEXT NOT NULL, unit_id TEXT NOT NULL, seq INTEGER NOT NULL, revision INTEGER NOT NULL,
       task_id INTEGER NOT NULL, body TEXT NOT NULL, by_peer TEXT NOT NULL, at INTEGER NOT NULL, private INTEGER NOT NULL,
       PRIMARY KEY(campaign_id,unit_id,seq))`);
+    this.db.run(`CREATE TABLE IF NOT EXISTS research_evidence_links (
+      project TEXT NOT NULL, id TEXT NOT NULL, revision INTEGER NOT NULL, task_id INTEGER NOT NULL,
+      body TEXT NOT NULL, body_sha256 TEXT NOT NULL, PRIMARY KEY(project,id,revision))`);
+    this.db.run(`CREATE TABLE IF NOT EXISTS review_comments (
+      task_id INTEGER NOT NULL,task_created INTEGER NOT NULL,id TEXT NOT NULL,body TEXT NOT NULL,lifecycle TEXT NOT NULL,revision INTEGER NOT NULL,
+      PRIMARY KEY(task_id,task_created,id))`);
+    this.db.run("CREATE INDEX IF NOT EXISTS review_comments_sent ON review_comments(task_id,task_created,id) WHERE lifecycle='sent'");
+    this.db.run(`CREATE TABLE IF NOT EXISTS review_comment_packages (
+      id TEXT PRIMARY KEY,task_id INTEGER NOT NULL,task_created INTEGER NOT NULL,body TEXT NOT NULL)`);
+    this.db.run("CREATE INDEX IF NOT EXISTS review_comment_packages_owner ON review_comment_packages(CASE WHEN json_valid(body)=1 THEN json_extract(body,'$.owner') END,task_id,task_created)");
     this.db.run(`CREATE TABLE IF NOT EXISTS research_protocols (
       hash TEXT PRIMARY KEY, project TEXT NOT NULL, campaign_id TEXT NOT NULL, campaign_revision INTEGER NOT NULL, task_id INTEGER NOT NULL, body TEXT NOT NULL,
       by_peer TEXT NOT NULL, at INTEGER NOT NULL, private INTEGER NOT NULL)`);
@@ -576,26 +612,72 @@ export class Board {
     this.db.query("INSERT INTO task_handoff_origin(task_id, project_id, peer, origin_task, at) VALUES(?,?,?,?,?) ON CONFLICT(task_id) DO NOTHING").run(taskId, origin.projectId, origin.peer, origin.originTask ?? null, Date.now());
   }
 
-  /** ORIGIN side: what this project handed to another one. Keyed by the target project and its task id, so a repeated event updates one row. */
+  /**
+   * #731: the task a handoff key already made for this origin project, with the digest of the request that made it, or undefined. A read: a replayed key is answered from here.
+   */
+  handoffOriginByKey(projectId: string, key: string): { taskId: number; digest: string | null } | undefined {
+    const row = this.db.query("SELECT task_id, request_digest FROM task_handoff_origin WHERE project_id=? AND handoff_key=?").get(projectId, key) as { task_id: number; request_digest: string | null } | null;
+    return row ? { taskId: row.task_id, digest: row.request_digest } : undefined;
+  }
+  /**
+   * #731 (H9): the proposal and its origin row in ONE transaction, so a crash or a failure between them can never leave a task with no origin (which the origin could then never be told about),
+   * and a replayed key answers with the task it already made instead of filing a second one. The unique index is the last guard: even two writers of one key cannot both commit.
+   * Observers (`onChange`) run after the commit, as for every other multi-row write.
+   */
+  proposeHandoff(by: PeerId, t: Parameters<Board["propose"]>[1], origin: { projectId: string; peer: string; originTask?: number; key?: string; digest?: string }): { task: Task; replayed: boolean } {
+    return this.atomic(() => {
+      if (origin.key !== undefined) {
+        const existing = this.handoffOriginByKey(origin.projectId, origin.key);
+        if (existing) { const task = this.get(existing.taskId); if (task) return { task, replayed: true }; }
+      }
+      const task = this.propose(by, t);
+      this.db.query("INSERT INTO task_handoff_origin(task_id, project_id, peer, origin_task, at, handoff_key, request_digest) VALUES(?,?,?,?,?,?,?)")
+        .run(task.id, origin.projectId, origin.peer, origin.originTask ?? null, Date.now(), origin.key ?? null, origin.digest ?? null);
+      return { task, replayed: false };
+    });
+  }
+
+  /**
+   * ORIGIN side: what this project handed to another one, newest first, for the person's list (`ahub board --handoffs`). Keyed by the target project and its task id, so a repeated event updates
+   * one row. Capped for display only: the catch-up never reads this (`handoffOutboundOpen`), so a row the list does not show is still caught up (#733).
+   */
   handoffOutbound(): HandoffOutboundRow[] {
-    return (this.db.query("SELECT remote_project, remote_task, origin_peer, local_task, title, last_state, pr, head, updated_at FROM task_handoff_outbound ORDER BY updated_at DESC, remote_project, remote_task LIMIT 200").all() as Record<string, unknown>[]).map(handoffOutboundFromRow);
+    return (this.db.query(`SELECT ${OUTBOUND_COLUMNS} FROM task_handoff_outbound ORDER BY updated_at DESC, remote_project, remote_task LIMIT 200`).all() as Record<string, unknown>[]).map(handoffOutboundFromRow);
+  }
+  /** #733 (H5): every row the catch-up still asks about, no cap, oldest first so a long backlog is worked through in the same order every pass. The caller filters with `handoffCatchUpRow`. */
+  handoffOutboundOpen(): HandoffOutboundRow[] {
+    return (this.db.query(`SELECT ${OUTBOUND_COLUMNS} FROM task_handoff_outbound WHERE last_state != 'cancelled' ORDER BY updated_at, remote_project, remote_task`).all() as Record<string, unknown>[]).map(handoffOutboundFromRow);
   }
   handoffOutboundFor(remoteProject: string, remoteTask: number): HandoffOutboundRow | undefined {
-    const row = this.db.query("SELECT remote_project, remote_task, origin_peer, local_task, title, last_state, pr, head, updated_at FROM task_handoff_outbound WHERE remote_project=? AND remote_task=?").get(remoteProject, remoteTask) as Record<string, unknown> | null;
+    const row = this.db.query(`SELECT ${OUTBOUND_COLUMNS} FROM task_handoff_outbound WHERE remote_project=? AND remote_task=?`).get(remoteProject, remoteTask) as Record<string, unknown> | null;
     return row ? handoffOutboundFromRow(row) : undefined;
   }
-  recordHandoffOutbound(row: { remoteProject: string; remoteTask: number; originPeer: string; localTask?: number; title: string; state: string; pr?: number; head?: string }): void {
-    this.db.query(`INSERT INTO task_handoff_outbound(remote_project, remote_task, origin_peer, local_task, title, last_state, pr, head, updated_at) VALUES(?,?,?,?,?,?,?,?,?)
-      ON CONFLICT(remote_project, remote_task) DO UPDATE SET last_state=excluded.last_state, pr=COALESCE(excluded.pr, pr), head=COALESCE(excluded.head, head), updated_at=excluded.updated_at`)
-      .run(row.remoteProject, row.remoteTask, row.originPeer, row.localTask ?? null, row.title, row.state, row.pr ?? null, row.head ?? null, Date.now());
+  /**
+   * Record a state. With a `seq` the write applies only when it is newer than the stored one (#733 H4: events use a connection each and can arrive out of order), decided inside the one statement so
+   * two events cannot both pass a check made before either wrote. Returns whether the row changed. An event with no `seq` (an older target, or the origin's own first write) behaves as before:
+   * it applies, and keeps the highest `seq` already stored.
+   */
+  recordHandoffOutbound(row: { remoteProject: string; remoteTask: number; originPeer: string; localTask?: number; title: string; state: string; pr?: number; head?: string; seq?: number }): { applied: boolean } {
+    const result = this.db.query(`INSERT INTO task_handoff_outbound(remote_project, remote_task, origin_peer, local_task, title, last_state, pr, head, updated_at, seq) VALUES(?,?,?,?,?,?,?,?,?,?)
+      ON CONFLICT(remote_project, remote_task) DO UPDATE SET last_state=excluded.last_state, pr=COALESCE(excluded.pr, pr), head=COALESCE(excluded.head, head), updated_at=excluded.updated_at, seq=COALESCE(MAX(excluded.seq, seq), excluded.seq, seq)
+      WHERE excluded.seq IS NULL OR seq IS NULL OR excluded.seq > seq`)
+      .run(row.remoteProject, row.remoteTask, row.originPeer, row.localTask ?? null, row.title, row.state, row.pr ?? null, row.head ?? null, Date.now(), row.seq ?? null);
+    return { applied: result.changes > 0 };
   }
   /** A digest over both tables, so a recovery that restores or loses a row is seen. */
   handoffIntegrity(): { origins: number; outbound: number; digest: string } {
     return this.db.transaction(() => {
       const digest = createHash("sha256").update("agent-hub.handoff-integrity/v1\n");
       let origins = 0, outbound = 0;
-      for (const row of this.db.query("SELECT task_id, project_id, peer, origin_task, at FROM task_handoff_origin ORDER BY task_id").iterate()) { digest.update(JSON.stringify(row)).update("\n"); origins++; }
-      for (const row of this.db.query("SELECT remote_project, remote_task, origin_peer, local_task, title, last_state, pr, head, updated_at FROM task_handoff_outbound ORDER BY remote_project, remote_task").iterate()) { digest.update(JSON.stringify(row)).update("\n"); outbound++; }
+      for (const row of this.db.query("SELECT task_id, project_id, peer, origin_task, at, handoff_key, request_digest FROM task_handoff_origin ORDER BY task_id").iterate() as Iterable<Record<string, unknown>>) {
+        // A row from before handoff keys has no key columns in its digest, so an upgrade does not change what a recovery compares (#731).
+        if (row.handoff_key === null) { delete row.handoff_key; delete row.request_digest; }
+        digest.update(JSON.stringify(row)).update("\n"); origins++;
+      }
+      for (const row of this.db.query(`SELECT ${OUTBOUND_COLUMNS} FROM task_handoff_outbound ORDER BY remote_project, remote_task`).iterate() as Iterable<Record<string, unknown>>) {
+        if (row.seq === null) delete row.seq;   // a row from before sequences keeps its digest (#733)
+        digest.update(JSON.stringify(row)).update("\n"); outbound++;
+      }
       return { origins, outbound, digest: digest.digest("hex") };
     })();
   }
@@ -912,6 +994,257 @@ export class Board {
     });
   }
 
+  /** Immutable declared link revisions. Caller/source/privacy admission belongs to Tasks. */
+  evidenceLink(project: string, id: string, revision?: number): EvidenceLinkV1 | undefined {
+    if (!researchText(project) || !/^ev:[a-f0-9]{32}$/.test(id) || revision !== undefined && !researchInteger(revision)) throw new Error("invalid evidence identity; use the recorded evidence id and revision");
+    const row = this.db.query(`SELECT project,id,revision,task_id,CASE WHEN length(CAST(body AS BLOB))<=${MAX_EVIDENCE_RECORD_BYTES} THEN body END AS body,body_sha256
+      FROM research_evidence_links WHERE project=? AND id=?${revision === undefined ? "" : " AND revision=?"} ORDER BY revision DESC LIMIT 1`)
+      .get(...(revision === undefined ? [project, id] : [project, id, revision])) as { project: string; id: string; revision: number; task_id: number; body: string | null; body_sha256: string } | null;
+    if (!row) return undefined;
+    try {
+      if (typeof row.body !== "string") throw new Error("invalid body");
+      const link = parseEvidenceLink(JSON.parse(row.body)), canonical = evidenceLinkCanonical(link);
+      if (link.id !== row.id || link.revision !== row.revision || link.taskId !== row.task_id || createHash("sha256").update(canonical).digest("hex") !== row.body_sha256) throw new Error("invalid binding");
+      return link;
+    } catch { throw new Error("evidence storage invalid; stop the hub and restore a trusted hub.db backup; then restart and retry"); }
+  }
+
+  recordEvidenceLink(project: string, input: EvidenceLinkV1, fence: { taskFlowRevision: number; taskCreated: number; owner: PeerId }): EvidenceLinkV1 {
+    const link = parseEvidenceLink(input), canonical = evidenceLinkCanonical(link);
+    if (!researchText(project) || !researchInteger(fence.taskFlowRevision, 0) || !researchInteger(fence.taskCreated, 0) || fence.owner !== link.recordedBy) throw new Error("evidence write binding is invalid; refresh the task before retrying");
+    return this.atomic(() => {
+      const task = this.get(link.taskId);
+      if (!task || task.created !== fence.taskCreated || task.history.length !== fence.taskFlowRevision || task.owner !== fence.owner || task.state !== "in_progress" || task.profile !== "research"
+        || task.signals.includes("pii") || task.signals.includes("pii_path")) throw new Error("evidence task authority changed; refresh ahub task show before retrying");
+      const identity = taskClaimIdentity(task, Number(link.claimId.split(":").at(-1)));
+      if (identity.claimId !== link.claimId || identity.claimRevision !== link.claimRevision) throw new Error("evidence claim revision changed; refresh the claim binding before retrying");
+      const latest = this.evidenceLink(project, link.id), next = (latest?.revision ?? 0) + 1;
+      if (latest && (latest.taskId !== link.taskId || latest.claimId !== link.claimId)) throw new Error("evidence id belongs to another claim; use a new evidence id");
+      const known = this.evidenceLink(project, link.id, link.revision);
+      if (known) {
+        if (evidenceLinkCanonical(known) !== canonical) throw new Error(`evidence revision already records different content; use next revision ${next} or a new evidence id`);
+        return known;
+      }
+      if (link.revision !== next) throw new Error(`evidence revision is out of sequence; expected next revision ${next}; use that revision or replay an unchanged recorded revision`);
+      this.taskWrite(() => this.db.query("INSERT INTO research_evidence_links(project,id,revision,task_id,body,body_sha256) VALUES(?,?,?,?,?,?)")
+        .run(project, link.id, link.revision, link.taskId, canonical, createHash("sha256").update(canonical).digest("hex")));
+      return this.evidenceLink(project, link.id, link.revision)!;
+    });
+  }
+
+  hasResearchEvidenceState(): boolean {
+    return (this.db.query("SELECT EXISTS(SELECT 1 FROM research_evidence_links) AS present").get() as { present: number }).present === 1;
+  }
+
+  researchEvidenceIntegrity(): { links: number; revisions: number; digest: string } {
+    return this.db.transaction(() => {
+      const digest = createHash("sha256").update("agent-hub.research-evidence/v1\n");
+      let links = 0, revisions = 0, previous: string | undefined, previousRevision = 0;
+      let claim: string | undefined, task: number | undefined;
+      for (const row of this.db.query("SELECT project,id,revision FROM research_evidence_links ORDER BY project,id,revision").iterate() as Iterable<{ project: string; id: string; revision: number }>) {
+        const link = this.evidenceLink(row.project, row.id, row.revision);
+        if (!link) throw new Error("evidence storage changed during integrity read; retry recovery inspection");
+        const key = JSON.stringify([row.project, row.id]);
+        if (key !== previous) { links++; previous = key; previousRevision = 0; claim = link.claimId; task = link.taskId; }
+        if (row.revision !== previousRevision + 1 || link.claimId !== claim || link.taskId !== task) throw new Error("evidence revision history is incomplete or changed claims; stop the hub and restore a trusted hub.db backup; then restart and retry recovery");
+        previousRevision = row.revision; revisions++;
+        digest.update(JSON.stringify([row.project, evidenceLinkCanonical(link)])).update("\n");
+      }
+      return { links, revisions, digest: digest.digest("hex") };
+    })();
+  }
+
+  reviewComments(task: number, created: number): ReviewCommentRecord[] {
+    const rows = this.db.query(`SELECT id,lifecycle,revision,CASE WHEN length(CAST(body AS BLOB))<=32768 THEN body END AS body FROM review_comments WHERE task_id=? AND task_created=? ORDER BY id LIMIT ${REVIEW_COMMENT_LIMIT + 1}`).all(task, created) as { id: string; lifecycle: string; revision: number; body: string | null }[];
+    if (rows.length > REVIEW_COMMENT_LIMIT) throw new Error("review comment storage limit invalid; restore a trusted hub.db backup before retrying");
+    return rows.map(row => {
+      try {
+        if (typeof row.body !== "string") throw new Error("missing body");
+        const record = parseStoredReviewComment(JSON.parse(row.body));
+        if (record.task !== task || record.taskCreated !== created || record.thread.id !== row.id || record.lifecycle !== row.lifecycle || record.revision !== row.revision) throw new Error("binding differs");
+        return record;
+      } catch { throw new Error("review comment storage invalid; stop the hub and restore a trusted hub.db backup, then restart and retry"); }
+    });
+  }
+  reviewCommentCounts(task: number, created: number): ReviewCommentCounts {
+    const counts = emptyReviewCommentCounts();
+    for (const row of this.db.query("SELECT lifecycle,COUNT(*) AS n FROM review_comments WHERE task_id=? AND task_created=? GROUP BY lifecycle").all(task, created) as { lifecycle: string; n: number }[]) {
+      if (!Object.hasOwn(counts, row.lifecycle)) throw new Error("review comment storage invalid; restore a trusted hub.db backup before retrying");
+      counts[row.lifecycle as keyof ReviewCommentCounts] = row.n;
+    }
+    return counts;
+  }
+  private reviewCommentFence(fence: ReviewCommentFence): Task {
+    const task = this.get(fence.task);
+    if (!task || task.created !== fence.taskCreated || task.history.length !== fence.flow || task.owner !== fence.owner || (task.refs.commit ?? task.sdlc?.head ?? task.sdlc?.localHead) !== fence.head) throw new Error("review task changed; refresh the task review before retrying");
+    return task;
+  }
+  putReviewComment(input: ReviewCommentRecord, fence: ReviewCommentFence, expected?: number): ReviewCommentRecord {
+    const record = parseStoredReviewComment(input);
+    return this.atomic(() => {
+      this.reviewCommentFence(fence);
+      if (record.task !== fence.task || record.taskCreated !== fence.taskCreated || record.lifecycle !== "draft") throw new Error("review comment binding changed; refresh the draft before retrying");
+      const comments = this.reviewComments(record.task, record.taskCreated), previous = comments.find(row => row.thread.id === record.thread.id);
+      if (previous ? previous.lifecycle !== "draft" || previous.revision !== expected || record.revision !== previous.revision + 1 : expected !== undefined || record.revision !== 1 || comments.length >= REVIEW_COMMENT_LIMIT) throw new Error("review draft changed or the comment limit is full; refresh the draft list before retrying");
+      this.taskWrite(() => this.db.query("INSERT INTO review_comments(task_id,task_created,id,body,lifecycle,revision) VALUES(?,?,?,?,?,?) ON CONFLICT(task_id,task_created,id) DO UPDATE SET body=excluded.body,lifecycle=excluded.lifecycle,revision=excluded.revision")
+        .run(record.task, record.taskCreated, record.thread.id, JSON.stringify(record), record.lifecycle, record.revision));
+      return this.reviewComments(record.task, record.taskCreated).find(row => row.thread.id === record.thread.id)!;
+    });
+  }
+  deleteReviewComment(id: string, revision: number, fence: ReviewCommentFence): { deleted: boolean; record: ReviewCommentRecord } {
+    return this.atomic(() => {
+      this.reviewCommentFence(fence);
+      const record = this.reviewComments(fence.task, fence.taskCreated).find(row => row.thread.id === id);
+      if (!record) throw new Error("review comment is unavailable; refresh the draft list before retrying");
+      if (record.lifecycle === "dismissed") return { deleted: false, record };
+      if (record.revision !== revision) throw new Error("review comment revision changed; refresh the list before retrying");
+      if (record.lifecycle === "draft") {
+        this.taskWrite(() => this.db.query("DELETE FROM review_comments WHERE task_id=? AND task_created=? AND id=?").run(fence.task, fence.taskCreated, id));
+        return { deleted: true, record };
+      }
+      const dismissed: ReviewCommentRecord = { ...record, lifecycle: "dismissed", revision: record.revision + 1 };
+      this.taskWrite(() => this.db.query("UPDATE review_comments SET body=?,lifecycle=?,revision=? WHERE task_id=? AND task_created=? AND id=?").run(JSON.stringify(dismissed), dismissed.lifecycle, dismissed.revision, fence.task, fence.taskCreated, id));
+      return { deleted: false, record: dismissed };
+    });
+  }
+  sendReviewComments(selected: readonly ReviewCommentRecord[], packet: ReviewCommentPackage, fence: ReviewCommentFence): Task {
+    return this.atomic(() => {
+      const task = this.reviewCommentFence(fence), rows = this.reviewComments(task.id, task.created);
+      if (!selected.length || selected.length > REVIEW_COMMENT_LIMIT || new Set(selected.map(row => row.thread.id)).size !== selected.length || selected.length !== packet.ids.length
+        || task.id !== packet.task || task.created !== packet.taskCreated || task.owner !== packet.owner || selected.some(row => !packet.ids.includes(row.thread.id))) throw new Error("review package binding changed; refresh the selected drafts before sending");
+      const encodedPacket = JSON.stringify(packet);
+      if (typeof encodedPacket !== "string" || Buffer.byteLength(encodedPacket, "utf8") > 32768) throw new Error("review package storage exceeds 32768 UTF-8 bytes; select fewer ids before sending");
+      for (const expected of selected) {
+        const record = rows.find(row => row.thread.id === expected.thread.id);
+        if (!record || record.lifecycle !== "draft" || record.revision !== expected.revision) throw new Error("review drafts changed; refresh the list before sending");
+        const sent: ReviewCommentRecord = { ...record, lifecycle: "sent", sentAt: packet.at, revision: record.revision + 1 };
+        this.taskWrite(() => this.db.query("UPDATE review_comments SET body=?,lifecycle=?,revision=? WHERE task_id=? AND task_created=? AND id=?").run(JSON.stringify(sent), sent.lifecycle, sent.revision, task.id, task.created, record.thread.id));
+      }
+      this.taskWrite(() => this.db.query("INSERT INTO review_comment_packages(id,task_id,task_created,body) VALUES(?,?,?,?)").run(packet.id, task.id, task.created, encodedPacket));
+      return this.update(task.id, "user", `person review comments sent (${selected.length})`, {}, undefined, {}, task.history.length);
+    });
+  }
+  reviewCommentPackages(task: number, created: number): ReviewCommentPackageView[] {
+    const rows = this.db.query("SELECT id,CASE WHEN length(CAST(body AS BLOB))<=32768 THEN body END AS body FROM review_comment_packages WHERE task_id=? AND task_created=? ORDER BY id LIMIT 65").all(task, created) as { id: string; body: string | null }[];
+    if (rows.length > 64) throw new Error("review comment package storage limit invalid; restore a trusted hub.db backup before retrying");
+    return rows.map(row => {
+      try {
+        if (typeof row.body !== "string") throw new Error();
+        const packet = JSON.parse(row.body) as ReviewCommentPackage;
+        if (!packet || packet.id !== row.id || packet.task !== task || packet.taskCreated !== created || !Array.isArray(packet.ids) || packet.ids.length < 1 || packet.ids.length > REVIEW_COMMENT_LIMIT) throw new Error();
+        const ids = reviewCommentIds(packet.ids);
+        if (packet.visibleIds !== undefined && (reviewCommentIds(packet.visibleIds).some(id => !ids.includes(id)))) throw new Error();
+        const delivery = packet.delivery ?? "unconfirmed";
+        if (delivery !== "queued" && delivery !== "unconfirmed") throw new Error();
+        return { id: row.id, count: packet.ids.length, delivery: packet.body && packet.envelopeId && packet.trace && packet.ts !== undefined && packet.publicationEvidenceVersion === 1 ? delivery : "unavailable" };
+      } catch { throw new Error("review comment package storage invalid; stop the hub and restore a trusted hub.db backup, then restart and retry"); }
+    });
+  }
+  reviewCommentPackage(id: string): ReviewCommentPackage | undefined {
+    const row = this.db.query("SELECT CASE WHEN length(CAST(body AS BLOB))<=32768 THEN body END AS body FROM review_comment_packages WHERE id=?").get(id) as { body: string | null } | null;
+    if (!row) return undefined;
+    try {
+      if (typeof row.body !== "string") throw new Error();
+      const packet = JSON.parse(row.body) as ReviewCommentPackage;
+      if (!packet || packet.id !== id || !Number.isSafeInteger(packet.task) || !Number.isSafeInteger(packet.taskCreated) || !Array.isArray(packet.ids)
+        || packet.ids.length < 1 || packet.ids.length > REVIEW_COMMENT_LIMIT || reviewCommentIds(packet.ids).length !== packet.ids.length
+        || typeof packet.owner !== "string" || typeof packet.head !== "string" || typeof packet.at !== "string"
+        || packet.delivery !== undefined && packet.delivery !== "queued" && packet.delivery !== "unconfirmed"
+        || packet.publicationEvidenceVersion !== undefined && packet.publicationEvidenceVersion !== 1
+        || packet.visibleIds !== undefined && (reviewCommentIds(packet.visibleIds).some(value => !packet.ids.includes(value)))
+        || packet.body !== undefined && (typeof packet.body !== "string" || Buffer.byteLength(packet.body, "utf8") > 12000)
+        || packet.envelopeId !== undefined && !/^[a-f0-9-]{36}$/.test(packet.envelopeId)
+        || packet.trace !== undefined && !/^[a-f0-9-]{36}$/.test(packet.trace)
+        || packet.ts !== undefined && (!Number.isSafeInteger(packet.ts) || packet.ts < 0)) throw new Error();
+      return packet;
+    } catch { throw new Error("review comment package storage invalid; stop the hub and restore a trusted hub.db backup, then restart and retry"); }
+  }
+  markReviewCommentPackageQueued(id: string): void {
+    this.taskWrite(() => {
+      const packet = this.reviewCommentPackage(id);
+      if (!packet || !packet.body || !packet.envelopeId || !packet.trace || packet.ts === undefined) throw new Error("review comment package is unavailable for retry; inspect the task review before sending a new comment");
+      return this.db.query("UPDATE review_comment_packages SET body=? WHERE id=?").run(JSON.stringify({ ...packet, delivery: "queued" }), id);
+    });
+  }
+  hasOpenReviewCommentsFor(owner: string, taskId?: number): boolean {
+    const taskScope = taskId === undefined ? "" : " AND task.id=?", packetScope = taskId === undefined ? "" : " AND packet.task_id=?";
+    const currentOwner = this.db.query(`SELECT EXISTS(SELECT 1 FROM review_comments AS comment JOIN tasks AS task ON task.id=comment.task_id AND task.created=comment.task_created
+      WHERE task.owner=? AND comment.lifecycle='sent'${taskScope}) AS present`).get(...(taskId === undefined ? [owner] : [owner, taskId])) as { present: number };
+    if (currentOwner.present === 1) return true;
+    const savedOwner = this.db.query(`WITH candidates AS (
+        SELECT packet.id,packet.task_id,packet.task_created FROM review_comment_packages AS packet
+        WHERE CASE WHEN json_valid(packet.body)=1 THEN json_extract(packet.body,'$.owner') END=?${packetScope}
+          AND EXISTS(SELECT 1 FROM json_each(packet.body,'$.ids') AS package_id
+            JOIN review_comments AS comment ON comment.task_id=packet.task_id AND comment.task_created=packet.task_created AND comment.id=package_id.value
+            WHERE comment.lifecycle='sent')
+        LIMIT 501
+      ) SELECT COUNT(*) AS count FROM candidates`).get(...(taskId === undefined ? [owner] : [owner, taskId])) as { count: number };
+    return savedOwner.count > 0;
+  }
+  /**
+   * Durable task-scoped exclusion for sent person comments and anchored findings; resolved/dismissed comments no longer hold memory.
+   * ponytail: anchored-finding scope is conservative until task close; upgrade to a persisted review-package epoch for precise closure. Scans cap at 500
+   * tasks and 16 MiB aggregate history; corrupt or over-limit state fails closed. A stamp over local total_changes and cross-connection
+   * data_version makes repeated progress reads O(1) until the board changes.
+   */
+  hasReviewObserverScope(peer: string, taskId: number): boolean {
+    try {
+      const dataVersion = this.db.query("PRAGMA data_version").get() as { data_version: number };
+      const totalChanges = this.db.query("SELECT total_changes() AS changes").get() as { changes: number };
+      const stamp = `${dataVersion.data_version}:${totalChanges.changes}`;
+      if (stamp !== this.reviewObserverCacheStamp) { this.reviewObserverScopeCache.clear(); this.reviewObserverCacheStamp = stamp; }
+      const cacheKey = JSON.stringify([peer, taskId]), cached = this.reviewObserverScopeCache.get(cacheKey);
+      if (cached !== undefined) return cached;
+      const scope = " AND id=?";
+      const params = [peer, peer, taskId];
+      const counts = this.db.query(`WITH candidate AS (
+          SELECT history FROM tasks WHERE state NOT IN ('approved','cancelled') AND (owner=? OR reviewer=?)${scope} LIMIT 501
+        )
+        SELECT COUNT(*) AS tasks, COALESCE(SUM(length(CAST(history AS BLOB))),0) AS bytes,
+          SUM(CASE WHEN json_valid(history)<>1 THEN 1 ELSE 0 END) AS invalid FROM candidate`).get(...params) as { tasks: number; bytes: number; invalid: number };
+      let scoped = counts.tasks > 500 || counts.bytes > 16 * 1024 * 1024 || counts.invalid > 0;
+      if (!scoped) {
+        const comments = this.hasOpenReviewCommentsFor(peer, taskId);
+        const reviewerCommentScope = this.db.query(`WITH candidate AS (
+            SELECT id,created FROM tasks WHERE state='in_review' AND reviewer=?${scope} LIMIT 501
+          ) SELECT EXISTS(SELECT 1 FROM candidate JOIN review_comments AS comment ON comment.task_id=candidate.id AND comment.task_created=candidate.created
+            WHERE comment.lifecycle='sent') AS present`).get(peer, taskId) as { present: number };
+        const findings = this.db.query(`WITH candidate AS (
+            SELECT id,history FROM tasks WHERE state NOT IN ('approved','cancelled') AND (owner=? OR reviewer=?)${scope} LIMIT 501
+          )
+          SELECT EXISTS(SELECT 1 FROM candidate, json_each(candidate.history) AS history,
+            json_each(json_extract(history.value,'$.reviewFindings.items')) AS item
+            WHERE json_type(history.value,'$.reviewFindings.items')='array'
+              AND json_type(item.value,'$.anchor')='object') AS present`).get(...params) as { present: number };
+        scoped = comments || reviewerCommentScope.present === 1 || findings.present === 1;
+      }
+      this.reviewObserverScopeCache.set(cacheKey, scoped);
+      if (this.reviewObserverScopeCache.size > 512) this.reviewObserverScopeCache.delete(this.reviewObserverScopeCache.keys().next().value as string);
+      return scoped;
+    } catch { return true; }
+  }
+  reviewCommentResolution(task: Task, ids: readonly string[]): string[] {
+    const parsed = reviewCommentIds(ids), records = this.reviewComments(task.id, task.created);
+    return parsed.flatMap(id => {
+      const record = records.find(row => row.thread.id === id);
+      if (!record || record.lifecycle === "draft") throw new Error("only sent comments can be resolved; refresh the task review and use sent comment ids");
+      return record.lifecycle === "sent" ? [id] : []; // Dismissal is terminal and can never be reopened by the owner.
+    });
+  }
+  hasReviewCommentsState(): boolean {
+    return (this.db.query(`SELECT EXISTS(SELECT 1 FROM review_comments) OR EXISTS(SELECT 1 FROM review_comment_packages)
+      OR EXISTS(SELECT 1 FROM tasks AS task,json_each(task.history) AS history,json_each(json_extract(history.value,'$.reviewFindings.items')) AS finding
+        WHERE json_type(finding.value,'$.anchor')='object') AS present`).get() as { present: number }).present === 1;
+  }
+  reviewCommentsIntegrity(): { comments: number; packages: number; digest: string } {
+    return this.db.transaction(() => {
+      const digest = createHash("sha256").update("agent-hub.review-comments/v1\n"); let comments = 0, packages = 0;
+      for (const row of this.db.query("SELECT DISTINCT task_id,task_created FROM review_comments ORDER BY task_id,task_created").iterate() as Iterable<{ task_id: number; task_created: number }>) for (const record of this.reviewComments(row.task_id, row.task_created)) { digest.update(JSON.stringify(record)).update("\n"); comments++; }
+      for (const row of this.db.query("SELECT id,task_id,task_created,body FROM review_comment_packages ORDER BY id").iterate()) { digest.update(JSON.stringify(row)).update("\n"); packages++; }
+      return { comments, packages, digest: digest.digest("hex") };
+    })();
+  }
+
   hasResearchState(): boolean {
     return (this.db.query("SELECT EXISTS(SELECT 1 FROM research_campaigns) OR EXISTS(SELECT 1 FROM research_units) OR EXISTS(SELECT 1 FROM research_protocols) OR EXISTS(SELECT 1 FROM research_attempts) OR EXISTS(SELECT 1 FROM research_attempt_events) OR EXISTS(SELECT 1 FROM research_attempt_observations) OR EXISTS(SELECT 1 FROM research_runner_receipts) AS present").get() as { present: number }).present === 1;
   }
@@ -1421,7 +1754,7 @@ export class Board {
   }
   plannerWip(peer: string, except?: number): number {
     const row = this.db.query(`SELECT COUNT(*) AS n FROM tasks WHERE state NOT IN ('approved', 'cancelled', 'backlog') AND (? IS NULL OR id != ?) AND
-      (owner = ? OR (owner IS NULL AND state = 'proposed' AND reserved = ? AND
+      (owner = ? OR (owner IS NULL AND state = 'proposed' AND reserved = ? AND needs_person = 0 AND
         json_extract((SELECT value FROM json_each(tasks.history) WHERE json_extract(value, '$.event') IN ('backlog pulled', 'backlog returned') ORDER BY CAST(key AS INTEGER) DESC LIMIT 1), '$.planning.pull') = 1))`).get(except ?? null, except ?? null, peer, peer) as { n: number };
     return row.n;
   }
@@ -1435,7 +1768,7 @@ export class Board {
     const rows = this.db.query(`SELECT peer, kind, COUNT(*) AS n FROM (
       SELECT owner AS peer, CASE WHEN state = 'in_review' THEN 'reviewWait' ELSE 'active' END AS kind FROM tasks WHERE state NOT IN ('approved', 'cancelled', 'backlog') AND owner IS NOT NULL
       UNION ALL
-      SELECT reserved AS peer, 'reserved' AS kind FROM tasks WHERE state = 'proposed' AND owner IS NULL AND reserved IS NOT NULL AND
+      SELECT reserved AS peer, 'reserved' AS kind FROM tasks WHERE state = 'proposed' AND owner IS NULL AND reserved IS NOT NULL AND needs_person = 0 AND
         json_extract((SELECT value FROM json_each(tasks.history) WHERE json_extract(value, '$.event') IN ('backlog pulled', 'backlog returned') ORDER BY CAST(key AS INTEGER) DESC LIMIT 1), '$.planning.pull') = 1
     ) GROUP BY peer, kind`).all() as { peer: string; kind: "active" | "reviewWait" | "reserved"; n: number }[];
     const result: Record<string, { active: number; reviewWait: number; reserved: number }> = {};
@@ -1521,6 +1854,11 @@ export class Board {
   }
 
   /** Tasks per state, without parsing a single row: `status.json` is rewritten on every bus event and the board only grows. */
+  /** #1176: ids of open cards only the person can run, for status and the board (ids only, never text). Backlog first, then the rest, by id. */
+  personRunIds(): number[] {
+    return (this.db.query("SELECT id FROM tasks WHERE needs_person = 1 AND state NOT IN ('approved', 'cancelled') ORDER BY id").all() as { id: number }[]).map(row => row.id);
+  }
+
   counts(): Record<string, number> {
     const rows = this.db.query("SELECT state, COUNT(*) AS n FROM tasks GROUP BY state").all() as { state: string; n: number }[];
     return Object.fromEntries(rows.map((r) => [r.state, r.n]));
@@ -1528,7 +1866,8 @@ export class Board {
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
   /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "planner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "invocation" | "plannerReason" | "planAuthor" | "selfReview" | "profile" | "sweep" | "reason" | "from" | "capacity" | "conductorManual" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewScope" | "evidenceOnly" | "reviewedHead" | "reviewFindings" | "unmetCriteria" | "deliverables" | "checkKey" | "missingKeys" | "claim" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | "specReport" | "specRefBinding" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "planner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "invocation" | "plannerReason" | "planAuthor" | "selfReview" | "profile" | "sweep" | "reason" | "from" | "capacity" | "conductorManual" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewScope" | "evidenceOnly" | "reviewedHead" | "reviewFindings" | "unmetCriteria" | "deliverables" | "checkKey" | "missingKeys" | "claim" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | "specReport" | "specRefBinding" | "resolvedReviewComments" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
+    if (extra.resolvedReviewComments?.length && !this.db.inTransaction) return this.atomic(() => this.update(id, by, event, patch, note, extra, expectedFlowRevision, codeSymbolsAuthority));
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (expectedFlowRevision !== undefined && (!Number.isSafeInteger(expectedFlowRevision) || expectedFlowRevision < 0 || task.history.length !== expectedFlowRevision)) throw new Error("task flow revision changed");
@@ -1579,6 +1918,9 @@ export class Board {
       if (patch.state === "backlog" && task.owner) throw new Error(`task #${id}: owned work cannot return to backlog`);
     }
     if (patch.state === "backlog" && taskHasStarted(task) && !untouchedReturn) throw new Error(`task #${id}: started work cannot return to backlog`);
+    const requestedReviewComments = extra.resolvedReviewComments === undefined ? undefined : reviewCommentIds(extra.resolvedReviewComments);
+    if (requestedReviewComments?.length && (!["done", "done (checking)"].includes(event) || by !== task.owner || expectedFlowRevision === undefined)) throw new Error("comment resolution requires an admitted owner completion; use hub_task_done with sent comment ids");
+    const resolvedReviewComments = requestedReviewComments?.length ? this.reviewCommentResolution(task, requestedReviewComments) : undefined;
     const reviewMetadata = reviewerHistory(extra);
     let reviewFindings: ReviewFindingSet | undefined;
     if (extra.reviewFindings !== undefined) {
@@ -1612,8 +1954,13 @@ export class Board {
       && priorHead !== undefined && /^[a-f0-9]{40}$/.test(priorHead);
     const previousHistory = backfill ? task.history.map((entry, index) => index === priorApproval && !entry.reviewedHead
       ? { ...entry, reviewedHead: entry.reviewFindings?.head ?? priorHead } : entry) : task.history;
-    const history = [...previousHistory, { at: Date.now(), by, event, ...(returnPlanning ? { planning: returnPlanning } : {}), ...(extra.invocation ? { invocation: extra.invocation } : {}), ...plannerHistory, ...authorHistory, ...(extra.selfReview === true ? { selfReview: true as const } : {}), ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...specMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.conductorManual === true ? { conductorManual: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(extra.reviewedHead ? { reviewedHead: extra.reviewedHead } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewScope === "code" ? { reviewScope: "code" as const } : {}), ...(extra.evidenceOnly === true && event === "changes_requested" ? { evidenceOnly: true as const } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}), ...(["check passed", "check failed"].includes(event) && typeof extra.checkKey === "string" && /^[a-z][a-z0-9_]{0,47}$/.test(extra.checkKey) ? { checkKey: extra.checkKey } : {}), ...(["check passed", "check failed"].includes(event) && Number.isSafeInteger(extra.missingKeys) && extra.missingKeys! >= 0 && extra.missingKeys! <= 100_000 ? { missingKeys: extra.missingKeys } : {}), ...(event === "claim verdict" && extra.claim ? { claim: extra.claim } : {}) }];
+    const history = [...previousHistory, { at: Date.now(), by, event, ...(resolvedReviewComments?.length ? { resolvedReviewComments } : {}), ...(returnPlanning ? { planning: returnPlanning } : {}), ...(extra.invocation ? { invocation: extra.invocation } : {}), ...plannerHistory, ...authorHistory, ...(extra.selfReview === true ? { selfReview: true as const } : {}), ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...specMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.conductorManual === true ? { conductorManual: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(extra.reviewedHead ? { reviewedHead: extra.reviewedHead } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewScope === "code" ? { reviewScope: "code" as const } : {}), ...(extra.evidenceOnly === true && event === "changes_requested" ? { evidenceOnly: true as const } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}), ...(["check passed", "check failed"].includes(event) && typeof extra.checkKey === "string" && /^[a-z][a-z0-9_]{0,47}$/.test(extra.checkKey) ? { checkKey: extra.checkKey } : {}), ...(["check passed", "check failed"].includes(event) && Number.isSafeInteger(extra.missingKeys) && extra.missingKeys! >= 0 && extra.missingKeys! <= 100_000 ? { missingKeys: extra.missingKeys } : {}), ...(event === "claim verdict" && extra.claim ? { claim: extra.claim } : {}) }];
     this.taskWrite(() => {
+      if (resolvedReviewComments?.length) for (const record of this.reviewComments(task.id, task.created)) {
+        if (!resolvedReviewComments.includes(record.thread.id) || record.lifecycle !== "sent") continue;
+        const resolved: ReviewCommentRecord = { ...record, lifecycle: "resolved", revision: record.revision + 1 };
+        this.db.query("UPDATE review_comments SET body=?,lifecycle=?,revision=? WHERE task_id=? AND task_created=? AND id=?").run(JSON.stringify(resolved), resolved.lifecycle, resolved.revision, task.id, task.created, record.thread.id);
+      }
       const result = this.db.query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, updated = ?, planner = ?, planning_revision = ? WHERE id = ?")
         .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), planner, returnPlanning?.revision ?? task.planningRevision ?? 0, id);
       if (result.changes) {
@@ -1636,10 +1983,10 @@ export class Board {
     const next = { ...task, ...patch, sdlc: receipt ?? task.sdlc };
     if (next.plannedStart != null && next.due != null && next.plannedStart > next.due) throw new Error("planned start must not follow due");
     if (next.release != null && !this.release(next.release)) throw new Error("no such release");
-    const fields = Object.keys(patch) as (keyof PlanningFields)[], previous = Object.fromEntries(fields.map(key => [key, key === "sdlc" ? { repo: task.sdlc?.repo ?? null, issue: task.sdlc?.issue ?? null } : task[key] ?? (key === "pinned" ? false : key === "deps" ? [] : null)])) as PlanningFields;
+    const fields = Object.keys(patch) as (keyof PlanningFields)[], previous = Object.fromEntries(fields.map(key => [key, key === "sdlc" ? { repo: task.sdlc?.repo ?? null, issue: task.sdlc?.issue ?? null } : task[key] ?? (key === "pinned" || key === "needsPerson" ? false : key === "deps" ? [] : null)])) as PlanningFields;
     const now = Date.now(), entry: HistoryEntry = { at: now, by, event: "planned", planning: { revision: revision + 1, fields, previous }, ...(note ? { note } : {}), ...(withheld && note ? { withheld: true as const } : {}) };
-    const result = this.taskWrite(() => this.db.query(`UPDATE tasks SET rank=?, priority=?, "release"=?, planned_start=?, due=?, pinned=?, deps=?, reserved=?, planning_revision=planning_revision+1, history=?, updated=?, sdlc=? WHERE id=? AND planning_revision=?`)
-      .run(next.rank ?? null, next.priority ?? null, next.release ?? null, next.plannedStart ?? null, next.due ?? null, next.pinned ? 1 : 0, JSON.stringify(next.deps ?? []), next.reserved ?? null, JSON.stringify([...task.history, entry]), now, next.sdlc === undefined ? null : JSON.stringify(next.sdlc), id, revision));
+    const result = this.taskWrite(() => this.db.query(`UPDATE tasks SET rank=?, priority=?, "release"=?, planned_start=?, due=?, pinned=?, needs_person=?, deps=?, reserved=?, planning_revision=planning_revision+1, history=?, updated=?, sdlc=? WHERE id=? AND planning_revision=?`)
+      .run(next.rank ?? null, next.priority ?? null, next.release ?? null, next.plannedStart ?? null, next.due ?? null, next.pinned ? 1 : 0, next.needsPerson ? 1 : 0, JSON.stringify(next.deps ?? []), next.reserved ?? null, JSON.stringify([...task.history, entry]), now, next.sdlc === undefined ? null : JSON.stringify(next.sdlc), id, revision));
     if (result.changes !== 1) throw new Error("planning revision changed");
     const updated = this.get(id)!; this.changed(updated, entry); return updated;
   }
@@ -1692,6 +2039,8 @@ export class Board {
       // #334: the hub's own intake split is only ever for a draft. An approval clears the mark without moving the planning revision, so the revision alone cannot tell the
       // person approved the card while the model answered; checked here, in the same transaction as the write, nothing can slip between this and the children.
       if (requireDraft && !parent.draft) throw new Error("split changed or invalid");
+      // #1176: an agent's split of a person-run card, checked in the transaction so nothing slips in between the planner's check and the write.
+      if (by !== USER && parent.needsPerson) throw new Error("a person-run card is the person's to split");
       const children: Task[] = [];
       for (const part of parts) {
         const inherited = part.afterParts?.length ? (part.deps ?? []).filter(dep => !parent.deps?.includes(dep)) : part.deps ?? [];
@@ -1870,6 +2219,8 @@ function parse(row: Record<string, unknown>): Task {
   if (out.planning_revision) out.planningRevision = out.planning_revision;
   delete out.planning_revision;
   if (out.pinned) out.pinned = true; else delete out.pinned;
+  if (out.needs_person) out.needsPerson = true;
+  delete out.needs_person;
   if (out.draft) out.draft = true; else delete out.draft;
   for (const key of ["rank", "priority", "release", "due"]) if (out[key] == null) delete out[key];
   out.planner = row.planner ?? null;