agent-relay-server 0.61.2 → 0.62.1

package/src/services/issue-lifecycle.ts

@@ -0,0 +1,308 @@
+import { errMessage } from "agent-relay-sdk";
+import { getAgent, listPlansWithBoundOwner } from "../db";
+import { listIssuesForEntity, planNodeIssueEntityId } from "../db/issue-associations";
+import {
+  getSuccessfulIssueLifecycleAction,
+  listSuccessfulCloseActionsForCommit,
+  upsertIssueLifecycleAction,
+} from "../db/issue-lifecycle";
+import { getIssueRef, resolveIssueRefByExternalKey, resolveIssueRefFromString, updateIssueRef } from "../db/issue-refs";
+import { associateIssue } from "../db/issue-associations";
+import { resolveIssueTrackerAdapter } from "../issue-tracker";
+import type { IssueTrackerAdapter } from "../issue-tracker";
+import { recordAndEmitIssueActivity } from "./issue-activity";
+import type { IssueAssociationEntityType, IssueProvider, IssueRef, WorkspaceRecord } from "../types";
+
+type LifecycleWorkspace = Pick<WorkspaceRecord, "id" | "repoRoot" | "branch" | "baseRef" | "ownerAgentId">;
+type AdapterResolver = (ref: IssueRef) => IssueTrackerAdapter;
+type LogFn = (message: string) => void;
+
+export interface LandedIssueLifecycleInput {
+  workspace: LifecycleWorkspace;
+  mergedSha?: string;
+  subject?: string;
+  source?: string;
+}
+
+export interface ReopenIssueLifecycleInput {
+  issueRefId?: string;
+  ref?: string;
+  defaultRepo?: string;
+  provider?: IssueProvider;
+  repo?: string;
+  externalKey?: string;
+  url?: string;
+  title?: string;
+  comment?: string;
+  agentId?: string;
+  entityType?: IssueAssociationEntityType;
+  entityId?: string;
+}
+
+export interface IssueLifecycleOptions {
+  adapterResolver?: AdapterResolver;
+  log?: LogFn;
+}
+
+export type CloseIssueLifecycleResult =
+  | { issueRef: IssueRef; action: "closed"; source: "association" | "commit"; landKey: string }
+  | { issueRef: IssueRef; action: "skipped"; reason: "already-closed" | "already-processed"; landKey: string }
+  | { issueRef: IssueRef; action: "failed"; error: string; landKey: string };
+
+export type ReopenIssueLifecycleResult =
+  | { issueRef: IssueRef; action: "reopened"; landKey: string }
+  | { issueRef: IssueRef; action: "skipped"; reason: "already-open"; landKey: string }
+  | { issueRef: IssueRef; action: "failed"; error: string; landKey: string };
+
+let adapterResolverForTests: AdapterResolver | undefined;
+
+export function __setIssueLifecycleAdapterResolverForTests(resolver: AdapterResolver | undefined): void {
+  adapterResolverForTests = resolver;
+}
+
+function adapterFor(ref: IssueRef, opts: IssueLifecycleOptions): IssueTrackerAdapter {
+  return (opts.adapterResolver ?? adapterResolverForTests ?? resolveIssueTrackerAdapter)(ref);
+}
+
+function logFailure(opts: IssueLifecycleOptions, message: string): void {
+  if (opts.log) opts.log(message);
+  else console.warn(message);
+}
+
+function defaultIssueRepo(): string | undefined {
+  return process.env.AGENT_RELAY_DEFAULT_ISSUE_REPO || process.env.GITHUB_REPOSITORY || undefined;
+}
+
+function cleanText(value: string | undefined): string | undefined {
+  const cleaned = value?.trim();
+  return cleaned || undefined;
+}
+
+function landKey(input: LandedIssueLifecycleInput): string {
+  const base = input.workspace.baseRef ?? "main";
+  const sha = cleanText(input.mergedSha);
+  if (sha) return `land:${base}:${sha}`;
+  return `land:${base}:${input.workspace.id}:${input.workspace.branch ?? "unknown"}:${input.subject ?? ""}`.slice(0, 240);
+}
+
+function manualReopenKey(issueRef: IssueRef): string {
+  return `manual-reopen:${issueRef.id}:${Date.now()}`;
+}
+
+function issueRefMap(refs: IssueRef[]): IssueRef[] {
+  const out = new Map<string, IssueRef>();
+  for (const ref of refs) out.set(ref.id, ref);
+  return [...out.values()];
+}
+
+function associatedIssueRefs(workspace: LifecycleWorkspace): IssueRef[] {
+  const refs: IssueRef[] = [];
+  const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
+  if (owner?.teamId) {
+    refs.push(...listIssuesForEntity("team", owner.teamId).map((item) => item.issueRef));
+  }
+  if (workspace.ownerAgentId) {
+    for (const plan of listPlansWithBoundOwner(workspace.ownerAgentId)) {
+      for (const node of plan.nodes) {
+        if (node.ownerRef?.agentId !== workspace.ownerAgentId) continue;
+        refs.push(...listIssuesForEntity("plan-node", planNodeIssueEntityId(plan.id, node.id)).map((item) => item.issueRef));
+      }
+    }
+  }
+  return issueRefMap(refs);
+}
+
+const CLOSING_KEYWORD_RE = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+([^\n\r]+)/gi;
+const ISSUE_REF_AT_START_RE = /^(https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/issues\/[0-9]+(?:[/?#][^\s,)]*)?|[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[0-9]+|#[0-9]+)/;
+const REF_SEPARATOR_RE = /^(?:\s*,\s*|\s+(?:and|&)\s+)/i;
+
+export function parseClosingIssueRefs(text: string | undefined, fallbackDefaultRepo = defaultIssueRepo()): IssueRef[] {
+  if (!text) return [];
+  const refs: IssueRef[] = [];
+  for (const match of text.matchAll(CLOSING_KEYWORD_RE)) {
+    let rest = match[1] ?? "";
+    while (rest.trim()) {
+      rest = rest.trimStart();
+      const refMatch = rest.match(ISSUE_REF_AT_START_RE);
+      if (!refMatch) break;
+      try {
+        refs.push(resolveIssueRefFromString({ ref: refMatch[1]!, defaultRepo: fallbackDefaultRepo }));
+      } catch {
+        // Invalid or bare-without-default refs are ignored; the land itself must never fail here.
+      }
+      rest = rest.slice(refMatch[0].length);
+      const separator = rest.match(REF_SEPARATOR_RE);
+      if (!separator) break;
+      rest = rest.slice(separator[0].length);
+    }
+  }
+  return issueRefMap(refs);
+}
+
+export function resolveIssueRefsForLand(input: LandedIssueLifecycleInput): { source: "association" | "commit"; refs: IssueRef[] } {
+  const associated = associatedIssueRefs(input.workspace);
+  if (associated.length > 0) return { source: "association", refs: associated };
+  return { source: "commit", refs: parseClosingIssueRefs(input.subject) };
+}
+
+function closeAuditComment(input: LandedIssueLifecycleInput): string {
+  const commit = input.mergedSha ? input.mergedSha.slice(0, 12) : input.workspace.branch ?? input.workspace.id;
+  return `Closed by \`${commit}\` on merge to \`main\` - reopen if release surfaces more work.`;
+}
+
+async function closeIssueRefForLand(
+  issueRef: IssueRef,
+  source: "association" | "commit",
+  input: LandedIssueLifecycleInput,
+  opts: IssueLifecycleOptions,
+): Promise<CloseIssueLifecycleResult> {
+  const key = landKey(input);
+  if (getSuccessfulIssueLifecycleAction(issueRef.id, "close", key)) return { issueRef, action: "skipped", reason: "already-processed", landKey: key };
+  const latest = getIssueRef(issueRef.id) ?? issueRef;
+  if (latest.status === "closed") return { issueRef: latest, action: "skipped", reason: "already-closed", landKey: key };
+
+  const comment = closeAuditComment(input);
+  try {
+    await adapterFor(latest, opts).close(latest, { comment, labels: ["fixed"] });
+    const closed = updateIssueRef(latest.id, { status: "closed", statusSyncedAt: Date.now() }) ?? latest;
+    upsertIssueLifecycleAction({
+      issueRefId: latest.id,
+      action: "close",
+      landKey: key,
+      workspaceId: input.workspace.id,
+      branch: input.workspace.branch,
+      baseRef: input.workspace.baseRef ?? "main",
+      commitSha: input.mergedSha,
+      commitSubject: input.subject,
+      agentId: input.workspace.ownerAgentId,
+      source,
+      comment,
+      status: "succeeded",
+    });
+    if (input.workspace.ownerAgentId) {
+      recordAndEmitIssueActivity({
+        agentId: input.workspace.ownerAgentId,
+        action: "done",
+        issueRefId: latest.id,
+        clientId: `issue-close:${latest.id}:${key}`,
+        title: "Issue closed on land",
+        body: comment,
+        metadata: { workspaceId: input.workspace.id, branch: input.workspace.branch, commitSha: input.mergedSha, source },
+      });
+    }
+    return { issueRef: closed, action: "closed", source, landKey: key };
+  } catch (error) {
+    const message = errMessage(error);
+    upsertIssueLifecycleAction({
+      issueRefId: latest.id,
+      action: "close",
+      landKey: key,
+      workspaceId: input.workspace.id,
+      branch: input.workspace.branch,
+      baseRef: input.workspace.baseRef ?? "main",
+      commitSha: input.mergedSha,
+      commitSubject: input.subject,
+      agentId: input.workspace.ownerAgentId,
+      source,
+      comment,
+      status: "failed",
+      error: message,
+    });
+    logFailure(opts, `issue lifecycle close failed for ${latest.id} on ${key}: ${message}`);
+    return { issueRef: latest, action: "failed", error: message, landKey: key };
+  }
+}
+
+function revertedCommitLookup(subject: string | undefined): { commitSha?: string; commitSubject?: string } {
+  const text = cleanText(subject);
+  if (!text) return {};
+  const sha = text.match(/\bThis reverts commit ([0-9a-f]{7,64})\b/i)?.[1];
+  if (sha) return { commitSha: sha };
+  const revertedSubject = text.match(/^Revert "(.+)"$/)?.[1];
+  return revertedSubject ? { commitSubject: revertedSubject } : {};
+}
+
+async function reopenIssuesForRevert(input: LandedIssueLifecycleInput, opts: IssueLifecycleOptions): Promise<ReopenIssueLifecycleResult[]> {
+  const lookup = revertedCommitLookup(input.subject);
+  const closedActions = listSuccessfulCloseActionsForCommit(lookup);
+  const results: ReopenIssueLifecycleResult[] = [];
+  for (const action of closedActions) {
+    results.push(await reopenIssueLifecycle({
+      issueRefId: action.issueRefId,
+      comment: `Reopened by revert \`${input.mergedSha?.slice(0, 12) ?? input.workspace.branch ?? input.workspace.id}\` on merge to \`main\`.`,
+      agentId: input.workspace.ownerAgentId,
+    }, opts));
+  }
+  return results;
+}
+
+export async function handleLandedIssueLifecycle(input: LandedIssueLifecycleInput, opts: IssueLifecycleOptions = {}): Promise<{
+  source: "association" | "commit";
+  closed: CloseIssueLifecycleResult[];
+  reopened: ReopenIssueLifecycleResult[];
+  skipped: string[];
+}> {
+  if ((input.workspace.baseRef ?? "main") !== "main") return { source: "commit", closed: [], reopened: [], skipped: ["non-default-branch"] };
+  const resolved = resolveIssueRefsForLand(input);
+  const closed: CloseIssueLifecycleResult[] = [];
+  for (const ref of resolved.refs) {
+    closed.push(await closeIssueRefForLand(ref, resolved.source, input, opts));
+  }
+  const reopened = await reopenIssuesForRevert(input, opts);
+  return { source: resolved.source, closed, reopened, skipped: [] };
+}
+
+function resolveReopenRef(input: ReopenIssueLifecycleInput): IssueRef {
+  if (input.issueRefId) {
+    const issueRef = getIssueRef(input.issueRefId);
+    if (!issueRef) throw new Error(`issue ref ${input.issueRefId} not found`);
+    return issueRef;
+  }
+  if (input.ref) return resolveIssueRefFromString({ ref: input.ref, defaultRepo: input.defaultRepo ?? input.repo, provider: input.provider, title: input.title });
+  if (input.provider && input.repo && input.externalKey) {
+    return resolveIssueRefByExternalKey({
+      provider: input.provider,
+      repo: input.repo,
+      externalKey: input.externalKey,
+      url: input.url,
+      title: input.title,
+    });
+  }
+  throw new Error("issueRefId, ref, or provider/repo/externalKey required");
+}
+
+export async function reopenIssueLifecycle(input: ReopenIssueLifecycleInput, opts: IssueLifecycleOptions = {}): Promise<ReopenIssueLifecycleResult> {
+  const issueRef = resolveReopenRef(input);
+  const key = manualReopenKey(issueRef);
+  if (issueRef.status === "open") return { issueRef, action: "skipped", reason: "already-open", landKey: key };
+  const comment = input.comment ?? "Reopened by Agent Relay issue lifecycle.";
+  try {
+    await adapterFor(issueRef, opts).reopen(issueRef, { comment });
+    const opened = updateIssueRef(issueRef.id, { status: "open", statusSyncedAt: Date.now() }) ?? issueRef;
+    upsertIssueLifecycleAction({
+      issueRefId: issueRef.id,
+      action: "reopen",
+      landKey: key,
+      agentId: input.agentId,
+      comment,
+      status: "succeeded",
+      source: "explicit",
+    });
+    if (input.entityType && input.entityId) associateIssue(issueRef.id, input.entityType, input.entityId);
+    return { issueRef: opened, action: "reopened", landKey: key };
+  } catch (error) {
+    const message = errMessage(error);
+    upsertIssueLifecycleAction({
+      issueRefId: issueRef.id,
+      action: "reopen",
+      landKey: key,
+      agentId: input.agentId,
+      comment,
+      status: "failed",
+      error: message,
+      source: "explicit",
+    });
+    logFailure(opts, `issue lifecycle reopen failed for ${issueRef.id}: ${message}`);
+    return { issueRef, action: "failed", error: message, landKey: key };
+  }
+}

package/src/services/issue-refs.ts

@@ -0,0 +1,32 @@
+import {
+  deleteIssueRef,
+  getIssueRef,
+  listIssueRefs,
+  resolveIssueRefByExternalKey,
+  resolveIssueRefFromString,
+  updateIssueRef,
+  upsertIssueRef,
+  type ListIssueRefsOptions,
+  type ResolveIssueRefByExternalKeyInput,
+  type ResolveIssueRefFromStringInput,
+  type UpdateIssueRefInput,
+  type UpsertIssueRefInput,
+} from "../db/issue-refs";
+
+export { getIssueRef, listIssueRefs, type ListIssueRefsOptions };
+
+export function upsertIssueRefMapping(input: UpsertIssueRefInput) {
+  return upsertIssueRef(input);
+}
+
+export function resolveIssueRefMapping(input: ResolveIssueRefByExternalKeyInput | ResolveIssueRefFromStringInput) {
+  return "ref" in input ? resolveIssueRefFromString(input) : resolveIssueRefByExternalKey(input);
+}
+
+export function patchIssueRefMapping(id: string, input: UpdateIssueRefInput) {
+  return updateIssueRef(id, input);
+}
+
+export function deleteIssueRefMapping(id: string) {
+  return deleteIssueRef(id);
+}

package/src/services/plan-graph.ts

@@ -1,5 +1,7 @@
 import { isRecord } from "agent-relay-sdk";
 import { createPlanRow, deletePlan, getAgent, getEntry, getPlan, getPlanByTeam, getPlanByThread, listPlansWithBoundOwner, planThreadExists, replacePlan, ValidationError } from "../db";
+import { associateIssue, planNodeIssueEntityId, removeAssociation } from "../db/issue-associations";
+import { resolveIssueRefFromString } from "../db/issue-refs";
 import { emitRelayEvent } from "../events";
 import { cleanString, cleanStringArray, optionalEnum } from "../validation";
 import type { AuthContext } from "./auth-context";
@@ -72,7 +74,37 @@ function cleanOwnerRef(value: unknown): PlanOwnerRef | undefined {
 
 function cleanRefs(value: unknown): PlanNode["refs"] | undefined {
   if (value === undefined || value === null) return undefined;
-  throw new ValidationError("refs are populated by live binding in slice c");
+  const ref = cleanRecordRef(value, "refs");
+  if (!ref) return undefined;
+  const out: PlanNode["refs"] = {};
+  const issueId = cleanString(ref.issueId, "refs.issueId", { max: 1000 });
+  if (issueId) {
+    out.issueId = resolveIssueRefFromString({ ref: issueId, defaultRepo: defaultIssueRepo() }).id;
+  }
+  const unsupported = ["agentId", "taskId", "landingRef"].filter((key) => cleanString(ref[key], `refs.${key}`, { max: 240 }));
+  if (unsupported.length > 0) throw new ValidationError("agentId/taskId/landingRef refs are populated by live binding in slice c");
+  return Object.keys(out).length ? out : undefined;
+}
+
+function defaultIssueRepo(): string | undefined {
+  return process.env.AGENT_RELAY_DEFAULT_ISSUE_REPO || process.env.GITHUB_REPOSITORY || undefined;
+}
+
+function syncPlanNodeIssueAssociation(planId: string, node: PlanNode): void {
+  if (!node.refs?.issueId) return;
+  associateIssue(node.refs.issueId, "plan-node", planNodeIssueEntityId(planId, node.id));
+}
+
+function removePlanNodeIssueAssociation(planId: string, node: PlanNode): void {
+  if (!node.refs?.issueId) return;
+  removeAssociation(node.refs.issueId, "plan-node", planNodeIssueEntityId(planId, node.id));
+}
+
+function syncChangedPlanNodeIssueAssociation(planId: string, before: PlanNode | undefined, after: PlanNode): void {
+  if (before?.refs?.issueId && before.refs.issueId !== after.refs?.issueId) {
+    removeAssociation(before.refs.issueId, "plan-node", planNodeIssueEntityId(planId, before.id));
+  }
+  if (after.refs?.issueId) syncPlanNodeIssueAssociation(planId, after);
 }
 
 function cleanBlackboardRefs(value: unknown, planTeamId?: string): string[] | undefined {
@@ -229,6 +261,7 @@ export function createPlan(input: PlanCreateInput, ctx: AuthContext): Plan {
     edges,
     createdBy: actor,
   });
+  for (const node of plan.nodes) syncPlanNodeIssueAssociation(plan.id, node);
   emitPlan("plan.created", plan, actor);
   return plan;
 }
@@ -238,6 +271,7 @@ export function addPlanNode(planId: string, nodeInput: PlanNodeInput, ctx: AuthC
   const node = cleanNode(nodeInput, plan.teamId);
   if (plan.nodes.some((item) => item.id === node.id)) throw new ValidationError(`node ${node.id} already exists`);
   const updated = replacePlan({ ...plan, nodes: [...plan.nodes, node] }, actorId(ctx));
+  syncPlanNodeIssueAssociation(updated.id, node);
   emitPlan("plan.changed", updated, actorId(ctx));
   return updated;
 }
@@ -260,6 +294,7 @@ export function updatePlanNode(planId: string, nodeId: string, patch: PlanNodePa
   };
   const next = applyBoundStatus(base);
   const updated = replacePlan({ ...plan, nodes: plan.nodes.map((node) => node.id === nodeId ? next : node) }, actorId(ctx));
+  syncChangedPlanNodeIssueAssociation(updated.id, existing, next);
   emitPlan("plan.changed", updated, actorId(ctx));
   return updated;
 }
@@ -280,12 +315,14 @@ export function addPlanEdge(planId: string, edgeInput: unknown, ctx: AuthContext
 
 export function removePlanNode(planId: string, nodeId: string, ctx: AuthContext): Plan {
   const plan = existingPlan(planId);
-  if (!plan.nodes.some((node) => node.id === nodeId)) throw new ValidationError(`node ${nodeId} not found`);
+  const removed = plan.nodes.find((node) => node.id === nodeId);
+  if (!removed) throw new ValidationError(`node ${nodeId} not found`);
   const updated = replacePlan({
     ...plan,
     nodes: plan.nodes.filter((node) => node.id !== nodeId),
     edges: plan.edges.filter((edge) => edge.from !== nodeId && edge.to !== nodeId),
   }, actorId(ctx));
+  removePlanNodeIssueAssociation(plan.id, removed);
   emitPlan("plan.changed", updated, actorId(ctx));
   return updated;
 }
@@ -304,6 +341,7 @@ export function deletePlanGraph(planId: string, ctx: AuthContext): { id: string;
   const plan = existingPlan(planId);
   const actor = actorId(ctx);
   deletePlan(plan.id, actor);
+  for (const node of plan.nodes) removePlanNodeIssueAssociation(plan.id, node);
   emitPlan("plan.deleted", plan, actor);
   return { id: plan.id, deleted: true };
 }

package/src/services/team.ts

@@ -1,5 +1,6 @@
 import { dissolveTeam, ensureTeam, getAgent, getPlanByTeam, getTeam, getTeamRoster, setTeamBrief } from "../db";
 import { emitRelayEvent } from "../events";
+import { listIssueRefsForEntity } from "./issue-associations";
 import type { AuthContext } from "./auth-context";
 import type { Team } from "../types";
 
@@ -12,6 +13,7 @@ export interface TeamPayload {
   brief: string | null;
   definitionOfDone: string | null;
   plan: ReturnType<typeof getPlanByTeam>;
+  issues: ReturnType<typeof listIssueRefsForEntity>;
 }
 
 export interface TeamBriefInput {
@@ -41,6 +43,7 @@ function payloadForAgent(agentId: string, channel?: string): TeamPayload {
     brief: team.brief ?? null,
     definitionOfDone: team.definitionOfDone ?? null,
     plan: getPlanByTeam(team.id, channel) ?? null,
+    issues: listIssueRefsForEntity("team", team.id),
   };
 }
 
@@ -85,5 +88,6 @@ export function dissolveCallerTeam(ctx: AuthContext, input: TeamDissolveServiceI
     brief: team.brief ?? null,
     definitionOfDone: team.definitionOfDone ?? null,
     plan: getPlanByTeam(team.id) ?? null,
+    issues: listIssueRefsForEntity("team", team.id),
   };
 }

package/src/token-db.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { getDb } from "./db";
-import { signComponentToken } from "./security";
+import { signComponentToken, type TokenRevokeReason } from "./security";
 import type { ComponentToken, CreateTokenProfileInput, TokenConstraints, TokenProfile, TokenRecord, UpdateTokenProfileInput } from "./types";
 
 interface TokenRow {
@@ -13,6 +13,7 @@ interface TokenRow {
   issued_at: number;
   expires_at: number | null;
   revoked_at: number | null;
+  revoked_reason: string | null;
   created_by: string | null;
 }
 
@@ -77,7 +78,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Agent",
     description: "Coding-agent runtime access for messages, commands, tasks, and scoped memory reads.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "notifications:read", "notifications:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write"],
     ttlSeconds: 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -87,7 +88,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Child Agent",
     description: "Delegated child-agent runtime access, constrained to its parent and spawn request.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "notifications:read", "notifications:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write"],
     constraints: { canDelegate: false },
     ttlSeconds: 2 * 60 * 60,
     builtIn: true,
@@ -98,7 +99,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Interactive Agent",
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "notifications:read", "notifications:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "issue:read", "issue:write", "notifications:read", "notifications:write", "insights:write"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,
@@ -180,8 +181,26 @@ export function getToken(jti: string): TokenRecord | null {
   return row ? rowToToken(row) : null;
 }
 
-export function revokeToken(jti: string): boolean {
-  return getDb().query("UPDATE tokens SET revoked_at = ? WHERE jti = ? AND revoked_at IS NULL").run(Math.floor(Date.now() / 1000), jti).changes > 0;
+// Revoke a token, optionally tagging WHY (#484). The reason gates self-heal:
+// `verifyComponentTokenAllowExpired` lets the orchestrator re-mint a token revoked
+// as "stale" (the restart-strand case) but never one revoked as a hard kill
+// (admin/rotation/agent-removed/pruned). A NULL reason (legacy/unspecified) is a
+// hard kill. Only flips an un-revoked token — already-revoked rows are left as-is
+// (so the 404-on-double-revoke contract in routes/tokens.ts holds).
+export function revokeToken(jti: string, reason?: TokenRevokeReason): boolean {
+  return getDb()
+    .query("UPDATE tokens SET revoked_at = ?, revoked_reason = ? WHERE jti = ? AND revoked_at IS NULL")
+    .run(Math.floor(Date.now() / 1000), reason ?? null, jti).changes > 0;
+}
+
+// Downgrade a "stale"-revoked token to a hard "rotation" revocation so it can no
+// longer be re-minted (#484). Called after a successful orchestrator re-mint: the
+// fresh token now carries the identity, and the consumed stale token must not be
+// re-mintable a second time (bounds replay of a captured stale token).
+export function hardenStaleRevocation(jti: string): void {
+  getDb()
+    .query("UPDATE tokens SET revoked_reason = 'rotation' WHERE jti = ? AND revoked_reason = 'stale'")
+    .run(jti);
 }
 
 export function renewToken(input: {
@@ -201,7 +220,7 @@ export function renewToken(input: {
     profileId: previous.profileId,
     createdBy: input.createdBy ?? `renew:${previous.jti}`,
   });
-  revokeToken(previous.jti);
+  revokeToken(previous.jti, "rotation");
   return { ...renewed, previous };
 }
 
@@ -342,6 +361,7 @@ function rowToToken(row: TokenRow): TokenRecord {
     issuedAt: row.issued_at,
     expiresAt: row.expires_at ?? undefined,
     revokedAt: row.revoked_at ?? undefined,
+    revokedReason: row.revoked_reason ?? undefined,
     createdBy: row.created_by ?? undefined,
   };
 }

package/src/workspace-actions.ts

@@ -24,7 +24,8 @@ import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
 // tuple as the HTTP route without a second import hop (one source: workspace-merge, #304).
 export { LAND_STRATEGIES, DEFAULT_MERGE_STRATEGY } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
-import { TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { scheduleRepoMerge } from "./workspace-auto-merge";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
@@ -239,6 +240,12 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   });
   if (!updated) return { ok: false, httpStatus: 404, error: "workspace not found" };
 
+  // #237: a ready/request-review hand-off kicks the per-repo auto-merge inline right
+  // then, instead of waiting up to the backstop interval — this is what makes "mark
+  // ready → land" take seconds, not minutes (the #235 root-cause fix). Fire-and-forget
+  // + lease-serialized; a non-landable row is a harmless no-op (autoMergeForRepo re-checks).
+  if (READY_TO_LAND_STATUSES.has(nextStatus)) scheduleRepoMerge(updated.repoRoot);
+
   let command: Command | undefined;
   if (requiresCommand) {
     // Only `cleanup` reaches here — `merge` returned early via the shared helper.