@humwick/server 0.0.0-stage → 0.130.1

package/src/services/plan-import.ts

@@ -0,0 +1,66 @@
+import Ajv from "ajv";
+import { createHash } from "node:crypto";
+import { canonicalJson, errMessage, hasScope, isRecord, PLAN_IMPORT_DOCUMENT_SCHEMA } from "@humwick/sdk";
+import { getAgent, ValidationError } from "../db";
+import { getGateway } from "../db/gateway";
+import { planId } from "../db/plans";
+import { planTaskContext } from "../db/plan-graph";
+import { resolveActorIssueRepo } from "../agent-issue-repo";
+import { cleanString } from "../validation";
+import { emitPlanTaskEvents, cleanPlanAcceptance } from "./plan-conformance";
+import { emitPlan } from "./plan-graph";
+import { cleanTaskExecution } from "./plan-task-create";
+import { ServiceAuthError } from "./errors";
+import type { AuthContext } from "./auth-context";
+import type { PreparedPlanImport, PlanImportWriteResult } from "../db/plan-import";
+import type { PlanImportDocument, PlanImportResult } from "../types";
+
+const ajv = new Ajv({ allErrors: true });
+const validate = ajv.compile<PlanImportDocument>(PLAN_IMPORT_DOCUMENT_SCHEMA);
+const fingerprint = (value: unknown) => createHash("sha256").update(JSON.stringify(canonicalJson(value))).digest("hex");
+
+/** Both transports submit data, never server-side file paths or launch instructions. */
+export function preparePlanImport(input: Record<string, unknown>, ctx: AuthContext): PreparedPlanImport & { dryRun: boolean } {
+  for (const scope of ["plans:write", "task:write", "message:send"]) if (ctx.actor.kind !== "system" && !hasScope(ctx.scopes, scope)) throw new ServiceAuthError(`${scope} required for plan import`);
+  if (input.format !== "yaml" && input.format !== "json") throw new ValidationError("format must be yaml or json");
+  if (input.dryRun !== undefined && typeof input.dryRun !== "boolean") throw new ValidationError("dryRun must be boolean");
+  if (!Number.isSafeInteger(input.expectedVersion) || Number(input.expectedVersion) < 0) throw new ValidationError("expectedVersion must be 0 for create or the current plan version");
+  const requestKey = cleanString(input.requestKey, "requestKey", { required: true, max: 200 })!;
+  let parsed: unknown;
+  try { parsed = typeof input.document === "string" ? (input.format === "yaml" ? Bun.YAML.parse(input.document) : JSON.parse(input.document)) : structuredClone(input.document); }
+  catch (error) { throw new ValidationError(`IMPORT_PARSE_ERROR: ${errMessage(error)}`); }
+  if (!validate(parsed)) throw new ValidationError(`IMPORT_SCHEMA_INVALID: ${ajv.errorsText(validate.errors, { separator: "; " })}`);
+  const document = parsed;
+  document.acceptance = cleanPlanAcceptance(document.acceptance)!;
+  document.title = cleanString(document.title, "title", { required: true, max: 500 })!;
+  const seen = new Set<string>();
+  const executions: PreparedPlanImport["executions"] = {};
+  for (const task of document.tasks) {
+    if (seen.has(task.key)) throw new ValidationError(`IMPORT_DUPLICATE_KEY: duplicate task key ${task.key}`);
+    seen.add(task.key);
+    task.title = cleanString(task.title, `${task.key}.title`, { required: true, max: 500 })!;
+    task.intent = cleanString(task.intent, `${task.key}.intent`, { required: true, max: 1_000_000 })!;
+    const execution = cleanTaskExecution(task.execution, "build", true)!;
+    executions[task.key] = execution;
+    if (task.execution) task.execution = execution;
+  }
+  const actor = ctx.callerAgentId ?? ctx.actor.id;
+  const agent = getAgent(actor);
+  document.teamId ??= agent?.teamId;
+  const inherited = planTaskContext({ teamId: document.teamId, nodes: [], createdBy: actor });
+  document.projectId ??= inherited.projectId;
+  document.repo ??= inherited.repo ?? resolveActorIssueRepo(actor);
+  // Scope is independent of revision and provider attachment, so retries preserve Task identities.
+  const scope = JSON.stringify([document.teamId ?? null, document.projectId ?? null, document.repo ?? null, !document.teamId && !document.projectId && !document.repo ? actor : null]);
+  const documentHash = fingerprint(document);
+  return { document, executions, actor, scope, requestKey, expectedVersion: Number(input.expectedVersion), documentHash, requestHash: fingerprint({ documentHash, expectedVersion: input.expectedVersion }), newPlanId: planId(), dryRun: input.dryRun === true };
+}
+
+export async function importPlan(input: Record<string, unknown>, ctx: AuthContext): Promise<PlanImportResult> {
+  const { dryRun, ...args } = preparePlanImport(input, ctx);
+  if (dryRun) return await getGateway().read("planGraph.import.preview", args) as unknown as PlanImportResult;
+  const result = await getGateway().write("planGraph.import", args) as unknown as PlanImportWriteResult;
+  emitPlanTaskEvents(result.taskEvents);
+  if (result.plan) emitPlan(args.expectedVersion === 0 ? "plan.created" : "plan.changed", result.plan, args.actor);
+  return result.receipt;
+}

