@sqaoss/flowy 1.13.1 → 1.14.0

package/README.md

@@ -263,6 +263,19 @@ bun run typecheck     # TypeScript
 cd server && bunx --bun vitest run   # Server tests
 ```
 
+## Open Source vs. Hosted
+
+This repository — the `@sqaoss/flowy` CLI **and the bundled local server** it runs
+via `flowy serve` — is open source under Apache-2.0. You can self-host the full
+planning workflow with no account and no subscription; your data stays in a local
+SQLite file on your machine.
+
+The hosted service at `flowy-ai.fly.dev` is a separate, commercial offering. It is
+a proprietary backend whose source is **not** part of this repository, and it
+exposes a superset of the open-source server's GraphQL schema plus account and
+billing operations. Using the hosted service is optional — the CLI talks to either
+your local server or the hosted one depending on how you configure it.
+
 ## License
 
 Apache-2.0. Copyright 2026 SQA & Automation SRL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
@@ -47,6 +47,8 @@
   ],
   "scripts": {
     "cli": "bun src/index.ts",
+    "audit": "bun audit",
+    "audit:prod": "bun audit --production --json",
     "check": "biome check --write .",
     "test": "vitest run",
     "test:watch": "vitest",

package/server/src/contract.test.ts

@@ -255,6 +255,41 @@ describe('CLI/local-server contract (P1-1)', () => {
     expect(updateNode.title).toBe('Renamed Task')
     expect(updateNode.metadata).toContain('note')
 
+    // CLAIM_NODE (P2-1/F28): atomically claim a task for work. A fresh draft
+    // task is claimable -> flips to in_progress and is returned. A second claim
+    // on the same (now in_progress) task loses the race -> claimNode is null.
+    // A non-claimable (done) task is also rejected with null. This is the
+    // primitive `task claim`/`task next` use so parallel agents never
+    // double-claim; the SaaS contract guard mirrors it (flowy-ai v35).
+    const { createNode: claimable } = await ok<{
+      createNode: { id: string }
+    }>(LOCAL_CONTRACT_OPERATIONS.CREATE_TASK, {
+      type: 'task',
+      title: 'Claimable Task',
+      description: 'up for grabs',
+    })
+    const firstClaim = await ok<{
+      claimNode: { id: string; status: string } | null
+    }>(LOCAL_CONTRACT_OPERATIONS.CLAIM_NODE, { id: claimable.id })
+    expect(firstClaim.claimNode?.id).toBe(claimable.id)
+    expect(firstClaim.claimNode?.status).toBe('in_progress')
+    // Second claim on the same task loses: already in_progress, not claimable.
+    const secondClaim = await ok<{ claimNode: { id: string } | null }>(
+      LOCAL_CONTRACT_OPERATIONS.CLAIM_NODE,
+      { id: claimable.id },
+    )
+    expect(secondClaim.claimNode).toBeNull()
+    // A done task is never claimable.
+    await ok(LOCAL_CONTRACT_OPERATIONS.UPDATE_STATUS, {
+      id: claimable.id,
+      status: 'done',
+    })
+    const doneClaim = await ok<{ claimNode: { id: string } | null }>(
+      LOCAL_CONTRACT_OPERATIONS.CLAIM_NODE,
+      { id: claimable.id },
+    )
+    expect(doneClaim.claimNode).toBeNull()
+
     // --- Queries: reads ----------------------------------------------------
     const getNode = await ok<{ node: { id: string } | null }>(
       LOCAL_CONTRACT_OPERATIONS.GET_NODE,
@@ -489,6 +524,7 @@ describe('CLI/local-server contract (P1-1)', () => {
       'UPDATE_NODE',
       'UPDATE_STATUS',
       'APPROVE_NODE',
+      'CLAIM_NODE',
       'DELETE_NODE',
       'CREATE_EDGE',
       'LINK_TASK',

package/server/src/resolvers.test.ts

@@ -395,6 +395,40 @@ describe('createResolvers', () => {
         expect(e.extensions?.code).toBe('VALIDATION_ERROR')
       }
     })
+
+    it('applies the row update and its audit rows in one transaction (F28)', () => {
+      // The read-modify-write must be a single transaction so a node update and
+      // its audit trail commit together. We assert the observable contract: a
+      // multi-field update lands the row change AND exactly the matching audit
+      // entries (no partial application).
+      const node = create(resolvers, {
+        type: 'task',
+        title: 'Old',
+        description: 'old body',
+      })
+      const auditBefore = resolvers.Query.auditLog(null, {
+        nodeId: node.id,
+      }).length
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        title: 'New',
+        status: 'in_progress',
+      })
+      expect(updated.title).toBe('New')
+      expect(updated.status).toBe('in_progress')
+      // Row change is persisted (read-back).
+      const persisted = find(resolvers, node.id)
+      expect(persisted.title).toBe('New')
+      expect(persisted.status).toBe('in_progress')
+      // Two field diffs -> two new audit rows (a title `update` + a
+      // `status_change`), committed in the same unit as the row write.
+      const history = resolvers.Query.auditLog(null, { nodeId: node.id })
+      expect(history.length).toBe(auditBefore + 2)
+      expect(history.some((e) => e.action === 'status_change')).toBe(true)
+      expect(
+        history.some((e) => e.action === 'update' && e.field === 'title'),
+      ).toBe(true)
+    })
   })
 
   describe('Mutation.deleteNode', () => {
@@ -514,6 +548,73 @@ describe('createResolvers', () => {
     })
   })
 
+  describe('Mutation.claimNode (F28 atomic CAS)', () => {
+    const CLAIMABLE = ['draft', 'pending_review', 'approved', 'blocked']
+
+    it.each(
+      CLAIMABLE,
+    )('claims a %s task into in_progress and returns it', (status) => {
+      const node = create(resolvers, { type: 'task', title: 'Claim me' })
+      if (status !== 'draft') {
+        resolvers.Mutation.updateNode(null, { id: node.id, status })
+      }
+      const claimed = resolvers.Mutation.claimNode(null, { id: node.id })
+      expect(claimed).not.toBeNull()
+      expect(claimed?.id).toBe(node.id)
+      expect(claimed?.status).toBe('in_progress')
+      // The change is persisted, not just returned.
+      expect(find(resolvers, node.id).status).toBe('in_progress')
+    })
+
+    it('returns null when the node is already in_progress (lost the race)', () => {
+      const node = create(resolvers, { type: 'task', title: 'Hot' })
+      const first = resolvers.Mutation.claimNode(null, { id: node.id })
+      expect(first?.status).toBe('in_progress')
+      // A second claim on the same node loses: CAS no longer matches.
+      const second = resolvers.Mutation.claimNode(null, { id: node.id })
+      expect(second).toBeNull()
+      // Still in_progress, untouched by the losing claim.
+      expect(find(resolvers, node.id).status).toBe('in_progress')
+    })
+
+    it.each([
+      'done',
+      'cancelled',
+      'in_progress',
+    ])('returns null for a non-claimable %s node', (status) => {
+      const node = create(resolvers, { type: 'task', title: 'Nope' })
+      resolvers.Mutation.updateNode(null, { id: node.id, status })
+      const claimed = resolvers.Mutation.claimNode(null, { id: node.id })
+      expect(claimed).toBeNull()
+      expect(find(resolvers, node.id).status).toBe(status)
+    })
+
+    it('returns null for a nonexistent node (nothing to claim)', () => {
+      expect(
+        resolvers.Mutation.claimNode(null, { id: 'task_missing' }),
+      ).toBeNull()
+    })
+
+    it('records a status_change audit entry on a successful claim', () => {
+      const node = create(resolvers, { type: 'task', title: 'Audited' })
+      resolvers.Mutation.claimNode(null, { id: node.id })
+      const history = resolvers.Query.auditLog(null, { nodeId: node.id })
+      const statusChange = history.find((e) => e.action === 'status_change')
+      expect(statusChange?.field).toBe('status')
+      expect(statusChange?.oldValue).toBe('draft')
+      expect(statusChange?.newValue).toBe('in_progress')
+    })
+
+    it('writes no audit entry when the claim loses', () => {
+      const node = create(resolvers, { type: 'task', title: 'Loser' })
+      resolvers.Mutation.claimNode(null, { id: node.id })
+      const before = resolvers.Query.auditLog(null, { nodeId: node.id }).length
+      resolvers.Mutation.claimNode(null, { id: node.id }) // loses
+      const after = resolvers.Query.auditLog(null, { nodeId: node.id }).length
+      expect(after).toBe(before)
+    })
+  })
+
   describe('Mutation.createEdge', () => {
     it('links two nodes', () => {
       const project = resolvers.Mutation.createNode(null, {

package/server/src/resolvers.ts

@@ -118,6 +118,15 @@ const VALID_STATUSES = new Set([
   'cancelled',
 ])
 
+/**
+ * Statuses a task may be atomically claimed *from* by `claimNode` (F28). A claim
+ * flips any of these to `in_progress` in a single CAS statement. `in_progress`,
+ * `done`, and `cancelled` are intentionally excluded: an already-claimed,
+ * finished, or abandoned task is not up for grabs. Kept in lockstep with the
+ * SaaS `CLAIMABLE_STATUSES` so a claim behaves identically across backends.
+ */
+const CLAIMABLE_STATUSES = ['draft', 'pending_review', 'approved', 'blocked']
+
 function assertValidStatus(status: string): void {
   if (!VALID_STATUSES.has(status)) {
     throw validationError(
@@ -588,80 +597,92 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
           metadata?: string
         },
       ) => {
-        const existing = db.raw
-          .query('SELECT * FROM nodes WHERE id = ?')
-          .get(args.id) as NodeRow | null
-        if (!existing) throw notFoundError(`Node ${args.id} not found`)
-
+        // Input validation that does NOT depend on the current row is done up
+        // front so a malformed request errors before opening a transaction.
         if (args.title != null && !args.title.trim()) {
           throw validationError('Title cannot be empty')
         }
         if (args.description != null && !args.description.trim()) {
           throw validationError('Description cannot be empty')
         }
-        if (args.status != null) {
-          assertValidStatus(args.status)
-          if (enforceStatusLifecycle) {
+        if (args.status != null) assertValidStatus(args.status)
+        // Normalize metadata up front too: a non-JSON value must be rejected
+        // (VALIDATION_ERROR) without touching the database.
+        const nextMetadata =
+          args.metadata != null ? normalizeMetadata(args.metadata) : undefined
+
+        const now = new Date().toISOString()
+        // Transactional read-modify-write (F28). The SELECT, the diff, the
+        // UPDATE, and the audit rows all run inside ONE transaction so a
+        // mid-update failure rolls the whole unit back (never a half-applied
+        // row with no audit, or vice versa) and the read can't observe a row a
+        // concurrent writer is mid-mutating. SQLite is a single writer, so the
+        // transaction also serializes this RMW against any other write —
+        // matching the SaaS FOR UPDATE row lock.
+        let next!: NodeRow
+        db.raw.transaction(() => {
+          const existing = db.raw
+            .query('SELECT * FROM nodes WHERE id = ?')
+            .get(args.id) as NodeRow | null
+          if (!existing) throw notFoundError(`Node ${args.id} not found`)
+          // The lifecycle transition check reads the current status, so it
+          // belongs inside the transaction with the row it validates against.
+          if (args.status != null && enforceStatusLifecycle) {
             assertValidTransition(existing.status, args.status)
           }
-        }
 
-        const next: NodeRow = {
-          ...existing,
-          title: args.title ?? existing.title,
-          description:
-            args.description !== undefined
-              ? args.description
-              : existing.description,
-          status: args.status ?? existing.status,
-          metadata:
-            args.metadata != null
-              ? normalizeMetadata(args.metadata)
-              : existing.metadata,
-        }
-        // Field-level diffs, mirroring SaaS: title/description/metadata changes
-        // are 'update' entries; a status change is a 'status_change' entry.
-        const diffs: Array<{
-          field: string
-          action: string
-          oldValue: string | null
-          newValue: string | null
-        }> = []
-        if (next.title !== existing.title) {
-          diffs.push({
-            field: 'title',
-            action: 'update',
-            oldValue: existing.title,
-            newValue: next.title,
-          })
-        }
-        if (next.description !== existing.description) {
-          diffs.push({
-            field: 'description',
-            action: 'update',
-            oldValue: existing.description,
-            newValue: next.description,
-          })
-        }
-        if (next.status !== existing.status) {
-          diffs.push({
-            field: 'status',
-            action: 'status_change',
-            oldValue: existing.status,
-            newValue: next.status,
-          })
-        }
-        if (next.metadata !== existing.metadata) {
-          diffs.push({
-            field: 'metadata',
-            action: 'update',
-            oldValue: existing.metadata,
-            newValue: next.metadata,
-          })
-        }
+          next = {
+            ...existing,
+            title: args.title ?? existing.title,
+            description:
+              args.description !== undefined
+                ? args.description
+                : existing.description,
+            status: args.status ?? existing.status,
+            metadata:
+              nextMetadata !== undefined ? nextMetadata : existing.metadata,
+          }
+          // Field-level diffs, mirroring SaaS: title/description/metadata
+          // changes are 'update' entries; a status change is 'status_change'.
+          const diffs: Array<{
+            field: string
+            action: string
+            oldValue: string | null
+            newValue: string | null
+          }> = []
+          if (next.title !== existing.title) {
+            diffs.push({
+              field: 'title',
+              action: 'update',
+              oldValue: existing.title,
+              newValue: next.title,
+            })
+          }
+          if (next.description !== existing.description) {
+            diffs.push({
+              field: 'description',
+              action: 'update',
+              oldValue: existing.description,
+              newValue: next.description,
+            })
+          }
+          if (next.status !== existing.status) {
+            diffs.push({
+              field: 'status',
+              action: 'status_change',
+              oldValue: existing.status,
+              newValue: next.status,
+            })
+          }
+          if (next.metadata !== existing.metadata) {
+            diffs.push({
+              field: 'metadata',
+              action: 'update',
+              oldValue: existing.metadata,
+              newValue: next.metadata,
+            })
+          }
 
-        const now = new Date().toISOString()
-        db.raw.transaction(() => {
           db.raw.run(
             'UPDATE nodes SET title = ?, description = ?, status = ?, metadata = ?, updated_at = ? WHERE id = ?',
             [
@@ -752,6 +773,52 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
         return rowToNode({ ...existing, status: 'approved', updated_at: now })
       },
 
+      // Atomically claim a task for work (F28). A single compare-and-set
+      // `UPDATE ... WHERE id = ? AND status IN (<claimable>)` flips a claimable
+      // node to in_progress and returns the new row via RETURNING. SQLite is a
+      // single writer, so the statement is its own atomic unit: exactly one of
+      // two concurrent claimers can match the WHERE clause and get a row back;
+      // the loser's UPDATE matches nothing and returns null. This is the
+      // primitive that lets parallel agents share one backlog without
+      // double-claiming. Returns null when the node is missing, already
+      // in_progress/done/cancelled, or lost the race. Mirrors SaaS `claimNode`.
+      claimNode: (_: unknown, args: { id: string }): NodeGql | null => {
+        const placeholders = CLAIMABLE_STATUSES.map(() => '?').join(', ')
+        const now = new Date().toISOString()
+        let claimed: NodeRow | null = null
+        // Read-then-CAS inside ONE transaction. SQLite is a single writer, so
+        // the transaction serializes against any concurrent claimer: we capture
+        // the prior status (for an accurate audit oldValue), then run the gated
+        // CAS. Reading first is safe precisely because the write below is in the
+        // same atomic unit — no other writer can slip in between. The CAS
+        // (`WHERE status IN (<claimable>)`) is still the source of truth for who
+        // wins; the prior read only labels the audit entry.
+        db.raw.transaction(() => {
+          const prior = db.raw
+            .query('SELECT status FROM nodes WHERE id = ?')
+            .get(args.id) as { status: string } | null
+          claimed = db.raw
+            .query(
+              `UPDATE nodes SET status = 'in_progress', updated_at = ?
+               WHERE id = ? AND status IN (${placeholders})
+               RETURNING ${NODE_COLS}`,
+            )
+            .get(now, args.id, ...CLAIMABLE_STATUSES) as NodeRow | null
+          // Only the winner audits a status_change; a losing/no-match claim
+          // touches no row and writes nothing.
+          if (claimed) {
+            insertAudit(db, {
+              nodeId: claimed.id,
+              action: 'status_change',
+              field: 'status',
+              oldValue: prior?.status ?? null,
+              newValue: 'in_progress',
+            })
+          }
+        })()
+        return claimed ? rowToNode(claimed) : null
+      },
+
       createEdge: (
         _: unknown,
         args: { sourceId: string; targetId: string; relation: string },

package/server/src/schema.test.ts

@@ -70,7 +70,7 @@ describe('schema', () => {
     expect(fields.tree).toBeUndefined()
   })
 
-  it('Mutation type has createNode, updateNode, approveNode, deleteNode, createEdge, removeEdge', () => {
+  it('Mutation type has createNode, updateNode, approveNode, claimNode, deleteNode, createEdge, removeEdge', () => {
     const mutationType = schema.getType(
       'Mutation',
     ) as import('graphql').GraphQLObjectType
@@ -78,11 +78,24 @@ describe('schema', () => {
     expect(fields.createNode).toBeDefined()
     expect(fields.updateNode).toBeDefined()
     expect(fields.approveNode).toBeDefined()
+    expect(fields.claimNode).toBeDefined()
     expect(fields.deleteNode).toBeDefined()
     expect(fields.createEdge).toBeDefined()
     expect(fields.removeEdge).toBeDefined()
   })
 
+  it('claimNode takes an id arg and returns a NULLABLE Node (null on lost race)', () => {
+    const mutationType = schema.getType(
+      'Mutation',
+    ) as import('graphql').GraphQLObjectType
+    const claimNode = mutationType.getFields().claimNode
+    const args = claimNode.args.map((a) => a.name)
+    expect(args).toEqual(expect.arrayContaining(['id']))
+    // Nullable on purpose: a lost race / non-claimable node returns null, not
+    // an error. So the type must be `Node`, never `Node!`.
+    expect(String(claimNode.type)).toBe('Node')
+  })
+
   it('createNode accepts type, title, description, status, metadata args', () => {
     const mutationType = schema.getType(
       'Mutation',

package/server/src/schema.ts

@@ -95,6 +95,12 @@ export const typeDefs = /* GraphQL */ `
       metadata: String
     ): Node!
     approveNode(id: String!): Node!
