fix(plan): stabilize claim recovery and compact listing (#560)

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

apps/mcp-server/src/tools/plan.ts

@@ -171,18 +171,19 @@ function recoveryDetailsForClaimFailure(
   store: MemoryStore,
   code:
     | 'PLAN_SUBTASK_NOT_FOUND'
+    | 'PLAN_SUBTASK_STALE'
     | 'PLAN_SUBTASK_DEPS_UNMET'
     | 'PLAN_SUBTASK_NOT_AVAILABLE'
     | 'PLAN_ARCHIVED'
     | 'CLAIM_TAKEOVER_RECOMMENDED'
     | 'CLAIM_HELD_BY_ACTIVE_OWNER',
   args: { plan_slug: string; subtask_index: number; repo_root?: string },
 ): Record<string, unknown> {
-  if (code !== 'PLAN_SUBTASK_NOT_AVAILABLE') return {};
+  if (code !== 'PLAN_SUBTASK_NOT_AVAILABLE' && code !== 'PLAN_SUBTASK_STALE') return {};
   try {
     const plan = listPlans(store, {
       ...(args.repo_root !== undefined ? { repo_root: args.repo_root } : {}),
-      limit: 200,
+      limit: 2000,
     }).find((candidate) => candidate.plan_slug === args.plan_slug);
     if (!plan) return {};
     const candidates = plan.next_available
@@ -421,18 +422,20 @@ export function register(server: McpServer, ctx: ToolContext): void {
       // bad to good without requiring an operator to call colony plan
       // close manually.
       sweepCompletedPlansForAutoArchive(store, args.repo_root);
+      const limit = args.limit ?? 10;
       const plans = listPlans(store, {
         ...(args.repo_root !== undefined ? { repo_root: args.repo_root } : {}),
         ...(args.only_with_available_subtasks !== undefined
           ? { only_with_available_subtasks: args.only_with_available_subtasks }
           : {}),
         ...(args.capability_match !== undefined ? { capability_match: args.capability_match } : {}),
-        ...(args.limit !== undefined ? { limit: args.limit } : {}),
+        limit: 2000,
       });
       const includeUnpublished = args.include_unpublished ?? true;
       const merged = includeUnpublished ? mergeUnpublishedDiskPlans(plans, args.repo_root) : plans;
       const detail = args.detail ?? 'compact';
-      const payload = detail === 'full' ? merged : merged.map(toCompactPlan);
+      const limited = merged.slice(0, limit);
+      const payload = detail === 'full' ? limited : limited.map(toCompactPlan);
       return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
     }),
   );
@@ -648,6 +651,7 @@ export type ClaimPlanSubtaskArgs = {
   subtask_index: number;
   session_id: string;
   agent: string;
+  repo_root?: string | undefined;
 };
 
 export type ClaimPlanSubtaskResult =
@@ -657,6 +661,7 @@ export type ClaimPlanSubtaskResult =
       ok: false;
       code:
         | 'PLAN_SUBTASK_NOT_FOUND'
+        | 'PLAN_SUBTASK_STALE'
         | 'PLAN_SUBTASK_DEPS_UNMET'
         | 'PLAN_SUBTASK_NOT_AVAILABLE'
         | 'CLAIM_TAKEOVER_RECOMMENDED'
@@ -686,7 +691,22 @@ export function attemptClaimPlanSubtask(
       session_id: args.session_id,
     });
     if (archived) return { ok: false, ...archived };
-    return { ok: false, code: 'PLAN_SUBTASK_NOT_FOUND', message: `no sub-task at ${branch}` };
+    const planExists = listPlans(store, {
+      ...(args.repo_root !== undefined ? { repo_root: args.repo_root } : {}),
+      limit: 2000,
+    }).some((candidate) => candidate.plan_slug === args.plan_slug);
+    if (planExists) {
+      return {
+        ok: false,
+        code: 'PLAN_SUBTASK_STALE',
+        message: `stale sub-task pointer: no sub-task at ${branch}`,
+      };
+    }
+    return {
+      ok: false,
+      code: 'PLAN_SUBTASK_NOT_FOUND',
+      message: `unknown plan or sub-task: no sub-task at ${branch}`,
+    };
   }
 
   const allTasks = store.storage.listTasks(2000);