package/src/services/plan-live-bindings.ts

@@ -0,0 +1,139 @@
+import { getTeam, getTeamAsync } from "../db";
+import { getGateway } from "../db/gateway";
+import { subscribeRelayEvents, type RelayEvent } from "../events";
+import { routeNotification } from "../notification-router";
+import { updateBoundPlanNodesForAgent, updateBoundPlanNodesForAgentAsync, updateBoundPlanNodesFromAgent, updateBoundPlanNodesFromAgentAsync } from "./plan-graph";
+
+let unsubscribe: (() => void) | undefined;
+
+const GRACEFUL_EXIT_REASONS = new Set([
+  "transient-complete",
+  "shutdown",
+  "manual-stop",
+  "manual-restart",
+  "policy-deleted",
+  "task-complete",
+  "mcp-shutdown",
+  "http-shutdown",
+  "bus-shutdown",
+  "self-resume",
+  "self-resume-continuation",
+  "compact",
+  "clear",
+  "resume",
+  "restart",
+]);
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function isGracefulExitReason(reason: string | undefined): boolean {
+  if (!reason) return false;
+  return GRACEFUL_EXIT_REASONS.has(reason);
+}
+
+function agentIdFromEvent(event: RelayEvent): string | undefined {
+  return stringField(event.data.agentId) ?? stringField(event.data.id) ?? event.subject;
+}
+
+async function notifyBoundExit(event: RelayEvent, updatedPlans: Awaited<ReturnType<typeof updateBoundPlanNodesForAgentAsync>>): Promise<void> {
+  const agentId = agentIdFromEvent(event);
+  if (!agentId) return;
+  const reason = stringField(event.data.reason);
+
+  for (const plan of updatedPlans) {
+    if (!plan.teamId) continue;
+    const team = await getTeamAsync(plan.teamId);
+    const target = team?.coordinatorId ?? `team:${plan.teamId}`;
+    const blockedNodes = plan.nodes.filter((node) => node.statusSource === "bound" && node.ownerRef?.agentId === agentId && node.status === "blocked");
+    if (blockedNodes.length === 0) continue;
+    routeNotification({
+      type: "plan.bound_agent_exited",
+      scope: { agentId, planId: plan.id, teamId: plan.teamId },
+      recipients: [target],
+      message: {
+        subject: "Bound plan node blocked",
+        body: `Agent \`${agentId}\` exited${reason ? ` (${reason})` : ""}; blocked plan node(s) ${blockedNodes.map((node) => `\`${node.id}\``).join(", ")} in \`${plan.id}\`.`,
+        payload: { kind: "plan.bound_agent_exited", planId: plan.id, agentId, nodeIds: blockedNodes.map((node) => node.id), reason },
+        replyExpected: false,
+      },
+    });
+  }
+}
+
+let pending = Promise.resolve();
+
+function eventPlanStatus(event: RelayEvent): "pending" | "in-progress" | "landed" | "blocked" | undefined {
+  const status = stringField(event.data.status);
+  if (status === "busy") return "in-progress";
+  if (status === "idle" || status === "ready" || status === "blocked") return status === "blocked" ? "blocked" : "pending";
+  return undefined;
+}
+
+async function handlePlanBindingEventAsync(event: RelayEvent): Promise<void> {
+  if (event.type === "agent.status") {
+    const agentId = agentIdFromEvent(event);
+    if (agentId) await updateBoundPlanNodesFromAgentAsync(agentId, eventPlanStatus(event), event.source || "server");
+    return;
+  }
+  if (event.type === "branch.landed") {
+    const agentId = stringField(event.data.author);
+    if (agentId) await updateBoundPlanNodesForAgentAsync(agentId, "landed", event.source || "server");
+    return;
+  }
+  if (event.type === "agent.exited") {
+    const agentId = agentIdFromEvent(event);
+    if (!agentId) return;
+    if (isGracefulExitReason(stringField(event.data.reason))) return;
+    const updated = await updateBoundPlanNodesForAgentAsync(agentId, "blocked", event.source || "server");
+    await notifyBoundExit(event, updated);
+  }
+}
+
+function handlePlanBindingEvent(event: RelayEvent): void {
+  // The in-process backend exists only for legacy/unit tests. Keep its old synchronous reducer
+  // contract so these tests do not accidentally test scheduling; worker-backed production never
+  // takes this branch and has no event-loop SQLite access.
+  if (getGateway().stats.backend === "in-process") {
+    if (event.type === "agent.status") {
+      const agentId = agentIdFromEvent(event);
+      if (agentId) updateBoundPlanNodesFromAgent(agentId, event.source || "server");
+      return;
+    }
+    if (event.type === "branch.landed") {
+      const agentId = stringField(event.data.author);
+      if (agentId) updateBoundPlanNodesForAgent(agentId, "landed", event.source || "server");
+      return;
+    }
+    if (event.type === "agent.exited") {
+      const agentId = agentIdFromEvent(event);
+      if (!agentId || isGracefulExitReason(stringField(event.data.reason))) return;
+      const updated = updateBoundPlanNodesForAgent(agentId, "blocked", event.source || "server");
+      const reason = stringField(event.data.reason);
+      for (const plan of updated) {
+        if (!plan.teamId) continue;
+        const team = getTeam(plan.teamId);
+        const nodes = plan.nodes.filter((node) => node.statusSource === "bound" && node.ownerRef?.agentId === agentId && node.status === "blocked");
+        if (nodes.length) routeNotification({ type: "plan.bound_agent_exited", scope: { agentId, planId: plan.id, teamId: plan.teamId }, recipients: [team?.coordinatorId ?? `team:${plan.teamId}`], message: { subject: "Bound plan node blocked", body: `Agent \`${agentId}\` exited${reason ? ` (${reason})` : ""}; blocked plan node(s) ${nodes.map((node) => `\`${node.id}\``).join(", ")} in \`${plan.id}\`.`, payload: { kind: "plan.bound_agent_exited", planId: plan.id, agentId, nodeIds: nodes.map((node) => node.id), reason }, replyExpected: false } });
+      }
+      return;
+    }
+  }
+  // Event listeners are synchronous. Serialize the asynchronous aggregate submissions so an
+  // agent's rapid status sequence reaches the FIFO writer in event order.
+  pending = pending.then(() => handlePlanBindingEventAsync(event)).catch((error) => {
+    console.error("plan live binding update failed", error);
+  });
+}
+
+export function startPlanLiveBindings(): void {
+  if (unsubscribe) return;
+  unsubscribe = subscribeRelayEvents(handlePlanBindingEvent);
+}
+
+export function __resetPlanLiveBindingsForTests(): void {
+  unsubscribe?.();
+  unsubscribe = undefined;
+  pending = Promise.resolve();
+}

