@humwick/server 0.130.1 → 0.130.3

package/src/db/schema.ts

@@ -1,3 +1,5 @@
+import { COMMAND_RETENTION_SCHEMA } from "./command-retention";
+import { TOKEN_USAGE_RETENTION_SCHEMA } from "./token-usage-retention";
 import { DURABLE_PAYLOAD_SCHEMA } from "./durable-payloads"; import { PLAN_IMPORT_SCHEMA_SQL } from "./plan-import-schema";
 import { PROJECT_ROOTS_SCHEMA } from "./project-root-schema";
 import { seedBuiltInTokenProfiles } from "../token-db";
@@ -25,7 +27,8 @@ import { resetLifecycleSeqSeed } from "./lifecycle-seq.ts";
 import { resetFannedSeq } from "../sse-outbox-cursor";
 import { dropLegacyContinuationArchiveIndex } from "./continuation-archive-search.ts";
 import { applyMigrations } from "./migrations.ts";
-import { PROMPT_TEMPLATES_SCHEMA_SQL, seedPromptTemplatesIfNeeded } from "./prompt-templates-schema";
+import { reconcileProviderModelSeed } from "./provider-model-seed"; import { PROMPT_TEMPLATES_SCHEMA_SQL, seedPromptTemplatesIfNeeded } from "./prompt-templates-schema";
+import { PROJECT_PROFILE_INSTRUCTIONS_SCHEMA_SQL } from "./project-profile-instructions";
 import { ensureLandingPhaseOneSchema } from "./landing-schema.ts";
 import { beginStartupPhase, timeStartupPhase } from "../startup-timing";
 import { resetMainConnectionWrites } from "./main-connection-writes";
@@ -552,6 +555,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_config_history_key ON config_history(namespace, key, version);
 
     ${PROMPT_TEMPLATES_SCHEMA_SQL}
+    ${PROJECT_PROFILE_INSTRUCTIONS_SCHEMA_SQL}
 
     -- Per-user settings (#391, epic #388). The user dimension the global \`config\` table lacks:
     -- the same \`(namespace, key)\` descriptor address resolves to a per-user value, keyed by the
@@ -844,6 +848,8 @@ export function initDb(path: string = "agent-relay.db"): Database {
       -- distinct from severity). Both optional; absent on claim-kind rows.
       tags TEXT,
       priority TEXT,
+      -- #3736 — paths[] (JSON array of repo-relative paths) a project spawn policy matches.
+      paths TEXT,
       -- #1535 WS1 — parent/epic tree edge: a task has at most one parent. Cycle-guarded
       -- in application code (src/db/task-entity.ts setTaskParent), the same way as the
       -- depends-on DAG below (#834 finding 7) — SQLite CHECK can't express acyclicity.
@@ -858,7 +864,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       -- gate-validated but does NOT arm a land (no ingress); the coordinator's clear (CAS on
       -- the held delivery's host-probed HEAD) promotes that exact delivery. Distinct from the
       -- permanent workspace landBlocked. Default 0 keeps every pre-#2518 Task unheld.
-      validation_items TEXT, terminal_stage TEXT, completed_at INTEGER,
+      validation_items TEXT, terminal_stage TEXT, completed_at INTEGER, on_deploy TEXT,
       review_hold INTEGER NOT NULL DEFAULT 0 CHECK (review_hold IN (0, 1)),
       -- #2862 durable owner: a coordinator role (coordinator:TEAM) or a human id, never an agent id.
       owner TEXT
@@ -867,6 +873,8 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
     CREATE INDEX IF NOT EXISTS idx_tasks_target ON tasks(target);
     CREATE INDEX IF NOT EXISTS idx_tasks_updated ON tasks(updated_at);
+    -- #3740: cover the integration aggregation without fetching task bodies/metadata.
+    CREATE INDEX IF NOT EXISTS idx_tasks_integration_stats ON tasks(coalesce(json_extract(metadata, '$.relayIntegrationName'), source), status, claimed_by, last_seen_at, updated_at, source);
     CREATE INDEX IF NOT EXISTS idx_tasks_message_status
       ON tasks(message_id, status)
       WHERE message_id IS NOT NULL;
@@ -958,7 +966,6 @@ export function initDb(path: string = "agent-relay.db"): Database {
       shutdown_requested_at INTEGER
     );
     CREATE INDEX IF NOT EXISTS idx_automation_runs_automation ON automation_runs(automation_id, created_at);
-    CREATE INDEX IF NOT EXISTS idx_automation_runs_status ON automation_runs(status);
     CREATE INDEX IF NOT EXISTS idx_automation_runs_task ON automation_runs(task_id);
 
     CREATE TABLE IF NOT EXISTS task_events (
@@ -1258,6 +1265,8 @@ export function initDb(path: string = "agent-relay.db"): Database {
     ${PLAN_IMPORT_SCHEMA_SQL};
     ${IDLE_DIGEST_SCHEMA_SQL};
     ${TASK_TOKEN_TOTALS_SCHEMA};
+    ${TOKEN_USAGE_RETENTION_SCHEMA};
+    ${COMMAND_RETENTION_SCHEMA};
     ${LONG_RUNNING_WORK_SCHEMA};
     ${SHIPPING_STATS_SCHEMA};
     ${OPERATOR_ACTIONS_SCHEMA};
@@ -1456,7 +1465,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
   ensureLandingPhaseOneSchema();
   // Vault catalog, environments and metadata upgrades share applyMigrations (#3561, #3562).
   timeStartupPhase("db.migrations", applyMigrations);
-  timeStartupPhase("db.prompt-seed", seedPromptTemplatesIfNeeded);
+  timeStartupPhase("db.prompt-seed", seedPromptTemplatesIfNeeded); timeStartupPhase("db.model-seed", reconcileProviderModelSeed);
   timeStartupPhase("db.token-profile-seed", seedBuiltInTokenProfiles);
 
   timeStartupPhase("db.planner-statistics", () => refreshPlannerStats(getDb()));

package/src/db/spawn-budget.ts

@@ -45,6 +45,11 @@ function observedTokens(agentIds: string[]): ObservedSubtreeSpend {
     COALESCE(SUM(usage_status IS NOT NULL), 0) AS unknownReports
     FROM session_token_usage WHERE agent_id IN (SELECT value FROM json_each(?))`)
     .get(ids) as { tokens: number; unknownReports: number };