+    # Atomically claim a task for work (F28). Compare-and-set: flips a claimable
+    # node (draft/pending_review/approved/blocked) to in_progress in a single
+    # statement and returns it. Returns null if the node does not exist, is not
+    # claimable, or was already claimed by a concurrent caller (lost the race) —
+    # so parallel agents never double-claim the same task.
+    claimNode(id: String!): Node
     deleteNode(id: String!): Boolean!
     createEdge(sourceId: String!, targetId: String!, relation: String!): Edge!
     removeEdge(sourceId: String!, targetId: String!, relation: String!): Boolean!

package/src/commands/task.test.ts

@@ -23,10 +23,10 @@ describe('task command', () => {
     vi.clearAllMocks()
   })
 
-  test('exports a command group with 8 subcommands', async () => {
+  test('exports a command group with 10 subcommands', async () => {
     const { taskCommand } = await import('./task.ts')
     expect(taskCommand.name()).toBe('task')
-    expect(taskCommand.commands).toHaveLength(8)
+    expect(taskCommand.commands).toHaveLength(10)
 
     const names = taskCommand.commands.map((c) => c.name())
     expect(names).toContain('create')
@@ -37,6 +37,8 @@ describe('task command', () => {
     expect(names).toContain('update')
     expect(names).toContain('delete')
     expect(names).toContain('deps')
+    expect(names).toContain('claim')
+    expect(names).toContain('next')
   })
 
   test('create exposes both --description and --description-file options', async () => {
@@ -437,4 +439,156 @@ describe('task command', () => {
       { id: 'task_2', type: 'task', title: 'Two', status: 'done' },
     ])
   })
+
+  test('claim sends claimNode and prints the claimed task', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      claimNode: { id: 'task_1', status: 'in_progress' },
+    })
+
+    const claimCmd = taskCommand.commands.find((c) => c.name() === 'claim')!
+    await claimCmd.parseAsync(['task_1'], { from: 'user' })
+
+    const [query, variables] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('claimNode')
+    expect(variables).toMatchObject({ id: 'task_1' })
+    expect(output).toHaveBeenCalledWith({ id: 'task_1', status: 'in_progress' })
+  })
+
+  test('claim reports a lost race (null) via outputError with non-zero exit', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output, outputError } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    // claimNode returns null: the task was already claimed / not claimable.
+    vi.mocked(graphql).mockResolvedValueOnce({ claimNode: null })
+
+    const claimCmd = taskCommand.commands.find((c) => c.name() === 'claim')!
+    await claimCmd.parseAsync(['task_1'], { from: 'user' })
+
+    expect(output).not.toHaveBeenCalled()
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringMatching(/already claimed|not claimable/i),
+      }),
+    )
+  })
+
+  test('next claims the first ready task and prints it', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql)
+      // readyTasks
+      .mockResolvedValueOnce({
+        readyTasks: [
+          { id: 'task_a', title: 'A', status: 'draft' },
+          { id: 'task_b', title: 'B', status: 'draft' },
+        ],
+      })
+      // claimNode(task_a) wins
+      .mockResolvedValueOnce({
+        claimNode: { id: 'task_a', status: 'in_progress' },
+      })
+
+    const nextCmd = taskCommand.commands.find((c) => c.name() === 'next')!
+    await nextCmd.parseAsync([], { from: 'user' })
+
+    expect(graphql).toHaveBeenCalledTimes(2)
+    const [readyQuery] = vi.mocked(graphql).mock.calls[0]!
+    expect(readyQuery).toContain('readyTasks')
+    const [claimQuery, claimVars] = vi.mocked(graphql).mock.calls[1]!
+    expect(claimQuery).toContain('claimNode')
+    expect(claimVars).toMatchObject({ id: 'task_a' })
+    expect(output).toHaveBeenCalledWith({ id: 'task_a', status: 'in_progress' })
+  })
+
+  test('next retries the next candidate when a claim loses the race', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql)
+      // readyTasks
+      .mockResolvedValueOnce({
+        readyTasks: [
+          { id: 'task_a', title: 'A', status: 'draft' },
+          { id: 'task_b', title: 'B', status: 'draft' },
+        ],
+      })
+      // claimNode(task_a) loses (another agent took it)
+      .mockResolvedValueOnce({ claimNode: null })
+      // claimNode(task_b) wins
+      .mockResolvedValueOnce({
+        claimNode: { id: 'task_b', status: 'in_progress' },
+      })
+
+    const nextCmd = taskCommand.commands.find((c) => c.name() === 'next')!
+    await nextCmd.parseAsync([], { from: 'user' })
+
+    expect(graphql).toHaveBeenCalledTimes(3)
+    expect(vi.mocked(graphql).mock.calls[1]![1]).toMatchObject({ id: 'task_a' })
+    expect(vi.mocked(graphql).mock.calls[2]![1]).toMatchObject({ id: 'task_b' })
+    expect(output).toHaveBeenCalledWith({ id: 'task_b', status: 'in_progress' })
+  })
+
+  test('next reports when no ready tasks exist via outputError', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output, outputError } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({ readyTasks: [] })
+
+    const nextCmd = taskCommand.commands.find((c) => c.name() === 'next')!
+    await nextCmd.parseAsync([], { from: 'user' })
+
+    expect(output).not.toHaveBeenCalled()
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringMatching(/no ready|no claimable/i),
+      }),
+    )
+  })
+
+  test('next reports when every ready task lost its race via outputError', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output, outputError } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql)
+      .mockResolvedValueOnce({
+        readyTasks: [{ id: 'task_a', title: 'A', status: 'draft' }],
+      })
+      .mockResolvedValueOnce({ claimNode: null }) // lost
+
+    const nextCmd = taskCommand.commands.find((c) => c.name() === 'next')!
+    await nextCmd.parseAsync([], { from: 'user' })
+
+    expect(output).not.toHaveBeenCalled()
+    expect(outputError).toHaveBeenCalled()
+  })
+
+  test('next --project scopes readyTasks to the given project', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql)
+      .mockResolvedValueOnce({
+        readyTasks: [{ id: 'task_a', title: 'A', status: 'draft' }],
+      })
+      .mockResolvedValueOnce({
+        claimNode: { id: 'task_a', status: 'in_progress' },
+      })
+
+    const nextCmd = taskCommand.commands.find((c) => c.name() === 'next')!
+    await nextCmd.parseAsync(['--project', 'proj_42'], { from: 'user' })
+
+    const [readyQuery, readyVars] = vi.mocked(graphql).mock.calls[0]!
+    expect(readyQuery).toContain('readyTasks')
+    expect(readyVars).toMatchObject({ projectId: 'proj_42' })
+  })
 })