package/src/services/plan-task-create.ts

@@ -0,0 +1,80 @@
+// #3660 — one-call Task create: with `plan` membership or an `execution` recipe, relay_task_create and
+// POST /api/task-entities persist the Task, its recipe, dependencies and bound plan node in one writer
+// transaction (src/db/plan-task-create.ts). Defaults resolve once here; events go out only after COMMIT.
+import { WORKFLOW_AUTO_START_NAME, TASK_EXECUTION_STAGES, isRecord, workflowAutoStarts } from "@humwick/sdk";
+import { randomUUID } from "node:crypto";
+import { getTaskDetailAsync, ValidationError } from "../db";
+import { getGateway } from "../db/gateway";
+import { cleanIssueRefRelation } from "../db/task-issue-relation";
+import type { CreatePlanTaskArgs, CreatePlanTaskResult } from "../db/plan-task-create";
+import { cleanString, cleanStringArray, optionalEnum, type DependencyRef } from "../validation";
+import { emitPlanTaskEvents } from "./plan-conformance";
+import { emitPlan } from "./plan-graph";
+import { issueRepoForCreate, type CreateTaskEntityInput } from "./task-issue-link";
+import { parseWorkflowPins } from "./workflow-pins";
+import type { TaskDetail, TaskExecution, TaskIssueSource } from "../types";
+
+/** The transport's raw `execution` and `plan` fields, beside its already-cleaned create input. */
+export interface PlanTaskCreateExtras { dependsOn: Array<number | DependencyRef>; execution?: unknown; plan?: unknown; issueSource?: TaskIssueSource }
+
+/** Whether a create call takes the one-call aggregate rather than the plain Task create. */
+export function isPlanTaskCreate(args: { execution?: unknown; plan?: unknown; fromIssue?: unknown }): boolean {
+  return args.execution !== undefined || args.plan !== undefined || args.fromIssue !== undefined;
+}
+
+/** A recipe resolves once: explicit fields win; code work (the build-review Task types) defaults to build-review.
+ *  A plan member of another type gets no recipe, and its plan's start names it rather than inventing one. */
+export function cleanTaskExecution(value: unknown, dispatchType: string | undefined, member: boolean): TaskExecution | undefined {
+  if (value === undefined || value === null) {
+    return member && workflowAutoStarts(dispatchType) ? { workflow: WORKFLOW_AUTO_START_NAME } : undefined;
+  }
+  if (!isRecord(value)) throw new ValidationError("execution must be { workflow?, inputs?, pins? }");
+  const unknown = Object.keys(value).filter((key) => !["workflow", "inputs", "pins", "stage", "proof"].includes(key));
+  if (unknown.length) throw new ValidationError(`execution: unknown field ${unknown.join(", ")}; allowed: workflow, inputs, pins, stage, proof`);
+  const workflow = cleanString(value.workflow, "execution.workflow", { max: 120 }) ?? (workflowAutoStarts(dispatchType) ? WORKFLOW_AUTO_START_NAME : undefined);
+  if (!workflow) throw new ValidationError(`execution.workflow is required: a ${dispatchType ?? "untyped"} Task has no default workflow (only ${WORKFLOW_AUTO_START_NAME} for code work)`);
+  if (value.inputs !== undefined && !isRecord(value.inputs)) throw new ValidationError("execution.inputs must be an object");
+  const stage = value.stage === undefined ? undefined : optionalEnum(value.stage, "execution.stage", TASK_EXECUTION_STAGES);
+  let proof: TaskExecution["proof"];
+  if (value.proof !== undefined) {
+    if (!isRecord(value.proof) || Object.keys(value.proof).some((key) => !["command", "paths"].includes(key))) throw new ValidationError("execution.proof must be { command, paths? }");
+    proof = { command: cleanString(value.proof.command, "execution.proof.command", { required: true, max: 10000 })! };
+    const paths = cleanStringArray(value.proof.paths, "execution.proof.paths", { itemMax: 1000, maxItems: 100 });
+    if (paths) proof.paths = paths;
+  }
+  const pins = parseWorkflowPins(value.pins);
+  return { workflow, ...(stage ? { stage } : {}), ...(proof ? { proof } : {}), ...(value.inputs !== undefined ? { inputs: value.inputs as Record<string, unknown> } : {}), ...(pins && Object.keys(pins).length ? { pins } : {}) };
+}
+
+function cleanMembership(value: unknown): CreatePlanTaskArgs["plan"] {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError("plan must be { planId, nodeId? }");
+  const planId = cleanString(value.planId, "plan.planId", { required: true, max: 120 })!;
+  const nodeId = cleanString(value.nodeId, "plan.nodeId", { max: 120 });
+  return { planId, ...(nodeId ? { nodeId } : {}) };
+}
+
+export interface PlanTaskCreated { task: TaskDetail; plan?: { planId: string; nodeId: string; version: number } }
+
+export async function createPlanTaskAsync(input: CreateTaskEntityInput, extras: PlanTaskCreateExtras, options: { idempotencyKey?: string } = {}): Promise<PlanTaskCreated> {
+  const plan = cleanMembership(extras.plan);
+  const execution = cleanTaskExecution(extras.execution, input.dispatch?.type, Boolean(plan));
+  const relation = cleanIssueRefRelation(input.relation);
+  const defaultRepo = input.issueRefs?.length ? issueRepoForCreate(input) : undefined;
+  const { createdBy, issueRefs = [], relation: _relation, defaultRepo: _defaultRepo, ...fields } = input;
+  const args: CreatePlanTaskArgs = {
+    task: { ...fields, issueRefs: issueRefs.map((issue) => ({ issue, ...(relation ? { relation } : {}), ...(defaultRepo ? { defaultRepo } : {}) })) },
+    dependsOn: [...new Map(extras.dependsOn.map((dep) => typeof dep === "number" ? { taskId: dep } : dep).map((ref) => [ref.taskId, ref])).values()],
+    ...(execution ? { execution } : {}),
+    ...(plan ? { plan } : {}),
+    ...(extras.issueSource ? { issueSource: extras.issueSource } : {}),
+    actor: createdBy,
+  };
+  // The caller's key makes a retry return the first result instead of a second Task or node.
+  const result = await getGateway().write("planGraph.task.create", args, { idempotencyKey: options.idempotencyKey ?? randomUUID() }) as unknown as CreatePlanTaskResult;
+  emitPlanTaskEvents(result.taskEvents);
+  if (result.plan) emitPlan("plan.changed", result.plan, createdBy);
+  // A replay returns the first write's result; the receipt reads the Task as it is now.
+  const task = await getTaskDetailAsync(result.task.id) ?? result.task;
+  return { task, ...(result.plan && result.nodeId ? { plan: { planId: result.plan.id, nodeId: result.nodeId, version: result.plan.version } } : {}) };
+}