+  const retired = getDb().query(`SELECT COALESCE(SUM(tokens), 0) AS tokens,
+    COALESCE(SUM(unknown_reports), 0) AS unknownReports FROM retired_token_usage_totals
+    WHERE agent_id IN (SELECT value FROM json_each(?))`).get(ids) as { tokens: number; unknownReports: number };
+  row.tokens += retired.tokens;
+  row.unknownReports += retired.unknownReports;
   const live = getDb().query(`SELECT COALESCE(SUM(status = 'busy'), 0) AS busyAgents,
     COALESCE(SUM(CASE WHEN json_valid(meta) THEN MAX(0, COALESCE(json_extract(meta, '$.unreportedTokenUsage'), 0)) ELSE 0 END), 0) AS unreportedReports
     FROM agents WHERE id IN (SELECT value FROM json_each(?))`)

package/src/db/spawn-delegation-state.ts

@@ -77,13 +77,20 @@ export function spawnDelegationState(agentId: string, launchProfile?: string) {
     participating: Boolean((ancestors?.length !== 1 || launchProfile === "sub-coordinator")
       && (grant || ownTeam?.parentTeamId || (rootTeam && hasPrivateTeams(rootTeam.id)))), enabled: grant?.enabled === true,
     grant, projectId: ancestors && ancestors.length > 1 ? delegatedProjectId(agentId) ?? projectIdForAgent(agent) : rootTeam?.projectId,
-    displaced: (ancestors ?? [agentId]).some(id => {
-      const ancestor = getAgent(id);
-      return isDisplacedSeat(id, ancestor?.teamId ?? seatTeam(id)?.id);
-    }),
+    displaced: displacedThroughDelegation(ancestors ?? [agentId]),
   };
 }
 
