@staix/agent-hub 0.29.0 → 0.31.0

package/src/hub/review-comments.ts

@@ -0,0 +1,115 @@
+import type { ActionMeta, ReviewAnchor, ReviewThread } from "@staix/agent-console/contract";
+import { types } from "node:util";
+import { sanitize } from "./envelope.ts";
+import { parseReviewAnchor, type ReviewAnchorStatus as AnchorPlacement } from "./review-anchor.ts";
+
+export const REVIEW_COMMENT_LIMIT = 64;
+export const REVIEW_COMMENT_BODY_BYTES = 2048;
+export const REVIEW_PACKAGE_BYTES = 12000;
+export type ReviewCommentLifecycle = "draft" | "sent" | "resolved" | "dismissed";
+export interface ReviewCommentCounts { draft: number; sent: number; resolved: number; dismissed: number }
+export interface ReviewCommentRecord {
+  thread: ReviewThread; task: number; taskCreated: number; commit: string;
+  lifecycle: ReviewCommentLifecycle; revision: number; sentAt?: string; private: boolean;
+}
+export type ReviewCommentView = {
+  thread: ReviewThread; id?: never; task: number; commit: string; lifecycle: ReviewCommentLifecycle;
+  revision: number; sentAt?: string; placement: AnchorPlacement;
+} | { id: string; thread?: never; task: number; commit: string; lifecycle: ReviewCommentLifecycle;
+  revision: number; sentAt?: string; placement: { status: "unavailable" } };
+export interface ReviewCommentFence { task: number; taskCreated: number; flow: number; head?: string; owner: string | null }
+export interface ReviewCommentMutation { task: number; id: string; revision: number; lifecycle?: ReviewCommentLifecycle; deleted?: true }
+export interface ReviewCommentPackage {
+  task: number; taskCreated: number; id: string; ids: string[]; owner: string; head: string; at: string;
+  /** Immutable delivery payload. Missing on pre-recovery packages; those require explicit manual inspection. */
+  body?: string; envelopeId?: string; trace?: string; ts?: number; delivery?: "unconfirmed" | "queued"; publicationEvidenceVersion?: 1;
+  /** Ids whose quote/body were included in the immutable public envelope; absent on legacy packets. */
+  visibleIds?: string[];
+}
+export interface ReviewCommentPackageView { id: string; count: number; delivery: "queued" | "unconfirmed" | "unavailable" }
+export const emptyReviewCommentCounts = (): ReviewCommentCounts => ({ draft: 0, sent: 0, resolved: 0, dismissed: 0 });
+
+function fail(cause: string): never { throw new Error(`review comments ${cause}; refresh the task review and retry with a current bounded comment`); }
+export function reviewCommentFields(input: unknown, allowed: readonly string[]): Record<string, unknown> {
+  if (!input || typeof input !== "object" || Array.isArray(input) || types.isProxy(input) || ![Object.prototype, null].includes(Object.getPrototypeOf(input))
+    || Object.getOwnPropertySymbols(input).length) fail("request must be a plain object");
+  const descriptors = Object.getOwnPropertyDescriptors(input);
+  if (Object.entries(descriptors).some(([key, value]) => !allowed.includes(key) || !value.enumerable || !Object.hasOwn(value, "value"))) fail("request has unknown, hidden fields or accessors");
+  return Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, descriptor.value]));
+}
+export function reviewCommentNumber(value: unknown, name: string, minimum = 1): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum) fail(`${name} is invalid`);
+  return value;
+}
+export function reviewCommentId(value: unknown): string {
+  if (typeof value !== "string" || !/^comment-[a-f0-9-]{36}$/.test(value)) fail("id is invalid");
+  return value;
+}
+export function reviewCommentIds(value: unknown): string[] {
+  if (!Array.isArray(value) || types.isProxy(value) || Object.getPrototypeOf(value) !== Array.prototype || Object.getOwnPropertySymbols(value).length) fail("ids must be an inert array");
+  const descriptors = Object.getOwnPropertyDescriptors(value), length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+  if (!Number.isSafeInteger(length) || length < 0 || length > REVIEW_COMMENT_LIMIT || Object.keys(descriptors).some(key => key !== "length" && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= length))) fail("ids must be a bounded distinct list");
+  const ids: string[] = [];
+  for (let index = 0; index < length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) fail("ids cannot contain holes, hidden fields or accessors");
+    ids.push(reviewCommentId(descriptor.value));
+  }
+  if (new Set(ids).size !== ids.length) fail("ids must be distinct");
+  return ids;
+}
+export function reviewCommentHead(value: unknown): string {
+  if (typeof value !== "string" || !/^[a-f0-9]{40}$/.test(value)) fail("commit is not a full lowercase SHA");
+  return value;
+}
+export function reviewCommentBody(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) fail("body is empty or invalid");
+  const body = sanitize(value);
+  if (Buffer.byteLength(body, "utf8") > REVIEW_COMMENT_BODY_BYTES) fail("body exceeds 2048 UTF-8 bytes");
+  return body;
+}
+function authorText(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) fail("verified person identity is invalid");
+  const identity = sanitize(value);
+  if (Buffer.byteLength(identity, "utf8") > 512 || /[\p{Cc}\p{Cf}]/u.test(identity) || Buffer.from(identity).toString("utf8") !== identity) fail("verified person identity is invalid");
+  return identity;
+}
+export function reviewCommentAuthor(meta?: ActionMeta): string {
+  if (meta === undefined) return "local";
+  if (meta.via !== "console" || typeof meta.node !== "string" || !meta.node.trim()) fail("verified person identity is unavailable");
+  return authorText(meta.identity);
+}
+/** Private-path quotes are discarded, never converted into invented line/page coordinates. */
+export function privateReviewAnchor(anchor: ReviewAnchor): ReviewAnchor {
+  const selectors = anchor.selectors.filter(selector => selector.kind === "lineRange" || selector.kind === "structural");
+  if (!selectors.length) fail("private path needs an existing lineRange or structural selector");
+  return parseReviewAnchor({ ...anchor, selectors });
+}
+export function reviewThreadProjection(record: ReviewCommentRecord): ReviewThread {
+  return { ...record.thread, state: record.lifecycle === "resolved" || record.lifecycle === "dismissed" ? "resolved" : "open" };
+}
+/** Fixed storage validation; no stored body or parser cause is echoed on failure. */
+export function parseStoredReviewComment(input: unknown): ReviewCommentRecord {
+  try {
+    const row = reviewCommentFields(input, ["thread", "task", "taskCreated", "commit", "lifecycle", "revision", "sentAt", "private"]);
+    const thread = reviewCommentFields(row.thread, ["id", "anchor", "body", "author", "at"]);
+    const author = authorText(thread.author);
+    if (author !== thread.author) fail("stored author is not sanitized");
+    if (!["draft", "sent", "resolved", "dismissed"].includes(String(row.lifecycle)) || typeof row.private !== "boolean"
+      || typeof thread.author !== "string" || !thread.author || typeof thread.at !== "string" || !Number.isFinite(Date.parse(thread.at))
+      || row.sentAt !== undefined && (typeof row.sentAt !== "string" || !Number.isFinite(Date.parse(row.sentAt)))) fail("stored metadata is invalid");
+    if ((row.lifecycle === "sent" || row.lifecycle === "resolved") && row.sentAt === undefined) fail("stored sent time is missing");
+    return { task: reviewCommentNumber(row.task, "task"), taskCreated: reviewCommentNumber(row.taskCreated, "taskCreated", 0), commit: reviewCommentHead(row.commit),
+      lifecycle: row.lifecycle as ReviewCommentLifecycle, revision: reviewCommentNumber(row.revision, "revision"), private: row.private,
+      ...(row.sentAt === undefined ? {} : { sentAt: row.sentAt as string }), thread: { id: reviewCommentId(thread.id), anchor: parseReviewAnchor(thread.anchor), body: reviewCommentBody(thread.body), author, at: thread.at } };
+  } catch { throw new Error("review comment storage invalid; stop the hub and restore a trusted hub.db backup, then restart and retry"); }
+}
+export function renderReviewComment(record: ReviewCommentRecord, placement: AnchorPlacement, visible: boolean): string {
+  if (!visible) return `[${record.thread.id}] unavailable: this comment is kept on the board.`;
+  if (placement.status === "unavailable") return `[${record.thread.id}] unavailable: refresh the task review before using its text.`;
+  const { anchor } = record.thread;
+  const range = placement.status === "outdated" ? undefined : placement.range ?? anchor.selectors.find(selector => selector.kind === "lineRange");
+  const location = sanitize(anchor.path) + (range ? `:${range.startLine}-${range.endLine}` : "");
+  const quotes = anchor.selectors.filter(selector => selector.kind === "textQuote").map(selector => sanitize(selector.exact));
+  return [`[${record.thread.id}] ${location} (${placement.status}) at ${record.commit}`, ...quotes.map(quote => `> ${quote.replace(/\n/g, "\n> ")}`), sanitize(record.thread.body)].join("\n");
+}

