[codex] Add issue subtree pause, cancel, and restore controls (#4332)

## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - This branch extends the issue control-plane so board operators can pause, cancel, and later restore whole issue subtrees while keeping descendant execution and wake behavior coherent. > - That required new hold state in the database, shared contracts, server routes/services, and issue detail UI controls so subtree actions are durable and auditable instead of ad hoc. > - While this branch was in flight, `master` advanced with new environment lifecycle work, including a new `0065_environments` migration. > - Before opening the PR, this branch had to be rebased onto `paperclipai/paperclip:master` without losing the existing subtree-control work or leaving conflicting migration numbering behind. > - This pull request rebases the subtree pause/cancel/restore feature cleanly onto current `master`, renumbers the hold migration to `0066_issue_tree_holds`, and preserves the full branch diff in a single PR. > - The benefit is that reviewers get one clean, mergeable PR for the subtree-control feature instead of stale branch history with migration conflicts. ## What Changed - Added durable issue subtree hold data structures, shared API/types/validators, server routes/services, and UI flows for subtree pause, cancel, and restore operations. - Added server and UI coverage for subtree previewing, hold creation/release, dependency-aware scheduling under holds, and issue detail subtree controls. - Rebased the branch onto current `paperclipai/paperclip:master` and renumbered the branch migration from `0065_issue_tree_holds` to `0066_issue_tree_holds` so it no longer conflicts with upstream `0065_environments`. - Added a small follow-up commit that makes restore requests return `200 OK` explicitly while keeping pause/cancel hold creation at `201 Created`, and updated the route test to match that contract. ## Verification - `pnpm --filter @paperclipai/db typecheck` - `pnpm --filter @paperclipai/shared typecheck` - `pnpm --filter @paperclipai/server typecheck` - `pnpm --filter @paperclipai/ui typecheck` - `cd server && pnpm exec vitest run src/__tests__/issue-tree-control-routes.test.ts src/__tests__/issue-tree-control-service.test.ts src/__tests__/issue-tree-control-service-unit.test.ts src/__tests__/heartbeat-dependency-scheduling.test.ts` - `cd ui && pnpm exec vitest run src/components/IssueChatThread.test.tsx src/pages/IssueDetail.test.tsx` ## Risks - This is a broad cross-layer change touching DB/schema, shared contracts, server orchestration, and UI; regressions are most likely around subtree status restoration or wake suppression/resume edge cases. - The migration was renumbered during PR prep to avoid the new upstream `0065_environments` conflict. Reviewers should confirm the final `0066_issue_tree_holds` ordering is the only hold-related migration that lands. - The issue-tree restore endpoint now responds with `200` instead of relying on implicit behavior, which is semantically better for a restore operation but still changes an API detail that clients or tests could have assumed. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex coding agent in the Paperclip Codex runtime (GPT-5-class tool-using coding model; exact deployment ID/context window is not exposed inside this session). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [ ] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-06-14 01:50:39 +09:00 · 2026-04-23 14:51:46 -05:00 · 2026-04-23 14:51:46 -05:00 · f98c348e2b
commit f98c348e2b
parent 854fa81757
31 changed files with 4753 additions and 22 deletions
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@ -325,11 +325,20 @@ type PaperclipWakeBlockerSummary = {
  priority: string | null;
 };

+type PaperclipWakeTreeHoldSummary = {
+  holdId: string | null;
+  rootIssueId: string | null;
+  mode: string | null;
+  reason: string | null;
+};
+
 type PaperclipWakePayload = {
  reason: string | null;
  issue: PaperclipWakeIssue | null;
  checkedOutByHarness: boolean;
  dependencyBlockedInteraction: boolean;
+  treeHoldInteraction: boolean;
+  activeTreeHold: PaperclipWakeTreeHoldSummary | null;
  unresolvedBlockerIssueIds: string[];
  unresolvedBlockerSummaries: PaperclipWakeBlockerSummary[];
  executionStage: PaperclipWakeExecutionStage | null;
@ -435,6 +444,16 @@ function normalizePaperclipWakeBlockerSummary(value: unknown): PaperclipWakeBloc
  return { id, identifier, title, status, priority };
 }

+function normalizePaperclipWakeTreeHoldSummary(value: unknown): PaperclipWakeTreeHoldSummary | null {
+  const hold = parseObject(value);
+  const holdId = asString(hold.holdId, "").trim() || null;
+  const rootIssueId = asString(hold.rootIssueId, "").trim() || null;
+  const mode = asString(hold.mode, "").trim() || null;
+  const reason = asString(hold.reason, "").trim() || null;
+  if (!holdId && !rootIssueId && !mode && !reason) return null;
+  return { holdId, rootIssueId, mode, reason };
+}
+
 function normalizePaperclipWakeExecutionPrincipal(value: unknown): PaperclipWakeExecutionPrincipal | null {
  const principal = parseObject(value);
  const typeRaw = asString(principal.type, "").trim().toLowerCase();
@ -511,7 +530,8 @@ export function normalizePaperclipWakePayload(value: unknown): PaperclipWakePayl
        .filter((entry): entry is PaperclipWakeBlockerSummary => Boolean(entry))
    : [];

-  if (comments.length === 0 && commentIds.length === 0 && childIssueSummaries.length === 0 && unresolvedBlockerIssueIds.length === 0 && unresolvedBlockerSummaries.length === 0 && !executionStage && !continuationSummary && !livenessContinuation && !normalizePaperclipWakeIssue(payload.issue)) {
+  const activeTreeHold = normalizePaperclipWakeTreeHoldSummary(payload.activeTreeHold);
+  if (comments.length === 0 && commentIds.length === 0 && childIssueSummaries.length === 0 && unresolvedBlockerIssueIds.length === 0 && unresolvedBlockerSummaries.length === 0 && !activeTreeHold && !executionStage && !continuationSummary && !livenessContinuation && !normalizePaperclipWakeIssue(payload.issue)) {
    return null;
  }

@ -520,6 +540,8 @@ export function normalizePaperclipWakePayload(value: unknown): PaperclipWakePayl
    issue: normalizePaperclipWakeIssue(payload.issue),
    checkedOutByHarness: asBoolean(payload.checkedOutByHarness, false),
    dependencyBlockedInteraction: asBoolean(payload.dependencyBlockedInteraction, false),
+    treeHoldInteraction: asBoolean(payload.treeHoldInteraction, false),
+    activeTreeHold,
    unresolvedBlockerIssueIds,
    unresolvedBlockerSummaries,
    executionStage,
@ -614,6 +636,14 @@ export function renderPaperclipWakePrompt(
      lines.push(`- unresolved blocker issue ids: ${normalized.unresolvedBlockerIssueIds.join(", ")}`);
    }
  }
+  if (normalized.treeHoldInteraction) {
+    lines.push("- tree-hold interaction: yes");
+    lines.push("- execution scope: respond or triage the human comment; the subtree remains paused until an explicit resume action");
+    if (normalized.activeTreeHold) {
+      const hold = normalized.activeTreeHold;
+      lines.push(`- active tree hold: ${hold.holdId ?? "unknown"}${hold.rootIssueId ? ` rooted at ${hold.rootIssueId}` : ""}${hold.mode ? ` (${hold.mode})` : ""}`);
+    }
+  }
  if (normalized.missingCount > 0) {
    lines.push(`- omitted comments: ${normalized.missingCount}`);
  }
--- a/packages/db/src/migrations/0066_issue_tree_holds.sql
+++ b/packages/db/src/migrations/0066_issue_tree_holds.sql
@ -0,0 +1,107 @@
+CREATE TABLE IF NOT EXISTS "issue_tree_holds" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"root_issue_id" uuid NOT NULL,
+	"mode" text NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"reason" text,
+	"release_policy" jsonb,
+	"created_by_actor_type" text DEFAULT 'system' NOT NULL,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"created_by_run_id" uuid,
+	"released_at" timestamp with time zone,
+	"released_by_actor_type" text,
+	"released_by_agent_id" uuid,
+	"released_by_user_id" text,
+	"released_by_run_id" uuid,
+	"release_reason" text,
+	"release_metadata" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "issue_tree_hold_members" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"hold_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"parent_issue_id" uuid,
+	"depth" integer DEFAULT 0 NOT NULL,
+	"issue_identifier" text,
+	"issue_title" text NOT NULL,
+	"issue_status" text NOT NULL,
+	"assignee_agent_id" uuid,
+	"assignee_user_id" text,
+	"active_run_id" uuid,
+	"active_run_status" text,
+	"skipped" boolean DEFAULT false NOT NULL,
+	"skip_reason" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_holds_company_id_companies_id_fk') THEN
+  ALTER TABLE "issue_tree_holds" ADD CONSTRAINT "issue_tree_holds_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_holds_root_issue_id_issues_id_fk') THEN
+  ALTER TABLE "issue_tree_holds" ADD CONSTRAINT "issue_tree_holds_root_issue_id_issues_id_fk" FOREIGN KEY ("root_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_holds_created_by_agent_id_agents_id_fk') THEN
+  ALTER TABLE "issue_tree_holds" ADD CONSTRAINT "issue_tree_holds_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_holds_created_by_run_id_heartbeat_runs_id_fk') THEN
+  ALTER TABLE "issue_tree_holds" ADD CONSTRAINT "issue_tree_holds_created_by_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("created_by_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_holds_released_by_agent_id_agents_id_fk') THEN
+  ALTER TABLE "issue_tree_holds" ADD CONSTRAINT "issue_tree_holds_released_by_agent_id_agents_id_fk" FOREIGN KEY ("released_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_holds_released_by_run_id_heartbeat_runs_id_fk') THEN
+  ALTER TABLE "issue_tree_holds" ADD CONSTRAINT "issue_tree_holds_released_by_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("released_by_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_hold_members_company_id_companies_id_fk') THEN
+  ALTER TABLE "issue_tree_hold_members" ADD CONSTRAINT "issue_tree_hold_members_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_hold_members_hold_id_issue_tree_holds_id_fk') THEN
+  ALTER TABLE "issue_tree_hold_members" ADD CONSTRAINT "issue_tree_hold_members_hold_id_issue_tree_holds_id_fk" FOREIGN KEY ("hold_id") REFERENCES "public"."issue_tree_holds"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_hold_members_issue_id_issues_id_fk') THEN
+  ALTER TABLE "issue_tree_hold_members" ADD CONSTRAINT "issue_tree_hold_members_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_hold_members_parent_issue_id_issues_id_fk') THEN
+  ALTER TABLE "issue_tree_hold_members" ADD CONSTRAINT "issue_tree_hold_members_parent_issue_id_issues_id_fk" FOREIGN KEY ("parent_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_hold_members_assignee_agent_id_agents_id_fk') THEN
+  ALTER TABLE "issue_tree_hold_members" ADD CONSTRAINT "issue_tree_hold_members_assignee_agent_id_agents_id_fk" FOREIGN KEY ("assignee_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_tree_hold_members_active_run_id_heartbeat_runs_id_fk') THEN
+  ALTER TABLE "issue_tree_hold_members" ADD CONSTRAINT "issue_tree_hold_members_active_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("active_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "issue_tree_holds_company_root_status_idx" ON "issue_tree_holds" USING btree ("company_id","root_issue_id","status");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "issue_tree_holds_company_status_mode_idx" ON "issue_tree_holds" USING btree ("company_id","status","mode");--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "issue_tree_hold_members_hold_issue_uq" ON "issue_tree_hold_members" USING btree ("hold_id","issue_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "issue_tree_hold_members_company_issue_idx" ON "issue_tree_hold_members" USING btree ("company_id","issue_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "issue_tree_hold_members_hold_depth_idx" ON "issue_tree_hold_members" USING btree ("hold_id","depth");
--- a/packages/db/src/migrations/meta/_journal.json
+++ b/packages/db/src/migrations/meta/_journal.json
@ -463,6 +463,13 @@
      "when": 1776903900000,
      "tag": "0065_environments",
      "breakpoints": true
+    },
+    {
+      "idx": 66,
+      "version": "7",
+      "when": 1776903901000,
+      "tag": "0066_issue_tree_holds",
+      "breakpoints": true
    }
  ]
 }
--- a/packages/db/src/schema/index.ts
+++ b/packages/db/src/schema/index.ts
@ -38,6 +38,8 @@ export { issueLabels } from "./issue_labels.js";
 export { issueApprovals } from "./issue_approvals.js";
 export { issueComments } from "./issue_comments.js";
 export { issueThreadInteractions } from "./issue_thread_interactions.js";
+export { issueTreeHolds } from "./issue_tree_holds.js";
+export { issueTreeHoldMembers } from "./issue_tree_hold_members.js";
 export { issueExecutionDecisions } from "./issue_execution_decisions.js";
 export { issueInboxArchives } from "./issue_inbox_archives.js";
 export { inboxDismissals } from "./inbox_dismissals.js";
--- a/packages/db/src/schema/issue_tree_hold_members.ts
+++ b/packages/db/src/schema/issue_tree_hold_members.ts
@ -0,0 +1,33 @@
+import { index, pgTable, text, timestamp, uniqueIndex, uuid, boolean, integer } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+import { issues } from "./issues.js";
+import { issueTreeHolds } from "./issue_tree_holds.js";
+
+export const issueTreeHoldMembers = pgTable(
+  "issue_tree_hold_members",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    holdId: uuid("hold_id").notNull().references(() => issueTreeHolds.id, { onDelete: "cascade" }),
+    issueId: uuid("issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
+    parentIssueId: uuid("parent_issue_id").references(() => issues.id, { onDelete: "set null" }),
+    depth: integer("depth").notNull().default(0),
+    issueIdentifier: text("issue_identifier"),
+    issueTitle: text("issue_title").notNull(),
+    issueStatus: text("issue_status").notNull(),
+    assigneeAgentId: uuid("assignee_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    assigneeUserId: text("assignee_user_id"),
+    activeRunId: uuid("active_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    activeRunStatus: text("active_run_status"),
+    skipped: boolean("skipped").notNull().default(false),
+    skipReason: text("skip_reason"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    holdIssueUniqueIdx: uniqueIndex("issue_tree_hold_members_hold_issue_uq").on(table.holdId, table.issueId),
+    companyIssueIdx: index("issue_tree_hold_members_company_issue_idx").on(table.companyId, table.issueId),
+    holdDepthIdx: index("issue_tree_hold_members_hold_depth_idx").on(table.holdId, table.depth),
+  }),
+);
--- a/packages/db/src/schema/issue_tree_holds.ts
+++ b/packages/db/src/schema/issue_tree_holds.ts
@ -0,0 +1,39 @@
+import { index, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+import { issues } from "./issues.js";
+
+export const issueTreeHolds = pgTable(
+  "issue_tree_holds",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    rootIssueId: uuid("root_issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
+    mode: text("mode").notNull(),
+    status: text("status").notNull().default("active"),
+    reason: text("reason"),
+    releasePolicy: jsonb("release_policy").$type<Record<string, unknown>>(),
+    createdByActorType: text("created_by_actor_type").notNull().default("system"),
+    createdByAgentId: uuid("created_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    createdByUserId: text("created_by_user_id"),
+    createdByRunId: uuid("created_by_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    releasedAt: timestamp("released_at", { withTimezone: true }),
+    releasedByActorType: text("released_by_actor_type"),
+    releasedByAgentId: uuid("released_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    releasedByUserId: text("released_by_user_id"),
+    releasedByRunId: uuid("released_by_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    releaseReason: text("release_reason"),
+    releaseMetadata: jsonb("release_metadata").$type<Record<string, unknown>>(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyRootStatusIdx: index("issue_tree_holds_company_root_status_idx").on(
+      table.companyId,
+      table.rootIssueId,
+      table.status,
+    ),
+    companyStatusModeIdx: index("issue_tree_holds_company_status_mode_idx").on(table.companyId, table.status, table.mode),
+  }),
+);
--- a/packages/shared/src/api.ts
+++ b/packages/shared/src/api.ts
@ -6,6 +6,8 @@ export const API = {
  agents: `${API_PREFIX}/agents`,
  projects: `${API_PREFIX}/projects`,
  issues: `${API_PREFIX}/issues`,
+  issueTreeControl: `${API_PREFIX}/issues/:issueId/tree-control`,
+  issueTreeHolds: `${API_PREFIX}/issues/:issueId/tree-holds`,
  goals: `${API_PREFIX}/goals`,
  approvals: `${API_PREFIX}/approvals`,
  secrets: `${API_PREFIX}/secrets`,
--- a/packages/shared/src/constants.ts
+++ b/packages/shared/src/constants.ts
@ -170,6 +170,15 @@ export type IssueOriginKind = BuiltInIssueOriginKind | PluginIssueOriginKind;
 export const ISSUE_RELATION_TYPES = ["blocks"] as const;
 export type IssueRelationType = (typeof ISSUE_RELATION_TYPES)[number];

+export const ISSUE_TREE_CONTROL_MODES = ["pause", "resume", "cancel", "restore"] as const;
+export type IssueTreeControlMode = (typeof ISSUE_TREE_CONTROL_MODES)[number];
+
+export const ISSUE_TREE_HOLD_STATUSES = ["active", "released"] as const;
+export type IssueTreeHoldStatus = (typeof ISSUE_TREE_HOLD_STATUSES)[number];
+
+export const ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES = ["manual", "after_active_runs_finish"] as const;
+export type IssueTreeHoldReleasePolicyStrategy = (typeof ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES)[number];
+
 export const ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY = "continuation-summary" as const;
 export const SYSTEM_ISSUE_DOCUMENT_KEYS = [ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY] as const;
 export type SystemIssueDocumentKey = (typeof SYSTEM_ISSUE_DOCUMENT_KEYS)[number];
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@ -21,6 +21,9 @@ export {
  ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES,
  ISSUE_ORIGIN_KINDS,
  ISSUE_RELATION_TYPES,
+  ISSUE_TREE_CONTROL_MODES,
+  ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES,
+  ISSUE_TREE_HOLD_STATUSES,
  ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY,
  SYSTEM_ISSUE_DOCUMENT_KEYS,
  isSystemIssueDocumentKey,
@ -120,6 +123,9 @@ export {
  type PluginIssueOriginKind,
  type IssueOriginKind,
  type IssueRelationType,
+  type IssueTreeControlMode,
+  type IssueTreeHoldReleasePolicyStrategy,
+  type IssueTreeHoldStatus,
  type SystemIssueDocumentKey,
  type IssueReferenceSourceKind,
  type IssueExecutionPolicyMode,
@ -348,6 +354,15 @@ export type {
  LegacyPlanDocument,
  IssueAttachment,
  IssueLabel,
+  IssueTreeControlPreview,
+  IssueTreeHold,
+  IssueTreeHoldMember,
+  IssueTreeHoldReleasePolicy,
+  IssueTreePreviewAgent,
+  IssueTreePreviewIssue,
+  IssueTreePreviewRun,
+  IssueTreePreviewTotals,
+  IssueTreePreviewWarning,
  Goal,
  Approval,
  ApprovalComment,
@ -644,6 +659,11 @@ export {
  issueDocumentKeySchema,
  upsertIssueDocumentSchema,
  restoreIssueDocumentRevisionSchema,
+  createIssueTreeHoldSchema,
+  issueTreeControlModeSchema,
+  issueTreeHoldReleasePolicySchema,
+  previewIssueTreeControlSchema,
+  releaseIssueTreeHoldSchema,
  type CreateIssue,
  type CreateChildIssue,
  type CreateIssueLabel,
@ -662,6 +682,9 @@ export {
  type IssueDocumentFormat,
  type UpsertIssueDocument,
  type RestoreIssueDocumentRevision,
+  type CreateIssueTreeHold,
+  type PreviewIssueTreeControl,
+  type ReleaseIssueTreeHold,
  createGoalSchema,
  updateGoalSchema,
  type CreateGoal,
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@ -148,6 +148,17 @@ export type {
  IssueAttachment,
  IssueLabel,
 } from "./issue.js";
+export type {
+  IssueTreeControlPreview,
+  IssueTreeHold,
+  IssueTreeHoldMember,
+  IssueTreeHoldReleasePolicy,
+  IssueTreePreviewAgent,
+  IssueTreePreviewIssue,
+  IssueTreePreviewRun,
+  IssueTreePreviewTotals,
+  IssueTreePreviewWarning,
+} from "./issue-tree-control.js";
 export type { Goal } from "./goal.js";
 export type { Approval, ApprovalComment } from "./approval.js";
 export type {
--- a/packages/shared/src/types/issue-tree-control.ts
+++ b/packages/shared/src/types/issue-tree-control.ts
@ -0,0 +1,115 @@
+import type {
+  IssueStatus,
+  IssueTreeControlMode,
+  IssueTreeHoldReleasePolicyStrategy,
+  IssueTreeHoldStatus,
+} from "../constants.js";
+
+export interface IssueTreeHoldReleasePolicy {
+  strategy: IssueTreeHoldReleasePolicyStrategy;
+  note?: string | null;
+}
+
+export interface IssueTreePreviewRun {
+  id: string;
+  issueId: string;
+  agentId: string;
+  status: "queued" | "running";
+  startedAt: Date | null;
+  createdAt: Date;
+}
+
+export interface IssueTreePreviewAgent {
+  agentId: string;
+  issueCount: number;
+  activeRunCount: number;
+}
+
+export interface IssueTreePreviewIssue {
+  id: string;
+  identifier: string | null;
+  title: string;
+  status: IssueStatus;
+  parentId: string | null;
+  depth: number;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+  activeRun: IssueTreePreviewRun | null;
+  activeHoldIds: string[];
+  action: IssueTreeControlMode;
+  skipped: boolean;
+  skipReason: string | null;
+}
+
+export interface IssueTreePreviewWarning {
+  code: string;
+  message: string;
+  issueIds?: string[];
+}
+
+export interface IssueTreePreviewTotals {
+  totalIssues: number;
+  affectedIssues: number;
+  skippedIssues: number;
+  activeRuns: number;
+  queuedRuns: number;
+  affectedAgents: number;
+}
+
+export interface IssueTreeControlPreview {
+  companyId: string;
+  rootIssueId: string;
+  mode: IssueTreeControlMode;
+  generatedAt: Date;
+  releasePolicy: IssueTreeHoldReleasePolicy | null;
+  totals: IssueTreePreviewTotals;
+  countsByStatus: Partial<Record<IssueStatus, number>>;
+  issues: IssueTreePreviewIssue[];
+  skippedIssues: IssueTreePreviewIssue[];
+  activeRuns: IssueTreePreviewRun[];
+  affectedAgents: IssueTreePreviewAgent[];
+  warnings: IssueTreePreviewWarning[];
+}
+
+export interface IssueTreeHoldMember {
+  id: string;
+  companyId: string;
+  holdId: string;
+  issueId: string;
+  parentIssueId: string | null;
+  depth: number;
+  issueIdentifier: string | null;
+  issueTitle: string;
+  issueStatus: IssueStatus;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+  activeRunId: string | null;
+  activeRunStatus: string | null;
+  skipped: boolean;
+  skipReason: string | null;
+  createdAt: Date;
+}
+
+export interface IssueTreeHold {
+  id: string;
+  companyId: string;
+  rootIssueId: string;
+  mode: IssueTreeControlMode;
+  status: IssueTreeHoldStatus;
+  reason: string | null;
+  releasePolicy: IssueTreeHoldReleasePolicy | null;
+  createdByActorType: "user" | "agent" | "system";
+  createdByAgentId: string | null;
+  createdByUserId: string | null;
+  createdByRunId: string | null;
+  releasedAt: Date | null;
+  releasedByActorType: "user" | "agent" | "system" | null;
+  releasedByAgentId: string | null;
+  releasedByUserId: string | null;
+  releasedByRunId: string | null;
+  releaseReason: string | null;
+  releaseMetadata: Record<string, unknown> | null;
+  createdAt: Date;
+  updatedAt: Date;
+  members?: IssueTreeHoldMember[];
+}
--- a/packages/shared/src/validators/index.ts
+++ b/packages/shared/src/validators/index.ts
@ -197,6 +197,17 @@ export {
  type RestoreIssueDocumentRevision,
 } from "./issue.js";

+export {
+  createIssueTreeHoldSchema,
+  issueTreeControlModeSchema,
+  issueTreeHoldReleasePolicySchema,
+  previewIssueTreeControlSchema,
+  releaseIssueTreeHoldSchema,
+  type CreateIssueTreeHold,
+  type PreviewIssueTreeControl,
+  type ReleaseIssueTreeHold,
+} from "./issue-tree-control.js";
+
 export {
  createIssueWorkProductSchema,
  updateIssueWorkProductSchema,
--- a/packages/shared/src/validators/issue-tree-control.ts
+++ b/packages/shared/src/validators/issue-tree-control.ts
@ -0,0 +1,44 @@
+import { z } from "zod";
+import {
+  ISSUE_TREE_CONTROL_MODES,
+  ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES,
+} from "../constants.js";
+
+export const issueTreeControlModeSchema = z.enum(ISSUE_TREE_CONTROL_MODES);
+
+export const issueTreeHoldReleasePolicySchema = z
+  .object({
+    strategy: z.enum(ISSUE_TREE_HOLD_RELEASE_POLICY_STRATEGIES).default("manual"),
+    note: z.string().trim().min(1).max(500).optional().nullable(),
+  })
+  .strict();
+
+export const previewIssueTreeControlSchema = z
+  .object({
+    mode: issueTreeControlModeSchema,
+    releasePolicy: issueTreeHoldReleasePolicySchema.optional().nullable(),
+  })
+  .strict();
+
+export type PreviewIssueTreeControl = z.infer<typeof previewIssueTreeControlSchema>;
+
+export const createIssueTreeHoldSchema = z
+  .object({
+    mode: issueTreeControlModeSchema,
+    reason: z.string().trim().min(1).max(1000).optional().nullable(),
+    releasePolicy: issueTreeHoldReleasePolicySchema.optional().nullable(),
+    metadata: z.record(z.unknown()).optional().nullable(),
+  })
+  .strict();
+
+export type CreateIssueTreeHold = z.infer<typeof createIssueTreeHoldSchema>;
+
+export const releaseIssueTreeHoldSchema = z
+  .object({
+    reason: z.string().trim().min(1).max(1000).optional().nullable(),
+    releasePolicy: issueTreeHoldReleasePolicySchema.optional().nullable(),
+    metadata: z.record(z.unknown()).optional().nullable(),
+  })
+  .strict();
+
+export type ReleaseIssueTreeHold = z.infer<typeof releaseIssueTreeHoldSchema>;