Add accepted-plan decomposition exact-once guards and UI state (#6831)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies, so
planning approvals and child-issue fan-out are part of the core
control-plane loop.
> - Accepted plans are supposed to be a safe bridge from planning into
execution, especially when agents wake from review decisions and reuse
isolated workspaces.
> - The duplicate-subtask incident showed that an accepted plan revision
could be interpreted more than once across overlapping runs, which broke
the single-source-of-truth model for issue decomposition.
> - Fixing that required tightening the backend contract first:
accepted-plan decomposition needs an exact-once fingerprint, durable
claim state, and retry-safe child creation.
> - Once that backend behavior existed, the board still needed
visibility into what happened, so the issue detail view needed a
dedicated decomposition section instead of forcing operators to
reconstruct child creation from raw activity.
> - This pull request adds the exact-once decomposition primitive,
hardens wake routing and regressions around the incident, and surfaces
decomposition state in the UI so future incidents are both prevented and
easier to inspect.

## What Changed

- Added accepted-plan decomposition semantics to
`doc/execution-semantics.md`, including the exact-once fingerprint,
durable claim/result expectations, and retry/resume behavior.
- Added persistent accepted-plan decomposition claims in the backend,
including schema, shared types/validators, service logic, and issue
routes for creating and listing decomposition state.
- Hardened heartbeat routing so an accepted-plan continuation stays
scoped to the relevant planning issue instead of opportunistically
re-decomposing another accepted issue on the same assignee.
- Added regression coverage for the original failure modes: concurrent
same-parent retries, cross-issue accepted-plan isolation, and partial
child recreation under the same fingerprint.
- Added the `Plan decomposition` issue-detail section plus supporting
API/query-key/activity formatting updates so operators can see revision
status, owner, child counts, and the linked child issues directly in the
UI.
- Included the small follow-up UI fix so the decomposition section still
renders when the issue work mode is no longer `planning`.

## Verification

- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm --filter @paperclipai/db typecheck`
- `pnpm exec vitest run server/src/__tests__/issues-service.test.ts`
- `pnpm exec vitest run server/src/__tests__/issues-service.test.ts -t
"lists persisted decompositions with child issue summaries"`
- `pnpm exec vitest run server/src/__tests__/issues-service.test.ts -t
"accepted plan decomposition"
server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
server/src/__tests__/heartbeat-context-summary.test.ts`
- Manual UI path: create a planning issue without an isolated execution
workspace, add a `plan` document, accept the `request_confirmation`, let
Paperclip create child issues, then reopen the parent issue detail page
and confirm the `Plan decomposition` section shows the accepted
revision, status, idempotent-claim badge, and child links.
- Separate follow-up bug noted during manual UI validation: accepting a
plan on an issue whose run never records `workspace_finalize` is tracked
in `PAPA-445` and is not part of this PR’s fix scope.

## Risks

- This adds a new migration and a large Drizzle snapshot update;
reviewers should confirm the schema shape and generated metadata match
the intended decomposition table.
- The exact-once claim changes sit on the accepted-plan fan-out path, so
regressions there could block legitimate child creation or mis-handle
retries if the claim state machine is wrong.
- The new UI only appears when decomposition records exist; reviewers
should use the manual verification path above rather than expecting
existing issues on a stale local instance to show the section
automatically.
- `PAPA-445` remains an open follow-up for the `workspace_finalize`
accept gate when a planning handoff never records finalize; that bug can
interfere with reproducing the UI flow on isolated workspaces but does
not change the correctness of the exact-once decomposition feature
itself.

> Checked `ROADMAP.md`: this PR is a bug fix / control-plane hardening
change for accepted-plan decomposition, not a new uncoordinated roadmap
feature.

## Model Used

- OpenAI Codex via Paperclip `codex_local` (GPT-5-based coding agent;
exact backend model ID/context window not exposed in the run context),
with repository tool use, shell execution, and code-editing
capabilities.

<img width="806" height="1069" alt="Screenshot 2026-05-27 at 11 05
48 PM"
src="https://github.com/user-attachments/assets/5b00b670-96cd-4470-b0a3-581743bcae28"
/>


## 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
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] 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>

doc/execution-semantics.md

@@ -1,7 +1,7 @@
 # Execution Semantics
 
 Status: Current implementation guide
-Date: 2026-04-26
+Date: 2026-05-23
 Audience: Product and engineering
 
 This document explains how Paperclip interprets issue assignment, issue status, execution runs, wakeups, parent/sub-issue structure, and blocker relationships.
@@ -152,7 +152,73 @@ Blocked issues should stay idle while blockers remain unresolved. Paperclip shou
 
 If a parent is truly waiting on a child, model that with blockers. Do not rely on the parent/child relationship alone.
 
-## 7. Non-Terminal Issue Liveness Contract
+## 7. Accepted-Plan Decomposition
+
+An accepted plan confirmation is permission to decompose one specific accepted plan revision into child issues.
+
+This complements the existing accepted-plan continuation rule: once a plan is accepted, the source issue may create child implementation issues, but it must not start implementation work on the source issue itself during that continuation.
+
+Paperclip must treat accepted-plan decomposition as an exact-once control-plane primitive, not as a free-floating wake that any later run may interpret again.
+
+### Exact-once fingerprint
+
+The canonical decomposition fingerprint is:
+
+- `(sourceIssueId, acceptedPlanRevisionId)`
+
+Where:
+
+- `sourceIssueId` is the issue whose `plan` document revision was accepted
+- `acceptedPlanRevisionId` is the accepted `plan` document revision
+
+This is the product contract because the accepted revision is the thing being authorized for decomposition. Re-accepting, re-waking, or re-reading the same accepted revision must not authorize a second child tree. A later accepted revision on the same source issue is a new fingerprint and may produce a different decomposition result.
+
+An implementation may also store the accepted interaction id, acceptance run id, or other evidence, but those values must collapse onto the same uniqueness guarantee. They must not allow a second decomposition claim for the same `(sourceIssueId, acceptedPlanRevisionId)` pair.
+
+### Durable claim and durable result
+
+Before creating child issues, the first decomposition attempt must create or reuse a durable record for the fingerprint.
+
+That durable record must be able to answer, without reconstructing the thread from comments or transcripts:
+
+- whether decomposition for the fingerprint is `in_flight` or `completed`
+- which run or owner currently holds the in-flight claim
+- which child issues, if any, have already been created under that fingerprint
+- which final child issue ids belong to the completed result
+
+Paperclip does not need to mandate a specific storage shape in this document. The record may live in a dedicated table, source-issue execution state, interaction metadata, or another durable product surface. What matters is the contract:
+
+- the claim is durable before fan-out starts
+- partial progress is durable while fan-out is underway
+- the completed child result set is durable after fan-out finishes
+
+If a run creates some children and then dies, retries must continue from the same fingerprint and reuse the already-recorded partial result. They must not restart decomposition as if nothing happened.
+
+### Parent live path while decomposition is in flight
+
+While decomposition for an accepted fingerprint is incomplete, the source issue must expose an explicit live path for that same fingerprint.
+
+The accepted interaction by itself is only evidence that the plan was approved. It is not a sufficient live path once decomposition begins. The source issue must make it clear what moves the fingerprint forward next, such as:
+
+- the active decomposition run
+- a queued continuation wake for the same assignee
+- a monitor or explicit recovery action tied to the same decomposition claim
+- a blocked state that names the real blocker for finishing that claimed decomposition
+
+If the live run disappears, Paperclip must repair, resume, or visibly block the existing claim. It must not leave the source issue in a state where a second run can interpret the same acceptance as fresh permission to create sibling issues again.
+
+### Concurrent and repeat attempts
+
+Every later run that encounters the same accepted-plan fingerprint must consult the durable claim/result before creating children.
+
+- If no claim exists, the run may atomically create the claim and become the decomposition owner.
+- If a claim exists and is `in_flight`, the later run must reuse that claim. It may resume the same decomposition if it is the valid continuation owner, or it may exit after observing that another run already owns the work.
+- If a claim exists and is `completed`, the later run must reuse the recorded child result and must not create new sibling issues.
+- If the prior attempt ended after partial child creation, the retry must continue under the same fingerprint and preserve the already-created child ids.
+
+Concurrent accepted-plan runs are therefore idempotent relative to the fingerprint. Creating multiple child trees for the same `(sourceIssueId, acceptedPlanRevisionId)` pair is a product bug.
+
+## 8. Non-Terminal Issue Liveness Contract
 
 For agent-owned, non-terminal issues, Paperclip should never leave work in a state where nobody is responsible for the next move and nothing will wake or surface it.
 
@@ -292,13 +358,13 @@ A blocker chain is covered only when its unresolved leaf is live or explicitly w
 
 A `blocked` issue is stalled when the unresolved blocker leaf has no active run, queued wake, typed participant, pending interaction or approval, user owner, external owner/action, or recovery action. In that case the parent should show the first stalled leaf instead of presenting the dependency as calmly covered.
 
-## 8. Crash and Restart Recovery
+## 9. Crash and Restart Recovery
 
 Paperclip now treats crash/restart recovery as a stranded-assigned-work problem, not just a stranded-run problem.
 
 There are two distinct failure modes.
 
-### 8.1 Stranded assigned `todo`
+### 9.1 Stranded assigned `todo`
 
 Example:
 
@@ -314,7 +380,7 @@ Recovery rule:
 
 This is a dispatch recovery, not a continuation recovery.
 
-### 8.2 Stranded assigned `in_progress`
+### 9.2 Stranded assigned `in_progress`
 
 Example:
 
@@ -330,13 +396,13 @@ Recovery rule:
 
 This is an active-work continuity recovery.
 
-### 8.3 Recovery model-profile lane
+### 9.3 Recovery model-profile lane
 
 Cheap model profiles are only for status-only operational recovery overhead. Paperclip may request `modelProfile: "cheap"` for bounded recovery-owner work that updates task liveness, clears bad status, records a disposition, or asks for human/manager intervention. Those wakes must carry guard context such as `allowDeliverableWork: false`, `allowDocumentUpdates: false`, and `resumeRequiresNormalModel: true`.
 
 Automatic retries that can continue source work must use the original/normal model lane. This includes failed source-work retries, process-loss retries, transient/scheduled retries, max-turn continuations, source-assignee continuations, assigned-todo dispatch recovery, and any run that can update repo files, issue documents, plans, work products, or attachments. When a cheap status-only recovery determines that actual work remains, it must hand back to a normal-model worker run before source work or persistent deliverable updates resume. Cheap recovery hints must be scrubbed from copied retry, resume, child, and downstream source-work contexts.
 
-## 9. Startup and Periodic Reconciliation
+## 10. Startup and Periodic Reconciliation
 
 Startup recovery and periodic recovery are different from normal wakeup delivery.
 
@@ -350,7 +416,7 @@ On startup and on the periodic recovery loop, Paperclip now does five things in
 
 The stranded-work pass closes the gap where issue state survives a crash but the wake/run path does not. The silent-run scan covers the separate case where a live process exists but has stopped producing observable output. The productivity-review pass is later and separate; it reviews unusual progression patterns on assigned source issues, not stale run handles after a source issue already has a valid disposition.
 
-## 10. Silent Active-Run Watchdog
+## 11. Silent Active-Run Watchdog
 
 An active run can still be unhealthy even when its process is `running`. Paperclip treats prolonged output silence as a watchdog signal, not as proof that the run is failed.
 
@@ -402,7 +468,7 @@ This is distinct from productivity review. Productivity review asks whether an a
 
 Detached process cleanup is operational hygiene, not source issue liveness. Cleanup should be best-effort and auditable. If cleanup fails but the source issue is already terminal with same-run durable evidence, Paperclip should preserve the cleanup failure on the run/watchdog audit trail and route only the cleanup concern to bounded recovery when a real owner/action remains.
 
-## 11. Auto-Recover vs Explicit Recovery vs Human Escalation
+## 12. Auto-Recover vs Explicit Recovery vs Human Escalation
 
 Paperclip uses three different recovery outcomes, depending on how much it can safely infer.
 
@@ -446,7 +512,7 @@ Examples:
 
 In these cases Paperclip should leave a visible issue/comment trail instead of silently retrying.
 
-## 12. What This Does Not Mean
+## 13. What This Does Not Mean
 
 These semantics do not change V1 into an auto-reassignment system.
 
@@ -463,7 +529,7 @@ The recovery model is intentionally conservative:
 - open an explicit recovery action when the system can identify a bounded recovery owner/action
 - escalate visibly when the system cannot safely keep going
 
-## 13. Practical Interpretation
+## 14. Practical Interpretation
 
 For a board operator, the intended meaning is:
 

packages/db/src/migrations/0092_mighty_puma.sql

@@ -0,0 +1,28 @@
+CREATE TABLE "issue_plan_decompositions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"source_issue_id" uuid NOT NULL,
+	"accepted_plan_revision_id" uuid NOT NULL,
+	"accepted_interaction_id" uuid,
+	"status" text DEFAULT 'in_flight' NOT NULL,
+	"request_fingerprint" text NOT NULL,
+	"requested_child_count" integer DEFAULT 0 NOT NULL,
+	"requested_children" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"child_issue_ids" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"owner_agent_id" uuid,
+	"owner_user_id" text,
+	"owner_run_id" uuid,
+	"completed_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_plan_revision_id_document_revisions_id_fk" FOREIGN KEY ("accepted_plan_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_interaction_id_issue_thread_interactions_id_fk" FOREIGN KEY ("accepted_interaction_id") REFERENCES "public"."issue_thread_interactions"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_owner_agent_id_agents_id_fk" FOREIGN KEY ("owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_owner_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("owner_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "issue_plan_decompositions_company_source_status_idx" ON "issue_plan_decompositions" USING btree ("company_id","source_issue_id","status");--> statement-breakpoint
+CREATE INDEX "issue_plan_decompositions_active_owner_idx" ON "issue_plan_decompositions" USING btree ("company_id","owner_agent_id") WHERE "issue_plan_decompositions"."status" = 'in_flight';--> statement-breakpoint
+CREATE UNIQUE INDEX "issue_plan_decompositions_source_revision_uq" ON "issue_plan_decompositions" USING btree ("company_id","source_issue_id","accepted_plan_revision_id");

packages/db/src/migrations/meta/_journal.json

@@ -645,6 +645,13 @@
       "when": 1778810394522,
       "tag": "0091_old_swarm",
       "breakpoints": true
+    },
+    {
+      "idx": 92,
+      "version": "7",
+      "when": 1779999768200,
+      "tag": "0092_mighty_puma",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/src/schema/index.ts

@@ -32,6 +32,7 @@ export { workspaceRuntimeServices } from "./workspace_runtime_services.js";
 export { projectGoals } from "./project_goals.js";
 export { goals } from "./goals.js";
 export { issues } from "./issues.js";
+export { issuePlanDecompositions } from "./issue_plan_decompositions.js";
 export { issueRecoveryActions } from "./issue_recovery_actions.js";
 export { issueReferenceMentions } from "./issue_reference_mentions.js";
 export { issueRelations } from "./issue_relations.js";

packages/db/src/schema/issue_plan_decompositions.ts

@@ -0,0 +1,48 @@
+import { sql } from "drizzle-orm";
+import { pgTable, uuid, text, integer, timestamp, jsonb, index, uniqueIndex } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { documentRevisions } from "./document_revisions.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+import { issueThreadInteractions } from "./issue_thread_interactions.js";
+import { issues } from "./issues.js";
+
+export const issuePlanDecompositions = pgTable(
+  "issue_plan_decompositions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    sourceIssueId: uuid("source_issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
+    acceptedPlanRevisionId: uuid("accepted_plan_revision_id")
+      .notNull()
+      .references(() => documentRevisions.id, { onDelete: "cascade" }),
+    acceptedInteractionId: uuid("accepted_interaction_id")
+      .references(() => issueThreadInteractions.id, { onDelete: "set null" }),
+    status: text("status").notNull().default("in_flight"),
+    requestFingerprint: text("request_fingerprint").notNull(),
+    requestedChildCount: integer("requested_child_count").notNull().default(0),
+    requestedChildren: jsonb("requested_children").$type<Record<string, unknown>[]>().notNull().default(sql`'[]'::jsonb`),
+    childIssueIds: jsonb("child_issue_ids").$type<string[]>().notNull().default(sql`'[]'::jsonb`),
+    ownerAgentId: uuid("owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    ownerUserId: text("owner_user_id"),
+    ownerRunId: uuid("owner_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companySourceStatusIdx: index("issue_plan_decompositions_company_source_status_idx").on(
+      table.companyId,
+      table.sourceIssueId,
+      table.status,
+    ),
+    activeOwnerIdx: index("issue_plan_decompositions_active_owner_idx")
+      .on(table.companyId, table.ownerAgentId)
+      .where(sql`${table.status} = 'in_flight'`),
+    sourceRevisionUq: uniqueIndex("issue_plan_decompositions_source_revision_uq").on(
+      table.companyId,
+      table.sourceIssueId,
+      table.acceptedPlanRevisionId,
+    ),
+  }),
+);

packages/shared/src/index.ts

@@ -473,6 +473,12 @@ export type {
   RequestConfirmationTarget,
   RequestConfirmationPayload,
   RequestConfirmationResult,
+  AcceptedPlanDecompositionStatus,
+  AcceptedPlanDecompositionChild,
+  AcceptedPlanDecomposition,
+  AcceptedPlanDecompositionResult,
+  AcceptedPlanDecompositionChildIssue,
+  AcceptedPlanDecompositionSummary,
   IssueThreadInteractionBase,
   SuggestTasksInteraction,
   AskUserQuestionsInteraction,
@@ -868,6 +874,7 @@ export {
   createIssueSchema,
   createIssueInputSchema,
   createChildIssueSchema,
+  createAcceptedPlanDecompositionSchema,
   resolveCreateIssueStatusDefault,
   createIssueLabelSchema,
   issueBlockedInboxAttentionSchema,
@@ -936,6 +943,7 @@ export {
   releaseIssueTreeHoldSchema,
   type CreateIssue,
   type CreateChildIssue,
+  type CreateAcceptedPlanDecomposition,
   type CreateIssueLabel,
   type UpdateIssue,
   type ResolveIssueRecoveryAction,

packages/shared/src/types/index.ts

@@ -238,6 +238,12 @@ export type {
   RequestConfirmationTarget,
   RequestConfirmationPayload,
   RequestConfirmationResult,
+  AcceptedPlanDecompositionStatus,
+  AcceptedPlanDecompositionChild,
+  AcceptedPlanDecomposition,
+  AcceptedPlanDecompositionResult,
+  AcceptedPlanDecompositionChildIssue,
+  AcceptedPlanDecompositionSummary,
   IssueThreadInteractionBase,
   SuggestTasksInteraction,
   AskUserQuestionsInteraction,

packages/shared/src/types/instance.ts

@@ -29,6 +29,7 @@ export interface InstanceGeneralSettings {
 export interface InstanceExperimentalSettings {
   enableEnvironments: boolean;
   enableIsolatedWorkspaces: boolean;
+  enableIssuePlanDecompositions: boolean;
   enableCloudSync: boolean;
   autoRestartDevServerWhenIdle: boolean;
   enableIssueGraphLivenessAutoRecovery: boolean;

packages/shared/src/types/issue.ts

@@ -129,6 +129,71 @@ export interface LegacyPlanDocument {
   source: "issue_description";
 }
 
+export type AcceptedPlanDecompositionStatus = "in_flight" | "completed";
+
+export interface AcceptedPlanDecompositionChild {
+  projectId?: string | null;
+  projectWorkspaceId?: string | null;
+  goalId?: string | null;
+  blockedByIssueIds?: string[];
+  title: string;
+  description?: string | null;
+  status: IssueStatus;
+  workMode: IssueWorkMode;
+  priority: IssuePriority;
+  assigneeAgentId?: string | null;
+  assigneeUserId?: string | null;
+  requestDepth?: number;
+  billingCode?: string | null;
+  assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
+  executionPolicy?: IssueExecutionPolicy | null;
+  executionWorkspaceId?: string | null;
+  executionWorkspacePreference?: string | null;
+  executionWorkspaceSettings?: IssueExecutionWorkspaceSettings | null;
+  labelIds?: string[];
+  acceptanceCriteria?: string[];
+  blockParentUntilDone?: boolean;
+}
+
+export interface AcceptedPlanDecomposition {
+  id: string;
+  companyId: string;
+  sourceIssueId: string;
+  acceptedPlanRevisionId: string;
+  acceptedInteractionId: string | null;
+  status: AcceptedPlanDecompositionStatus;
+  requestFingerprint: string;
+  requestedChildCount: number;
+  childIssueIds: string[];
+  ownerAgentId: string | null;
+  ownerUserId: string | null;
+  ownerRunId: string | null;
+  completedAt: Date | string | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+}
+
+export interface AcceptedPlanDecompositionResult {
+  decomposition: AcceptedPlanDecomposition;
+  childIssueIds: string[];
+  newlyCreatedChildIssueIds: string[];
+}
+
+export interface AcceptedPlanDecompositionChildIssue {
+  id: string;
+  identifier: string | null;
+  title: string;
+  status: IssueStatus;
+  priority: IssuePriority;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+}
+
+export interface AcceptedPlanDecompositionSummary extends AcceptedPlanDecomposition {
+  acceptedPlanRevisionNumber: number | null;
+  childIssues: AcceptedPlanDecompositionChildIssue[];
+}
+
 export interface IssueRelationIssueSummary {
   id: string;
   identifier: string | null;

packages/shared/src/validators/index.ts

@@ -186,6 +186,7 @@ export {
   createIssueSchema,
   createIssueInputSchema,
   createChildIssueSchema,
+  createAcceptedPlanDecompositionSchema,
   resolveCreateIssueStatusDefault,
   createIssueLabelSchema,
   issueBlockedInboxAttentionSchema,
@@ -237,6 +238,7 @@ export {
   restoreIssueDocumentRevisionSchema,
   type CreateIssue,
   type CreateChildIssue,
+  type CreateAcceptedPlanDecomposition,
   type CreateIssueLabel,
   type UpdateIssue,
   type IssueExecutionWorkspaceSettings,

packages/shared/src/validators/instance.ts

@@ -38,6 +38,7 @@ export const patchInstanceGeneralSettingsSchema = instanceGeneralSettingsSchema.
 export const instanceExperimentalSettingsSchema = z.object({
   enableEnvironments: z.boolean().default(false),
   enableIsolatedWorkspaces: z.boolean().default(false),
+  enableIssuePlanDecompositions: z.boolean().default(false),
   enableCloudSync: z.boolean().default(false),
   autoRestartDevServerWhenIdle: z.boolean().default(false),
   enableIssueGraphLivenessAutoRecovery: z.boolean().default(false),

packages/shared/src/validators/issue.ts

@@ -412,6 +412,13 @@ export const createChildIssueSchema = withCreateIssueStatusDefault(createIssueBa
 
 export type CreateChildIssue = z.infer<typeof createChildIssueSchema>;
 
+export const createAcceptedPlanDecompositionSchema = z.object({
+  acceptedPlanRevisionId: z.string().uuid(),
+  children: z.array(createChildIssueSchema).min(1).max(25),
+});
+
+export type CreateAcceptedPlanDecomposition = z.infer<typeof createAcceptedPlanDecompositionSchema>;
+
 export const createIssueLabelSchema = z.object({
   name: z.string().trim().min(1).max(48),
   color: z.string().regex(/^#(?:[0-9a-fA-F]{6})$/, "Color must be a 6-digit hex value"),

server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts

@@ -7,15 +7,26 @@ import { promisify } from "node:util";
 import { eq, ne } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import {
+  activityLog,
+  agentRuntimeState,
   agentTaskSessions,
+  agentWakeupRequests,
   agents,
   companies,
+  companySkills,
   createDb,
+  documentRevisions,
+  documents,
   executionWorkspaces,
+  heartbeatRunEvents,
   heartbeatRuns,
+  issueComments,
+  issueDocuments,
+  issuePlanDecompositions,
   issues,
   projects,
   projectWorkspaces,
+  workspaceOperations,
 } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
@@ -97,6 +108,25 @@ describeEmbeddedPostgres("accepted plan workspace refresh", () => {
       const root = tempRoots.pop();
       if (root) await rm(root, { recursive: true, force: true }).catch(() => undefined);
     }
+    await db.delete(issuePlanDecompositions);
+    await db.delete(issueDocuments);
+    await db.delete(documentRevisions);
+    await db.delete(documents);
+    await db.delete(agentTaskSessions);
+    await db.delete(executionWorkspaces);
+    await db.delete(activityLog);
+    await db.delete(heartbeatRunEvents);
+    await db.delete(heartbeatRuns);
+    await db.delete(issueComments);
+    await db.delete(issues);
+    await db.delete(projectWorkspaces);
+    await db.delete(projects);
+    await db.delete(agentWakeupRequests);
+    await db.delete(agentRuntimeState);
+    await db.delete(agents);
+    await db.delete(workspaceOperations);
+    await db.delete(companySkills);
+    await db.delete(companies);
   });
 
   afterAll(async () => {
@@ -104,6 +134,57 @@ describeEmbeddedPostgres("accepted plan workspace refresh", () => {
     await tempDb?.cleanup();
   });
 
+  async function seedAcceptedPlanClaim(args: {
+    companyId: string;
+    issueId: string;
+    ownerAgentId: string;
+    status?: "in_flight" | "completed";
+  }) {
+    const documentId = randomUUID();
+    const revisionId = randomUUID();
+
+    await db.insert(documents).values({
+      id: documentId,
+      companyId: args.companyId,
+      title: "Plan",
+      format: "markdown",
+      latestBody: "Plan body",
+      latestRevisionId: revisionId,
+      latestRevisionNumber: 1,
+      createdByAgentId: args.ownerAgentId,
+      updatedByAgentId: args.ownerAgentId,
+    });
+    await db.insert(documentRevisions).values({
+      id: revisionId,
+      companyId: args.companyId,
+      documentId,
+      revisionNumber: 1,
+      title: "Plan",
+      format: "markdown",
+      body: "Plan body",
+      createdByAgentId: args.ownerAgentId,
+    });
+    await db.insert(issueDocuments).values({
+      companyId: args.companyId,
+      issueId: args.issueId,
+      documentId,
+      key: "plan",
+    });
+    await db.insert(issuePlanDecompositions).values({
+      companyId: args.companyId,
+      sourceIssueId: args.issueId,
+      acceptedPlanRevisionId: revisionId,
+      status: args.status ?? "in_flight",
+      requestFingerprint: `claim:${args.issueId}`,
+      requestedChildCount: 1,
+      requestedChildren: [{ title: "child-1" }],
+      childIssueIds: [],
+      ownerAgentId: args.ownerAgentId,
+      updatedAt: new Date(),
+      ...(args.status === "completed" ? { completedAt: new Date() } : {}),
+    });
+  }
+
   it("realizes an isolated workspace and drops stale shared task-session params before executing", async () => {
     const companyId = randomUUID();
     const projectId = randomUUID();
@@ -276,4 +357,451 @@ describeEmbeddedPostgres("accepted plan workspace refresh", () => {
     });
     expect(isolatedRows[0]?.cwd).not.toBe(repoRoot);
   }, 20_000);
+
+  it("forces a fresh session and suppresses accepted-plan continuation when another issue owns the in-flight claim", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const issueId = randomUUID();
+    const otherPlanningIssueId = randomUUID();
+    const agentId = randomUUID();
+    const repoRoot = await createGitRepo();
+    tempRoots.push(repoRoot);
+
+    await instanceSettingsService(db).updateExperimental({
+      enableIsolatedWorkspaces: false,
+    });
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Accepted Plan Routing",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary",
+      cwd: repoRoot,
+      isPrimary: true,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "idle",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(issues).values([
+      {
+        id: issueId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        title: "Later planning wake",
+        status: "in_progress",
+        workMode: "planning",
+        priority: "medium",
+        assigneeAgentId: agentId,
+        identifier: "PAP-9301",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      {
+        id: otherPlanningIssueId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        title: "Earlier accepted plan",
+        status: "in_progress",
+        workMode: "planning",
+        priority: "medium",
+        assigneeAgentId: agentId,
+        identifier: "PAP-9302",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    ]);
+    await seedAcceptedPlanClaim({
+      companyId,
+      issueId: otherPlanningIssueId,
+      ownerAgentId: agentId,
+      status: "in_flight",
+    });
+    await db.insert(agentTaskSessions).values({
+      companyId,
+      agentId,
+      adapterType: "codex_local",
+      taskKey: issueId,
+      sessionParamsJson: {
+        sessionId: "stale-cross-issue-session",
+        cwd: repoRoot,
+      },
+      sessionDisplayId: "stale-cross-issue-session",
+    });
+    adapterExecute.mockImplementationOnce(async () => {
+      await db.update(issues).set({ status: "done", updatedAt: new Date() }).where(eq(issues.id, issueId));
+      return {
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        sessionParams: { sessionId: "fresh-session" },
+        sessionDisplayId: "fresh-session",
+        summary: "Suppressed cross-issue accepted-plan continuation.",
+        provider: "test",
+        model: "test-model",
+      };
+    });
+
+    const heartbeat = heartbeatService(db);
+    const run = await heartbeat.wakeup(agentId, {
+      source: "automation",
+      triggerDetail: "system",
+      reason: "issue_blockers_resolved",
+      payload: {
+        issueId,
+        interactionId: "interaction-cross-issue",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+        mutation: "interaction",
+      },
+      contextSnapshot: {
+        issueId,
+        taskId: issueId,
+        wakeReason: "issue_blockers_resolved",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+      },
+    });
+
+    expect(run).not.toBeNull();
+    await vi.waitFor(async () => {
+      const latest = await heartbeat.getRun(run!.id);
+      expect(latest?.status).toBe("succeeded");
+    }, { timeout: 10_000 });
+
+    expect(adapterExecute).toHaveBeenCalledTimes(1);
+    const adapterInput = adapterExecute.mock.calls[0]?.[0] as {
+      runtime: { sessionId: string | null; sessionParams: Record<string, unknown> | null };
+      context: Record<string, unknown>;
+    };
+    expect(adapterInput.runtime.sessionId).toBeNull();
+    expect(adapterInput.runtime.sessionParams).toBeNull();
+    expect(adapterInput.context.acceptedPlanWakeRouting).toEqual(expect.objectContaining({
+      reason: "other_issue_claim_in_flight",
+      otherActiveClaimIssueId: otherPlanningIssueId,
+      otherActiveClaimIdentifier: "PAP-9302",
+    }));
+    expect(adapterInput.context.paperclipTaskMarkdown).toContain("Make the plan only.");
+    expect(adapterInput.context.paperclipTaskMarkdown).not.toContain("Create child issues from the approved plan only");
+  }, 20_000);
+
+  it("guards cross-issue accepted-plan retries even when the waking issue is standard work mode", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const issueId = randomUUID();
+    const otherPlanningIssueId = randomUUID();
+    const agentId = randomUUID();
+    const repoRoot = await createGitRepo();
+    tempRoots.push(repoRoot);
+
+    await instanceSettingsService(db).updateExperimental({
+      enableIsolatedWorkspaces: false,
+    });
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Accepted Plan Routing",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary",
+      cwd: repoRoot,
+      isPrimary: true,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "idle",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(issues).values([
+      {
+        id: issueId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        title: "Implementation wake after accepted plan",
+        status: "in_progress",
+        workMode: "standard",
+        priority: "medium",
+        assigneeAgentId: agentId,
+        identifier: "PAP-9401",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      {
+        id: otherPlanningIssueId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        title: "Earlier accepted plan",
+        status: "in_progress",
+        workMode: "planning",
+        priority: "medium",
+        assigneeAgentId: agentId,
+        identifier: "PAP-9402",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    ]);
+    await seedAcceptedPlanClaim({
+      companyId,
+      issueId: otherPlanningIssueId,
+      ownerAgentId: agentId,
+      status: "in_flight",
+    });
+    await db.insert(agentTaskSessions).values({
+      companyId,
+      agentId,
+      adapterType: "codex_local",
+      taskKey: issueId,
+      sessionParamsJson: {
+        sessionId: "stale-standard-cross-issue-session",
+        cwd: repoRoot,
+      },
+      sessionDisplayId: "stale-standard-cross-issue-session",
+    });
+    adapterExecute.mockImplementationOnce(async () => {
+      await db.update(issues).set({ status: "done", updatedAt: new Date() }).where(eq(issues.id, issueId));
+      return {
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        sessionParams: { sessionId: "fresh-session" },
+        sessionDisplayId: "fresh-session",
+        summary: "Suppressed cross-issue accepted-plan continuation for a standard-work wake.",
+        provider: "test",
+        model: "test-model",
+      };
+    });
+
+    const heartbeat = heartbeatService(db);
+    const run = await heartbeat.wakeup(agentId, {
+      source: "automation",
+      triggerDetail: "system",
+      reason: "issue_commented",
+      payload: {
+        issueId,
+        interactionId: "interaction-standard-cross-issue",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+        mutation: "interaction",
+      },
+      contextSnapshot: {
+        issueId,
+        taskId: issueId,
+        wakeReason: "issue_commented",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+        forceFreshSession: true,
+        workspaceRefreshReason: "accepted_plan_confirmation",
+      },
+    });
+
+    expect(run).not.toBeNull();
+    await vi.waitFor(async () => {
+      const latest = await heartbeat.getRun(run!.id);
+      expect(latest?.status).toBe("succeeded");
+    }, { timeout: 10_000 });
+
+    expect(adapterExecute).toHaveBeenCalledTimes(1);
+    const adapterInput = adapterExecute.mock.calls[0]?.[0] as {
+      runtime: { sessionId: string | null; sessionParams: Record<string, unknown> | null };
+      context: Record<string, unknown>;
+    };
+    expect(adapterInput.runtime.sessionId).toBeNull();
+    expect(adapterInput.runtime.sessionParams).toBeNull();
+    expect(adapterInput.context.acceptedPlanWakeRouting).toEqual(expect.objectContaining({
+      reason: "other_issue_claim_in_flight",
+      otherActiveClaimIssueId: otherPlanningIssueId,
+      otherActiveClaimIdentifier: "PAP-9402",
+    }));
+    expect(adapterInput.context.paperclipTaskMarkdown).toContain("Issue: \"PAP-9401\"");
+    expect(adapterInput.context.paperclipTaskMarkdown).not.toContain("Create child issues from the approved plan only");
+  }, 20_000);
+
+  it("preserves accepted-plan continuation resume state when the wake issue owns the in-flight claim", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const issueId = randomUUID();
+    const agentId = randomUUID();
+    const repoRoot = await createGitRepo();
+    tempRoots.push(repoRoot);
+
+    await instanceSettingsService(db).updateExperimental({
+      enableIsolatedWorkspaces: false,
+    });
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Accepted Plan Retry",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary",
+      cwd: repoRoot,
+      isPrimary: true,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "idle",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(issues).values({
+      id: issueId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      title: "Accepted plan retry",
+      status: "in_progress",
+      workMode: "planning",
+      priority: "medium",
+      assigneeAgentId: agentId,
+      identifier: "PAP-9303",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await seedAcceptedPlanClaim({
+      companyId,
+      issueId,
+      ownerAgentId: agentId,
+      status: "in_flight",
+    });
+    await db.insert(agentTaskSessions).values({
+      companyId,
+      agentId,
+      adapterType: "codex_local",
+      taskKey: issueId,
+      sessionParamsJson: {
+        sessionId: "accepted-plan-retry-session",
+        cwd: repoRoot,
+      },
+      sessionDisplayId: "accepted-plan-retry-session",
+    });
+    adapterExecute.mockImplementationOnce(async () => {
+      await db.update(issues).set({ status: "done", updatedAt: new Date() }).where(eq(issues.id, issueId));
+      return {
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        sessionParams: { sessionId: "accepted-plan-retry-session" },
+        sessionDisplayId: "accepted-plan-retry-session",
+        summary: "Resumed accepted-plan continuation for the same issue.",
+        provider: "test",
+        model: "test-model",
+      };
+    });
+
+    const heartbeat = heartbeatService(db);
+    const run = await heartbeat.wakeup(agentId, {
+      source: "automation",
+      triggerDetail: "system",
+      reason: "issue_blockers_resolved",
+      payload: {
+        issueId,
+        interactionId: "interaction-same-issue",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+        mutation: "interaction",
+      },
+      contextSnapshot: {
+        issueId,
+        taskId: issueId,
+        wakeReason: "issue_blockers_resolved",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+      },
+    });
+
+    expect(run).not.toBeNull();
+    await vi.waitFor(async () => {
+      const latest = await heartbeat.getRun(run!.id);
+      expect(latest?.status).toBe("succeeded");
+    }, { timeout: 10_000 });
+
+    expect(adapterExecute).toHaveBeenCalledTimes(1);
+    const adapterInput = adapterExecute.mock.calls[0]?.[0] as {
+      runtime: { sessionId: string | null; sessionParams: Record<string, unknown> | null };
+      context: Record<string, unknown>;
+    };
+    expect(adapterInput.runtime.sessionId).toBe("accepted-plan-retry-session");
+    expect(adapterInput.context.acceptedPlanWakeRouting).toBeUndefined();
+    expect(adapterInput.context.paperclipTaskMarkdown).toContain("Create child issues from the approved plan only");
+  }, 20_000);
 });

server/src/__tests__/heartbeat-context-summary.test.ts

@@ -55,6 +55,23 @@ describe("buildPaperclipTaskMarkdown", () => {
     expect(acceptedConfirmation).not.toContain("Make the plan only.");
   });
 
+  it("adds accepted-plan continuation guidance for standard-work issues when the wake is flagged as a plan continuation", () => {
+    const acceptedConfirmation = buildPaperclipTaskMarkdown({
+      issue: {
+        id: "issue-2",
+        identifier: "PAP-415",
+        title: "Implement the fix",
+        workMode: "standard",
+        description: null,
+      },
+      acceptedPlanContinuation: true,
+    });
+
+    expect(acceptedConfirmation).toContain("Accepted plan directive:");
+    expect(acceptedConfirmation).toContain("Create child issues from the approved plan only");
+    expect(acceptedConfirmation).not.toContain("- Work mode: \"planning\"");
+  });
+
   it("prefers ordinary comment planning guidance over stale accepted confirmation state", () => {
     const commentWake = buildPaperclipTaskMarkdown({
       issue: {

server/src/__tests__/heartbeat-process-recovery.test.ts

@@ -11,6 +11,9 @@ import {
   companySkills,
   companies,
   costEvents,
+  documentAnnotationAnchorSnapshots,
+  documentAnnotationComments,
+  documentAnnotationThreads,
   createDb,
   documentRevisions,
   documents,
@@ -20,8 +23,10 @@ import {
   heartbeatRuns,
   issueComments,
   issueDocuments,
+  issuePlanDecompositions,
   issueRecoveryActions,
   issueRelations,
+  issueThreadInteractions,
   issueTreeHoldMembers,
   issueTreeHolds,
   issueWorkProducts,
@@ -323,6 +328,11 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     await db.delete(costEvents);
     await db.delete(environmentLeases);
     await db.delete(environments);
+    await db.delete(issuePlanDecompositions);
+    await db.delete(issueThreadInteractions);
+    await db.delete(documentAnnotationComments);
+    await db.delete(documentAnnotationAnchorSnapshots);
+    await db.delete(documentAnnotationThreads);
     await db.delete(issueWorkProducts);
     await db.delete(issueComments);
     await db.delete(issueDocuments);
@@ -368,6 +378,14 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     }
     for (let attempt = 0; attempt < 5; attempt += 1) {
       await db.delete(companySkills);
+      await db.delete(issuePlanDecompositions);
+      await db.delete(issueThreadInteractions);
+      await db.delete(documentAnnotationComments);
+      await db.delete(documentAnnotationAnchorSnapshots);
+      await db.delete(documentAnnotationThreads);
+      await db.delete(issueDocuments);
+      await db.delete(documentRevisions);
+      await db.delete(documents);
       try {
         await db.delete(companies);
         break;

server/src/__tests__/instance-settings-routes.test.ts

@@ -64,6 +64,7 @@ describe("instance settings routes", () => {
     mockInstanceSettingsService.getExperimental.mockResolvedValue({
       enableEnvironments: false,
       enableIsolatedWorkspaces: false,
+      enableIssuePlanDecompositions: false,
       enableCloudSync: false,
       autoRestartDevServerWhenIdle: false,
       enableIssueGraphLivenessAutoRecovery: true,
@@ -82,6 +83,7 @@ describe("instance settings routes", () => {
       experimental: {
         enableEnvironments: true,
         enableIsolatedWorkspaces: true,
+        enableIssuePlanDecompositions: true,
         enableCloudSync: true,
         autoRestartDevServerWhenIdle: false,
         enableIssueGraphLivenessAutoRecovery: true,
@@ -125,6 +127,7 @@ describe("instance settings routes", () => {
     expect(getRes.body).toEqual({
       enableEnvironments: false,
       enableIsolatedWorkspaces: false,
+      enableIssuePlanDecompositions: false,
       enableCloudSync: false,
       autoRestartDevServerWhenIdle: false,
       enableIssueGraphLivenessAutoRecovery: true,

server/src/__tests__/instance-settings-service.test.ts

@@ -6,6 +6,7 @@ describe("instance settings service", () => {
     expect(normalizeExperimentalSettings({
       enableEnvironments: true,
       enableIsolatedWorkspaces: true,
+      enableIssuePlanDecompositions: true,
       enableCloudSync: true,
       autoRestartDevServerWhenIdle: true,
       enableIssueGraphLivenessAutoRecovery: true,
@@ -14,6 +15,7 @@ describe("instance settings service", () => {
     })).toEqual({
       enableEnvironments: true,
       enableIsolatedWorkspaces: true,
+      enableIssuePlanDecompositions: true,
       enableCloudSync: true,
       autoRestartDevServerWhenIdle: true,
       enableIssueGraphLivenessAutoRecovery: true,

server/src/__tests__/issue-thread-interaction-routes.test.ts

@@ -537,6 +537,14 @@ describe.sequential("issue thread interaction routes", () => {
         payload: {
           version: 1,
           prompt: "Approve this plan?",
+          target: {
+            type: "issue_document",
+            issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+            documentId: "document-plan",
+            key: "plan",
+            revisionId: "revision-plan",
+            revisionNumber: 1,
+          },
         },
         result: {
           version: 1,
@@ -572,6 +580,65 @@ describe.sequential("issue thread interaction routes", () => {
     );
   });
 
+  it("forces a fresh workspace-aware session when accepting a plan document confirmation on a standard-work issue", async () => {
+    mockIssueService.getById.mockResolvedValueOnce(createIssue({ workMode: "standard" }));
+    mockInteractionService.acceptInteraction.mockResolvedValueOnce({
+      interaction: {
+        id: "interaction-standard-plan",
+        companyId: "company-1",
+        issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+        kind: "request_confirmation",
+        status: "accepted",
+        continuationPolicy: "wake_assignee_on_accept",
+        idempotencyKey: "confirmation:issue:plan:revision-standard",
+        sourceCommentId: null,
+        sourceRunId: "run-standard-plan",
+        payload: {
+          version: 1,
+          prompt: "Approve this plan?",
+          target: {
+            type: "issue_document",
+            issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+            documentId: "document-plan",
+            key: "plan",
+            revisionId: "revision-standard",
+            revisionNumber: 2,
+          },
+        },
+        result: {
+          version: 1,
+          outcome: "accepted",
+        },
+        createdAt: "2026-04-20T12:00:00.000Z",
+        updatedAt: "2026-04-20T12:05:00.000Z",
+        resolvedAt: "2026-04-20T12:05:00.000Z",
+      },
+      createdIssues: [],
+    });
+    const app = await createApp();
+
+    const res = await request(app)
+      .post("/api/issues/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/interactions/interaction-standard-plan/accept")
+      .send({});
+
+    expect(res.status).toBe(200);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledTimes(1);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(
+      ASSIGNEE_AGENT_ID,
+      expect.objectContaining({
+        reason: "issue_commented",
+        contextSnapshot: expect.objectContaining({
+          issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+          interactionId: "interaction-standard-plan",
+          interactionKind: "request_confirmation",
+          interactionStatus: "accepted",
+          forceFreshSession: true,
+          workspaceRefreshReason: "accepted_plan_confirmation",
+        }),
+      }),
+    );
+  });
+
   it("wakes the returned agent when accepting an agent-authored confirmation from a board review assignee", async () => {
     mockIssueService.getById.mockResolvedValueOnce(createIssue({
       status: "in_review",

server/src/__tests__/issues-service.test.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { eq } from "drizzle-orm";
+import { asc, eq } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { sql } from "drizzle-orm";
 import {
@@ -7,6 +7,8 @@ import {
   agents,
   companies,
   createDb,
+  documentRevisions,
+  documents,
   environments,
   executionWorkspaces,
   goals,
@@ -14,7 +16,10 @@ import {
   instanceSettings,
   issueComments,
   issueInboxArchives,
+  issueDocuments,
+  issuePlanDecompositions,
   issueRelations,
+  issueThreadInteractions,
   issues,
   projectWorkspaces,
   projects,
@@ -3236,3 +3241,702 @@ describeEmbeddedPostgres("issueService.clearExecutionRunIfTerminal", () => {
     expect(row).toEqual({ executionRunId: null, executionLockedAt: null });
   });
 });
+
+describeEmbeddedPostgres("accepted plan decomposition", () => {
+  let db!: ReturnType<typeof createDb>;
+  let svc!: ReturnType<typeof issueService>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-accepted-plan-decomposition-");
+    db = createDb(tempDb.connectionString);
+    svc = issueService(db);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(issuePlanDecompositions);
+    await db.delete(issueThreadInteractions);
+    await db.delete(issueDocuments);
+    await db.delete(documentRevisions);
+    await db.delete(documents);
+    await db.delete(issueComments);
+    await db.delete(issueRelations);
+    await db.delete(issueInboxArchives);
+    await db.delete(activityLog);
+    await db.delete(issues);
+    await db.delete(executionWorkspaces);
+    await db.delete(projectWorkspaces);
+    await db.delete(projects);
+    await db.delete(goals);
+    await db.delete(heartbeatRuns);
+    await db.delete(agents);
+    await db.delete(instanceSettings);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function seedAcceptedPlanContext() {
+    const companyId = randomUUID();
+    const goalId = randomUUID();
+    const assigneeAgentId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await instanceSettingsService(db).updateExperimental({ enableIsolatedWorkspaces: false });
+    await db.insert(agents).values({
+      id: assigneeAgentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+    await db.insert(goals).values({
+      id: goalId,
+      companyId,
+      title: "Accepted plan decomposition",
+      level: "task",
+      status: "active",
+    });
+
+    return { companyId, goalId, assigneeAgentId };
+  }
+
+  async function seedAcceptedPlanIssue(args?: {
+    companyId?: string;
+    goalId?: string;
+    assigneeAgentId?: string;
+    sourceIssueId?: string;
+    issueTitle?: string;
+    workMode?: "planning" | "standard";
+  }) {
+    const companyId = args?.companyId ?? randomUUID();
+    const goalId = args?.goalId ?? randomUUID();
+    const assigneeAgentId = args?.assigneeAgentId ?? randomUUID();
+    const sourceIssueId = args?.sourceIssueId ?? randomUUID();
+    const planDocumentId = randomUUID();
+    const acceptedPlanRevisionId = randomUUID();
+    const acceptedInteractionId = randomUUID();
+
+    if (!args?.companyId || !args?.goalId || !args?.assigneeAgentId) {
+      await db.insert(companies).values({
+        id: companyId,
+        name: "Paperclip",
+        issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+        requireBoardApprovalForNewAgents: false,
+      });
+      await instanceSettingsService(db).updateExperimental({ enableIsolatedWorkspaces: false });
+      await db.insert(agents).values({
+        id: assigneeAgentId,
+        companyId,
+        name: "CodexCoder",
+        role: "engineer",
+        status: "active",
+        adapterType: "codex_local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      });
+      await db.insert(goals).values({
+        id: goalId,
+        companyId,
+        title: "Accepted plan decomposition",
+        level: "task",
+        status: "active",
+      });
+    }
+
+    await db.insert(issues).values({
+      id: sourceIssueId,
+      companyId,
+      goalId,
+      title: args?.issueTitle ?? "Planning issue",
+      status: "in_progress",
+      priority: "medium",
+      workMode: args?.workMode ?? "planning",
+      assigneeAgentId: assigneeAgentId,
+    });
+    await db.insert(documents).values({
+      id: planDocumentId,
+      companyId,
+      title: "Plan",
+      format: "markdown",
+      latestBody: "Plan body",
+      latestRevisionId: acceptedPlanRevisionId,
+      latestRevisionNumber: 1,
+      createdByAgentId: assigneeAgentId,
+      updatedByAgentId: assigneeAgentId,
+    });
+    await db.insert(documentRevisions).values({
+      id: acceptedPlanRevisionId,
+      companyId,
+      documentId: planDocumentId,
+      revisionNumber: 1,
+      title: "Plan",
+      format: "markdown",
+      body: "Plan body",
+      createdByAgentId: assigneeAgentId,
+    });
+    await db.insert(issueDocuments).values({
+      companyId,
+      issueId: sourceIssueId,
+      documentId: planDocumentId,
+      key: "plan",
+    });
+    await db.insert(issueThreadInteractions).values({
+      id: acceptedInteractionId,
+      companyId,
+      issueId: sourceIssueId,
+      kind: "request_confirmation",
+      status: "accepted",
+      continuationPolicy: "wake_assignee",
+      payload: {
+        version: 1,
+        prompt: "Approve this plan?",
+        target: {
+          type: "issue_document",
+          issueId: sourceIssueId,
+          documentId: planDocumentId,
+          key: "plan",
+          revisionId: acceptedPlanRevisionId,
+          revisionNumber: 1,
+        },
+      },
+      result: {
+        version: 1,
+        outcome: "accepted",
+      },
+      resolvedAt: new Date(),
+      createdByUserId: "local-board",
+      resolvedByUserId: "local-board",
+    });
+
+    return { companyId, sourceIssueId, acceptedPlanRevisionId, assigneeAgentId };
+  }
+
+  async function getAcceptedPlanClaim(sourceIssueId: string) {
+    return db
+      .select()
+      .from(issuePlanDecompositions)
+      .where(eq(issuePlanDecompositions.sourceIssueId, sourceIssueId))
+      .then((rows) => rows[0] ?? null);
+  }
+
+  it("reuses the same child issue set on repeat decomposition attempts for an accepted plan revision", async () => {
+    const { companyId, sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+
+    const children = [
+      {
+        title: "Implement the claim table",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+        assigneeAgentId,
+      },
+      {
+        title: "Add decomposition route tests",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+    ];
+
+    const first = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+
+    expect(first.decomposition).not.toHaveProperty("requestedChildren");
+    expect(first.childIssueIds).toHaveLength(2);
+    expect(first.newlyCreatedIssues).toHaveLength(2);
+    expect(first.decomposition.status).toBe("completed");
+
+    const second = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+
+    expect(second.childIssueIds).toEqual(first.childIssueIds);
+    expect(second.newlyCreatedIssues).toHaveLength(0);
+    expect(second.decomposition.status).toBe("completed");
+
+    const persistedClaims = await db
+      .select()
+      .from(issuePlanDecompositions)
+      .where(eq(issuePlanDecompositions.sourceIssueId, sourceIssueId));
+    expect(persistedClaims).toHaveLength(1);
+    expect(persistedClaims[0]?.requestedChildCount).toBe(2);
+    expect(persistedClaims[0]?.childIssueIds).toEqual(first.childIssueIds);
+
+    const childrenRows = await db
+      .select({ id: issues.id, title: issues.title })
+      .from(issues)
+      .where(eq(issues.parentId, sourceIssueId));
+    expect(childrenRows).toHaveLength(2);
+    expect(childrenRows.map((row) => row.id).sort()).toEqual([...first.childIssueIds].sort());
+
+    const companyIssues = await svc.list(companyId, { parentId: sourceIssueId });
+    expect(companyIssues).toHaveLength(2);
+  });
+
+  it("rejects a different child set for the same accepted plan fingerprint", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+
+    await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Implement the claim table",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    });
+
+    await expect(svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Implement the claim table",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+        {
+          title: "This duplicate should be rejected",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    })).rejects.toMatchObject({
+      status: 409,
+    });
+  });
+
+  it("allows accepted-plan decomposition on a standard-work issue with an accepted plan document", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue({
+      workMode: "standard",
+      issueTitle: "Implement after planning",
+    });
+
+    const result = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Implement the approved first slice",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    });
+
+    expect(result.childIssueIds).toHaveLength(1);
+    expect(result.newlyCreatedIssues).toHaveLength(1);
+    expect(result.decomposition.status).toBe("completed");
+  });
+
+  it("serializes concurrent accepted-plan retries for the same parent issue without duplicate children", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+    const children = [
+      {
+        title: "Persist exact-once decomposition claim",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+      {
+        title: "Guard concurrent retry callers",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+    ];
+
+    const initial = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+    const claim = await getAcceptedPlanClaim(sourceIssueId);
+    expect(claim).not.toBeNull();
+
+    for (const childIssueId of initial.childIssueIds) {
+      await db.delete(issues).where(eq(issues.id, childIssueId));
+    }
+    await db
+      .update(issuePlanDecompositions)
+      .set({
+        status: "in_flight",
+        childIssueIds: [],
+        completedAt: null,
+        updatedAt: new Date(),
+      })
+      .where(eq(issuePlanDecompositions.id, claim!.id));
+
+    const svcA = issueService(db);
+    const svcB = issueService(db);
+    const [first, second] = await Promise.all([
+      svcA.decomposeAcceptedPlan(sourceIssueId, {
+        acceptedPlanRevisionId,
+        children,
+        actorAgentId: assigneeAgentId,
+      }),
+      svcB.decomposeAcceptedPlan(sourceIssueId, {
+        acceptedPlanRevisionId,
+        children,
+        actorAgentId: assigneeAgentId,
+      }),
+    ]);
+
+    expect(first.childIssueIds).toEqual(second.childIssueIds);
+    expect(first.childIssueIds).toHaveLength(2);
+    expect(first.newlyCreatedIssues.length + second.newlyCreatedIssues.length).toBe(2);
+
+    const persistedClaim = await getAcceptedPlanClaim(sourceIssueId);
+    expect(persistedClaim?.status).toBe("completed");
+    expect(persistedClaim?.childIssueIds).toEqual(first.childIssueIds);
+
+    const childrenRows = await db
+      .select({ id: issues.id, title: issues.title })
+      .from(issues)
+      .where(eq(issues.parentId, sourceIssueId));
+    expect(childrenRows).toHaveLength(2);
+    expect(childrenRows.map((row) => row.id).sort()).toEqual([...first.childIssueIds].sort());
+  });
+
+  it("rejects another planning parent's accepted revision even when both issues share the assignee", async () => {
+    const { companyId, goalId, assigneeAgentId } = await seedAcceptedPlanContext();
+    const firstIssue = await seedAcceptedPlanIssue({
+      companyId,
+      goalId,
+      assigneeAgentId,
+      issueTitle: "Earlier accepted plan",
+    });
+    const secondIssue = await seedAcceptedPlanIssue({
+      companyId,
+      goalId,
+      assigneeAgentId,
+      issueTitle: "Later accepted plan",
+    });
+
+    await svc.decomposeAcceptedPlan(firstIssue.sourceIssueId, {
+      acceptedPlanRevisionId: firstIssue.acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Decompose the first issue only",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    });
+
+    await expect(svc.decomposeAcceptedPlan(secondIssue.sourceIssueId, {
+      acceptedPlanRevisionId: firstIssue.acceptedPlanRevisionId,
+      children: [
+        {
+          title: "This must not land on the second parent",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    })).rejects.toMatchObject({
+      status: 422,
+    });
+
+    const secondIssueChildren = await db
+      .select({ id: issues.id })
+      .from(issues)
+      .where(eq(issues.parentId, secondIssue.sourceIssueId));
+    expect(secondIssueChildren).toHaveLength(0);
+  });
+
+  it("resumes partial child creation under the claimed fingerprint without duplicating completed children", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+    const children = [
+      {
+        title: "Create the first child once",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+      {
+        title: "Recreate only the missing tail child",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+    ];
+
+    const initial = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+    const claim = await getAcceptedPlanClaim(sourceIssueId);
+    expect(claim).not.toBeNull();
+
+    const [firstChildId, secondChildId] = initial.childIssueIds;
+    expect(firstChildId).toBeTruthy();
+    expect(secondChildId).toBeTruthy();
+
+    await db.delete(issues).where(eq(issues.id, secondChildId!));
+    await db
+      .update(issuePlanDecompositions)
+      .set({
+        status: "in_flight",
+        childIssueIds: [firstChildId!],
+        completedAt: null,
+        updatedAt: new Date(),
+      })
+      .where(eq(issuePlanDecompositions.id, claim!.id));
+
+    const retried = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+
+    expect(retried.decomposition.status).toBe("completed");
+    expect(retried.childIssueIds[0]).toBe(firstChildId);
+    expect(retried.newlyCreatedIssues).toHaveLength(1);
+    expect(retried.newlyCreatedIssues[0]?.title).toBe("Recreate only the missing tail child");
+
+    const childrenRows = await db
+      .select({ id: issues.id, title: issues.title })
+      .from(issues)
+      .where(eq(issues.parentId, sourceIssueId));
+    expect(childrenRows).toHaveLength(2);
+    expect(childrenRows.some((row) => row.id === firstChildId)).toBe(true);
+    expect(childrenRows.map((row) => row.title).sort()).toEqual(children.map((child) => child.title).sort());
+  });
+
+  it("resumes a partial decomposition after reassignment when only actor metadata changes", async () => {
+    const { companyId, sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+    const reassignedAgentId = randomUUID();
+    await db.insert(agents).values({
+      id: reassignedAgentId,
+      companyId,
+      name: "SecondCoder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+
+    const children = [
+      {
+        title: "Keep the original child",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+        createdByAgentId: assigneeAgentId,
+        actorAgentId: assigneeAgentId,
+      },
+      {
+        title: "Create only the missing child after reassignment",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+        createdByAgentId: assigneeAgentId,
+        actorAgentId: assigneeAgentId,
+      },
+    ];
+
+    const initial = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+    const claim = await getAcceptedPlanClaim(sourceIssueId);
+    const [firstChildId, secondChildId] = initial.childIssueIds;
+
+    expect(claim).not.toBeNull();
+    expect(firstChildId).toBeTruthy();
+    expect(secondChildId).toBeTruthy();
+
+    await db.delete(issues).where(eq(issues.id, secondChildId!));
+    await db
+      .update(issues)
+      .set({ assigneeAgentId: reassignedAgentId, updatedAt: new Date() })
+      .where(eq(issues.id, sourceIssueId));
+    await db
+      .update(issuePlanDecompositions)
+      .set({
+        status: "in_flight",
+        childIssueIds: [firstChildId!],
+        completedAt: null,
+        ownerAgentId: assigneeAgentId,
+        updatedAt: new Date(),
+      })
+      .where(eq(issuePlanDecompositions.id, claim!.id));
+
+    const retried = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: children.map((child) => ({
+        ...child,
+        createdByAgentId: reassignedAgentId,
+        actorAgentId: reassignedAgentId,
+      })),
+      actorAgentId: reassignedAgentId,
+    });
+
+    expect(retried.decomposition.status).toBe("completed");
+    expect(retried.decomposition.ownerAgentId).toBe(reassignedAgentId);
+    expect(retried.childIssueIds[0]).toBe(firstChildId);
+    expect(retried.newlyCreatedIssues).toHaveLength(1);
+    expect(retried.newlyCreatedIssues[0]?.title).toBe("Create only the missing child after reassignment");
+
+    const childrenRows = await db
+      .select({ id: issues.id, title: issues.title, createdByAgentId: issues.createdByAgentId })
+      .from(issues)
+      .where(eq(issues.parentId, sourceIssueId))
+      .orderBy(asc(issues.createdAt), asc(issues.id));
+    expect(childrenRows).toHaveLength(2);
+    expect(childrenRows.map((row) => row.id).sort()).toEqual([...retried.childIssueIds].sort());
+    expect(childrenRows.find((row) => row.id !== firstChildId)?.createdByAgentId).toBe(reassignedAgentId);
+  });
+
+  it("preserves the existing live claim owner when another actor resumes the same fingerprint", async () => {
+    const { companyId, sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+    const competingAgentId = randomUUID();
+    const liveOwnerRunId = randomUUID();
+    const competingRunId = randomUUID();
+    await db.insert(agents).values({
+      id: competingAgentId,
+      companyId,
+      name: "SecondCoder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+    await db.insert(heartbeatRuns).values([
+      {
+        id: liveOwnerRunId,
+        companyId,
+        agentId: assigneeAgentId,
+        status: "running",
+        invocationSource: "manual",
+      },
+      {
+        id: competingRunId,
+        companyId,
+        agentId: competingAgentId,
+        status: "running",
+        invocationSource: "manual",
+      },
+    ]);
+
+    const children = [
+      {
+        title: "Keep the first created child",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+      {
+        title: "Create the missing second child",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+    ];
+
+    const initial = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+      actorRunId: liveOwnerRunId,
+    });
+    const [firstChildId, secondChildId] = initial.childIssueIds;
+    const claim = await getAcceptedPlanClaim(sourceIssueId);
+
+    await db.delete(issues).where(eq(issues.id, secondChildId!));
+    await db
+      .update(issuePlanDecompositions)
+      .set({
+        status: "in_flight",
+        childIssueIds: [firstChildId!],
+        completedAt: null,
+        ownerAgentId: assigneeAgentId,
+        ownerRunId: liveOwnerRunId,
+        updatedAt: new Date(),
+      })
+      .where(eq(issuePlanDecompositions.id, claim!.id));
+
+    const retried = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: competingAgentId,
+      actorRunId: competingRunId,
+    });
+
+    expect(retried.decomposition.status).toBe("completed");
+    expect(retried.decomposition.ownerAgentId).toBe(assigneeAgentId);
+    expect(retried.decomposition.ownerRunId).toBe(liveOwnerRunId);
+  });
+
+  it("lists persisted decompositions with child issue summaries", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+
+    const initial = await svc.listAcceptedPlanDecompositions(sourceIssueId);
+    expect(initial).toEqual([]);
+
+    const result = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Surface decomposition status in operator UI",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+        {
+          title: "Add regression coverage",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    });
+
+    const decompositions = await svc.listAcceptedPlanDecompositions(sourceIssueId);
+    expect(decompositions).toHaveLength(1);
+    const [record] = decompositions;
+    expect(record?.status).toBe("completed");
+    expect(record?.acceptedPlanRevisionId).toBe(acceptedPlanRevisionId);
+    expect(record?.acceptedPlanRevisionNumber).toBeTypeOf("number");
+    expect(record?.childIssues.map((child) => child.id).sort()).toEqual(
+      [...result.childIssueIds].sort(),
+    );
+    expect(record).not.toHaveProperty("requestedChildren");
+    expect(record?.childIssues.every((child) => typeof child.title === "string")).toBe(true);
+  });
+});

server/src/routes/issues.ts

@@ -22,6 +22,7 @@ import {
   createIssueThreadInteractionSchema,
   createIssueWorkProductSchema,
   createIssueLabelSchema,
+  createAcceptedPlanDecompositionSchema,
   checkoutIssueSchema,
   createDocumentAnnotationCommentSchema,
   createDocumentAnnotationThreadSchema,
@@ -99,6 +100,7 @@ import { assertEnvironmentSelectionForCompany } from "./environment-selection.js
 import { executionWorkspaceService as executionWorkspaceServiceDirect } from "../services/execution-workspaces.js";
 import { feedbackService } from "../services/feedback.js";
 import { instanceSettingsService } from "../services/instance-settings.js";
+import { readAcceptedPlanConfirmationTarget } from "../services/issues.js";
 import { environmentService } from "../services/environments.js";
 import { redactSensitiveText } from "../redaction.js";
 import {
@@ -3692,6 +3694,151 @@ export function issueRoutes(
     res.status(201).json(issue);
   });
 
+  router.get("/issues/:id/accepted-plan-decompositions", async (req, res) => {
+    const sourceIssueId = req.params.id as string;
+    const sourceIssue = await svc.getById(sourceIssueId);
+    if (!sourceIssue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, sourceIssue.companyId);
+    const decompositions = await svc.listAcceptedPlanDecompositions(sourceIssue.id);
+    res.json(decompositions);
+  });
+
+  router.post("/issues/:id/accepted-plan-decompositions", validate(createAcceptedPlanDecompositionSchema), async (req, res) => {
+    const sourceIssueId = req.params.id as string;
+    const sourceIssue = await svc.getById(sourceIssueId);
+    if (!sourceIssue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, sourceIssue.companyId);
+    if (!(await assertAgentIssueMutationAllowed(req, res, sourceIssue))) return;
+
+    for (const child of req.body.children as Array<typeof req.body.children[number]>) {
+      assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(child));
+      if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, sourceIssue, child))) return;
+      if (child.assigneeAgentId || child.assigneeUserId) {
+        await assertCanAssignTasks(req, sourceIssue.companyId, {
+          projectId: child.projectId ?? sourceIssue.projectId ?? null,
+          parentIssueId: sourceIssue.id,
+          assigneeAgentId: child.assigneeAgentId ?? null,
+          assigneeUserId: child.assigneeUserId ?? null,
+        });
+      }
+      await assertIssueEnvironmentSelection(sourceIssue.companyId, child.executionWorkspaceSettings?.environmentId);
+    }
+
+    const actor = getActorInfo(req);
+    const normalizedChildren = req.body.children.map((child: typeof req.body.children[number]) => {
+      const executionPolicy = applyActorMonitorScheduledBy(
+        normalizeIssueExecutionPolicy(child.executionPolicy),
+        actor.actorType,
+      );
+      assertCanManageIssueMonitor(req, child.assigneeAgentId ?? null, Boolean(executionPolicy?.monitor));
+      return {
+        ...child,
+        executionPolicy,
+        createdByAgentId: actor.agentId,
+        createdByUserId: actor.actorType === "user" ? actor.actorId : null,
+        actorAgentId: actor.agentId,
+        actorUserId: actor.actorType === "user" ? actor.actorId : null,
+      };
+    });
+
+    const result = await svc.decomposeAcceptedPlan(sourceIssue.id, {
+      acceptedPlanRevisionId: req.body.acceptedPlanRevisionId,
+      children: normalizedChildren,
+      actorAgentId: actor.agentId,
+      actorUserId: actor.actorType === "user" ? actor.actorId : null,
+      actorRunId: actor.runId ?? null,
+    });
+
+    await logActivity(db, {
+      companyId: sourceIssue.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "issue.accepted_plan_decomposition_updated",
+      entityType: "issue",
+      entityId: sourceIssue.id,
+      details: {
+        identifier: sourceIssue.identifier,
+        acceptedPlanRevisionId: req.body.acceptedPlanRevisionId,
+        decompositionId: result.decomposition.id,
+        status: result.decomposition.status,
+        requestedChildCount: req.body.children.length,
+        childIssueIds: result.childIssueIds,
+        newlyCreatedChildIssueIds: result.newlyCreatedIssues.map((issue) => issue.id),
+      },
+    });
+
+    for (const issue of result.newlyCreatedIssues) {
+      await logActivity(db, {
+        companyId: sourceIssue.companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        runId: actor.runId,
+        action: "issue.child_created",
+        entityType: "issue",
+        entityId: issue.id,
+        details: {
+          parentId: sourceIssue.id,
+          identifier: issue.identifier,
+          title: issue.title,
+          inheritedExecutionWorkspaceFromIssueId: sourceIssue.id,
+          acceptedPlanRevisionId: req.body.acceptedPlanRevisionId,
+          ...buildCreateIssueActivityStatusDetails(issue, res),
+        },
+      });
+
+      const executionPolicy = normalizeIssueExecutionPolicy(issue.executionPolicy);
+      if (executionPolicy?.monitor) {
+        await logActivity(db, {
+          companyId: sourceIssue.companyId,
+          actorType: actor.actorType,
+          actorId: actor.actorId,
+          agentId: actor.agentId,
+          runId: actor.runId,
+          action: "issue.monitor_scheduled",
+          entityType: "issue",
+          entityId: issue.id,
+          details: {
+            identifier: issue.identifier,
+            parentId: sourceIssue.id,
+            acceptedPlanRevisionId: req.body.acceptedPlanRevisionId,
+            nextCheckAt: executionPolicy.monitor.nextCheckAt,
+            notes: executionPolicy.monitor.notes,
+            scheduledBy: executionPolicy.monitor.scheduledBy,
+            serviceName: executionPolicy.monitor.serviceName ?? null,
+            timeoutAt: executionPolicy.monitor.timeoutAt ?? null,
+            maxAttempts: executionPolicy.monitor.maxAttempts ?? null,
+            recoveryPolicy: executionPolicy.monitor.recoveryPolicy ?? null,
+          },
+        });
+      }
+
+      void queueIssueAssignmentWakeup({
+        heartbeat,
+        issue,
+        reason: "issue_assigned",
+        mutation: "accepted_plan_decomposition",
+        contextSource: "issue.accepted_plan_decomposition",
+        requestedByActorType: actor.actorType,
+        requestedByActorId: actor.actorId,
+      });
+    }
+
+    res.json({
+      decomposition: result.decomposition,
+      childIssueIds: result.childIssueIds,
+      newlyCreatedChildIssueIds: result.newlyCreatedIssues.map((issue) => issue.id),
+    });
+  });
+
   router.post("/issues/:id/monitor/check-now", async (req, res) => {
     const id = req.params.id as string;
     const issue = await svc.getById(id);
@@ -5118,10 +5265,12 @@ export function issueRoutes(
         });
       }
 
+      const acceptedPlanTarget = readAcceptedPlanConfirmationTarget(interaction.payload);
       const acceptedPlanConfirmation =
         interaction.kind === "request_confirmation" &&
         interaction.status === "accepted" &&
-        issue.workMode === "planning";
+        acceptedPlanTarget?.issueId === issue.id &&
+        acceptedPlanTarget.key === "plan";
       queueResolvedInteractionContinuationWakeup({
         heartbeat,
         issue: continuationWakeIssue,

server/src/services/heartbeat.ts

@@ -37,6 +37,7 @@ import {
   heartbeatRuns,
   issueApprovals,
   issueComments,
+  issuePlanDecompositions,
   issueRelations,
   issueThreadInteractions,
   issues,
@@ -1933,6 +1934,59 @@ function normalizeInteractionContinuationWakeContext(
   clearInteractionContinuationWakeContext(contextSnapshot);
 }
 
+type AcceptedPlanWakeRoutingDecision = {
+  otherActiveClaimIssueId: string;
+  otherActiveClaimIdentifier: string | null;
+  otherActiveClaimTitle: string;
+  forceFreshSession: boolean;
+  suppressAcceptedContinuation: boolean;
+};
+
+async function resolveAcceptedPlanWakeRoutingDecision(args: {
+  db: Db;
+  companyId: string;
+  agentId: string;
+  issueId: string | null;
+  acceptedPlanContinuationWake: boolean;
+  contextSnapshot: Record<string, unknown>;
+}): Promise<AcceptedPlanWakeRoutingDecision | null> {
+  if (args.issueId === null) return null;
+  if (!args.acceptedPlanContinuationWake) return null;
+
+  const activeClaims = await args.db
+    .select({
+      sourceIssueId: issuePlanDecompositions.sourceIssueId,
+      identifier: issues.identifier,
+      title: issues.title,
+    })
+    .from(issuePlanDecompositions)
+    .innerJoin(issues, eq(issues.id, issuePlanDecompositions.sourceIssueId))
+    .where(and(
+      eq(issuePlanDecompositions.companyId, args.companyId),
+      eq(issuePlanDecompositions.ownerAgentId, args.agentId),
+      eq(issuePlanDecompositions.status, "in_flight"),
+    ))
+    .orderBy(desc(issuePlanDecompositions.updatedAt), asc(issuePlanDecompositions.createdAt));
+
+  if (activeClaims.length === 0) return null;
+  if (activeClaims.some((claim) => claim.sourceIssueId === args.issueId)) return null;
+
+  const otherActiveClaim = activeClaims[0];
+  if (!otherActiveClaim) return null;
+
+  const hasAcceptedContinuationWake =
+    readNonEmptyString(args.contextSnapshot.interactionKind) === "request_confirmation" &&
+    readNonEmptyString(args.contextSnapshot.interactionStatus) === "accepted";
+
+  return {
+    otherActiveClaimIssueId: otherActiveClaim.sourceIssueId,
+    otherActiveClaimIdentifier: otherActiveClaim.identifier ?? null,
+    otherActiveClaimTitle: otherActiveClaim.title,
+    forceFreshSession: true,
+    suppressAcceptedContinuation: hasAcceptedContinuationWake,
+  };
+}
+
 export function mergeCoalescedContextSnapshot(
   existingRaw: unknown,
   incoming: Record<string, unknown>,
@@ -2229,6 +2283,7 @@ export function buildPaperclipTaskMarkdown(input: {
     kind?: string | null;
     status?: string | null;
   } | null;
+  acceptedPlanContinuation?: boolean;
 }) {
   const quoteTaskScalar = (value: string) => JSON.stringify(value);
   const fenceTaskText = (value: string) => {
@@ -2243,8 +2298,11 @@ export function buildPaperclipTaskMarkdown(input: {
   const wakeComment = input.wakeComment ?? null;
   const acceptedPlanContinuation =
     !wakeComment &&
-    input.interaction?.kind === "request_confirmation" &&
-    input.interaction.status === "accepted";
+    (input.acceptedPlanContinuation || (
+      input.interaction?.kind === "request_confirmation" &&
+      input.interaction.status === "accepted" &&
+      issue?.workMode === "planning"
+    ));
   if (!issue && !wakeComment) return null;
 
   const lines = [
@@ -2270,6 +2328,12 @@ export function buildPaperclipTaskMarkdown(input: {
         "Planning mode directive:",
         directive,
       );
+    } else if (acceptedPlanContinuation) {
+      lines.push(
+        "",
+        "Accepted plan directive:",
+        "Create child issues from the approved plan only. Do not write code or perform implementation work on the source issue.",
+      );
     }
     const description = issue.description?.trim();
     if (description) {
@@ -7055,6 +7119,37 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
           .where(and(eq(projects.id, executionProjectId), eq(projects.companyId, agent.companyId)))
           .then((rows) => rows[0] ?? null)
       : null;
+    const acceptedPlanWakeRoutingDecision = issueContext
+      ? await resolveAcceptedPlanWakeRoutingDecision({
+          db,
+          companyId: agent.companyId,
+          agentId: agent.id,
+          issueId,
+          acceptedPlanContinuationWake:
+            readNonEmptyString(context.workspaceRefreshReason) === "accepted_plan_confirmation"
+            || (
+              issueContext.workMode === "planning"
+              && readNonEmptyString(context.interactionKind) === "request_confirmation"
+              && readNonEmptyString(context.interactionStatus) === "accepted"
+            ),
+          contextSnapshot: context,
+        })
+      : null;
+    if (acceptedPlanWakeRoutingDecision) {
+      context.forceFreshSession = true;
+      context.acceptedPlanWakeRouting = {
+        reason: "other_issue_claim_in_flight",
+        otherActiveClaimIssueId: acceptedPlanWakeRoutingDecision.otherActiveClaimIssueId,
+        otherActiveClaimIdentifier: acceptedPlanWakeRoutingDecision.otherActiveClaimIdentifier,
+        otherActiveClaimTitle: acceptedPlanWakeRoutingDecision.otherActiveClaimTitle,
+      };
+      if (acceptedPlanWakeRoutingDecision.suppressAcceptedContinuation) {
+        clearInteractionContinuationWakeContext(context);
+        delete context.workspaceRefreshReason;
+      }
+    } else {
+      delete context.acceptedPlanWakeRouting;
+    }
     const routineEnvContext = await getRoutineEnvForExecutionIssue(agent.companyId, issueContext);
     const projectExecutionWorkspacePolicy = gateProjectExecutionWorkspacePolicy(
       parseProjectExecutionWorkspacePolicy(projectContext?.executionWorkspacePolicy),
@@ -7154,6 +7249,9 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
         kind: readNonEmptyString(context.interactionKind),
         status: readNonEmptyString(context.interactionStatus),
       },
+      acceptedPlanContinuation:
+        readNonEmptyString(context.workspaceRefreshReason) === "accepted_plan_confirmation"
+        && !parseObject(context.acceptedPlanWakeRouting),
     });
     if (issueRef) {
       context.paperclipIssue = {

server/src/services/instance-settings.ts

@@ -43,6 +43,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimenta
     return {
       enableEnvironments: parsed.data.enableEnvironments ?? false,
       enableIsolatedWorkspaces: parsed.data.enableIsolatedWorkspaces ?? false,
+      enableIssuePlanDecompositions: parsed.data.enableIssuePlanDecompositions ?? false,
       enableCloudSync: parsed.data.enableCloudSync ?? false,
       autoRestartDevServerWhenIdle: parsed.data.autoRestartDevServerWhenIdle ?? false,
       enableIssueGraphLivenessAutoRecovery: parsed.data.enableIssueGraphLivenessAutoRecovery ?? false,
@@ -54,6 +55,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimenta
   return {
     enableEnvironments: false,
     enableIsolatedWorkspaces: false,
+    enableIssuePlanDecompositions: false,
     enableCloudSync: false,
     autoRestartDevServerWhenIdle: false,
     enableIssueGraphLivenessAutoRecovery: false,

server/src/services/issues.ts

@@ -1,4 +1,5 @@
 import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
 import { and, asc, desc, eq, gt, inArray, isNull, like, lt, ne, notInArray, or, sql, type SQL } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
@@ -9,6 +10,7 @@ import {
   assets,
   companies,
   companyMemberships,
+  documentRevisions,
   documents,
   goals,
   heartbeatRuns,
@@ -17,6 +19,7 @@ import {
   issueAttachments,
   issueInboxArchives,
   issueLabels,
+  issuePlanDecompositions,
   issueRecoveryActions,
   issueRelations,
   issueComments,
@@ -29,6 +32,7 @@ import {
   projects,
 } from "@paperclipai/db";
 import type {
+  AcceptedPlanDecomposition,
   IssueCommentAuthorType,
   IssueCommentMetadata,
   IssueCommentPresentation,
@@ -245,6 +249,7 @@ export interface IssueFilters {
 
 type IssueRow = typeof issues.$inferSelect;
 type IssueLabelRow = typeof labels.$inferSelect;
+type IssuePlanDecompositionRow = typeof issuePlanDecompositions.$inferSelect;
 type IssueActiveRunRow = {
   id: string;
   status: string;
@@ -284,6 +289,30 @@ type IssueLastActivityStat = {
   latestCommentAt: Date | null;
   latestLogAt: Date | null;
 };
+
+function serializeAcceptedPlanDecomposition(
+  decomposition: IssuePlanDecompositionRow,
+): AcceptedPlanDecomposition {
+  return {
+    id: decomposition.id,
+    companyId: decomposition.companyId,
+    sourceIssueId: decomposition.sourceIssueId,
+    acceptedPlanRevisionId: decomposition.acceptedPlanRevisionId,
+    acceptedInteractionId: decomposition.acceptedInteractionId,
+    status: decomposition.status as AcceptedPlanDecomposition["status"],
+    requestFingerprint: decomposition.requestFingerprint,
+    // Intentionally omit requestedChildren here; the API only needs stable counts
+    // and child ids, while the durable table keeps the full child draft payload.
+    requestedChildCount: decomposition.requestedChildCount,
+    childIssueIds: normalizeIssuePlanDecompositionChildIds(decomposition.childIssueIds),
+    ownerAgentId: decomposition.ownerAgentId,
+    ownerUserId: decomposition.ownerUserId,
+    ownerRunId: decomposition.ownerRunId,
+    completedAt: decomposition.completedAt,
+    createdAt: decomposition.createdAt,
+    updatedAt: decomposition.updatedAt,
+  };
+}
 type IssueUserContextInput = {
   createdByUserId: string | null;
   assigneeUserId: string | null;
@@ -303,6 +332,16 @@ type IssueChildCreateInput = IssueCreateInput & {
   actorAgentId?: string | null;
   actorUserId?: string | null;
 };
+type AcceptedPlanDecompositionInput = {
+  acceptedPlanRevisionId: string;
+  children: IssueChildCreateInput[];
+  actorAgentId?: string | null;
+  actorUserId?: string | null;
+  actorRunId?: string | null;
+};
+type AcceptedPlanDocumentInteraction = {
+  id: string;
+};
 type IssueRelationSummaryMap = {
   blockedBy: IssueRelationIssueSummary[];
   blocks: IssueRelationIssueSummary[];
@@ -376,6 +415,167 @@ function appendAcceptanceCriteriaToDescription(description: string | null | unde
   return base ? `${base}\n\n${criteriaMarkdown}` : criteriaMarkdown;
 }
 
+function normalizeAcceptedPlanDecompositionFingerprintValue(value: unknown): unknown {
+  if (value === undefined) return null;
+  if (
+    value == null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeAcceptedPlanDecompositionFingerprintValue(item));
+  }
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return Object.fromEntries(
+      Object.keys(record)
+        .sort()
+        .map((key) => [key, normalizeAcceptedPlanDecompositionFingerprintValue(record[key])]),
+    );
+  }
+  return String(value);
+}
+
+const ACCEPTED_PLAN_DECOMPOSITION_FINGERPRINT_CHILD_METADATA_KEYS = new Set([
+  "id",
+  "companyId",
+  "parentId",
+  "identifier",
+  "checkoutRunId",
+  "executionRunId",
+  "executionLockedAt",
+  "startedAt",
+  "completedAt",
+  "cancelledAt",
+  "hiddenAt",
+  "createdAt",
+  "updatedAt",
+  "createdByAgentId",
+  "createdByUserId",
+  "updatedByAgentId",
+  "updatedByUserId",
+  "actorAgentId",
+  "actorUserId",
+]);
+
+function normalizeAcceptedPlanDecompositionFingerprintChild(child: IssueChildCreateInput) {
+  return Object.fromEntries(
+    Object.entries(child).filter(([key]) => !ACCEPTED_PLAN_DECOMPOSITION_FINGERPRINT_CHILD_METADATA_KEYS.has(key)),
+  );
+}
+
+function createAcceptedPlanDecompositionRequestFingerprint(input: {
+  acceptedPlanRevisionId: string;
+  children: IssueChildCreateInput[];
+}) {
+  const canonical = JSON.stringify(normalizeAcceptedPlanDecompositionFingerprintValue({
+    acceptedPlanRevisionId: input.acceptedPlanRevisionId,
+    children: input.children.map(normalizeAcceptedPlanDecompositionFingerprintChild),
+  }));
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+function normalizeIssuePlanDecompositionChildIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string" && item.length > 0);
+}
+
+export function readAcceptedPlanConfirmationTarget(payload: unknown): {
+  revisionId: string;
+  key: string;
+  issueId: string;
+} | null {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const target = (payload as Record<string, unknown>).target;
+  if (!target || typeof target !== "object" || Array.isArray(target)) return null;
+  const record = target as Record<string, unknown>;
+  if (record.type !== "issue_document") return null;
+  const revisionId = readStringFromRecord(record, "revisionId");
+  const key = readStringFromRecord(record, "key");
+  const issueId = readStringFromRecord(record, "issueId");
+  if (!revisionId || !key || !issueId) return null;
+  return { revisionId, key, issueId };
+}
+
+async function resolveAcceptedPlanClaimOwner(input: {
+  dbOrTx: Pick<Db, "select">;
+  claim: Pick<typeof issuePlanDecompositions.$inferSelect, "ownerAgentId" | "ownerUserId" | "ownerRunId">;
+  actorAgentId?: string | null;
+  actorUserId?: string | null;
+  actorRunId?: string | null;
+}) {
+  const nextOwner = {
+    ownerAgentId: input.actorAgentId ?? null,
+    ownerUserId: input.actorUserId ?? null,
+    ownerRunId: input.actorRunId ?? null,
+  };
+  if (
+    input.claim.ownerAgentId === nextOwner.ownerAgentId
+    && input.claim.ownerUserId === nextOwner.ownerUserId
+    && input.claim.ownerRunId === nextOwner.ownerRunId
+  ) {
+    return nextOwner;
+  }
+
+  if (!input.claim.ownerRunId) {
+    return nextOwner;
+  }
+
+  const existingOwnerRun = await input.dbOrTx
+    .select({ status: heartbeatRuns.status })
+    .from(heartbeatRuns)
+    .where(eq(heartbeatRuns.id, input.claim.ownerRunId))
+    .then((rows) => rows[0] ?? null);
+  if (existingOwnerRun && !TERMINAL_HEARTBEAT_RUN_STATUSES.has(existingOwnerRun.status)) {
+    return {
+      ownerAgentId: input.claim.ownerAgentId,
+      ownerUserId: input.claim.ownerUserId,
+      ownerRunId: input.claim.ownerRunId,
+    };
+  }
+
+  return nextOwner;
+}
+
+async function findAcceptedPlanDocumentInteraction(
+  dbOrTx: Pick<Db, "select">,
+  input: {
+    companyId: string;
+    sourceIssueId: string;
+    acceptedPlanRevisionId: string;
+  },
+): Promise<AcceptedPlanDocumentInteraction | null> {
+  const rows = await dbOrTx
+    .select({
+      id: issueThreadInteractions.id,
+      payload: issueThreadInteractions.payload,
+    })
+    .from(issueThreadInteractions)
+    .where(and(
+      eq(issueThreadInteractions.companyId, input.companyId),
+      eq(issueThreadInteractions.issueId, input.sourceIssueId),
+      eq(issueThreadInteractions.kind, "request_confirmation"),
+      eq(issueThreadInteractions.status, "accepted"),
+    ))
+    .orderBy(desc(issueThreadInteractions.resolvedAt), desc(issueThreadInteractions.createdAt));
+
+  for (const row of rows) {
+    const target = readAcceptedPlanConfirmationTarget(row.payload);
+    if (
+      target?.issueId === input.sourceIssueId &&
+      target.key === "plan" &&
+      target.revisionId === input.acceptedPlanRevisionId
+    ) {
+      return { id: row.id };
+    }
+  }
+  return null;
+}
+
 function createIssueDependencyReadiness(issueId: string): IssueDependencyReadiness {
   return {
     issueId,
@@ -4058,6 +4258,278 @@ export function issueService(db: Db) {
       };
     },
 
+    decomposeAcceptedPlan: async (
+      sourceIssueId: string,
+      data: AcceptedPlanDecompositionInput,
+    ) => {
+      const sourceIssue = await db
+        .select({
+          id: issues.id,
+          companyId: issues.companyId,
+          projectId: issues.projectId,
+          goalId: issues.goalId,
+        })
+        .from(issues)
+        .where(eq(issues.id, sourceIssueId))
+        .then((rows) => rows[0] ?? null);
+      if (!sourceIssue) throw notFound("Source issue not found");
+
+      const requestFingerprint = createAcceptedPlanDecompositionRequestFingerprint({
+        acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+        children: data.children,
+      });
+
+      const initialClaim = await db.transaction(async (tx) => {
+        await tx.execute(sql`select ${issues.id} from ${issues} where ${issues.id} = ${sourceIssue.id} for update`);
+
+        const belongsToPlanDocument = await tx
+          .select({ revisionId: documentRevisions.id })
+          .from(issueDocuments)
+          .innerJoin(documentRevisions, eq(issueDocuments.documentId, documentRevisions.documentId))
+          .where(and(
+            eq(issueDocuments.companyId, sourceIssue.companyId),
+            eq(issueDocuments.issueId, sourceIssue.id),
+            eq(issueDocuments.key, "plan"),
+            eq(documentRevisions.id, data.acceptedPlanRevisionId),
+          ))
+          .then((rows) => rows[0] ?? null);
+        if (!belongsToPlanDocument) {
+          throw unprocessable("acceptedPlanRevisionId must belong to the source issue's plan document");
+        }
+
+        const acceptedInteraction = await findAcceptedPlanDocumentInteraction(tx, {
+          companyId: sourceIssue.companyId,
+          sourceIssueId: sourceIssue.id,
+          acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+        });
+        if (!acceptedInteraction) {
+          throw unprocessable("acceptedPlanRevisionId must have an accepted plan confirmation");
+        }
+
+        const existing = await tx
+          .select()
+          .from(issuePlanDecompositions)
+          .where(and(
+            eq(issuePlanDecompositions.companyId, sourceIssue.companyId),
+            eq(issuePlanDecompositions.sourceIssueId, sourceIssue.id),
+            eq(issuePlanDecompositions.acceptedPlanRevisionId, data.acceptedPlanRevisionId),
+          ))
+          .then((rows) => rows[0] ?? null);
+
+        const now = new Date();
+        if (!existing) {
+          const [created] = await tx
+            .insert(issuePlanDecompositions)
+            .values({
+              companyId: sourceIssue.companyId,
+              sourceIssueId: sourceIssue.id,
+              acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+              acceptedInteractionId: acceptedInteraction.id,
+              status: "in_flight",
+              requestFingerprint,
+              requestedChildCount: data.children.length,
+              requestedChildren: data.children as unknown as Record<string, unknown>[],
+              childIssueIds: [],
+              ownerAgentId: data.actorAgentId ?? null,
+              ownerUserId: data.actorUserId ?? null,
+              ownerRunId: data.actorRunId ?? null,
+              updatedAt: now,
+            })
+            .returning();
+          if (!created) throw new Error("Failed to create accepted-plan decomposition claim");
+          return created;
+        }
+
+        if (existing.requestFingerprint !== requestFingerprint) {
+          throw conflict("Accepted-plan decomposition already exists for this revision with a different child set");
+        }
+
+        return existing;
+      });
+
+      let currentClaim = initialClaim;
+      const newlyCreatedIssues: Array<typeof issues.$inferSelect> = [];
+
+      while (true) {
+        const step = await db.transaction(async (tx) => {
+          await tx.execute(
+            sql`select ${issuePlanDecompositions.id}
+                from ${issuePlanDecompositions}
+                where ${issuePlanDecompositions.id} = ${currentClaim.id}
+                for update`,
+          );
+
+          const claim = await tx
+            .select()
+            .from(issuePlanDecompositions)
+            .where(eq(issuePlanDecompositions.id, currentClaim.id))
+            .then((rows) => rows[0] ?? null);
+          if (!claim) throw notFound("Accepted-plan decomposition claim not found");
+          if (claim.requestFingerprint !== requestFingerprint) {
+            throw conflict("Accepted-plan decomposition already exists for this revision with a different child set");
+          }
+
+          const existingChildIssueIds = normalizeIssuePlanDecompositionChildIds(claim.childIssueIds);
+          if (claim.status === "completed" || existingChildIssueIds.length >= data.children.length) {
+            const nextIds = existingChildIssueIds.slice(0, data.children.length);
+            if (claim.status === "completed" && nextIds.length === data.children.length) {
+              return {
+                claim,
+                createdIssue: null,
+              };
+            }
+
+            const completedAt = claim.completedAt ?? new Date();
+            const ownerPatch = await resolveAcceptedPlanClaimOwner({
+              dbOrTx: tx,
+              claim,
+              actorAgentId: data.actorAgentId,
+              actorUserId: data.actorUserId,
+              actorRunId: data.actorRunId,
+            });
+            const [completed] = await tx
+              .update(issuePlanDecompositions)
+              .set({
+                status: "completed",
+                childIssueIds: nextIds,
+                completedAt,
+                ...ownerPatch,
+                updatedAt: completedAt,
+              })
+              .where(eq(issuePlanDecompositions.id, claim.id))
+              .returning();
+            if (!completed) throw new Error("Failed to complete accepted-plan decomposition claim");
+            return {
+              claim: completed,
+              createdIssue: null,
+            };
+          }
+
+          const nextChildInput = data.children[existingChildIssueIds.length];
+          if (!nextChildInput) {
+            throw new Error("Accepted-plan decomposition child cursor moved past the requested children");
+          }
+
+          const createdChild = await issueService(tx as unknown as Db).createChild(sourceIssue.id, nextChildInput);
+          const nextIds = [...existingChildIssueIds, createdChild.issue.id];
+          const now = new Date();
+          const nextStatus = nextIds.length === data.children.length ? "completed" : "in_flight";
+          const ownerPatch = await resolveAcceptedPlanClaimOwner({
+            dbOrTx: tx,
+            claim,
+            actorAgentId: data.actorAgentId,
+            actorUserId: data.actorUserId,
+            actorRunId: data.actorRunId,
+          });
+          const [updatedClaim] = await tx
+            .update(issuePlanDecompositions)
+            .set({
+              status: nextStatus,
+              childIssueIds: nextIds,
+              completedAt: nextStatus === "completed" ? now : null,
+              ...ownerPatch,
+              updatedAt: now,
+            })
+            .where(eq(issuePlanDecompositions.id, claim.id))
+            .returning();
+          if (!updatedClaim) throw new Error("Failed to persist accepted-plan decomposition progress");
+          return {
+            claim: updatedClaim,
+            createdIssue: createdChild.issue,
+          };
+        });
+
+        currentClaim = step.claim;
+        if (step.createdIssue) {
+          newlyCreatedIssues.push(step.createdIssue);
+        }
+        if (step.claim.status === "completed") break;
+      }
+
+      const childIssueIds = normalizeIssuePlanDecompositionChildIds(currentClaim.childIssueIds);
+      const childIssueRows = childIssueIds.length > 0
+        ? await db
+            .select()
+            .from(issues)
+            .where(and(eq(issues.companyId, sourceIssue.companyId), inArray(issues.id, childIssueIds)))
+        : [];
+      const childIssueMap = new Map(childIssueRows.map((row) => [row.id, row]));
+      const orderedChildIssues = childIssueIds
+        .map((childIssueId) => childIssueMap.get(childIssueId))
+        .filter((row): row is typeof issues.$inferSelect => Boolean(row));
+
+      const decomposition = serializeAcceptedPlanDecomposition(currentClaim);
+
+      return {
+        decomposition,
+        childIssueIds: decomposition.childIssueIds,
+        childIssues: orderedChildIssues,
+        newlyCreatedIssues,
+      };
+    },
+
+    listAcceptedPlanDecompositions: async (sourceIssueId: string) => {
+      const sourceIssue = await db
+        .select({ id: issues.id, companyId: issues.companyId })
+        .from(issues)
+        .where(eq(issues.id, sourceIssueId))
+        .then((rows) => rows[0] ?? null);
+      if (!sourceIssue) return [];
+
+      const rows = await db
+        .select({
+          decomposition: issuePlanDecompositions,
+          revisionNumber: documentRevisions.revisionNumber,
+        })
+        .from(issuePlanDecompositions)
+        .leftJoin(
+          documentRevisions,
+          eq(documentRevisions.id, issuePlanDecompositions.acceptedPlanRevisionId),
+        )
+        .where(and(
+          eq(issuePlanDecompositions.companyId, sourceIssue.companyId),
+          eq(issuePlanDecompositions.sourceIssueId, sourceIssue.id),
+        ))
+        .orderBy(desc(issuePlanDecompositions.createdAt));
+
+      if (rows.length === 0) return [];
+
+      const allChildIds = new Set<string>();
+      for (const row of rows) {
+        for (const childId of normalizeIssuePlanDecompositionChildIds(row.decomposition.childIssueIds)) {
+          allChildIds.add(childId);
+        }
+      }
+
+      const childIssueRows = allChildIds.size > 0
+        ? await db
+            .select({
+              id: issues.id,
+              identifier: issues.identifier,
+              title: issues.title,
+              status: issues.status,
+              priority: issues.priority,
+              assigneeAgentId: issues.assigneeAgentId,
+              assigneeUserId: issues.assigneeUserId,
+            })
+            .from(issues)
+            .where(and(eq(issues.companyId, sourceIssue.companyId), inArray(issues.id, Array.from(allChildIds))))
+        : [];
+      const childIssueMap = new Map(childIssueRows.map((row) => [row.id, row]));
+
+      return rows.map((row) => {
+        const decomposition = serializeAcceptedPlanDecomposition(row.decomposition);
+        const childIds = decomposition.childIssueIds;
+        return {
+          ...decomposition,
+          acceptedPlanRevisionNumber: row.revisionNumber ?? null,
+          childIssues: childIds
+            .map((childId) => childIssueMap.get(childId) ?? null)
+            .filter((entry): entry is NonNullable<typeof entry> => entry !== null),
+        };
+      });
+    },
+
     create: async (
       companyId: string,
       data: IssueCreateInput,

ui/src/api/issues.ts

@@ -1,4 +1,5 @@
 import type {
+  AcceptedPlanDecompositionSummary,
   AskUserQuestionsAnswer,
   Approval,
   CreateIssueTreeHold,
@@ -201,6 +202,8 @@ export const issuesApi = {
   },
   listInteractions: (id: string) =>
     api.get<IssueThreadInteraction[]>(`/issues/${id}/interactions`),
+  listAcceptedPlanDecompositions: (id: string) =>
+    api.get<AcceptedPlanDecompositionSummary[]>(`/issues/${id}/accepted-plan-decompositions`),
   createInteraction: (id: string, data: Record<string, unknown>) =>
     api.post<IssueThreadInteraction>(`/issues/${id}/interactions`, data),
   acceptInteraction: (

ui/src/components/IssuePlanDecompositionsSection.tsx

@@ -0,0 +1,160 @@
+import { useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import type { Agent, AcceptedPlanDecompositionSummary } from "@paperclipai/shared";
+import { ChevronRight, GitBranch, Repeat, CheckCircle2, Loader2 } from "lucide-react";
+import { Link } from "@/lib/router";
+import { issuesApi } from "../api/issues";
+import { queryKeys } from "../lib/queryKeys";
+import { cn, formatDateTime, relativeTime } from "../lib/utils";
+
+interface IssuePlanDecompositionsSectionProps {
+  issueId: string;
+  issueIdentifier: string | null;
+  agentMap?: Map<string, Agent>;
+}
+
+function StatusBadge({ status }: { status: AcceptedPlanDecompositionSummary["status"] }) {
+  if (status === "completed") {
+    return (
+      <span className="inline-flex items-center gap-1 rounded-sm border border-emerald-500/50 bg-emerald-500/10 px-2 py-0.5 text-[11px] font-medium text-emerald-900 dark:text-emerald-100">
+        <CheckCircle2 className="h-3 w-3" />
+        Completed
+      </span>
+    );
+  }
+  return (
+    <span className="inline-flex items-center gap-1 rounded-sm border border-amber-500/50 bg-amber-500/10 px-2 py-0.5 text-[11px] font-medium text-amber-900 dark:text-amber-100">
+      <Loader2 className="h-3 w-3 animate-spin" />
+      In flight
+    </span>
+  );
+}
+
+export function IssuePlanDecompositionsSection({
+  issueId,
+  issueIdentifier,
+  agentMap,
+}: IssuePlanDecompositionsSectionProps) {
+  const { data: decompositions } = useQuery({
+    queryKey: queryKeys.issues.acceptedPlanDecompositions(issueId),
+    queryFn: () => issuesApi.listAcceptedPlanDecompositions(issueId),
+  });
+
+  const items = useMemo(() => decompositions ?? [], [decompositions]);
+  if (items.length === 0) return null;
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center justify-between gap-2">
+        <h3 className="text-sm font-medium text-muted-foreground">Plan decomposition</h3>
+        <span className="text-[11px] text-muted-foreground/80">
+          {items.length === 1 ? "1 accepted plan revision" : `${items.length} accepted plan revisions`}
+        </span>
+      </div>
+
+      <ul className="space-y-3">
+        {items.map((record) => {
+          const requested = record.requestedChildCount ?? 0;
+          const created = record.childIssueIds?.length ?? 0;
+          const ownerName = record.ownerAgentId
+            ? agentMap?.get(record.ownerAgentId)?.name ?? "agent"
+            : null;
+          const revisionLabel =
+            record.acceptedPlanRevisionNumber != null
+              ? `revision ${record.acceptedPlanRevisionNumber}`
+              : `revision ${record.acceptedPlanRevisionId.slice(0, 8)}`;
+          const completedAt =
+            record.completedAt && typeof record.completedAt === "string"
+              ? record.completedAt
+              : record.completedAt instanceof Date
+                ? record.completedAt.toISOString()
+                : null;
+          const updatedAt =
+            typeof record.updatedAt === "string"
+              ? record.updatedAt
+              : record.updatedAt instanceof Date
+                ? record.updatedAt.toISOString()
+                : null;
+          const startedAt =
+            typeof record.createdAt === "string"
+              ? record.createdAt
+              : record.createdAt instanceof Date
+                ? record.createdAt.toISOString()
+                : null;
+
+          return (
+            <li
+              key={record.id}
+              className="rounded-md border border-border bg-card/50 p-3 text-sm"
+            >
+              <div className="flex flex-wrap items-center gap-2">
+                <StatusBadge status={record.status} />
+                <span className="text-xs text-muted-foreground">
+                  Plan {revisionLabel}
+                </span>
+                <span className="text-xs text-muted-foreground/70">·</span>
+                <span className="inline-flex items-center gap-1 text-xs text-foreground">
+                  <GitBranch className="h-3 w-3 text-muted-foreground" />
+                  {created} of {requested} child {requested === 1 ? "issue" : "issues"} created
+                </span>
+                {record.status === "completed" && requested > 0 ? (
+                  <span
+                    className="inline-flex items-center gap-1 rounded-sm border border-sky-500/40 bg-sky-500/10 px-1.5 py-0.5 text-[10px] font-medium text-sky-900 dark:text-sky-100"
+                    title="Repeat attempts with this fingerprint reuse this record instead of creating new children"
+                  >
+                    <Repeat className="h-3 w-3" />
+                    Idempotent claim
+                  </span>
+                ) : null}
+              </div>
+
+              <div className="mt-1 flex flex-wrap gap-x-3 gap-y-0.5 text-[11px] text-muted-foreground">
+                {ownerName ? <span>Owner: {ownerName}</span> : null}
+                {startedAt ? (
+                  <span title={formatDateTime(startedAt)}>Started {relativeTime(startedAt)}</span>
+                ) : null}
+                {completedAt ? (
+                  <span title={formatDateTime(completedAt)}>Completed {relativeTime(completedAt)}</span>
+                ) : updatedAt ? (
+                  <span title={formatDateTime(updatedAt)}>Updated {relativeTime(updatedAt)}</span>
+                ) : null}
+                {issueIdentifier ? (
+                  <Link
+                    to={`/issues/${issueIdentifier}#document-plan`}
+                    className="underline-offset-2 hover:underline"
+                  >
+                    Plan document
+                  </Link>
+                ) : null}
+              </div>
+
+              {record.childIssues && record.childIssues.length > 0 ? (
+                <ul className="mt-2 flex flex-wrap gap-1.5">
+                  {record.childIssues.map((child) => (
+                    <li key={child.id}>
+                      <Link
+                        to={`/issues/${child.identifier ?? child.id}`}
+                        className={cn(
+                          "inline-flex max-w-full items-center gap-1 rounded-sm border border-border bg-background px-2 py-0.5 text-[11px] text-foreground transition-colors hover:bg-accent/40",
+                        )}
+                        title={child.title}
+                      >
+                        <span className="font-medium">
+                          {child.identifier ?? child.id.slice(0, 8)}
+                        </span>
+                        <span className="truncate max-w-[24ch] text-muted-foreground">
+                          {child.title}
+                        </span>
+                        <ChevronRight className="h-3 w-3 text-muted-foreground" />
+                      </Link>
+                    </li>
+                  ))}
+                </ul>
+              ) : null}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

