feat(coordination): open mode — advisory role gates, loud claim contention (new default) (#591)

* feat(coordination): open mode — advisory role gates, loud claim contention (new default)

Unprofiled agents default to the executor role and could not propose;
scouts could not claim; contended claims hard-failed. coordinationMode
('open' default | 'guarded') makes roles advisory: open lifts
SCOUT_NO_CLAIM, EXECUTOR_CANNOT_PROPOSE, the scout proposal cap, and
executor proposal filtering, and turns claim-conflict errors into
successful responses carrying contention/warning/contention_detail
(table ownership stays with the live owner). Queen-only approval,
subtask completion ownership, evidence, and protected-branch rejection
stay hard in both modes. task_plan_claim_subtask gains force:true with
a plan-subtask-force-claim audit note.

* test(coordination): force-claim coverage + open-mode handler tests; review fixes

Audit note for force-claims now writes inside the claim transaction so
lost races leave no false trail. filterReadyForExecutor mode param is
required (no silent guarded default).

---------

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

Author: NagyVikt

.changeset/open-coordination-mode.md

@@ -0,0 +1,6 @@
+---
+'@colony/mcp-server': minor
+'@colony/config': minor
+---
+
+Open coordination mode (new default): role gates become advisory. `settings.coordinationMode: 'open' | 'guarded'` — under open, scouts can claim, any agent can propose (no cap), everyone sees all proposals, and contended `task_claim_file` calls succeed with loud contention info (`contention`, `contention_detail`, `warning`) instead of erroring; table ownership stays with the live owner. Queen-only approval, subtask completion ownership, evidence requirements, and protected-branch rejection stay hard in both modes. `task_plan_claim_subtask` gains `force: boolean` to override unmet deps with an audit note. Set `coordinationMode: 'guarded'` to restore strict behavior.

apps/mcp-server/src/handlers/claims.ts

@@ -31,14 +31,19 @@ export function actorRole(store: MemoryStore, ctx: ClaimActorContext): AgentRole
 }
 
 export function enforceScoutNoClaim(store: MemoryStore, ctx: ClaimActorContext): void {
+  // Open mode (default): roles are advisory hints, not capability walls.
+  if (store.settings.coordinationMode === 'open') return;
   if (actorRole(store, ctx) !== 'scout') return;
   throw new ClaimsHandlerError(SCOUT_NO_CLAIM, 'scouts cannot claim files; propose instead');
 }
 
 export function filterReadyForExecutor<T extends ProposalReadyRow>(
   rows: readonly T[],
   role: AgentRole,
+  mode: 'open' | 'guarded',
 ): T[] {
+  // Open mode: every agent sees every proposal, approved or not.
+  if (mode === 'open') return [...rows];
   if (role === 'scout') return [];
   if (role === 'executor') {
     return rows.filter((row) => row.proposal_status == null || row.proposal_status === 'approved');

apps/mcp-server/src/handlers/proposals.ts

@@ -89,7 +89,10 @@ export function handleTaskPropose(
       const db = rawDb(store);
       assertProposalSchema(db);
       const actor = loadActorProfile(store, ctx.agent);
-      if (actor.role === 'executor') {
+      // Role gate and cap apply only in guarded mode; the evidence requirement
+      // below is data quality, not role policy, and holds in both modes.
+      const guarded = store.settings.coordinationMode === 'guarded';
+      if (guarded && actor.role === 'executor') {
         throw new TaskThreadError(
           TASK_THREAD_ERROR_CODES.EXECUTOR_CANNOT_PROPOSE,
           'executors cannot propose; scouts must provide evidence first',
@@ -101,7 +104,7 @@ export function handleTaskPropose(
           'observationEvidenceIds must contain at least one evidence id',
         );
       }
-      if (actor.openProposalCount >= MAX_OPEN_PROPOSALS_PER_SCOUT) {
+      if (guarded && actor.openProposalCount >= MAX_OPEN_PROPOSALS_PER_SCOUT) {
         throw new TaskThreadError(
           TASK_THREAD_ERROR_CODES.PROPOSAL_CAP_EXCEEDED,
           `scout ${ctx.agent} already has ${MAX_OPEN_PROPOSALS_PER_SCOUT} open proposals`,

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

@@ -450,6 +450,10 @@ export function register(server: McpServer, ctx: ToolContext): void {
       agent: z.string().min(1),
       repo_root: z.string().min(1).optional(),
       file_scope: z.array(z.string().min(1)).optional(),
+      force: z
+        .boolean()
+        .optional()
+        .describe('Claim even when depends_on sub-tasks are incomplete; records an audit note.'),
     },
     wrapHandler('task_plan_claim_subtask', async (args) => {
       const result = attemptClaimPlanSubtask(store, args);
@@ -658,6 +662,8 @@ export type ClaimPlanSubtaskArgs = {
   session_id: string;
   agent: string;
   repo_root?: string | undefined;
+  /** Skip the depends_on completeness check (records a force-claim note). */
+  force?: boolean | undefined;
 };
 
 export type ClaimPlanSubtaskResult =
@@ -725,16 +731,20 @@ export function attemptClaimPlanSubtask(
     .filter((s): s is SubtaskLookup => s !== null)
     .map((s) => s.info);
 
+  let forcedUnmetDeps: number[] = [];
   if (!areDepsMet(located.info, siblings)) {
     const unmet = located.info.depends_on.filter((idx) => {
       const dep = siblings.find((s) => s.subtask_index === idx);
       return dep?.status !== 'completed';
     });
-    return {
-      ok: false,
-      code: 'PLAN_SUBTASK_DEPS_UNMET',
-      message: `dependencies not met: sub-tasks [${unmet.join(', ')}] are not completed`,
-    };
+    if (!args.force) {
+      return {
+        ok: false,
+        code: 'PLAN_SUBTASK_DEPS_UNMET',
+        message: `dependencies not met: sub-tasks [${unmet.join(', ')}] are not completed`,
+      };
+    }
+    forcedUnmetDeps = unmet;
   }
 
   try {
@@ -781,6 +791,18 @@ export function attemptClaimPlanSubtask(
             };
           }
         }
+        // Audit the dep override only once the claim is actually happening —
+        // written outside this transaction it would record force-claims that
+        // lost the race and never occurred.
+        if (forcedUnmetDeps.length > 0) {
+          store.addObservation({
+            session_id: args.session_id,
+            task_id: fresh.task_id,
+            kind: 'note',
+            content: `force-claimed sub-${args.subtask_index} of ${args.plan_slug} past unmet deps [${forcedUnmetDeps.join(', ')}]`,
+            metadata: { kind: 'plan-subtask-force-claim', unmet_deps: forcedUnmetDeps },
+          });
+        }
         store.addObservation({
           session_id: args.session_id,
           task_id: fresh.task_id,

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

@@ -465,6 +465,7 @@ export async function buildReadyForAgent(
         ),
     ),
     role,
+    store.settings.coordinationMode,
   );
   const currentClaims = filterReadyForExecutor(
     plans.flatMap((plan) =>
@@ -491,6 +492,7 @@ export async function buildReadyForAgent(
         ),
     ),
     role,
+    store.settings.coordinationMode,
   );
   const urgentTaskIds = blockingMessageTaskIds(store, {
     session_id: args.session_id,

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

@@ -402,14 +402,16 @@ export function register(server: McpServer, ctx: ToolContext): void {
         session_id,
         file_path: normalizedFilePath,
       });
-      if (guarded.status === 'takeover_recommended') {
-        return mcpErrorResponse(
-          'CLAIM_TAKEOVER_RECOMMENDED',
-          guarded.recommendation ?? 'release or take over inactive claim before claiming',
-          { ...guarded },
-        );
-      }
-      if (guarded.status === 'blocked_active_owner') {
+      const contended =
+        guarded.status === 'takeover_recommended' || guarded.status === 'blocked_active_owner';
+      if (contended && settings.coordinationMode === 'guarded') {
+        if (guarded.status === 'takeover_recommended') {
+          return mcpErrorResponse(
+            'CLAIM_TAKEOVER_RECOMMENDED',
+            guarded.recommendation ?? 'release or take over inactive claim before claiming',
+            { ...guarded },
+          );
+        }
         return mcpErrorResponse(
           'CLAIM_HELD_BY_ACTIVE_OWNER',
           guarded.recommendation ?? 'request handoff or explicit takeover before claiming',
@@ -443,12 +445,20 @@ export function register(server: McpServer, ctx: ToolContext): void {
       const previousClaim = previous
         ? compactPreviousClaim(previous, session_id, settings.claimStaleMinutes)
         : null;
+      // Open mode lets contended claims through: the claim succeeds, but the
+      // response carries the contention loudly so the agent coordinates
+      // instead of silently clobbering a live owner.
       return jsonReply({
         observation_id: id,
         file_path: normalizedFilePath,
         claim_status: guarded.status,
         claim_task_id: guarded.claim_task_id ?? task_id,
-        warning: null,
+        contention: contended,
+        contention_detail: contended ? { ...guarded } : null,
+        warning: contended
+          ? (guarded.recommendation ??
+            'another live session holds this file; coordinate via task_message before editing')
+          : null,
         live_file_contentions: [],
         overlap: previousClaim?.overlap ?? 'none',
         previous_claim: previousClaim,

apps/mcp-server/test/handlers/claims.test.ts

@@ -10,12 +10,16 @@ import {
   filterReadyForExecutor,
 } from '../../src/handlers/claims.js';
 
+// These suites exercise the strict role/claim gates, which only apply in
+// guarded mode (open is the default since the coordinationMode change).
+const guardedSettings = { ...defaultSettings, coordinationMode: 'guarded' as const };
+
 let dataDir: string;
 let store: MemoryStore;
 
 beforeEach(() => {
   dataDir = mkdtempSync(join(tmpdir(), 'colony-claims-handler-'));
-  store = new MemoryStore({ dbPath: join(dataDir, 'data.db'), settings: defaultSettings });
+  store = new MemoryStore({ dbPath: join(dataDir, 'data.db'), settings: guardedSettings });
 });
 
 afterEach(() => {
@@ -62,14 +66,43 @@ describe('filterReadyForExecutor', () => {
   ];
 
   it('hides proposal work from scout actors', () => {
-    expect(filterReadyForExecutor(rows, 'scout')).toEqual([]);
+    expect(filterReadyForExecutor(rows, 'scout', 'guarded')).toEqual([]);
   });
 
   it('shows only normal and approved proposal work to executors', () => {
-    expect(filterReadyForExecutor(rows, 'executor').map((row) => row.id)).toEqual([1, 3]);
+    expect(filterReadyForExecutor(rows, 'executor', 'guarded').map((row) => row.id)).toEqual([
+      1, 3,
+    ]);
   });
 
   it('leaves all work visible for queen actors', () => {
-    expect(filterReadyForExecutor(rows, 'queen')).toEqual(rows);
+    expect(filterReadyForExecutor(rows, 'queen', 'guarded')).toEqual(rows);
+  });
+});
+
+describe('open coordination mode', () => {
+  it('lets scouts claim and shows executors every proposal', () => {
+    const openStore = new MemoryStore({
+      dbPath: join(dataDir, 'open.db'),
+      settings: { ...defaultSettings, coordinationMode: 'open' },
+    });
+    try {
+      openStore.storage.upsertAgentProfile({
+        agent: 'scout-open',
+        capabilities: '{}',
+        role: 'scout',
+        updated_at: 1,
+      });
+      expect(() => enforceScoutNoClaim(openStore, { agent: 'scout-open' })).not.toThrow();
+      const rows = [
+        { id: 1, proposal_status: null },
+        { id: 2, proposal_status: 'proposed' as const },
+        { id: 3, proposal_status: 'approved' as const },
+      ];
+      expect(filterReadyForExecutor(rows, 'executor', 'open').map((r) => r.id)).toEqual([1, 2, 3]);
+      expect(filterReadyForExecutor(rows, 'scout', 'open').map((r) => r.id)).toEqual([1, 2, 3]);
+    } finally {
+      openStore.close();
+    }
   });
 });

apps/mcp-server/test/handlers/proposals.test.ts

@@ -10,6 +10,10 @@ import {
   handleTaskPropose,
 } from '../../src/handlers/proposals.js';
 
+// These suites exercise the strict role/claim gates, which only apply in
+// guarded mode (open is the default since the coordinationMode change).
+const guardedSettings = { ...defaultSettings, coordinationMode: 'guarded' as const };
+
 interface SqlRunResult {
   changes: number;
   lastInsertRowid: number | bigint;
@@ -35,7 +39,7 @@ let db: SqlDatabase;
 
 beforeEach(() => {
   dir = mkdtempSync(join(tmpdir(), 'colony-mcp-proposals-'));
-  store = new MemoryStore({ dbPath: join(dir, 'data.db'), settings: defaultSettings });
+  store = new MemoryStore({ dbPath: join(dir, 'data.db'), settings: guardedSettings });
   db = (store.storage as unknown as StorageWithDb).db;
   installProposalSchema();
 });

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

@@ -879,6 +879,41 @@ describe('task_plan_claim_subtask', () => {
     expect(err.code).toBe('PLAN_SUBTASK_DEPS_UNMET');
   });
 
+  it('force=true claims past unmet deps and records an audit note', async () => {
+    await call<PublishResult>('task_plan_publish', basicPublishArgs());
+    const claimed = await call<{ task_id: number }>('task_plan_claim_subtask', {
+      plan_slug: 'add-widget-page',
+      subtask_index: 1,
+      session_id: 'B',
+      agent: 'codex',
+      force: true,
+    });
+    expect(claimed.task_id).toBeGreaterThan(0);
+    const notes = store.storage
+      .taskObservationsByKind(claimed.task_id, 'note', 10)
+      .filter((o) => o.metadata?.includes('plan-subtask-force-claim'));
+    expect(notes).toHaveLength(1);
+    expect(notes[0]?.content).toContain('past unmet deps [0]');
+  });
+
+  it('force=true does not bypass the already-claimed race check', async () => {
+    await call<PublishResult>('task_plan_publish', basicPublishArgs());
+    await call('task_plan_claim_subtask', {
+      plan_slug: 'add-widget-page',
+      subtask_index: 0,
+      session_id: 'A',
+      agent: 'claude',
+    });
+    const err = await callError('task_plan_claim_subtask', {
+      plan_slug: 'add-widget-page',
+      subtask_index: 0,
+      session_id: 'B',
+      agent: 'codex',
+      force: true,
+    });
+    expect(err.code).toBe('PLAN_SUBTASK_NOT_AVAILABLE');
+  });
+
   it('rejects a second claim on an already-claimed sub-task (race)', async () => {
     // The load-bearing test for the lane: two agents racing on the same
     // available sub-task. The transaction-based scan-before-stamp inside the

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

@@ -458,12 +458,17 @@ beforeEach(async () => {
   dataDir = mkdtempSync(join(tmpdir(), 'colony-ready-data-'));
   repoRoot = mkdtempSync(join(tmpdir(), 'colony-ready-repo-'));
   writeFileSync(join(repoRoot, 'SPEC.md'), '# SPEC\n', 'utf8');
-  store = new MemoryStore({ dbPath: join(dataDir, 'data.db'), settings: defaultSettings });
+  // Executor proposal filtering only applies in guarded mode (open is the
+  // default since the coordinationMode change).
+  store = new MemoryStore({
+    dbPath: join(dataDir, 'data.db'),
+    settings: { ...defaultSettings, coordinationMode: 'guarded' as const },
+  });
   store.startSession({ id: 'planner', ide: 'claude-code', cwd: repoRoot });
   store.startSession({ id: 'queen', ide: 'queen', cwd: repoRoot });
   store.startSession({ id: 'agent-session', ide: 'codex', cwd: repoRoot });
   store.startSession({ id: 'other-session', ide: 'claude-code', cwd: repoRoot });
-  const server = buildServer(store, defaultSettings);
+  const server = buildServer(store, { ...defaultSettings, coordinationMode: 'guarded' as const });
   const [clientT, serverT] = InMemoryTransport.createLinkedPair();
   client = new Client({ name: 'test', version: '0.0.0' });
   await Promise.all([server.connect(serverT), client.connect(clientT)]);