@@ -720,7 +740,7 @@ export function attemptClaimPlanSubtask(
         const fresh = readSubtaskByBranch(store, branch);
         if (!fresh) {
           const err: CodedError = new Error(`no sub-task at ${branch}`);
-          err.__code = 'PLAN_SUBTASK_NOT_AVAILABLE';
+          err.__code = 'PLAN_SUBTASK_STALE';
           throw err;
         }
         if (fresh.info.status !== 'available') {
@@ -802,6 +822,7 @@ export function attemptClaimPlanSubtask(
     const code = (err as CodedError).__code;
     if (
       code === 'PLAN_SUBTASK_NOT_AVAILABLE' ||
+      code === 'PLAN_SUBTASK_STALE' ||
       code === 'CLAIM_TAKEOVER_RECOMMENDED' ||
       code === 'CLAIM_HELD_BY_ACTIVE_OWNER'
     ) {

apps/mcp-server/src/tools/ready-queue.ts

@@ -330,6 +330,7 @@ async function maybeAutoClaim(
   const claimResult = attemptClaimPlanSubtask(store, {
     plan_slug: claim_args.plan_slug,
     subtask_index: claim_args.subtask_index,
+    repo_root: claim_args.repo_root,
     session_id: caller.session_id,
     agent: caller.agent,
   });
@@ -424,24 +425,29 @@ export async function buildReadyForAgent(
     ]),
   );
   const role = actorRole(store, { agent: args.agent, session_id: args.session_id });
+  const liveSubtaskBranches = new Set(
+    allTasks.map((task) => subtaskBranchKey(task.repo_root, task.branch)),
+  );
   const quotaRelays = quotaRelayReadyItems(store, args, plans, allTasks);
   const available = filterReadyForExecutor(
     plans.flatMap((plan) =>
-      plan.next_available.map((subtask) =>
-        rankSubtask(store, {
-          plan_slug: plan.plan_slug,
-          repo_root: plan.repo_root,
-          subtask,
-          session_id: args.session_id,
-          agent: args.agent,
-          profile,
-          parent_plan_created_by: tasksById.get(plan.spec_task_id)?.created_by ?? null,
-          created_at: tasksById.get(subtask.task_id)?.created_at ?? plan.created_at,
-          proposal_status: tasksById.get(subtask.task_id)?.proposal_status ?? null,
-          reason: 'ready_high_score',
-          current_claim: false,
-        }),
-      ),
+      plan.next_available
+        .filter((subtask) => hasLiveSubtaskBranch(liveSubtaskBranches, plan, subtask))
+        .map((subtask) =>
+          rankSubtask(store, {
+            plan_slug: plan.plan_slug,
+            repo_root: plan.repo_root,
+            subtask,
+            session_id: args.session_id,
+            agent: args.agent,
+            profile,
+            parent_plan_created_by: tasksById.get(plan.spec_task_id)?.created_by ?? null,
+            created_at: tasksById.get(subtask.task_id)?.created_at ?? plan.created_at,
+            proposal_status: tasksById.get(subtask.task_id)?.proposal_status ?? null,
+            reason: 'ready_high_score',
+            current_claim: false,
+          }),
+        ),
     ),
     role,
   );
@@ -452,6 +458,7 @@ export async function buildReadyForAgent(
           (subtask) =>
             subtask.status === 'claimed' && subtask.claimed_by_session_id === args.session_id,
         )
+        .filter((subtask) => hasLiveSubtaskBranch(liveSubtaskBranches, plan, subtask))
         .map((subtask) =>
           rankSubtask(store, {
             plan_slug: plan.plan_slug,
@@ -631,6 +638,20 @@ function specRootSetupIssue(repoRoot: string | undefined): SpecRootSetupIssue |
   };
 }
 
+function hasLiveSubtaskBranch(
+  liveSubtaskBranches: Set<string>,
+  plan: Pick<PlanInfo, 'repo_root' | 'plan_slug'>,
+  subtask: Pick<SubtaskInfo, 'subtask_index'>,
+): boolean {
+  return liveSubtaskBranches.has(
+    subtaskBranchKey(plan.repo_root, `spec/${plan.plan_slug}/sub-${subtask.subtask_index}`),
+  );
+}
+
+function subtaskBranchKey(repoRoot: string, branch: string): string {
+  return `${repoRoot}\0${branch}`;
+}
+
 function codexMcpCall(args: TaskPlanClaimArgs): string {
   return `mcp__colony__task_plan_claim_subtask({ agent: ${JSON.stringify(args.agent)}, session_id: ${JSON.stringify(args.session_id)}, repo_root: ${JSON.stringify(args.repo_root)}, plan_slug: ${JSON.stringify(args.plan_slug)}, subtask_index: ${args.subtask_index}, file_scope: ${JSON.stringify(args.file_scope)} })`;
 }

apps/mcp-server/src/tools/shared.ts

@@ -284,6 +284,7 @@ export function mcpErrorResponse(
     | 'PLAN_WAVE_SCOPE_OVERLAP'
     | 'PLAN_FINALIZER_NOT_LAST'
     | 'PLAN_SUBTASK_NOT_FOUND'
+    | 'PLAN_SUBTASK_STALE'
     | 'PLAN_SUBTASK_DEPS_UNMET'
     | 'PLAN_SUBTASK_NOT_AVAILABLE'
     | 'PLAN_SUBTASK_NOT_CLAIMED'

apps/mcp-server/test/plan.test.ts

@@ -723,6 +723,29 @@ describe('task_plan_list', () => {
     expect(uiPlans).toHaveLength(0);
   });
 
+  it('defaults task_plan_list to 10 plans while honoring explicit limits up to the cap', async () => {
+    for (let index = 0; index < 12; index += 1) {
+      await call<PublishResult>(
+        'task_plan_publish',
+        basicPublishArgs({
+          slug: `limit-plan-${index}`,
+          title: `Limit plan ${index}`,
+        }),
+      );
+    }
+
+    const defaultPlans = await call<PlanRollup[]>('task_plan_list', {
+      repo_root: repoRoot,
+    });
+    const expandedPlans = await call<PlanRollup[]>('task_plan_list', {
+      repo_root: repoRoot,
+      limit: 12,
+    });
+
+    expect(defaultPlans).toHaveLength(10);
+    expect(expandedPlans).toHaveLength(12);
+  });
+
   it('returns a compact rollup by default that omits description and file_scope', async () => {
     await call<PublishResult>('task_plan_publish', basicPublishArgs());
 
@@ -991,6 +1014,56 @@ describe('task_plan_claim_subtask', () => {
     expect(archivedWarnings()).toHaveLength(1);
   });
 
+  it('returns recovery details for stale sub-task pointers on an existing plan', async () => {
+    await call<PublishResult>(
+      'task_plan_publish',
+      basicPublishArgs({
+        slug: 'stale-claim-recovery',
+        subtasks: [
+          {
+            title: 'Build widget API',
+            description: 'Add GET /api/widgets.',
+            file_scope: ['apps/api/src/widgets.ts'],
+            capability_hint: 'api_work',
+          },
+          {
+            title: 'Build widget page',
+            description: 'Render the widget list.',
+            file_scope: ['apps/frontend/src/pages/widgets.tsx'],
+            capability_hint: 'ui_work',
+          },
+        ],
+      }),
+    );
+
+    const res = await client.callTool({
+      name: 'task_plan_claim_subtask',
+      arguments: {
+        plan_slug: 'stale-claim-recovery',
+        subtask_index: 9,
+        session_id: 'B',
+        agent: 'codex',
+      },
+    });
+    expect(res.isError).toBe(true);
+    const payload = JSON.parse(
+      (res.content as Array<{ type: string; text: string }>)[0]?.text ?? '{}',
+    ) as {
+      code: string;
+      error: string;
+      plan_slug: string;
+      next_available_subtask_index: number | null;
+      next_available_count: number;
+      next_available: Array<{ subtask_index: number; capability_hint: string | null }>;
+    };
+    expect(payload.code).toBe('PLAN_SUBTASK_STALE');
+    expect(payload.error).toContain('spec/stale-claim-recovery/sub-9');
+    expect(payload.plan_slug).toBe('stale-claim-recovery');
+    expect(payload.next_available_count).toBe(2);
+    expect(payload.next_available_subtask_index).toBe(0);
+    expect(payload.next_available.map((s) => s.subtask_index)).toEqual([0, 1]);
+  });
+
   it('reports a claimed sub-task by bound spec row id', async () => {
     await call<PublishResult>(
       'task_plan_publish',

apps/mcp-server/test/ready-queue.test.ts

@@ -792,6 +792,50 @@ describe('task_ready_for_agent', () => {
     });
   });
 
+  it('does not return ready entries whose advertised sub-task index has no branch row', async () => {
+    const parent = TaskThread.open(store, {
+      repo_root: repoRoot,
+      branch: 'spec/stale-ready-pointer',
+      session_id: 'planner',
+      title: 'Stale ready pointer',
+    });
+    const subtask = TaskThread.open(store, {
+      repo_root: repoRoot,
+      branch: 'spec/stale-ready-pointer/sub-0',
+      session_id: 'planner',
+      title: 'Stale subtask branch',
+    });
+    store.addObservation({
+      session_id: 'planner',
+      task_id: subtask.task_id,
+      kind: 'plan-subtask',
+      content: 'Stale advertised index\n\nThe metadata points at sub-7, but only sub-0 exists.',
+      metadata: {
+        parent_plan_slug: 'stale-ready-pointer',
+        parent_plan_title: 'Stale ready pointer',
+        parent_spec_task_id: parent.task_id,
+        subtask_index: 7,
+        title: 'Stale advertised index',
+        description: 'The metadata points at sub-7, but only sub-0 exists.',
+        file_scope: ['apps/api/stale-ready.ts'],
+        depends_on: [],
+        spec_row_id: null,
+        capability_hint: 'api_work',
+        status: 'available',
+      },
+    });
+
+    const result = await call<ReadyResult>('task_ready_for_agent', {
+      session_id: 'agent-session',
+      agent: 'codex',
+      repo_root: repoRoot,
+      auto_claim: false,
+    });
+
+    expect(result.ready).toEqual([]);
+    expect(result.total_available).toBe(0);
+  });
+
   it('returns the empty state when all future sub-tasks are blocked', async () => {
     await call('task_plan_publish', {
       ...publishArgs(
@@ -1313,6 +1357,7 @@ describe('task_ready_for_agent', () => {
 
   it('keeps quota relay ready payloads compact for many files and long handoffs', async () => {
     const sessionId = 'quota-session';
+    store.startSession({ id: sessionId, ide: 'codex', cwd: repoRoot });
     const thread = TaskThread.open(store, {
       repo_root: repoRoot,
       branch: 'agent/codex/large-quota-relay',

openspec/changes/agent-codex-task-plan-list-default-limit-10-2026-05-14-02-37/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-14

openspec/changes/agent-codex-task-plan-list-default-limit-10-2026-05-14-02-37/proposal.md

@@ -0,0 +1,20 @@
+## Why
+
+- `task_plan_list` defaults to returning up to 50 plans, which makes routine
+  MCP calls heavier than needed when the plan registry is large.
+- Agents should still be able to request a larger page explicitly, but the
+  default browse surface should stay compact.
+
+## What Changes
+
+- Lower the core `listPlans()` default limit from 50 to 10.
+- Preserve the MCP `task_plan_list.limit` validation cap at 50.
+- Add regression coverage that verifies the default returns 10 plans and an
+  explicit `limit` can still return more.
+
+## Impact
+
+- Affected surfaces: Colony core plan listing and the MCP `task_plan_list`
+  tool.
+- Callers that need larger responses must pass `limit` explicitly.
+- No schema or migration changes.

openspec/changes/agent-codex-task-plan-list-default-limit-10-2026-05-14-02-37/specs/task-plan-list-default-limit-10/spec.md

@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Compact task_plan_list default
+The system SHALL default `task_plan_list` and core `listPlans()` responses to at most 10 plans when callers omit an explicit limit.
+
+#### Scenario: Default list is compact
+- **WHEN** more than 10 published plans exist
+- **AND** a caller invokes `task_plan_list` without `limit`
+- **THEN** the response contains at most 10 plans.
+
+#### Scenario: Explicit larger limit remains available
+- **WHEN** more than 10 published plans exist
+- **AND** a caller invokes `task_plan_list` with an explicit limit above 10 and within the existing cap
+- **THEN** the response honors the explicit limit.