package/src/services/plan-terminal-refs.ts

@@ -0,0 +1,83 @@
+// #2520 — the ONE application seam for ref-driven plan-node terminal propagation. When a Task a
+// plan node is bound to reaches terminal success (status=done, or deliverable stage
+// landed-on-main/deploying/deployed), or a linked issue reaches closed-completed, the bound
+// node's stored status advances to `landed`. Every trigger site funnels through one of these two
+// twins so the propagation policy lives in exactly one place, backed by the single
+// `planGraph.refs.terminal.apply` writer primitive (the statusSource:"manual" override guard,
+// monotonic no-revert, archived-plan skip, and the fresh-snapshot CAS no-op guard all live in
+// the op body — see applyTerminalPlanRefsBody).
+import { applyTerminalPlanRefsAsync } from "../db/plan-graph-async";
+import { applyTerminalPlanRefsBody } from "../db/plan-graph";
+import { emitRelayEvent } from "../events";
+import { publishPlanConformanceNotice } from "./plan-conformance";
+import { errMessage } from "@humwick/sdk";
+import type { Plan } from "../types";
+
+const SOURCE = "plan-terminal-refs";
+
+export interface TerminalRefTrigger {
+  taskId?: number;
+  issueRefId?: string;
+  actor?: string;
+}
+
+function normalize(trigger: TerminalRefTrigger): { taskIds: number[]; issueRefIds: string[]; actor: string } {
+  return {
+    taskIds: trigger.taskId !== undefined ? [trigger.taskId] : [],
+    issueRefIds: trigger.issueRefId !== undefined ? [trigger.issueRefId] : [],
+    actor: trigger.actor ?? SOURCE,
+  };
+}
+
+function emitChanged(plans: Plan[], actor: string): void {
+  // The full plan.changed Relay event per returned plan, exactly like the bound-owner twin.
+  for (const plan of plans) {
+    emitRelayEvent({ type: "plan.changed", source: actor, subject: plan.id, data: { plan, actor } });
+    publishPlanConformanceNotice(plan);
+  }
+}
+
+/**
+ * Awaitable twin — the sanctioned path for async callers (HTTP, MCP tools, the land/issue lifecycle).
+ * Submitting through the gateway keeps the node mutation off the event loop.
+ *
+ * HIGH-1 (#2520 review) — a propagation failure degrades to warn-and-continue, so it
+ * can NEVER fail the already-durable task/issue write that
+ * triggered it (nor misreport a succeeded close as failed). Guarding here — once, at the choke
+ * every trigger site funnels through — instead of try/catch at each of the ~8 call sites keeps
+ * the contract unskippable and drift-free.
+ */
+export async function advanceTerminalPlanRefsAsync(trigger: TerminalRefTrigger): Promise<Plan[]> {
+  const { taskIds, issueRefIds, actor } = normalize(trigger);
+  if (taskIds.length === 0 && issueRefIds.length === 0) return [];
+  try {
+    const plans = (await applyTerminalPlanRefsAsync({ taskIds, issueRefIds, actor })).map((result) => result.plan);
+    emitChanged(plans, actor);
+    return plans;
+  } catch (error) {
+    console.warn(`plan-terminal-refs propagation failed (${trigger.taskId !== undefined ? `task ${trigger.taskId}` : trigger.issueRefId !== undefined ? `issue ${trigger.issueRefId}` : "trigger"}): ${errMessage(error)}`);
+    return [];
+  }
+}
+
+/**
+ * In-process twin for the synchronous seams that cannot await (src/bus.ts's WebSocket frame
+ * dispatcher → setTaskEntityStatus/setTaskEntityStage). Runs the SAME op body directly on the
+ * caller thread after its durable write; never fire-and-forget, so the work is synchronous. The
+ * per-plan write inside the body is fenced behind the bounded version-CAS retry
+ * (replacePlanNodeScoped), and a residual failure degrades to warn-and-continue exactly like the
+ * async twin — a propagation failure must never fail the durable status/stage write.
+ */
+export function advanceTerminalPlanRefs(trigger: TerminalRefTrigger): Plan[] {
+  const { taskIds, issueRefIds, actor } = normalize(trigger);
+  if (taskIds.length === 0 && issueRefIds.length === 0) return [];
+  try {
+    const results = applyTerminalPlanRefsBody({ taskIds, issueRefIds, actor }, Date.now());
+    const plans = results.map((result) => result.plan);
+    emitChanged(plans, actor);
+    return plans;
+  } catch (error) {
+    console.warn(`plan-terminal-refs propagation failed (${trigger.taskId !== undefined ? `task ${trigger.taskId}` : trigger.issueRefId !== undefined ? `issue ${trigger.issueRefId}` : "trigger"}): ${errMessage(error)}`);
+    return [];
+  }
+}