package/src/commands/task.ts

@@ -6,6 +6,7 @@ import { output, outputError } from '../util/format.ts'
 import {
   ALL_TASKS,
   BLOCK_TASK,
+  CLAIM_NODE,
   CREATE_TASK,
   DELETE_NODE,
   LIST_TASKS,
@@ -16,6 +17,12 @@ import {
   UPDATE_NODE,
 } from '../util/operations.ts'
 
+/** A task as returned by claimNode/readyTasks selections. */
+interface ClaimedTask {
+  id: string
+  [key: string]: unknown
+}
+
 export const taskCommand = new Command('task').description(
   'Manage tasks in the active feature',
 )
@@ -171,6 +178,80 @@ taskCommand
     }
   })
 
+taskCommand
+  .command('claim')
+  .description(
+    'Atomically claim a task for work (draft/pending_review/approved/blocked → in_progress)',
+  )
+  .argument('<id>', 'Task ID')
+  .action(async (id: string) => {
+    try {
+      // One atomic compare-and-set on the server: the task flips to in_progress
+      // only if it is still claimable, so two agents can never both claim it.
+      const data = await graphql<{ claimNode: ClaimedTask | null }>(
+        CLAIM_NODE,
+        {
+          id,
+        },
+      )
+      if (!data.claimNode) {
+        // Lost the race or never claimable. Surface a clear message + non-zero
+        // exit so a caller (or a wrapping script) can branch on the failure.
+        throw new Error(
+          `Could not claim ${id}: already claimed by another agent or not claimable (must be draft/pending_review/approved/blocked).`,
+        )
+      }
+      output(data.claimNode)
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
+taskCommand
+  .command('next')
+  .description(
+    'Atomically claim the next ready task — picks a ready task and claims it, ' +
+      'retrying past any a concurrent agent grabs first',
+  )
+  .option(
+    '--project <id>',
+    'Scope to a project (defaults to the active project; omit with --all)',
+  )
+  .option('--all', 'Consider ready tasks across the whole backlog')
+  .action(async (opts) => {
+    try {
+      const projectId =
+        opts.project ?? (opts.all ? undefined : resolveProject()?.id)
+      const ready = await graphql<{ readyTasks: ClaimedTask[] }>(READY_TASKS, {
+        projectId: projectId ?? null,
+      })
+      if (ready.readyTasks.length === 0) {
+        throw new Error(
+          'No ready tasks to claim (none are actionable, or all are blocked/done).',
+        )
+      }
+      // Walk the ready list and claim the first task we win. A null claimNode
+      // means a concurrent agent took that one between our read and our claim —
+      // skip to the next candidate so parallel agents each get a distinct task.
+      for (const candidate of ready.readyTasks) {
+        const data = await graphql<{ claimNode: ClaimedTask | null }>(
+          CLAIM_NODE,
+          { id: candidate.id },
+        )
+        if (data.claimNode) {
+          output(data.claimNode)
+          return
+        }
+      }
+      // Every ready candidate was claimed out from under us.
+      throw new Error(
+        'No claimable task left: every ready task was claimed by another agent. Try again.',
+      )
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
 taskCommand
   .command('block')
   .description('Mark a task as blocking another')

package/src/util/operations.test.ts

@@ -74,6 +74,7 @@ describe('commands send canonical operations (no re-inlined queries)', () => {
       'BLOCK_TASK',
       'UNBLOCK_TASK',
       'TASK_DEPS',
+      'CLAIM_NODE',
     ],
     'status.ts': ['UPDATE_STATUS'],
     'approve.ts': ['APPROVE_NODE'],

package/src/util/operations.ts

@@ -209,6 +209,20 @@ export const APPROVE_NODE = `mutation ApproveNode($id: String!) {
   approveNode(id: $id) { id type title status updatedAt }
 }`
 
+/**
+ * task.ts `claim`/`next` — atomically claim a task for work (F28). The server
+ * compare-and-sets a claimable node (draft/pending_review/approved/blocked) to
+ * in_progress and returns it; it returns `null` when the node is missing, not
+ * claimable, or was already claimed by a concurrent caller (lost the race), so
+ * parallel agents never double-claim the same task. Served by BOTH backends:
+ * the bundled local server (since P2-1) and SaaS (flowy-ai v35).
+ */
+export const CLAIM_NODE = `mutation ClaimNode($id: String!) {
+  claimNode(id: $id) {
+    id type title description status metadata createdAt updatedAt
+  }
+}`
+
 /** project/feature/task `delete` — remove a node (and its edges). */
 export const DELETE_NODE = `mutation DeleteNode($id: String!) {
   deleteNode(id: $id)
@@ -352,6 +366,7 @@ export const LOCAL_CONTRACT_OPERATIONS = {
   UPDATE_NODE,
   UPDATE_STATUS,
   APPROVE_NODE,
+  CLAIM_NODE,
   DELETE_NODE,
   CREATE_EDGE,
   LINK_TASK,