package/src/hub/review-findings.ts

@@ -1,5 +1,7 @@
 import { types } from "node:util";
 import { sanitize } from "./envelope.ts";
+import { parseReviewAnchor } from "./review-anchor.ts";
+import type { ReviewAnchor } from "@staix/agent-console/contract";
 
 export interface ReviewFinding {
   id: string;
@@ -8,6 +10,7 @@ export interface ReviewFinding {
   path?: string;
   disposition: "open" | "fixed" | "false_positive" | "accepted";
   rationale?: string;
+  anchor?: ReviewAnchor;
 }
 export interface ReviewFindingSet { head?: string; items: ReviewFinding[] }
 export interface ReviewFindingTally { important: number; nit: number; openImportant: number; openNit: number; fixed: number; falsePositive: number; accepted: number }
@@ -19,7 +22,7 @@ function fields(raw: unknown): Record<string, PropertyDescriptor> {
     || ![Object.prototype, null].includes(Object.getPrototypeOf(raw)) || Object.getOwnPropertySymbols(raw).length) return fail("plain own-data finding required");
   const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
   if (Object.values(descriptors).some(field => !Object.hasOwn(field, "value") || !field.enumerable)) return fail("accessors and hidden fields refused");
-  if (Object.keys(descriptors).some(key => !["id", "pass", "severity", "path", "disposition", "rationale"].includes(key))) return fail("unknown finding field");
+  if (Object.keys(descriptors).some(key => !["id", "pass", "severity", "path", "disposition", "rationale", "anchor"].includes(key))) return fail("unknown finding field");
   return descriptors;
 }
 function text(raw: unknown, max: number, path: boolean): string {
@@ -50,8 +53,10 @@ export function parseReviewFindings(raw: unknown, options: { person: boolean; ma
     if (disposition !== "open" && disposition !== "fixed" && disposition !== "false_positive" && disposition !== "accepted") return fail("invalid finding disposition");
     const path = item.path ? text(item.path.value, 512, true) : undefined;
     const rationale = item.rationale ? text(item.rationale.value, 2048, false) : undefined;
+    const anchor = item.anchor ? parseReviewAnchor(item.anchor.value) : undefined;
+    if (path !== undefined && anchor && path !== anchor.path) return fail("path and anchor.path differ; use the same task-scoped file path");
     if (disposition === "accepted" && (!options.person || !rationale)) return fail("accepted findings require a person and rationale");
-    return { id, pass, severity, disposition, ...(path !== undefined ? { path } : {}), ...(rationale !== undefined ? { rationale } : {}) };
+    return { id, pass, severity, disposition, ...(path !== undefined ? { path } : {}), ...(rationale !== undefined ? { rationale } : {}), ...(anchor ? { anchor } : {}) };
   });
   if (result.filter(item => item.severity === "nit").length > options.maxNits) return fail("nit limit exceeded");
   if (Buffer.byteLength(JSON.stringify(result)) > MAX_BYTES) return fail("finding report exceeds 64 KiB");

package/src/hub/review-material.ts

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { extname, join } from "node:path";
+import { projectionPath, snapshotBytes, PROJECTED_DIFF_BYTES } from "./projected-diff.ts";
+import type { Repo } from "./snapshots.ts";
+import type { TextProjections } from "./text-projection.ts";
+
+export interface ReviewReadRequest { path: string; side?: "base" | "head" }
+export type ReviewMaterial =
+  | { state: "available"; path: string; side: "base" | "head"; text: string; rawHash: string; contentHash: string; projection?: { name: string; version: string } }
+  | { state: "unavailable"; path: string; side: "base" | "head" };
+export interface ReviewMaterialBatch { head: string; materials: ReviewMaterial[] }
+export interface ReviewMaterialOptions {
+  repo: Repo;
+  base: string;
+  head: string;
+  /** Trusted execution-root-relative scopes, prepared by the host, never enlarged from a read request. */
+  paths: readonly string[];
+  projections: Pick<TextProjections, "handles" | "projectBytes">;
+  deny?: readonly string[];
+  privatePath?: (path: string) => boolean;
+  nameable?: (text: string) => boolean;
+  /** Host-only clock for the shared call budget. */
+  now?: () => number;
+  /** An earlier operation deadline includes the host's head/scope preparation in the same 8 s budget. */
+  deadline?: number;
+}
+
+const MAX_FILES = 8, READ_MS = 8000;
+const hash = (bytes: Buffer) => createHash("sha256").update(bytes).digest("hex");
+
+/** Immutable Git material only. Create one reader per read/send operation so every side shares its budgets. */
+export function createReviewMaterialReader(options: ReviewMaterialOptions): { readonly head: string; read(path: string, side?: "base" | "head"): ReviewMaterial } {
+  const now = options.now ?? (() => performance.now()), deadline = Math.min(now() + READ_MS, options.deadline ?? Infinity);
+  const files = new Set<string>(), scopes = [...options.paths];
+  let presentationBytes = 0;
+  const remaining = () => deadline - now();
+  const allowed = (path: string, repoPath: string): boolean => {
+    try {
+      const deny = [...(options.deny ?? [])];
+      return !/[\p{Cc}\p{Cf}]/u.test(path) && projectionPath({ ...options.repo, prefix: "" }, path, deny)
+        && projectionPath(options.repo, repoPath, deny)
+        && scopes.some(scope => scope === "" || path === scope || path.startsWith(scope + "/"))
+        && (!options.privatePath || options.privatePath(path) === false) && (!options.nameable || options.nameable(path) === true);
+    } catch { return false; }
+  };
+  return {
+    head: options.head,
+    read(path, side = "head") {
+      const unavailable: ReviewMaterial = { state: "unavailable", path, side };
+      try {
+        if (typeof path !== "string" || (side !== "base" && side !== "head") || !Number.isFinite(deadline) || remaining() <= 0) return unavailable;
+        const repoPath = options.repo.prefix + path;
+        if (!allowed(path, repoPath) || !files.has(path) && files.size >= MAX_FILES) return unavailable;
+        files.add(path);
+        // The existing Git/converter ports use performance.now(); translate the host clock's remaining budget once per operation.
+        const bytes = snapshotBytes(options.repo, side === "base" ? options.base : options.head, repoPath, performance.now() + remaining());
+        if (!bytes || remaining() <= 0) return unavailable;
+        const rawHash = hash(bytes), file = join(options.repo.top, repoPath);
+        let text: string, projection: { name: string; version: string } | undefined;
+        if (options.projections.handles(file)) {
+          const converted = options.projections.projectBytes(file, bytes, performance.now() + remaining());
+          if (!converted || converted.inputHash !== rawHash || !/^[a-f0-9]{64}$/.test(converted.configHash)) return unavailable;
+          text = converted.text;
+          // This is the existing configured converter fingerprint, not a claimed upstream semantic version.
+          projection = { name: "text-projection:" + extname(path).toLowerCase(), version: converted.configHash };
+        } else text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        if (typeof text !== "string" || text.includes("\0") || remaining() <= 0 || !allowed(path, repoPath) || options.nameable && options.nameable(text) !== true) return unavailable;
+        const material: ReviewMaterial = { state: "available", path, side, text, rawHash, contentHash: projection ? hash(Buffer.from(text, "utf8")) : rawHash, ...(projection ? { projection } : {}) };
+        const size = Buffer.byteLength(JSON.stringify(material), "utf8");
+        if (presentationBytes + size > PROJECTED_DIFF_BYTES || remaining() <= 0) return unavailable;
+        presentationBytes += size;
+        return material;
+      } catch { return unavailable; }
+    },
+  };
+}

package/src/hub/routing.ts

@@ -422,7 +422,7 @@ export function plannerWalk(input: PlannerWalkInput): PlannerWalk {
  * prints its trace. `states`: effective bus states of attached peers (a peer that is not in the map is not attached).
  */
 export function assign(
-  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state" | "title" | "detail" | "refs" | "external" | "id" | "sdlc" | "history">>,
+  task: Pick<Task, "class" | "signals" | "reserved"> & Partial<Pick<Task, "state" | "title" | "detail" | "refs" | "external" | "id" | "sdlc" | "history" | "needsPerson">>,
   states: Record<PeerId, PeerState>,
   routing: Routing,
   opts: InstanceRoutingOptions & {
@@ -464,6 +464,8 @@ export function assign(
 ): Assignment {
   if (task.state === "cancelled" || task.state === "approved") return { trace: [`${task.state}: closed; not routed`] };
   if (task.state === "backlog") return { trace: ["backlog: not routed; pull into To Do first"] };
+  // #1176: a person-run leg is nobody's to take, whatever its reservation says (the reservation stays as the "who will run it" hint). A pure input, so `ahub route explain` reads the same line.
+  if (task.needsPerson) return { trace: [`person-run: only the person can run this leg${task.reserved ? ` (reserved for ${task.reserved} as a hint only)` : ""}; no agent is offered it`] };
   const instanceMode = hasInstances(opts);
   const policy = routing.classes[task.class];
   const trace: string[] = [`class ${task.class}${policy ? "" : " (no [classes] entry: only an explicit owner can take it)"}`, `signals: ${task.signals.join(", ") || "none"}`];

package/src/hub/settings.ts

@@ -85,6 +85,9 @@ export const SETTINGS: readonly SettingDef[] = [
   { key: "specs.review", group: "Switches", label: "Covering spec review", type: "enum", values: ["off", "report", "require"], store: "config", applies: "live", risk: "safe", path: ["specs", "review"] },
   { key: "approvals.notify", group: "Switches", label: "Desktop notice for a waiting approval", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["approvals", "notify"] },
   { key: "snapshots.enabled", group: "Switches", label: "Per-turn snapshots", type: "boolean", store: "config", applies: "live", risk: "safe", path: ["snapshots", "enabled"] },
+  // #1057: the worktree shelf. Both only choose what the shelf shows and when it raises one inbox alert; neither deletes anything, so they are safe and live.
+  { key: "worktrees.quiet_days", group: "Switches", label: "Worktrees: shelve one idle this many days (0 never)", type: "integer", min: 0, max: 3650, store: "config", applies: "live", risk: "safe", path: ["worktrees", "quiet_days"] },
+  { key: "worktrees.alert_over", group: "Switches", label: "Worktrees: inbox alert above this many settled (0 never)", type: "integer", min: 0, max: 100000, store: "config", applies: "live", risk: "safe", path: ["worktrees", "alert_over"] },
   { key: "coordination", group: "Switches", label: "Coordination of overlapping owners", type: "enum", values: ["advisory", "turn-free"], store: "config", applies: "next use", risk: "safe", path: ["coordination"] },
 ];
 

package/src/hub/task-sweep.ts

@@ -52,6 +52,8 @@ export function taskSweepConfig(input: unknown): TaskSweepConfig {
 /** Pure time/kind ladder; Tasks decides whether the responsible peer is available. */
 export function nextSweep(task: Task, config: TaskSweepConfig, now: number, ready = true): SweepRecord | undefined {
   if (!config.enabled || !Number.isFinite(now)) return undefined;
+  // #1176: a person-run leg waits on the person, so no idle step ever escalates it to an agent.
+  if (task.needsPerson) return undefined;
   const kind = task.state === "proposed" && task.owner ? "unaccepted-assignment"
     : task.state === "in_progress" && task.owner ? "idle-owner"
       : task.state === "in_review" && task.reviewer ? "review-pending" : task.state === "proposed" && !task.owner && !task.reviewer && ready ? "ready-unassigned" : undefined;