+/** The agent's own seat was claimed, or that of an ancestor it reaches only through delegated launches. An
+ * ordinary child is inherited by the claimant and keeps its standing (#3773). */
+function displacedThroughDelegation(ancestors: readonly string[]): boolean {
+  for (const id of ancestors) {
+    if (isDisplacedSeat(id, getAgent(id)?.teamId ?? seatTeam(id)?.id)) return true;
+    if (!delegatedLaunch(id)) return false;
+  }
+  return false;
+}
+
 /** Ordinary tokens avoid ancestry reads; private-team linkage survives grant removal. */
 export function participatesInSpawnDelegation(agentId: string): boolean {
   return Boolean(getDb().query(`WITH RECURSIVE lineage(id, depth) AS (

package/src/db/spawn-delegation.ts

@@ -5,8 +5,6 @@ import { getPersistedAgentRuntimeCard as getAgent } from "./agent-card-read";
 import { getDb, ValidationError } from "./connection";
 import { runnerSpawnGrantForAgent } from "../runtime-grant";
 import { optionalNonNegativeInt } from "../validation";
-import { sameHostIdentity } from "../utils";
-import { getOrchestrator } from "./orchestrators";
 import { stringValue } from "@humwick/sdk";
 import type { CreateCommandInput } from "../types";
 import { getLaunchFact } from "./launch-facts";
@@ -37,15 +35,7 @@ export function assertDelegatedSpawnTarget(input: CreateCommandInput) {
     return !agent || agent.status === "offline" || agent.meta?.lifecycleAction === "shutting-down";
   })) throw new ValidationError("SPAWN_SUBTREE_STOPPING: caller or ancestor has stopped");
   const projectId = delegatedProjectTarget(input, state);
-  const parentHost = stringValue(getAgent(parentId)?.machine);
-  const targetHost = stringValue(input.params?.orchestratorId);
-  if (parentHost && targetHost) {
-    // #3650: machine is the raw os.hostname() ("WBOX"); orchestrator identity is configured ("wbox"/"wbox-1").
-    const target = getOrchestrator(targetHost);
-    const sameHost = sameHostIdentity(parentHost, targetHost)
-      || (target && [target.id, target.hostname, target.agentId].some(identity => sameHostIdentity(identity, parentHost)));
-    if (!sameHost) throw new ValidationError("SPAWN_PROJECT_MISMATCH: delegated launches stay on their parent's host");
-  }
+  // #3769 — placement owns the host; delegatedProjectTarget checks its registered project checkout.
   if (state.depth === 1 && profile === "sub-coordinator") throw new ValidationError("SPAWN_DEPTH_EXCEEDED: sub-coordinators cannot delegate another coordinator");
   const workflow = Boolean(input.params?.workflowRunId);
   const grant = runnerSpawnGrantForAgent(parentId);

package/src/db/sql-audit-indexes.ts

@@ -44,6 +44,9 @@ export const SQL_AUDIT_INDEXES = [
   `CREATE INDEX IF NOT EXISTS idx_task_events_land_workspace ON task_events(json_extract(metadata, '$.workspaceId'))
     WHERE type = 'deliverable' AND json_extract(metadata, '$.land.requested') = 1`,
   LAND_WITHDRAWN_INDEX_SQL,
+  // #3779 spawnRequestId -> Task resolution (every register/land/deliver auth check): a full task_events scan blocked the loop.
+  `CREATE INDEX IF NOT EXISTS idx_task_events_spawn_request ON task_events(json_extract(metadata, '$.spawnRequestId'))
+    WHERE type = 'agent.spawn_requested'`,
   `CREATE INDEX IF NOT EXISTS idx_task_events_land_bound_workspace ON task_events(${LAND_WORKSPACE_EXPRESSION})
     WHERE type = 'deliverable' AND json_extract(metadata, '$.land.requested') = 1`,
   `CREATE INDEX IF NOT EXISTS idx_task_events_deliverable_workspace ON task_events(${LAND_WORKSPACE_EXPRESSION}, task_id)

package/src/db/stats-async.ts

@@ -1,4 +1,4 @@
-import { mainConnectionWrites } from "./main-connection-writes";
+import { mainConnectionBootWrites, mainConnectionWrites } from "./main-connection-writes";
 import { allWriterOps } from "./write-ops";
 import { assertMainThreadState } from "./main-thread-state";
 // Async reader-pool facades for DB-only stats. Health is a deliberate documented deferral: its
@@ -105,7 +105,7 @@ async function probeDatabaseLiveness(): Promise<HealthCheck> {
  * `readerBackend`/`writerBackend` plus reader-pool depth/in-flight/shed counts unconditionally (the
  * in-process backend's zeroed pool numbers ARE the "report that plainly" answer, not a special case).
  */
-function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
+export function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
   const reader = stats.reader;
   const readerActive = reader.backend !== "uninitialized";
   const wedged = stats.writer.wedged;
@@ -117,9 +117,11 @@ function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
   const detail = [
     `writer=${stats.writerBackend}`,
     `reader=${stats.readerBackend}`,
-    `onLoopOps=${specs.length - offLoop}; writerThreadOps=${offLoop}`,
+    // #3798 — the op split counts executed writes; the registered op definitions are named as such.
+    `onLoopOps=${stats.writer.onLoopOps}; writerThreadOps=${stats.writer.writerThreadOps}`,
+    `opDefinitions onLoop=${specs.length - offLoop} offLoop=${offLoop}`,
     `mainConnectionWrites1h=${JSON.stringify(writes)}`,
-    ...(wedged ? ["writer wedged"] : []),
+    ...(wedged ? [`writer wedged: op ${wedged.op} running ${Math.round(wedged.runningMs / 1000)}s`] : []),
     ...(shedCount > 0 ? [`${shedCount} reader shed(s)`] : []),
   ].join("; ");
   return {
@@ -128,9 +130,10 @@ function buildDbGatewayCheck(stats: DbGatewayStats): HealthCheck {
     deployRole: "load",
     detail,
     metrics: {
-      onLoopOps: specs.length - offLoop,
-      writerThreadOps: offLoop,
+      onLoopOps: stats.writer.onLoopOps,
+      writerThreadOps: stats.writer.writerThreadOps,
       mainConnectionWrites1h: Object.values(writes).reduce((sum, count) => sum + count, 0),
+      mainConnectionBootWrites: mainConnectionBootWrites(),
       writerQueued: stats.writer.queued,
       writerBusy: stats.writer.busy,
       writerHighWater: stats.writer.highWater,

package/src/db/task-entity.ts

@@ -37,6 +37,7 @@ import {
   type TaskStatus,
 } from "../types";
 import { parseJson } from "../utils";
+import { repoRelativePath } from "@humwick/sdk/spawn-policy";
 import { cleanEnum, cleanStringArray, optionalEnum } from "../validation";
 import { getDb, writeTransaction, ValidationError } from "./connection.ts";
 import { ownerForNewTask } from "./task-owner.ts";
@@ -108,6 +109,16 @@ function cleanTags(value: unknown, field = "tags"): string[] | undefined {
   return cleanStringArray(value, field, { itemMax: 60, maxItems: 30 });
 }
 
+/** #3736 — repo-relative, normalized; a path that leaves the repo is refused. Stored null when empty. */
+function taskPathsColumn(value: unknown): string | null {
+  const paths = (cleanStringArray(value, "paths", { itemMax: 300, maxItems: 50 }) ?? []).map((path, i) => {
+    const rel = repoRelativePath(path);
+    if (rel === undefined) throw new ValidationError(`paths[${i}] must be a repo-relative path inside the repo`);
+    return rel;
+  });
+  return paths.length ? JSON.stringify([...new Set(paths)]) : null;
+}
+
 // #1535 WS3 — backlog lifecycle state. Optional (like priority): absent stays undefined so a
 // non-backlog task's column is NULL; a present-but-invalid value throws rather than silently
 // dropping. The backlog→promoted flip is a distinct writer (setTaskBacklogState in db/backlog.ts).
@@ -196,6 +207,7 @@ export interface CreateDeliverableTaskInput {
   complexity?: TaskComplexity;
   context?: string;
   terminalStage?: Task["terminalStage"];
+  onDeploy?: string;
   doneWhen?: string; branch?: string;
   teamId?: string;
   projectId?: string;
@@ -206,6 +218,7 @@ export interface CreateDeliverableTaskInput {
   latestSteer?: string;
   dispatch?: TaskDispatch;
   tags?: string[];
+  paths?: string[];
   priority?: TaskPriority;
   /** #1535 WS3 — seed the task directly into the backlog (`backlog`) so it shows up in the
    * prioritized backlog query until promoted. Absent ⇒ not backlog-managed. */
@@ -225,6 +238,7 @@ export function createDeliverableTaskBody(input: CreateDeliverableTaskInput, now
   const intent = requireText(input.intent, "intent", 1_000_000);
   const dispatch = cleanTaskDispatch(input.dispatch);
   const complexity = cleanTaskComplexity(input.complexity ?? dispatch?.complexity, "complexity") ?? DEFAULT_TASK_COMPLEXITY;
+  const onDeploy = optionalText(input.onDeploy, "onDeploy", 500);
   const context = optionalText(input.context, "context", 1_000_000);
   const branch = optionalText(input.branch, "branch", 500);
   const taskProject = cleanTaskProject(input);
@@ -237,8 +251,8 @@ export function createDeliverableTaskBody(input: CreateDeliverableTaskInput, now
     INSERT INTO tasks (
       source, title, body, severity, status, target, occurrence_count, metadata,
       created_at, updated_at, last_seen_at,
-      kind, intent, complexity, context, latest_steer, deliverable_stage, done_when, branch, team_id, project_id, repo, created_by, dispatch, tags, priority, backlog_state, owner
-    ) VALUES (?, ?, ?, 'info', 'open', ?, 1, '{}', ?, ?, ?, '${DELIVERABLE_TASK_KIND}', ?, ?, ?, ?, 'none', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      kind, intent, complexity, context, latest_steer, deliverable_stage, done_when, branch, team_id, project_id, repo, created_by, dispatch, tags, paths, priority, backlog_state, owner, on_deploy
+    ) VALUES (?, ?, ?, 'info', 'open', ?, 1, '{}', ?, ?, ?, '${DELIVERABLE_TASK_KIND}', ?, ?, ?, ?, 'none', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     optionalText(input.source, "source", 200) ?? "coordinator",
     title,
@@ -254,9 +268,11 @@ export function createDeliverableTaskBody(input: CreateDeliverableTaskInput, now
     createdBy,
     dispatch ? JSON.stringify(dispatch) : null,
     tags.length ? JSON.stringify(tags) : null,
+    taskPathsColumn(input.paths),
     priority ?? null,
     backlogState ?? null,
     ownerForNewTask(createdBy, teamId),
+    onDeploy ?? null,
   );
   const id = Number(result.lastInsertRowid);
   if (input.terminalStage) getDb().query("UPDATE tasks SET terminal_stage = ? WHERE id = ?").run(input.terminalStage, id);
@@ -282,6 +298,7 @@ export interface UpdateDeliverableTaskInput {
   complexity?: TaskComplexity;
   context?: string;
   latestSteer?: string;
+  onDeploy?: string;
   doneWhen?: string;
   dispatch?: TaskDispatch;
   teamId?: string;
@@ -290,6 +307,8 @@ export interface UpdateDeliverableTaskInput {
   actor?: string;
   /** Absent ⇒ untouched. `[]` (or `null`) ⇒ clear all tags. */
   tags?: string[] | null;
+  /** Absent ⇒ untouched. `[]` (or `null`) ⇒ clear all paths. */
+  paths?: string[] | null;
   /** Absent ⇒ untouched. `null` ⇒ clear (priority has no default, unlike complexity). */
   priority?: TaskPriority | null;
 }
@@ -309,6 +328,7 @@ export function updateDeliverableTaskBody(id: number, input: UpdateDeliverableTa
   if (input.complexity !== undefined) push("complexity", cleanTaskComplexity(input.complexity) ?? null);
   if (input.context !== undefined) push("context", optionalText(input.context, "context", 1_000_000) ?? null);
   if (input.latestSteer !== undefined) push("latest_steer", optionalText(input.latestSteer, "latestSteer", 1_000_000) ?? null);
+  if (input.onDeploy !== undefined) push("on_deploy", optionalText(input.onDeploy, "onDeploy", 500) ?? null);
   if (input.doneWhen !== undefined) push("done_when", optionalText(input.doneWhen, "doneWhen", 1_000_000) ?? null);
   if (input.teamId !== undefined) push("team_id", optionalText(input.teamId, "teamId", 200) ?? null);
   if (input.projectId !== undefined || input.repo !== undefined) {
@@ -321,6 +341,7 @@ export function updateDeliverableTaskBody(id: number, input: UpdateDeliverableTa
     const tags = input.tags === null ? [] : (cleanTags(input.tags) ?? []);
     push("tags", tags.length ? JSON.stringify(tags) : null);
   }
+  if (input.paths !== undefined) push("paths", taskPathsColumn(input.paths ?? []));
   if (input.terminalStage !== undefined) push("terminal_stage", input.terminalStage === null ? null : cleanTaskTerminalStage(input.terminalStage));
   if (input.priority !== undefined) push("priority", input.priority === null ? null : requireTaskPriority(input.priority));
   if (sets.length > 0) {
@@ -1064,14 +1085,15 @@ export function deliverableTaskIdsByOwnerAgent(agentId: string): number[] {
 // event (recorded BEFORE the child registers) carries the spawnRequestId. The landing worker's
 // `meta.spawnRequestId` resolves back through it to the Task. Returns every matching task id so a
 // reused spawnRequestId can't silently drop a link.
+export const TASK_IDS_BY_SPAWN_REQUEST_SQL = `SELECT DISTINCT te.task_id AS id FROM task_events te INDEXED BY idx_task_events_spawn_request
+            JOIN tasks t ON t.id = te.task_id AND t.kind = '${DELIVERABLE_TASK_KIND}'
+            WHERE te.type = 'agent.spawn_requested' AND json_extract(te.metadata, '$.spawnRequestId') = ?
+            ORDER BY te.task_id ASC`;
 export function deliverableTaskIdsBySpawnRequestId(spawnRequestId: string): number[] {
   const cleaned = spawnRequestId?.trim();
   if (!cleaned) return [];
   return (getDb()
-    .query(`SELECT DISTINCT te.task_id AS id FROM task_events te
-            JOIN tasks t ON t.id = te.task_id AND t.kind = '${DELIVERABLE_TASK_KIND}'
-            WHERE te.type = 'agent.spawn_requested' AND json_extract(te.metadata, '$.spawnRequestId') = ?
-            ORDER BY te.task_id ASC`)
+    .query(TASK_IDS_BY_SPAWN_REQUEST_SQL)
     .all(cleaned) as Array<{ id: number }>)
     .map((r) => r.id);
 }

package/src/db/task-list.ts

@@ -41,7 +41,8 @@ function buildDeliverableTasksWhere(filter: ListDeliverableTasksFilter): { claus
   }
   if (filter.staleOwnerGone) conditions.push(STALE_TASK_OWNER_SQL);
   if (filter.status) { conditions.push("status = ?"); params.push(filter.status); }
-  if (filter.deliverableStage) { conditions.push("deliverable_stage = ?"); params.push(filter.deliverableStage); }
+  if (filter.deliverableStage === "awaiting-deploy") conditions.push("deliverable_stage IN ('landed-on-main', 'deploying')");
+  else if (filter.deliverableStage) { conditions.push("deliverable_stage = ?"); params.push(filter.deliverableStage); }
   if (filter.teamId) { conditions.push("team_id = ?"); params.push(filter.teamId); }
   if (filter.createdBy) { conditions.push("created_by = ?"); params.push(filter.createdBy); }
   if (filter.ownerAgentId) { conditions.push("owner_agent_id = ?"); params.push(filter.ownerAgentId); }
@@ -87,6 +88,7 @@ function taskListItem(task: Task): TaskListItem {
     status: task.status,
     kind: task.kind,
     ...(task.validationItems ? { validationItems: task.validationItems } : {}),
+    ...(task.onDeploy ? { onDeploy: task.onDeploy } : {}),
     ...(task.terminalStage ? { terminalStage: task.terminalStage } : {}),
     ...(task.completedAt ? { completedAt: task.completedAt } : {}),
     ...(task.staleOwnerGone ? { staleOwnerGone: true } : {}),

package/src/db/tasks.ts

@@ -1,19 +1,5 @@
 import { taskVisibilitySql, type ViewerScope } from "./viewer-scope";
-import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
-import { parseJson } from "../utils";
-import { isLiveIsolatedWorkspace } from "../workspace-phase";
-import {
-  CONTRACT_REQUIREMENTS,
-  contractCompatibility,
-  parseRuntimeCapabilities,
-  parseRuntimeContracts,
-  parseRuntimePackage,
-  type RuntimeContracts,
-} from "../contracts";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
-import { matchAgents } from "../agent-ref";
+import { CLAIM_LEASE_MS } from "../config";
 import { getAgent, validateAgentSession } from "./agents.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { ClaimError, getDb, writeTransaction } from "./connection.ts";
@@ -51,7 +37,6 @@ export function taskMessageBody(task: Pick<Task, "id" | "source" | "severity" |
   return lines.join("\n");
 }
 
-
 export function getTask(id: number): Task | null {
   const row = getDb().query(`${TASK_SELECT} WHERE id = ?`).get(id) as any;
   return row ? rowToTask(row) : null;
@@ -85,7 +70,6 @@ export function listTasks(filter?: { viewer?: ViewerScope | null; status?: strin
   return (getDb().query(`${TASK_SELECT} ${where} ORDER BY updated_at DESC LIMIT ?`).all(...params) as any[]).map(rowToTask);
 }
 
-
 /** Deliverable stages meaning the work already left the worker's hands (#2036): a Task sitting in
  *  `in_progress` while its land gate runs is not a stalled worker. Excluded IN SQL, not after the
  *  fact — these rows carry the OLDEST claims, so a post-LIMIT filter would let them consume the

package/src/db/team-claim-policy.ts

@@ -0,0 +1,60 @@
+import { STALE_TTL_MS } from "../config";
+import { getAgent } from "./agents";
+import { countLiveTeamMembers, getTeam, claimTeamWithAdoption, isClaimableTeam } from "./teams";
+import type { Team } from "../types";
+export class TeamAuthError extends Error {}
+export class TeamNotFoundError extends Error {}
+function lineageRootForAgent(agentId: string): string | undefined {
+  let current = getAgent(agentId);
+  const seen = new Set<string>();
+  while (current) {
+    if (seen.has(current.id)) return undefined;
+    seen.add(current.id);
+    if (!current.spawnedBy) return current.id;
+    current = getAgent(current.spawnedBy);
+  }
+  return undefined;
+}
+
+function coordinatorIsLive(team: Team): boolean {
+  if (!team.coordinatorId) return false;
+  const coordinator = getAgent(team.coordinatorId);
+  if (!coordinator || coordinator.status === "offline") return false;
+  if (coordinator.teamId === team.id) return countLiveTeamMembers(team.id, Date.now() - STALE_TTL_MS) > 0;
+  return coordinator.lastSeen > Date.now() - STALE_TTL_MS;
+}
+
+/** How a claim was authorized — carried into the audit trail so an orphan takeover is
+ * distinguishable from a routine same-lineage reclaim. */
+export type TeamClaimMode = "admin" | "same-lineage" | "orphan-takeover";
+
+// #1454 — live owners require same-lineage authority; dead owners permit orphan takeover.
+
+function assertCanClaimTeam(admin: boolean, team: Team, callerAgentId: string): TeamClaimMode {
+  const caller = getAgent(callerAgentId);
+  const callerTeam = caller?.teamId ? getTeam(caller.teamId) : null;
+  if (!admin && callerTeam?.parentTeamId && team.id !== callerTeam.id) {
+    throw new TeamAuthError("a sub-coordinator may claim only its own private team");
+  }
+  const callerRoot = lineageRootForAgent(callerAgentId);
+  const teamRoot = team.rootCoordinatorId ?? team.coordinatorId;
+  // Same-lineage reclaim is the routine fast path (a replacement spawned under the original
+  // founder) and stays allowed regardless of owner liveness.
+  if (callerRoot && teamRoot && callerRoot === teamRoot) return "same-lineage";
+  if (admin) return "admin";
+  // #1454 orphan takeover: a replacement coordinator of a DIFFERENT lineage may adopt the team only
+  // when its owning coordinator is not live (offline, or stale past the heartbeat TTL). This is the
+  // sole security boundary for the cross-lineage path — a healthy owner is never displaced.
+  if (!coordinatorIsLive(team)) return "orphan-takeover";
+  throw new TeamAuthError(`caller ${callerAgentId} cannot claim team ${team.id}`);
+}
+
+
+export function claimAuthorizedTeam(teamId: string, agentId: string, admin: boolean) {
+  if (!isClaimableTeam(getTeam(teamId))) throw new TeamNotFoundError(`active team ${teamId} not found`);
+  let captured: { mode: TeamClaimMode; priorCoordinatorId: string | null } | undefined;
+  const result = claimTeamWithAdoption(teamId, agentId, team => {
+    captured = { mode: assertCanClaimTeam(admin, team, agentId), priorCoordinatorId: team.coordinatorId ?? null };
+  });
+  return { ...result, ...captured! };
+}

package/src/db/teams-async.ts

@@ -56,3 +56,7 @@ export function setTeamBriefAsync(input: Parameters<typeof setTeamBrief>[0]): Pr
 export function dissolveTeamAsync(teamId: string, input?: Parameters<typeof dissolveTeam>[1], requestId: string = randomUUID()): Promise<ReturnType<typeof dissolveTeam>> {
   return getGateway().write("teams.dissolve", { teamId, input }, { idempotencyKey: requestId }) as unknown as Promise<ReturnType<typeof dissolveTeam>>;
 }
+
+export function ensureTeamAsync(agentId: string, opts: { projectId?: string } = {}): Promise<NonNullable<ReturnType<typeof getTeam>>> {
+  return write("teams.ensure", { agentId, id: `team_${randomUUID()}`, ...opts });
+}

package/src/db/teams-write-ops.ts

@@ -1,3 +1,5 @@
+import { claimAuthorizedTeam } from "./team-claim-policy";
+import { ensureTeamInternal } from "./teams";
 // Team writer operations. Guards that were formerly adjacent sync statements now execute inside
 // the writer transaction; async callers submit a main-thread generated id and never rely on worker
 // process-local state.
@@ -10,6 +12,8 @@ import {
 import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
 
 export const TEAMS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  "teams.ensure": { offLoop: true, idempotent: true, fn: (a: { agentId: string; id: string; projectId?: string }, ctx) => ensureTeamInternal(a.agentId, a.id, ctx.now, false, a.projectId ?? null) },
+  "teams.claimAuthorized": { offLoop: true, idempotent: true, fn: (a: { teamId: string; agentId: string; admin: boolean }) => claimAuthorizedTeam(a.teamId, a.agentId, a.admin) },
   "teams.zeroMembers.set": { offLoop: true, idempotent: true, fn: (a: { teamId: string; ts: number }) => setTeamZeroMembersSince(a.teamId, a.ts) },
   "teams.zeroMembers.clear": { offLoop: true, idempotent: true, fn: (a: { teamId: string }, ctx) => clearTeamZeroMembersSince(a.teamId, ctx.now) },
   "teams.brief.set": { offLoop: true, idempotent: true, fn: (a: Parameters<typeof setTeamBrief>[0], ctx) => setTeamBrief(a, ctx.now) },

package/src/db/terminal-events.ts

@@ -111,3 +111,18 @@ export function clearAgentNotice(child: Pick<AgentCard, "id" | "epoch" | "meta">
   getDb().query("DELETE FROM agent_exit_notices WHERE agent_id = ? AND epoch = ? AND spawn_request_id = ? AND kind = ?")
     .run(child.id, child.epoch, stringValue(child.meta?.spawnRequestId) ?? "", kind);
 }
+
+export interface AgentNoticeSlot {
+  child: Pick<AgentCard, "id" | "epoch" | "meta">;
+  kind: string;
+}
+
+/** Called inside notifications.agentNotice, so failure rolls back the slot and all sends. */
+export function insertAgentNoticeSlot({ child, kind }: AgentNoticeSlot, now: number): boolean {
+  if (kind === "agent.ready") {
+    getDb().query("DELETE FROM agent_exit_notices WHERE agent_id = ? AND kind = 'agent.ready' AND NOT (epoch = ? AND spawn_request_id = ?)")
+      .run(child.id, child.epoch, stringValue(child.meta?.spawnRequestId) ?? "");
+  }
+  return getDb().query("INSERT OR IGNORE INTO agent_exit_notices (agent_id, epoch, spawn_request_id, kind, created_at) VALUES (?, ?, ?, ?, ?)")
+    .run(child.id, child.epoch, stringValue(child.meta?.spawnRequestId) ?? "", kind, now).changes > 0;
+}