package/src/services/plan-wake-digest.ts

@@ -0,0 +1,88 @@
+import { coordinatedTeamIds } from "../db/coordinator-seat";
+import { getPlan, listPlansByTeam } from "../db/plans";
+import { getTask } from "../db/tasks";
+import { getIssueRef } from "../db/issue-refs";
+import { formatRelativeTime } from "../mcp/presentation";
+import { planResumeFrontier } from "./plan-frontier";
+import { projectPlanOverTasks } from "./task-plan-view";
+import type { Plan, PlanNode } from "../types";
+
+export const PLAN_WAKE_DIGEST_MAX_BYTES = 1024;
+const INTRO = "Open team Plans: keep plans current and drive acceptance; relay_decision only when really blocked. In-progress age = plan update age.";
+const MORE = "More plans/nodes: relay_plan_list; relay_plan_get mode=resume.";
+
+function compactText(value: string, maxBytes: number): string {
+  const text = value.slice(0, maxBytes).replace(/\s+/g, " ").trim();
+  if (Buffer.byteLength(value) <= maxBytes) return text;
+  let result = "";
+  let bytes = 0;
+  for (const char of text) {
+    const size = Buffer.byteLength(char);
+    if (bytes + size > maxBytes - 3) break;
+    result += char;
+    bytes += size;
+  }
+  return `${result}...`;
+}
+
+function nodeList(nodes: PlanNode[], render = (node: PlanNode) => compactText(node.id, 32)): string {
+  const listed = nodes.slice(0, 3).map(render).join(",");
+  return listed + (nodes.length > 3 ? `,+${nodes.length - 3}` : "");
+}
+
+/** Typed work refs only: missing, failed/canceled Tasks and uncompleted issues are not done. */
+function refsDone(node: PlanNode): boolean {
+  const { taskId, issueId } = node.refs ?? {};
+  if (!taskId && !issueId) return false;
+  if (taskId && getTask(Number(taskId))?.status !== "done") return false;
+  if (issueId) {
+    const issue = getIssueRef(issueId);
+    if (issue?.status !== "closed" || issue.closeReason !== "completed") return false;
+  }
+  return true;
+}
+
+function planLine(stored: Plan, now: number): string {
+  const plan = projectPlanOverTasks(stored);
+  const frontier = planResumeFrontier(plan);
+  const parts: string[] = [];
+  if (frontier.ready.length) parts.push(`ready: ${nodeList(frontier.ready)}`);
+  if (frontier.inProgress.length) {
+    const age = formatRelativeTime(plan.updatedAt, now).relative;
+    parts.push(`in-progress: ${nodeList(frontier.inProgress, node => {
+      const owner = node.ownerRef?.agentId ?? node.ownerRef?.policyName ?? node.ownerRef?.label ?? "unowned";
+      return `${compactText(node.id, 32)}@${compactText(owner, 48)} ${age}`;
+    })}`);
+  }
+  const stale = plan.nodes.filter(node => node.statusSource === "manual" && node.status !== "landed" && refsDone(node));
+  if (stale.length) parts.push(`refs done, node not landed: ${nodeList(stale)}`);
+  if (frontier.allLanded) parts.push(plan.completion === "done" ? "all landed: archive" : "all landed: relay_plan_conformance then archive");
+  if (frontier.blocked.length) parts.push(`blocked: ${nodeList(frontier.blocked)}`);
+  return `- ${compactText(plan.title ?? "Untitled", 56)} (${plan.id}): ${parts.join("; ") || "no ready nodes"}`;
+}
+
+/** Read live team ownership and stored DAGs; stop loading graphs once the injection budget is full. */
+export function renderPlanWakeDigest(agentId: string, now = Date.now()): string {
+  const lines: string[] = [];
+  let bytes = Buffer.byteLength(INTRO) + 1;
+  for (const teamId of coordinatedTeamIds(agentId)) {
+    let cursor: string | undefined;
+    do {
+      const page = listPlansByTeam(teamId, { limit: 8, cursor });
+      for (const summary of page.plans) {
+        const plan = getPlan(summary.id);
+        if (!plan) continue;
+        const line = planLine(plan, now);
+        if (bytes + Buffer.byteLength(line) + 1 + Buffer.byteLength(MORE) > PLAN_WAKE_DIGEST_MAX_BYTES) {
+          // A single large graph still gets its pointer; never silently omit the entire team.
+          if (!lines.length) lines.push(compactText(line, PLAN_WAKE_DIGEST_MAX_BYTES - bytes - Buffer.byteLength(MORE) - 1));
+          return [INTRO, ...lines, MORE].join("\n");
+        }
+        lines.push(line);
+        bytes += Buffer.byteLength(line) + 1;
+      }
+      cursor = page.nextCursor;
+    } while (cursor);
+  }
+  return lines.length ? [INTRO, ...lines].join("\n") : "";
+}

