[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>

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`,

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];

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,

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 {

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[];
+}

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,

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>;