The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(work-items): add 'claim' command for JIT work pickup
Affaan Mustafa7fd4ba95ae57
diff --git a/scripts/work-items.js b/scripts/work-items.jsindex 4add7f047..2afff5898 100644--- a/scripts/work-items.js+++ b/scripts/work-items.js@@ -6,6 +6,7 @@ const { spawnSync } = require('child_process');const { createStateStore } = require('./lib/state-store');const VALUE_FLAGS = new Set([+ '--as','--db','--github-repo','--id',@@ -21,7 +22,7 @@ const VALUE_FLAGS = new Set(['--source-id','--status','--title',- '--url',+ '--url']);function showHelp(exitCode = 0) {@@ -31,6 +32,7 @@ Usage:node scripts/work-items.js show <id> [--db <path>] [--json]node scripts/work-items.js upsert [<id>] --title <title> [options] [--json]node scripts/work-items.js close <id> [--status done] [--db <path>] [--json]+ node scripts/work-items.js claim [<id>] --owner <name> [--as agent|human] [--db <path>] [--json]node scripts/work-items.js sync-github --repo <owner/repo> [--db <path>] [--json]Track Linear, GitHub, handoff, and manual roadmap items in the ECC SQLite state@@ -43,7 +45,8 @@ Options:--status <status> Status such as open, in-progress, blocked, done--priority <priority> Optional priority label--url <url> Optional source URL- --owner <owner> Optional owner label+ --owner <owner> Optional owner label (required for claim)+ --as <agent|human> On claim, record whether the owner is an agent or human--repo-root <path> Optional repo root to associate with this item--repo <path> GitHub repo for sync-github, otherwise alias for --repo-root--github-repo <owner/repo> Explicit GitHub repo for sync-github@@ -57,7 +60,8 @@ Options:}function assignOption(options, flag, value) {- if (flag === '--db') options.dbPath = value;+ if (flag === '--as') options.claimAs = value;+ else if (flag === '--db') options.dbPath = value;else if (flag === '--github-repo') options.githubRepo = value;else if (flag === '--id') options.id = value;else if (flag === '--limit') options.limit = value;@@ -83,7 +87,7 @@ function parseArgs(argv) {help: false,json: false,limit: 20,- positionals: [],+ positionals: []};if (args[0] && !args[0].startsWith('-')) {@@ -144,7 +148,7 @@ function runGhJson(args) {const displayCommand = shimPath ? `node ${shimPath} ${args.join(' ')}` : `gh ${args.join(' ')}`;const result = spawnSync(command, commandArgs, {encoding: 'utf8',- maxBuffer: 10 * 1024 * 1024,+ maxBuffer: 10 * 1024 * 1024});if (result.error) {@@ -163,10 +167,12 @@ function runGhJson(args) {}function slugifyWorkItemSegment(value) {- return String(value || '')- .toLowerCase()- .replace(/[^a-z0-9]+/g, '-')- .replace(/^-+|-+$/g, '') || 'unknown';+ return (+ String(value || '')+ .toLowerCase()+ .replace(/[^a-z0-9]+/g, '-')+ .replace(/^-+|-+$/g, '') || 'unknown'+ );}function githubWorkItemId(repo, type, number) {@@ -204,8 +210,8 @@ function buildGithubPrWorkItem(repo, pr, options = {}) {isDraft: Boolean(pr.isDraft),headRefName: pr.headRefName || null,sourceUpdatedAt: pr.updatedAt || null,- syncedBy: 'ecc-work-items-sync-github',- },+ syncedBy: 'ecc-work-items-sync-github'+ }};}@@ -226,8 +232,8 @@ function buildGithubIssueWorkItem(repo, issue, options = {}) {type: 'issue',labels: Array.isArray(issue.labels) ? issue.labels.map(label => label.name || label).filter(Boolean) : [],sourceUpdatedAt: issue.updatedAt || null,- syncedBy: 'ecc-work-items-sync-github',- },+ syncedBy: 'ecc-work-items-sync-github'+ }};}@@ -244,15 +250,17 @@ function closeStaleGithubItems(store, repo, activeIds, options = {}) {if (item.status === 'closed' || item.status === 'done') {continue;}- closed.push(store.upsertWorkItem({- ...item,- status: 'closed',- updatedAt: new Date().toISOString(),- metadata: {- ...item.metadata,- sourceClosedAt: new Date().toISOString(),- },- }));+ closed.push(+ store.upsertWorkItem({+ ...item,+ status: 'closed',+ updatedAt: new Date().toISOString(),+ metadata: {+ ...item.metadata,+ sourceClosedAt: new Date().toISOString()+ }+ })+ );}return closed;}@@ -264,30 +272,8 @@ function syncGithubWorkItems(store, options) {}const limit = normalizeLimit(options.limit);- const prs = runGhJson([- 'pr',- 'list',- '--repo',- repo,- '--state',- 'open',- '--limit',- String(limit),- '--json',- 'number,title,author,url,updatedAt,mergeStateStatus,isDraft,headRefName',- ]);- const issues = runGhJson([- 'issue',- 'list',- '--repo',- repo,- '--state',- 'open',- '--limit',- String(limit),- '--json',- 'number,title,author,url,updatedAt,labels',- ]);+ const prs = runGhJson(['pr', 'list', '--repo', repo, '--state', 'open', '--limit', String(limit), '--json', 'number,title,author,url,updatedAt,mergeStateStatus,isDraft,headRefName']);+ const issues = runGhJson(['issue', 'list', '--repo', repo, '--state', 'open', '--limit', String(limit), '--json', 'number,title,author,url,updatedAt,labels']);const syncedAt = new Date().toISOString();const activeIds = new Set();@@ -295,20 +281,24 @@ function syncGithubWorkItems(store, options) {for (const pr of prs) {const payload = buildGithubPrWorkItem(repo, pr, options);activeIds.add(payload.id);- items.push(store.upsertWorkItem({- ...payload,- createdAt: undefined,- updatedAt: syncedAt,- }));+ items.push(+ store.upsertWorkItem({+ ...payload,+ createdAt: undefined,+ updatedAt: syncedAt+ })+ );}for (const issue of issues) {const payload = buildGithubIssueWorkItem(repo, issue, options);activeIds.add(payload.id);- items.push(store.upsertWorkItem({- ...payload,- createdAt: undefined,- updatedAt: syncedAt,- }));+ items.push(+ store.upsertWorkItem({+ ...payload,+ createdAt: undefined,+ updatedAt: syncedAt+ })+ );}const closedItems = closeStaleGithubItems(store, repo, activeIds, { limit: Math.max(limit * 4, 1000) });@@ -319,7 +309,7 @@ function syncGithubWorkItems(store, options) {issueCount: issues.length,closedCount: closedItems.length,items,- closedItems,+ closedItems};}@@ -345,11 +335,9 @@ function buildUpsertPayload(options, existing = null) {owner: options.owner ?? (existing && existing.owner) ?? null,repoRoot: options.repoRoot ?? (existing && existing.repoRoot) ?? process.cwd(),sessionId: options.sessionId ?? (existing && existing.sessionId) ?? null,- metadata: options.metadataJson !== undefined- ? parseMetadataJson(options.metadataJson)- : ((existing && existing.metadata) ?? null),+ metadata: options.metadataJson !== undefined ? parseMetadataJson(options.metadataJson) : ((existing && existing.metadata) ?? null),createdAt: existing ? existing.createdAt : undefined,- updatedAt: new Date().toISOString(),+ updatedAt: new Date().toISOString()};}@@ -400,6 +388,75 @@ function printGithubSyncResult(payload) {}}+const CLAIM_DONE_STATUSES = new Set(['done', 'closed', 'resolved', 'merged', 'cancelled']);+const CLAIM_PRIORITY_RANK = { critical: 0, high: 1, urgent: 1, medium: 2, normal: 2, low: 3 };++function isOpenWorkItemStatus(status) {+ return !CLAIM_DONE_STATUSES.has(+ String(status || '')+ .trim()+ .toLowerCase()+ );+}++// Resolve which work item a `claim` targets: an explicit id, otherwise the+// highest-priority unassigned open item (the JIT pickup queue the control-pane+// board surfaces).+function selectClaimTarget(store, options) {+ const explicitId = resolveWorkItemId(options);+ if (explicitId) {+ const item = store.getWorkItemById(explicitId);+ if (!item) {+ throw new Error(`Work item not found: ${explicitId}`);+ }+ return item;+ }+ const { items } = store.listWorkItems({ limit: 100 });+ return (+ items+ .filter(item => !item.owner && isOpenWorkItemStatus(item.status))+ .sort((a, b) => {+ const ra = CLAIM_PRIORITY_RANK[String(a.priority || '').toLowerCase()] ?? 2;+ const rb = CLAIM_PRIORITY_RANK[String(b.priority || '').toLowerCase()] ?? 2;+ return ra - rb;+ })[0] || null+ );+}++// Claim an unassigned work item for an agent or human — the just-in-time pickup+// primitive. Sets the owner (+ optional assigneeKind) and moves the card to+// running so the board reflects that work has started.+function claimWorkItem(store, options) {+ const owner = options.owner;+ if (!owner) {+ throw new Error('claim requires --owner <name>.');+ }+ const assigneeKind = options.claimAs ? String(options.claimAs).toLowerCase() : null;+ if (assigneeKind && assigneeKind !== 'agent' && assigneeKind !== 'human') {+ throw new Error("--as must be 'agent' or 'human'.");+ }+ const target = selectClaimTarget(store, options);+ if (!target) {+ return { claimed: false, reason: 'no-unassigned-open-items' };+ }+ if (!isOpenWorkItemStatus(target.status)) {+ throw new Error(`Work item ${target.id} is already done; cannot claim.`);+ }+ const metadata = { ...(target.metadata || {}) };+ if (assigneeKind) {+ metadata.assigneeKind = assigneeKind;+ }+ const item = store.upsertWorkItem({+ ...target,+ owner,+ sessionId: options.sessionId ?? target.sessionId ?? null,+ status: options.status ?? 'running',+ metadata,+ updatedAt: new Date().toISOString()+ });+ return { claimed: true, item };+}+async function main() {let store = null;@@ -411,7 +468,7 @@ async function main() {store = await createStateStore({dbPath: options.dbPath,- homeDir: process.env.HOME || os.homedir(),+ homeDir: process.env.HOME || os.homedir()});if (options.command === 'list') {@@ -462,11 +519,16 @@ async function main() {if (!existing) {throw new Error(`Work item not found: ${id}`);}- const item = store.upsertWorkItem(buildUpsertPayload({- ...options,- id,- status: options.status || 'done',- }, existing));+ const item = store.upsertWorkItem(+ buildUpsertPayload(+ {+ ...options,+ id,+ status: options.status || 'done'+ },+ existing+ )+ );if (options.json) {console.log(JSON.stringify(item, null, 2));} else {@@ -475,6 +537,19 @@ async function main() {return;}+ if (options.command === 'claim') {+ const result = claimWorkItem(store, options);+ if (options.json) {+ console.log(JSON.stringify(result, null, 2));+ } else if (!result.claimed) {+ console.log('No unassigned open work items to claim.');+ } else {+ console.log(`Claimed by ${result.item.owner}:`);+ printWorkItem(result.item);+ }+ return;+ }+if (options.command === 'sync-github') {const payload = syncGithubWorkItems(store, options);if (options.json) {@@ -506,5 +581,5 @@ module.exports = {buildGithubPrWorkItem,main,parseArgs,- syncGithubWorkItems,+ syncGithubWorkItems};diff --git a/tests/scripts/work-items.test.js b/tests/scripts/work-items.test.jsnew file mode 100644index 000000000..b5c32d4a1--- /dev/null+++ b/tests/scripts/work-items.test.js@@ -0,0 +1,152 @@+'use strict';+/**+ * Tests for scripts/work-items.js — focused on the `claim` JIT pickup command.+ */++const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');+const { spawnSync } = require('child_process');++const { createStateStore } = require('../../scripts/lib/state-store');++const CLI = path.join(__dirname, '..', '..', 'scripts', 'work-items.js');++let passed = 0;+let failed = 0;++async function test(name, fn) {+ try {+ await fn();+ console.log(` PASS ${name}`);+ passed += 1;+ } catch (error) {+ console.log(` FAIL ${name}`);+ console.log(` Error: ${error.message}`);+ failed += 1;+ }+}++function runClaim(dbPath, args) {+ const result = spawnSync('node', [CLI, 'claim', '--db', dbPath, '--json', ...args], {+ encoding: 'utf8'+ });+ return result;+}++async function seed(dbPath) {+ const store = await createStateStore({ dbPath });+ try {+ // High-priority, unassigned, open — the JIT pickup target.+ store.upsertWorkItem({+ id: 'wi-unassigned-high',+ source: 'github-issue',+ title: 'Fix the gate bypass',+ status: 'open',+ priority: 'high',+ owner: null,+ metadata: {}+ });+ // Low-priority, unassigned, open — should be picked only after the high one.+ store.upsertWorkItem({+ id: 'wi-unassigned-low',+ source: 'manual',+ title: 'Tidy docs',+ status: 'open',+ priority: 'low',+ owner: null,+ metadata: {}+ });+ // Already owned — must never be auto-claimed.+ store.upsertWorkItem({+ id: 'wi-owned',+ source: 'manual',+ title: 'In progress',+ status: 'running',+ priority: 'high',+ owner: 'codex',+ metadata: {}+ });+ // Done — must never be claimed.+ store.upsertWorkItem({+ id: 'wi-done',+ source: 'manual',+ title: 'Shipped',+ status: 'done',+ priority: 'high',+ owner: null,+ metadata: {}+ });+ } finally {+ store.close();+ }+}++async function run() {+ console.log('\n=== Testing work-items.js claim ===\n');++ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'work-items-claim-'));+ const dbPath = path.join(dir, 'state.db');++ try {+ await seed(dbPath);++ await test('claim picks the highest-priority unassigned open item and sets owner + kind', async () => {+ const result = runClaim(dbPath, ['--owner', 'alice', '--as', 'human']);+ assert.strictEqual(result.status, 0, result.stderr);+ const payload = JSON.parse(result.stdout);+ assert.strictEqual(payload.claimed, true);+ assert.strictEqual(payload.item.id, 'wi-unassigned-high', 'high-priority item claimed first');+ assert.strictEqual(payload.item.owner, 'alice');+ assert.strictEqual(payload.item.status, 'running', 'claim moves the card to running');+ assert.strictEqual(payload.item.metadata.assigneeKind, 'human');+ });++ await test('a second claim takes the next unassigned item, not an owned or done one', async () => {+ const result = runClaim(dbPath, ['--owner', 'bot-7', '--as', 'agent']);+ assert.strictEqual(result.status, 0, result.stderr);+ const payload = JSON.parse(result.stdout);+ assert.strictEqual(payload.claimed, true);+ assert.strictEqual(payload.item.id, 'wi-unassigned-low');+ assert.strictEqual(payload.item.metadata.assigneeKind, 'agent');+ });++ await test('claim reports nothing to do once the queue is drained', async () => {+ const result = runClaim(dbPath, ['--owner', 'alice']);+ assert.strictEqual(result.status, 0, result.stderr);+ const payload = JSON.parse(result.stdout);+ assert.strictEqual(payload.claimed, false);+ assert.strictEqual(payload.reason, 'no-unassigned-open-items');+ });++ await test('claim of a specific id works and rejects a missing id', async () => {+ const owned = runClaim(dbPath, ['wi-owned', '--owner', 'carol']);+ assert.strictEqual(owned.status, 0, owned.stderr);+ assert.strictEqual(JSON.parse(owned.stdout).item.owner, 'carol', 'explicit id can be re-claimed');++ const missing = runClaim(dbPath, ['nope-404', '--owner', 'carol']);+ assert.notStrictEqual(missing.status, 0, 'missing id should fail');+ assert.ok(/not found/i.test(missing.stderr), 'reports not found');+ });++ await test('claim requires --owner and validates --as', async () => {+ const noOwner = runClaim(dbPath, ['wi-done']);+ assert.notStrictEqual(noOwner.status, 0);+ assert.ok(/requires --owner/i.test(noOwner.stderr));++ const badKind = runClaim(dbPath, ['wi-owned', '--owner', 'x', '--as', 'robot']);+ assert.notStrictEqual(badKind.status, 0);+ assert.ok(/agent.*human/i.test(badKind.stderr));+ });+ } finally {+ fs.rmSync(dir, { recursive: true, force: true });+ }++ console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+ if (failed > 0) {+ process.exit(1);+ }+}++run();