package/src/services/plan-wake-policy.ts

@@ -0,0 +1,12 @@
+// #3660 — plan wake policy at the workflow notice seam: a plan-owned run's start and its successful, CI-clean
+// result are quiet (the plan reports once after conformance). Its own module: workflow-effects imports it.
+import { isRecord } from "@humwick/sdk";
+import { getGateway } from "../db/gateway";
+import { planQuietsNotice } from "./plan-dispatch-policy";
+
+/** The plan that quiets this run's `started`/`result` notice, if any: the plan owning its Task (a slot or its audit). */
+export async function planQuietingRunNotice(taskId: number, kind: "started" | "result", ci?: { status?: unknown }): Promise<string | undefined> {
+  if (!planQuietsNotice(kind, ci)) return undefined;
+  const owner = await getGateway().read("planDispatch.owner", { taskId });
+  return isRecord(owner) && typeof owner.planId === "string" ? owner.planId : undefined;
+}

package/src/services/profile-trust.ts

@@ -0,0 +1,54 @@
+// #3636 — project trust edits without the dashboard: set a profile's review mode, acknowledge its
+// project hooks/MCP, approve an observed value. One seam for the HTTP routes and the MCP tool.
+import { ValidationError, type AgentProfile, type ProfileProjectReviewMode } from "@humwick/sdk";
+import { getAgentProfile, setAgentProfile, validateAgentProfile } from "../config-store";
+import type { ConfigEntry } from "../types";
+import type { ProjectTrustApproval, ProjectTrustCapability } from "../db/project-trust-approvals";
+import { approveProjectCapabilityReview, projectCellsHash } from "../project-trust";
+import { emitConfigChanged } from "../sse";
+
+export const PROJECT_TRUST_CAPABILITIES = ["hooks", "mcp"] as const satisfies readonly ProjectTrustCapability[];
+export const PROJECT_REVIEW_MODES = ["fingerprint", "commit", "none"] as const satisfies readonly ProfileProjectReviewMode[];
+
+export interface ProjectTrustUpdate {
+  review?: ProfileProjectReviewMode;
+  /** Capabilities to acknowledge against the updated project cells. */
+  ack?: ProjectTrustCapability[];
+}
+
+function existingProfile(name: string): ConfigEntry<AgentProfile> {
+  const entry = getAgentProfile(name);
+  if (!entry) throw new ValidationError(`agent profile "${name}" not found`);
+  return entry;
+}
+
+/** The profile with `update` applied. Acks hash the validated cells, so they match what the gate reads. */
+export function withProjectTrust(profile: AgentProfile, update: ProjectTrustUpdate, by: string, at = Date.now()): AgentProfile {
+  const project = profile.sources?.project;
+  if (!project) throw new ValidationError(`agent profile "${profile.name}" has no project sources to trust`);
+  const reviewed = update.review ? { ...project, trust: { scope: project.trust?.scope ?? "roots", review: update.review } } : project;
+  const validated = validateAgentProfile(profile.name, { ...profile, sources: { ...profile.sources, project: reviewed } }, { allowBuiltIn: true });
+  const cells = validated.sources!.project!;
+  const cellsHash = projectCellsHash(cells);
+  for (const capability of update.ack ?? []) {
+    const cell = cells[capability];
+    if (!cell?.enabled) throw new ValidationError(`agent profile "${profile.name}" does not enable project ${capability}; enable it before acknowledging`);
+    cell.ack = { by, at, cellsHash };
+  }
+  return validated;
+}
+
+export function updateProfileProjectTrust(name: string, update: ProjectTrustUpdate, by: string): ConfigEntry<AgentProfile> {
+  if (!update.review && !update.ack?.length) throw new ValidationError("nothing to update: pass review and/or ack");
+  const saved = setAgentProfile(withProjectTrust(existingProfile(name).value, update, by), by, { overrideBuiltIn: true });
+  emitConfigChanged(saved.namespace, saved.key, saved.version);
+  return saved;
+}
+
+/** Approve an observed `sha256:…` (fingerprint) or `commit:…` value; the mode follows the prefix. */
+export function approveProfileProjectTrust(input: { name: string; capability: ProjectTrustCapability; repoKey: string; value: string; by: string }): ProjectTrustApproval {
+  const profileName = existingProfile(input.name).value.name;
+  const mode = input.value.startsWith("commit:") ? "commit" : input.value.startsWith("sha256:") ? "fingerprint" : undefined;
+  if (!mode) throw new ValidationError(`approved value must start with "sha256:" or "commit:", as shown in the refusal`);
+  return approveProjectCapabilityReview({ profileName, repoKey: input.repoKey, capability: input.capability, mode, approvedValue: input.value, approvedBy: input.by });
+}

