feat(task-board): add external_ref for idempotent task creation

Tasks can now carry an optional externalRef field (e.g.
"pr_shepherd:dimakis/centaur#42"). The server checks for an existing
task with the same ref before creating, returning 200 + deduplicated
flag instead of a duplicate 201. A partial unique index on external_ref
(WHERE NOT NULL) provides the DB-level safety net for concurrent
requests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: dimakis

server/__tests__/task-routes.test.ts

@@ -158,6 +158,41 @@ describe('task routes', () => {
     expect(res.body.task.annotations).toEqual(['a']);
   });
 
+  // --- POST /api/tasks idempotency ---
+
+  it('POST /api/tasks — deduplicates by externalRef', async () => {
+    const ref = `dedup-test-${Date.now()}`;
+    const first = await request(app)
+      .post('/api/tasks')
+      .send({ title: 'First create', externalRef: ref })
+      .set('Cookie', authCookie);
+    expect(first.status).toBe(201);
+    expect(first.body.task.externalRef).toBe(ref);
+
+    const second = await request(app)
+      .post('/api/tasks')
+      .send({ title: 'Duplicate create', externalRef: ref })
+      .set('Cookie', authCookie);
+    expect(second.status).toBe(200);
+    expect(second.body.deduplicated).toBe(true);
+    expect(second.body.task.id).toBe(first.body.task.id);
+    expect(second.body.task.title).toBe('First create');
+  });
+
+  it('POST /api/tasks — no dedup without externalRef', async () => {
+    const first = await request(app)
+      .post('/api/tasks')
+      .send({ title: 'No ref A' })
+      .set('Cookie', authCookie);
+    const second = await request(app)
+      .post('/api/tasks')
+      .send({ title: 'No ref B' })
+      .set('Cookie', authCookie);
+    expect(first.status).toBe(201);
+    expect(second.status).toBe(201);
+    expect(first.body.task.id).not.toBe(second.body.task.id);
+  });
+
   // --- GET /api/tasks/:id ---
 
   it('GET /api/tasks/:id — returns a task', async () => {

server/__tests__/task-store.test.ts

@@ -509,6 +509,41 @@ describe('TaskStore', () => {
     store2.close();
   });
 
+  // --- externalRef ---
+
+  it('creates a task with externalRef', () => {
+    const task = store.create({ title: 'Ref task', externalRef: 'pr_shepherd:org/repo#42' });
+    expect(task.externalRef).toBe('pr_shepherd:org/repo#42');
+  });
+
+  it('defaults externalRef to null', () => {
+    const task = store.create({ title: 'No ref' });
+    expect(task.externalRef).toBeNull();
+  });
+
+  it('getByExternalRef finds a task', () => {
+    store.create({ title: 'Findable', externalRef: 'test:find-me' });
+    const found = store.getByExternalRef('test:find-me');
+    expect(found).not.toBeNull();
+    expect(found!.title).toBe('Findable');
+  });
+
+  it('getByExternalRef returns null for unknown ref', () => {
+    expect(store.getByExternalRef('nonexistent')).toBeNull();
+  });
+
+  it('rejects duplicate externalRef', () => {
+    store.create({ title: 'First', externalRef: 'unique:ref' });
+    expect(() => store.create({ title: 'Second', externalRef: 'unique:ref' })).toThrow();
+  });
+
+  it('allows multiple tasks with null externalRef', () => {
+    store.create({ title: 'A' });
+    store.create({ title: 'B' });
+    const roots = store.listRoots();
+    expect(roots.length).toBeGreaterThanOrEqual(2);
+  });
+
   it('migrates existing database to add workflow columns', () => {
     // Create a DB without workflow columns, then reopen to trigger migration
     const dbPath = join(TEST_DIR, 'migrate.db');

server/api-schemas.ts

@@ -123,6 +123,7 @@ export const TaskCreateBody = z.object({
   gateConfig: z.record(z.string(), z.unknown()).optional(),
   maxRetries: z.number().min(0).optional(),
   templateId: z.string().optional(),
+  externalRef: z.string().optional(),
 });
 
 export const TaskUpdateBody = z.object({

server/app.ts

@@ -635,6 +635,14 @@ app.post('/api/tasks', (req, res) => {
     return;
   }
   try {
+    // Idempotency guard: if externalRef provided and already exists, return existing task
+    if (body.data.externalRef) {
+      const existing = taskStore.getByExternalRef(body.data.externalRef);
+      if (existing) {
+        res.status(200).json({ task: existing, deduplicated: true });
+        return;
+      }
+    }
     const task = taskStore.create(body.data as TaskCreateInput);
     res.status(201).json({ task });
     // Broadcast full tree so child tasks appear correctly in all clients

server/task-store.ts

@@ -49,6 +49,7 @@ export interface Task {
   retryCount: number;
   maxRetries: number;
   templateId: string | null;
+  externalRef: string | null;
   children: Task[];
 }
 
@@ -63,6 +64,7 @@ export interface TaskCreateInput {
   gateConfig?: GateConfig;
   maxRetries?: number;
   templateId?: string;
+  externalRef?: string;
 }
 
 export interface TaskUpdateInput {
@@ -106,6 +108,7 @@ interface TaskRow {
   retry_count: number;
   max_retries: number;
   template_id: string | null;
+  external_ref: string | null;
 }
 
 const SCHEMA = `
@@ -137,11 +140,13 @@ const SCHEMA = `
     artifacts       TEXT DEFAULT NULL,
     retry_count     INTEGER NOT NULL DEFAULT 0,
     max_retries     INTEGER NOT NULL DEFAULT 0,
-    template_id     TEXT DEFAULT NULL
+    template_id     TEXT DEFAULT NULL,
+    external_ref    TEXT DEFAULT NULL
   );
   CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_id);
   CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
   CREATE INDEX IF NOT EXISTS idx_tasks_session ON tasks(session_id);
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_external_ref ON tasks(external_ref) WHERE external_ref IS NOT NULL;
 `;
 
 const MIGRATIONS = [
@@ -158,6 +163,14 @@ const MIGRATIONS = [
       ALTER TABLE tasks ADD COLUMN template_id TEXT DEFAULT NULL;
     `,
   },
+  // Migration 2: Add external_ref for idempotent task creation
+  {
+    check: "SELECT COUNT(*) as cnt FROM pragma_table_info('tasks') WHERE name = 'external_ref'",
+    sql: `
+      ALTER TABLE tasks ADD COLUMN external_ref TEXT DEFAULT NULL;
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_external_ref ON tasks(external_ref) WHERE external_ref IS NOT NULL;
+    `,
+  },
 ];
 
 function rowToTask(row: TaskRow): Task {
@@ -194,6 +207,7 @@ function rowToTask(row: TaskRow): Task {
     retryCount: row.retry_count ?? 0,
     maxRetries: row.max_retries ?? 0,
     templateId: row.template_id ?? null,
+    externalRef: row.external_ref ?? null,
     children: [],
   };
 }
@@ -259,8 +273,8 @@ export class TaskStore {
     const gateConfig = input.gateConfig ? JSON.stringify(input.gateConfig) : null;
 
     db.prepare(
-      `INSERT INTO tasks (id, parent_id, title, description, status, session_policy, priority, depth, annotations, stage_type, gate_config, max_retries, template_id, created_at, updated_at)
-       VALUES (?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT INTO tasks (id, parent_id, title, description, status, session_policy, priority, depth, annotations, stage_type, gate_config, max_retries, template_id, external_ref, created_at, updated_at)
+       VALUES (?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     ).run(
       id,
       input.parentId ?? null,
@@ -274,6 +288,7 @@ export class TaskStore {
       gateConfig,
       input.maxRetries ?? 0,
       input.templateId ?? null,
+      input.externalRef ?? null,
       now,
       now,
     );
@@ -288,6 +303,14 @@ export class TaskStore {
     return row ? rowToTask(row) : null;
   }
 
+  /** Look up a task by its external reference (e.g. "pr_shepherd:dimakis/centaur#42"). */
+  getByExternalRef(ref: string): Task | null {
+    const row = this.getDb()
+      .prepare('SELECT * FROM tasks WHERE external_ref = ?')
+      .get(ref) as TaskRow | undefined;
+    return row ? rowToTask(row) : null;
+  }
+
   update(id: string, fields: TaskUpdateInput): Task | null {
     const existing = this.get(id);
     if (!existing) return null;