ui/src/lib/activity-format.ts

@@ -48,6 +48,7 @@ const ACTIVITY_ROW_VERBS: Record<string, string> = {
   "issue.successful_run_handoff_required": "flagged missing next step on",
   "issue.successful_run_handoff_resolved": "recorded next step chosen on",
   "issue.successful_run_handoff_escalated": "escalated missing next step on",
+  "issue.accepted_plan_decomposition_updated": "updated accepted-plan decomposition on",
   "issue.recovery_action_opened": "opened a recovery action on",
   "issue.recovery_action_resolved": "resolved the recovery action on",
   "issue.recovery_action_escalated": "escalated the recovery action on",
@@ -110,6 +111,7 @@ const ISSUE_ACTIVITY_LABELS: Record<string, string> = {
   "issue.recovery_action_opened": "Opened a source-scoped recovery action",
   "issue.recovery_action_resolved": "Resolved the recovery action",
   "issue.recovery_action_escalated": "Escalated the recovery action",
+  "issue.accepted_plan_decomposition_updated": "updated the accepted-plan decomposition",
   "agent.created": "created an agent",
   "agent.updated": "updated the agent",
   "agent.paused": "paused the agent",
@@ -189,6 +191,34 @@ function formatChangedEntityLabel(
   return `${labels.length} ${plural}`;
 }
 
+function readNumber(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  return null;
+}
+
+function readStringArrayLength(value: unknown): number {
+  if (!Array.isArray(value)) return 0;
+  return value.filter((entry) => typeof entry === "string" && entry.length > 0).length;
+}
+
+function formatAcceptedPlanDecompositionDetail(details: ActivityDetails): string | null {
+  if (!details) return null;
+  const status = typeof details.status === "string" ? details.status : null;
+  const requested = readNumber(details.requestedChildCount);
+  const totalChildren = readStringArrayLength(details.childIssueIds);
+  const newlyCreated = readStringArrayLength(details.newlyCreatedChildIssueIds);
+  const reused = Math.max(0, totalChildren - newlyCreated);
+  const parts: string[] = [];
+  if (newlyCreated > 0) parts.push(`created ${newlyCreated} new`);
+  if (reused > 0) parts.push(`reused ${reused} existing`);
+  if (parts.length === 0 && requested !== null) parts.push(`${requested} requested`);
+  const summary = parts.length > 0 ? parts.join(", ") : null;
+  if (status === "completed" && summary) return `decomposition completed (${summary})`;
+  if (status === "completed") return "decomposition completed";
+  if (status === "in_flight" && summary) return `decomposition in flight (${summary})`;
+  return summary;
+}
+
 function formatIssueUpdatedVerb(details: ActivityDetails): string | null {
   if (!details) return null;
   const previous = asRecord(details._previous) ?? {};
@@ -332,6 +362,11 @@ export function formatIssueActivityAction(
   });
   if (structuredChange) return structuredChange;
 
+  if (action === "issue.accepted_plan_decomposition_updated") {
+    const detail = formatAcceptedPlanDecompositionDetail(details);
+    if (detail) return detail;
+  }
+
   if (action.startsWith("issue.monitor_") && details) {
     const serviceName = typeof details.serviceName === "string" && details.serviceName.trim()
       ? details.serviceName.trim()

ui/src/lib/queryKeys.ts

@@ -59,6 +59,8 @@ export const queryKeys = {
     detail: (id: string) => ["issues", "detail", id] as const,
     comments: (issueId: string) => ["issues", "comments", issueId] as const,
     interactions: (issueId: string) => ["issues", "interactions", issueId] as const,
+    acceptedPlanDecompositions: (issueId: string) =>
+      ["issues", "accepted-plan-decompositions", issueId] as const,
     feedbackVotes: (issueId: string) => ["issues", "feedback-votes", issueId] as const,
     costSummary: (issueId: string, options: { excludeRoot?: boolean } = {}) =>
       options.excludeRoot

ui/src/pages/InstanceExperimentalSettings.tsx

@@ -205,6 +205,8 @@ export function InstanceExperimentalSettings() {
 
   const enableEnvironments = experimentalQuery.data?.enableEnvironments === true;
   const enableIsolatedWorkspaces = experimentalQuery.data?.enableIsolatedWorkspaces === true;
+  const enableIssuePlanDecompositions =
+    experimentalQuery.data?.enableIssuePlanDecompositions === true;
   const enableCloudSync = experimentalQuery.data?.enableCloudSync === true;
   const autoRestartDevServerWhenIdle = experimentalQuery.data?.autoRestartDevServerWhenIdle === true;
   const enableIssueGraphLivenessAutoRecovery =
@@ -299,6 +301,28 @@ export function InstanceExperimentalSettings() {
         </div>
       </section>
 
+      <section className="rounded-xl border border-border bg-card p-5">
+        <div className="flex items-start justify-between gap-4">
+          <div className="space-y-1.5">
+            <h2 className="text-sm font-semibold">Issue Plan Decomposition Panel</h2>
+            <p className="max-w-2xl text-sm text-muted-foreground">
+              Show accepted-plan decomposition history on issue detail pages. Intended for debugging and validating
+              subtask creation behavior while the presentation is still being refined.
+            </p>
+          </div>
+          <ToggleSwitch
+            checked={enableIssuePlanDecompositions}
+            onCheckedChange={() =>
+              toggleMutation.mutate({
+                enableIssuePlanDecompositions: !enableIssuePlanDecompositions,
+              })
+            }
+            disabled={toggleMutation.isPending}
+            aria-label="Toggle issue plan decomposition panel experimental setting"
+          />
+        </div>
+      </section>
+
       <section className="rounded-xl border border-border bg-card p-5">
         <div className="flex items-start justify-between gap-4">
           <div className="space-y-1.5">

ui/src/pages/IssueDetail.test.tsx

@@ -10,6 +10,7 @@ import { canBoardResolveRecoveryAction, IssueDetail } from "./IssueDetail";
 const mockIssuesApi = vi.hoisted(() => ({
   get: vi.fn(),
   list: vi.fn(),
+  listAcceptedPlanDecompositions: vi.fn(),
   listComments: vi.fn(),
   listAttachments: vi.fn(),
   listFeedbackVotes: vi.fn(),
@@ -59,6 +60,7 @@ const mockProjectsApi = vi.hoisted(() => ({
 
 const mockInstanceSettingsApi = vi.hoisted(() => ({
   getGeneral: vi.fn(),
+  getExperimental: vi.fn(),
 }));
 
 const mockNavigate = vi.hoisted(() => vi.fn());
@@ -823,6 +825,10 @@ describe("IssueDetail", () => {
       keyboardShortcuts: false,
       feedbackDataSharingPreference: "prompt",
     });
+    mockInstanceSettingsApi.getExperimental.mockResolvedValue({
+      enableIssuePlanDecompositions: false,
+    });
+    mockIssuesApi.listAcceptedPlanDecompositions.mockResolvedValue([]);
     mockIssuesListRender.mockClear();
     mockIssueChatThreadRender.mockClear();
   });
@@ -858,6 +864,79 @@ describe("IssueDetail", () => {
     expect(consoleErrorSpy).not.toHaveBeenCalled();
   });
 
+  it("hides the plan decomposition panel by default", async () => {
+    mockIssuesApi.get.mockResolvedValue(createIssue());
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <IssueDetail />
+        </QueryClientProvider>,
+      );
+    });
+
+    await flushReact();
+    await flushReact();
+
+    expect(container.textContent).not.toContain("Plan decomposition");
+    expect(mockIssuesApi.listAcceptedPlanDecompositions).not.toHaveBeenCalled();
+  });
+
+  it("shows the plan decomposition panel when the experimental flag is enabled", async () => {
+    mockIssuesApi.get.mockResolvedValue(createIssue());
+    mockInstanceSettingsApi.getExperimental.mockResolvedValue({
+      enableIssuePlanDecompositions: true,
+    });
+    mockIssuesApi.listAcceptedPlanDecompositions.mockResolvedValue([
+      {
+        id: "decomp-1",
+        companyId: "company-1",
+        sourceIssueId: "issue-1",
+        acceptedPlanRevisionId: "plan-rev-1",
+        acceptedPlanRevisionNumber: 2,
+        acceptedInteractionId: null,
+        status: "completed",
+        requestFingerprint: "fingerprint-1",
+        requestedChildCount: 2,
+        childIssueIds: ["issue-2", "issue-3"],
+        childIssues: [
+          {
+            id: "issue-2",
+            identifier: "PAP-2",
+            title: "First child issue",
+            status: "todo",
+            priority: "medium",
+            assigneeAgentId: null,
+            assigneeUserId: null,
+          },
+        ],
+        ownerAgentId: null,
+        ownerUserId: null,
+        ownerRunId: null,
+        completedAt: "2026-05-28T06:00:00.000Z",
+        createdAt: "2026-05-28T05:50:00.000Z",
+        updatedAt: "2026-05-28T06:00:00.000Z",
+      },
+    ]);
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <IssueDetail />
+        </QueryClientProvider>,
+      );
+    });
+
+    await flushReact();
+    await flushReact();
+
+    expect(container.textContent).toContain("Plan decomposition");
+    expect(container.textContent).toContain("Plan revision 2");
+    expect(container.textContent).toContain("2 of 2 child issues created");
+    expect(container.textContent).toContain("First child issue");
+    expect(mockIssuesApi.listAcceptedPlanDecompositions).toHaveBeenCalledWith("issue-1");
+  });
+
   it("renders sibling previous and next navigation at the chat footer", async () => {
     const issue = createIssue({
       id: "issue-2",

ui/src/pages/IssueDetail.tsx

@@ -66,6 +66,7 @@ import { InlineEditor } from "../components/InlineEditor";
 import { IssueChatThread, type IssueChatComposerHandle } from "../components/IssueChatThread";
 import { IssueContinuationHandoff } from "../components/IssueContinuationHandoff";
 import { IssueDocumentsSection } from "../components/IssueDocumentsSection";
+import { IssuePlanDecompositionsSection } from "../components/IssuePlanDecompositionsSection";
 import { IssueSiblingNavigation } from "../components/IssueSiblingNavigation";
 import { IssuesList } from "../components/IssuesList";
 import { AgentIcon } from "../components/AgentIconPicker";
@@ -1440,8 +1441,16 @@ export function IssueDetail() {
     enabled: !!issueId,
     retry: false,
   });
+  const { data: instanceExperimentalSettings } = useQuery({
+    queryKey: queryKeys.instance.experimentalSettings,
+    queryFn: () => instanceSettingsApi.getExperimental(),
+    enabled: !!issueId,
+    retry: false,
+  });
   const keyboardShortcutsEnabled = instanceGeneralSettings?.keyboardShortcuts === true;
   const feedbackDataSharingPreference = instanceGeneralSettings?.feedbackDataSharingPreference ?? "prompt";
+  const showPlanDecompositionsSection =
+    instanceExperimentalSettings?.enableIssuePlanDecompositions === true;
   const { orderedProjects } = useProjectOrder({
     projects: projects ?? [],
     companyId: selectedCompanyId,
@@ -3713,6 +3722,14 @@ export function IssueDetail() {
         </div>
       )}
 
+      {showPlanDecompositionsSection ? (
+        <IssuePlanDecompositionsSection
+          issueId={issue.id}
+          issueIdentifier={issue.identifier}
+          agentMap={agentMap}
+        />
+      ) : null}
+
       <IssueDocumentsSection
         issue={issue}
         canDeleteDocuments={Boolean(session?.user?.id)}

ui/storybook/stories/issue-plan-decompositions.stories.tsx

@@ -0,0 +1,129 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useQueryClient } from "@tanstack/react-query";
+import type { AcceptedPlanDecompositionSummary } from "@paperclipai/shared";
+import { IssuePlanDecompositionsSection } from "@/components/IssuePlanDecompositionsSection";
+import { queryKeys } from "@/lib/queryKeys";
+import { storybookAgentMap } from "../fixtures/paperclipData";
+
+const issueId = "issue-plan-decomposition-story";
+const issueIdentifier = "PAP-6831";
+
+function buildDecomposition(
+  overrides: Partial<AcceptedPlanDecompositionSummary>,
+): AcceptedPlanDecompositionSummary {
+  return {
+    id: "decomposition-story-1",
+    companyId: "company-storybook",
+    sourceIssueId: issueId,
+    acceptedPlanRevisionId: "revision-story-1",
+    acceptedInteractionId: "interaction-story-1",
+    status: "completed",
+    requestFingerprint: "fingerprint-story-1",
+    requestedChildCount: 2,
+    childIssueIds: ["issue-child-1", "issue-child-2"],
+    ownerAgentId: "agent-codex",
+    ownerUserId: null,
+    ownerRunId: "run-story-1",
+    completedAt: "2026-05-28T06:22:00.000Z",
+    createdAt: "2026-05-28T06:18:00.000Z",
+    updatedAt: "2026-05-28T06:22:00.000Z",
+    acceptedPlanRevisionNumber: 7,
+    childIssues: [
+      {
+        id: "issue-child-1",
+        identifier: "PAP-6840",
+        title: "Harden accepted-plan wake routing",
+        status: "done",
+        priority: "medium",
+        assigneeAgentId: "agent-codex",
+        assigneeUserId: null,
+      },
+      {
+        id: "issue-child-2",
+        identifier: "PAP-6841",
+        title: "Add decomposition regression coverage",
+        status: "in_progress",
+        priority: "medium",
+        assigneeAgentId: "agent-qa",
+        assigneeUserId: null,
+      },
+    ],
+    ...overrides,
+  };
+}
+
+function HydratedSection({
+  decompositions,
+}: {
+  decompositions: AcceptedPlanDecompositionSummary[];
+}) {
+  const queryClient = useQueryClient();
+  const [ready] = useState(() => {
+    queryClient.setQueryData(queryKeys.issues.acceptedPlanDecompositions(issueId), decompositions);
+    return true;
+  });
+
+  if (!ready) return null;
+
+  return (
+    <div className="paperclip-story">
+      <main className="paperclip-story__inner">
+        <div className="mx-auto max-w-3xl rounded-2xl border border-border bg-background/95 p-6 shadow-sm">
+          <IssuePlanDecompositionsSection
+            issueId={issueId}
+            issueIdentifier={issueIdentifier}
+            agentMap={storybookAgentMap}
+          />
+        </div>
+      </main>
+    </div>
+  );
+}
+
+const meta = {
+  title: "Issue Detail/Plan Decompositions",
+  component: HydratedSection,
+  args: {
+    decompositions: [],
+  },
+  parameters: {
+    layout: "fullscreen",
+  },
+} satisfies Meta<typeof HydratedSection>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const InFlight: Story = {
+  args: {
+    decompositions: [
+      buildDecomposition({
+        status: "in_flight",
+        completedAt: null,
+        updatedAt: "2026-05-28T06:20:00.000Z",
+        childIssueIds: ["issue-child-1"],
+        childIssues: [
+          {
+            id: "issue-child-1",
+            identifier: "PAP-6840",
+            title: "Harden accepted-plan wake routing",
+            status: "done",
+            priority: "medium",
+            assigneeAgentId: "agent-codex",
+            assigneeUserId: null,
+          },
+        ],
+      }),
+    ],
+  },
+};
+
+export const Completed: Story = {
+  args: {
+    decompositions: [
+      buildDecomposition({}),
+    ],
+  },
+};