package/src/services/project-checkout-binding.ts

@@ -0,0 +1,65 @@
+import { getGateway } from "../db/gateway";
+import { isAbsolute, resolve } from "node:path";
+import { cleanString, isPathWithinBase, normalizeGitRemoteIdentity } from "@humwick/sdk";
+import { addProjectRootAsync, getOrchestratorAsync, resolveProjectAsync, resolveProjectForCwdAsync, rootsForProjectAsync, unbindProjectCheckoutAsync, unboundProjectRootsAsync } from "../db";
+import { unboundOnHost } from "../db/project-lifecycle";
+import { emitConfigChanged } from "../sse";
+import { ProjectOnboardingError } from "./project-onboarding";
+import { probeHostRepo } from "./spawn-repo-probe";
+
+/** Register only a host-attested existing checkout; never acquire or modify its files. */
+export async function bindProjectCheckout(ref: string, input: Record<string, unknown>) {
+  const project = await resolveProjectAsync(ref);
+  if (!project || project.scope !== "project") throw new ProjectOnboardingError("project-not-found", "Project not found.", 404);
+  if (project.status !== "active") throw new ProjectOnboardingError("project-archived", "Restore this project before binding a checkout.", 409);
+  const hostId = cleanString(input.orchestratorId, "orchestratorId", { required: true, max: 200 })!;
+  const host = await getOrchestratorAsync(hostId);
+  if (!host || host.status !== "online") throw new ProjectOnboardingError("host-offline", "Start this host's orchestrator before binding a checkout.", 409);
+  const path = cleanString(input.rootPath, "rootPath", { required: true, max: 4000 })!;
+  if (!isAbsolute(path) || !isPathWithinBase(path, host.baseDir) || resolve(path) === resolve(host.baseDir)) {
+    throw new ProjectOnboardingError("path-conflict", "rootPath must be an absolute checkout path within the host base directory.", 409);
+  }
+  const rootPath = resolve(path);
+  const roots = await rootsForProjectAsync(project.id);
+  const root = roots.find(root => root.rootPath === rootPath && root.remoteUrl) ?? roots.find(root => root.remoteUrl);
+  const remoteUrl = root?.remoteUrl ?? (project.issueRepo ? `https://github.com/${project.issueRepo}.git` : undefined);
+  if (!remoteUrl) throw new ProjectOnboardingError("path-conflict", "The project needs a registered origin URL before binding a checkout.", 409);
+  const probe = await probeHostRepo(host, rootPath, undefined, true);
+  if (probe.kind === "timeout" || probe.kind === "unavailable") throw new ProjectOnboardingError("probe-failed", `Host repository probe ${probe.kind}; no root was bound.`, 409);
+  if (probe.kind !== "present" || !probe.repoRoot || resolve(probe.repoRoot) !== rootPath) {
+    throw new ProjectOnboardingError("path-conflict", "rootPath must name an existing Git checkout root.", 409);
+  }
+  if (!probe.remoteIdentity || probe.remoteIdentity !== normalizeGitRemoteIdentity(remoteUrl)) {
+    throw new ProjectOnboardingError("path-conflict", "Checkout origin does not match the registered project origin.", 409);
+  }
+  const bound = await addProjectRootAsync(project.id, rootPath, { orchestratorId: host.id, remoteUrl, ref: root?.ref });
+  emitConfigChanged("projects", project.id, Date.now());
+  return { project, roots: bound };
+}
+
+/** Drop one host binding and keep every file: no refresh, placement or gates use that host root again
+ * until it is bound (#3634). No host round trip, so an offline host can be unbound. */
+export async function unbindProjectCheckout(ref: string, input: Record<string, unknown>) {
+  const project = await resolveProjectAsync(ref);
+  if (!project || project.scope !== "project") throw new ProjectOnboardingError("project-not-found", "Project not found.", 404);
+  const orchestratorId = cleanString(input.orchestratorId, "orchestratorId", { required: true, max: 200 })!;
+  const path = cleanString(input.rootPath, "rootPath", { required: true, max: 4000 })!;
+  if (!isAbsolute(path)) throw new ProjectOnboardingError("path-conflict", "rootPath must be an absolute checkout path.", 409);
+  const rootPath = resolve(path);
+  const roots = await unbindProjectCheckoutAsync(project.id, rootPath, orchestratorId);
+  if (!roots) throw new ProjectOnboardingError("checkout-not-found", `No checkout of ${project.slug} is bound at ${rootPath} on ${orchestratorId}.`, 404);
+  emitConfigChanged("projects", project.id, Date.now());
+  return { project, roots, unbound: { orchestratorId, rootPath }, filesKept: true };
+}
+
+/** Repair known roots before admission, including a shared path already bound on another host. */
+export async function bindSpawnProjectCheckout(cwd: string, orchestratorId: string, parentId: string | undefined, profile: string): Promise<void> {
+  if (!parentId || !await getGateway().read("spawnTree.requiresHostRoot", { parentId, profile })) return;
+  const project = await resolveProjectForCwdAsync(cwd);
+  if (!project) return;
+  const roots = (await rootsForProjectAsync(project.id)).filter(root => isPathWithinBase(cwd, root.rootPath));
+  if (roots.some(root => root.orchestratorId === orchestratorId)) return;
+  if (unboundOnHost(await unboundProjectRootsAsync(project.id), cwd, orchestratorId)) return; // an explicit unbind is never auto-repaired (#3634)
+  const root = roots.sort((a, b) => b.rootPath.length - a.rootPath.length)[0];
+  if (root) await bindProjectCheckout(project.id, { orchestratorId, rootPath: root.rootPath });
+}

package/src/services/project-checkout-enrollment.ts

@@ -0,0 +1,27 @@
+import type { Project, ProjectCheckoutEnrollment, ProjectCheckoutStatus, ProjectRoot } from "@humwick/sdk";
+import { getOrchestratorAsync, unboundProjectRootsAsync } from "../db";
+
+/** One eligibility decision for maintenance and the checkout read surfaces. */
+export async function projectCheckoutEnrollment(project: Project, roots: ProjectRoot[], checkouts: ProjectCheckoutStatus[]): Promise<ProjectCheckoutEnrollment[]> {
+  const hosts = new Map(await Promise.all([...new Set(roots.flatMap(root => root.orchestratorId ? [root.orchestratorId] : []))]
+    .map(async id => [id, await getOrchestratorAsync(id)] as const)));
+  const enrollments: ProjectCheckoutEnrollment[] = roots.map(root => {
+    const identity = { rootPath: root.rootPath, ...(root.orchestratorId ? { orchestratorId: root.orchestratorId } : {}) };
+    if (project.status !== "active") return { ...identity, disposition: "archived", reason: "Project archived; restore it before enrolling a checkout." };
+    if (!root.orchestratorId || !root.remoteUrl) return { ...identity, disposition: "ambiguous",
+      reason: !root.remoteUrl ? "Missing registered origin; register the project origin, then bind the existing checkout on its intended host."
+        : "Unknown host binding; bind the existing checkout on its intended host." };
+    if (hosts.get(root.orchestratorId)?.status !== "online") return { ...identity, disposition: "offline", reason: "Registered host unavailable; reconnect its orchestrator." };
+    return { ...identity, disposition: "eligible", reason: "Host-bound root eligible; refresh also requires the global switch and enabled project config." };
+  });
+  // An unbind newer than a removal still holds its host row, so it supersedes the removal receipt (#3634).
+  const unbound = await unboundProjectRootsAsync(project.id);
+  for (const checkout of checkouts) {
+    if (checkout.type !== "project.checkout.remove" || checkout.status !== "succeeded" || checkout.result?.action !== "removed"
+      || [...roots, ...unbound].some(root => root.rootPath === checkout.rootPath && root.orchestratorId === checkout.orchestratorId)) continue;
+    enrollments.push({ rootPath: checkout.rootPath, orchestratorId: checkout.orchestratorId, disposition: "removed",
+      reason: "Checkout removed explicitly; bind an existing checkout to enroll it again." });
+  }
+  for (const root of unbound) enrollments.push({ ...root, disposition: "unbound", reason: "Unbound explicitly; files kept. Bind the checkout again to enroll it." });
+  return enrollments;
+}