agents-relay 1.0.0

package/test/github-webhook.test.js

@@ -0,0 +1,21 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHmac } from 'node:crypto';
+import { DeliveryDeduper, parseGitHubWebhook, verifyGitHubWebhook } from '../dist/github-webhook.js';
+
+test('GitHub webhook verifies HMAC, filters events, and extracts PR identity', () => {
+  const body = Buffer.from(JSON.stringify({ action: 'synchronize', repository: { full_name: 'lalalic/agents-relay' }, pull_request: { number: 11 } }));
+  const secret = 'test-secret';
+  const signature = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
+  assert.equal(verifyGitHubWebhook(secret, body, signature), true);
+  assert.equal(verifyGitHubWebhook(secret, body, 'sha256=bad'), false);
+  assert.deepEqual(parseGitHubWebhook({ 'x-github-delivery': 'delivery-1', 'x-github-event': 'pull_request' }, body), { deliveryId: 'delivery-1', event: 'pull_request', action: 'synchronize', repository: 'lalalic/agents-relay', pullRequest: 11 });
+  assert.equal(parseGitHubWebhook({ 'x-github-delivery': 'delivery-2', 'x-github-event': 'ping' }, body), null);
+});
+
+test('GitHub webhook delivery IDs are idempotent', () => {
+  const dedupe = new DeliveryDeduper(1000);
+  assert.equal(dedupe.accept('same', 100), true);
+  assert.equal(dedupe.accept('same', 200), false);
+  assert.equal(dedupe.accept('same', 1200), true);
+});

package/test/service.test.js

@@ -0,0 +1,116 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { normalizeDaemonArguments } from '../dist/relayd.js';
+import { createService, startService, SERVICE_DEFAULTS } from '../dist/cli.js';
+import { nextPatchVersion } from '../scripts/npm-version.mjs';
+
+test('daemon arguments require and normalize durable identifiers', () => {
+  const argv = ['--repo', 'OWNER/REPO', '--pr', '1', '--id', 'JOB_ID', '--port', '9000'];
+  const normalized = normalizeDaemonArguments(argv);
+  assert.equal(normalized.repository, 'OWNER/REPO');
+  assert.equal(normalized.pullRequest, 1);
+  assert.equal(normalized.jobId, 'JOB_ID');
+  assert.deepEqual(normalized.serviceArguments, argv);
+});
+
+test('repository daemon wires account usage telemetry into dashboard', async () => {
+  const source = await readFile(new URL('../src/relayd.ts', import.meta.url), 'utf8');
+  assert.match(source, /const usageRegistry = codexAndZaiUsageRegistry\(\)/);
+  assert.match(source, /fallback\?\.id,usageRegistry,overviews,webhook,\(\)=>client\.rateLimitStatus\(\),exactJob/);
+});
+
+test('daemon arguments support repository pool mode and validate legacy pairing', () => {
+  const pooled = normalizeDaemonArguments(['--repo','OWNER/REPO','--port','8787']);
+  assert.equal(pooled.pullRequest, null); assert.equal(pooled.jobId, null);
+  assert.throws(() => normalizeDaemonArguments(['--pr','1','--id','job']), /--repo is required/);
+  assert.throws(() => normalizeDaemonArguments(['--repo','OWNER/REPO','--pr','0','--id','job']), /--pr must be positive/);
+  assert.throws(() => normalizeDaemonArguments(['--repo','OWNER/REPO','--pr','1']), /supplied together/);
+});
+
+test('daemon arguments default to workspace mode without changing --repo mode', () => {
+  const workspace = normalizeDaemonArguments(['--workspace', '/tmp/Workspace']);
+  assert.equal(workspace.repository, null);
+  assert.equal(workspace.workspaceRoot, '/tmp/Workspace');
+  assert.equal(workspace.pullRequest, null);
+  assert.throws(() => normalizeDaemonArguments(['--repo', 'OWNER/REPO', '--workspace', '/tmp/Workspace']), /mutually exclusive/);
+});
+
+test('service defaults and package bins use stable package entrypoints', async () => {
+  const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  assert.deepEqual(pkg.bin, { 'agents-relay': 'dist/cli.js', 'agents-relayd': 'dist/relayd.js' });
+  assert.equal(SERVICE_DEFAULTS.port, 8787);
+  assert.equal(SERVICE_DEFAULTS.watchdogMs, 300000);
+  assert.equal(SERVICE_DEFAULTS.webhookWatchdogMs, 1800000);
+  assert.equal(SERVICE_DEFAULTS.dashboardRefreshMs, 300000);
+});
+
+test('release version selection starts at 1.0.0 and increments only the patch', () => {
+  assert.equal(nextPatchVersion(''), '1.0.0');
+  assert.equal(nextPatchVersion('1.0.0'), '1.0.1');
+  assert.equal(nextPatchVersion('2.7.9'), '2.7.10');
+  assert.throws(() => nextPatchVersion('latest'), /Unsupported npm version/);
+});
+
+test('CLI and daemon help are successful and do not require job storage', () => {
+  for (const [entry, args, expected] of [
+    ['dist/cli.js', ['--help'], 'npx agents-relay <command>'],
+    ['dist/cli.js', ['job', '--help'], 'npx agents-relay job <create|adopt|repair>'],
+    ['dist/cli.js', ['job', 'create', '--help'], 'Create or reuse an open PR'],
+    ['dist/cli.js', ['job', 'adopt', '--help'], 'Adopt an existing PR'],
+    ['dist/cli.js', ['job', 'repair', '--help'], 'Repair duplicate durable markers'],
+    ['dist/cli.js', ['init', '--help'], 'Initialize a new job'],
+    ['dist/cli.js', ['submit', '--help'], 'Queue a task for a managed job'],
+    ['dist/cli.js', ['record', '--help'], 'Backfill work completed outside the relay'],
+    ['dist/cli.js', ['status', '--help'], 'Show the durable state for a job'],
+    ['dist/cli.js', ['reconcile', '--help'], 'Reconcile a job once'],
+    ['dist/cli.js', ['retry', '--help'], 'Retry a task by setting it READY'],
+    ['dist/cli.js', ['cancel', '--help'], 'Cancel a task'],
+    ['dist/cli.js', ['serve', '--help'], 'Run the dashboard and reconciliation service'],
+    ['dist/cli.js', ['agent-register', '--help'], 'Register an agent role'],
+    ['dist/cli.js', ['agent-discover', '--help'], 'Find registered agents'],
+    ['dist/relayd.js', ['--help'], 'npx agents-relayd [options]']
+  ]) {
+    const result = spawnSync(process.execPath, [entry, ...args], { encoding: 'utf8' });
+    assert.equal(result.status, 0, `${entry} ${args.join(' ')} failed: ${result.stderr}`);
+    assert.match(result.stdout, new RegExp(expected.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+  }
+});
+
+test('published bin files are executable after build and npm pack', async () => {
+  assert.equal((await stat('dist/cli.js')).mode & 0o111, 0o111);
+  assert.equal((await stat('dist/relayd.js')).mode & 0o111, 0o111);
+  const packed = spawnSync('npm', ['pack', '--dry-run', '--json'], { encoding: 'utf8' });
+  assert.equal(packed.status, 0, packed.stderr);
+  const files = new Map(JSON.parse(packed.stdout)[0].files.map(file => [file.path, file.mode]));
+  assert.equal(files.get('dist/cli.js'), 0o755);
+  assert.equal(files.get('dist/relayd.js'), 0o755);
+});
+
+test('service stop clears watchdog and closes dashboard before resolving', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'agents-relay-service-'));
+  const file = join(directory, 'job.json');
+  await writeFile(file, JSON.stringify({ id: 'cleanup-job', tasks: [] }));
+  const service = await createService(['--file', file, '--port', '0', '--interval', '60000', '--refresh-ms', '15000']);
+  await service.stop();
+  assert.equal(service.dashboardServer.address(), null);
+  assert.equal(service.watchdogCleared, true);
+  await rm(directory, { recursive: true, force: true });
+});
+
+
+test('startup reconciliation failure does not take down dashboard', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'agents-relay-degraded-'));
+  const file = join(directory, 'job.json');
+  await writeFile(file, JSON.stringify({ id: 'degraded-job', title: 'Degraded', prNumber: 0, state: 'OPEN', createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), tasks: [] }));
+  const service = await createService(['--file', file, '--port', '0']);
+  service.reconciler.reconcile = async () => { throw new Error('GitHub rate limited'); };
+  // startService owns construction, so assert the equivalent startup policy directly:
+  try { await service.reconciler.reconcile(service.job.id); } catch {}
+  assert.notEqual(service.dashboardServer.address(), null);
+  await service.stop();
+  await rm(directory, { recursive: true, force: true });
+});

package/test/store.test.js

@@ -0,0 +1,390 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { dashboardManagedJobs, GitHubStore, InMemoryStore } from '../dist/store.js';
+import { AGENT_MARKER, JOB_MARKER, marker, parseAgent, parseJob, parseTask, TASK_MARKER } from '../dist/markers.js';
+
+test('marker parser tolerates Mermaid arrows inside JSON string values', () => {
+  const description = 'mermaid\\nflowchart TD\\nA --> B';
+  const body = marker(JOB_MARKER, { id: 'mermaid-job', title: 'Mermaid', description, tasks: undefined });
+  const parsed = parseJob(body);
+  assert.equal(parsed?.id, 'mermaid-job');
+  assert.equal(parsed?.description, description);
+});
+
+const now = () => new Date().toISOString();
+const task = (jobId, id, state = 'QUEUED') => ({
+  jobId,
+  id,
+  parentTaskId: null,
+  dependencies: [],
+  capabilities: [],
+  adapter: 'shell',
+  input: 'true',
+  state,
+  attempt: 0,
+  maxAttempts: 2,
+  leaseOwner: null,
+  leaseExpiresAt: null,
+  executionId: null,
+  threadId: null,
+  result: null,
+  error: null,
+  timeoutMs: 1000,
+  createdAt: now(),
+  updatedAt: now(),
+  continuation: null,
+  continuationDeliveredAt: null
+});
+const job = id => ({
+  id,
+  title: id,
+  prNumber: 1,
+  repository: 'owner/repo',
+  state: 'OPEN',
+  continuation: null,
+  createdAt: now(),
+  updatedAt: now(),
+  tasks: undefined
+});
+const githubComment = (body, login = 'bot', id = Math.floor(Math.random() * 1_000_000) + 100) => ({
+  id,
+  body,
+  updated_at: now(),
+  user: { login }
+});
+const trustedClient = comments => ({
+  request: async () => { throw new Error('REST should not be used by GitHubStore'); },
+  graphql: async (query, variables = {}) => {
+    if (query.includes('pullRequest(number:$number){id state merged mergedAt closedAt}')) return { repository:{ pullRequest:{ id:'PR_1', state:'OPEN', merged:false, mergedAt:null, closedAt:null } } };
+    if (query.includes('comments(first:100')) return { repository:{ pullRequest:{ comments:{ nodes:comments.map(item=>({id:'IC_'+item.id,databaseId:item.id,body:item.body,updatedAt:item.updated_at,author:{login:item.user.login}})), pageInfo:{hasNextPage:false,endCursor:null} } } } };
+    if (query.includes('addComment')) { const item=githubComment(variables.body); comments.push(item); return { addComment:{ commentEdge:{ node:{ id:'IC_'+item.id } } } }; }
+    if (query.includes('updateIssueComment')) { const id=Number(String(variables.id).replace('IC_','')); const item=comments.find(row=>row.id===id); item.body=variables.body; return { updateIssueComment:{ issueComment:{id:variables.id} } }; }
+    if (query.includes('deleteIssueComment')) { const id=Number(String(variables.id).replace('IC_','')); const index=comments.findIndex(row=>row.id===id); if(index>=0) comments.splice(index,1); return { deleteIssueComment:{clientMutationId:null} }; }
+    throw new Error('Unhandled fake GraphQL query: '+query);
+  }
+});
+const githubWithComments = comments => new GitHubStore(trustedClient(comments), 'owner/repo', 1, new Set(['bot']));
+const memoryWithComments = comments => {
+  const store = new InMemoryStore();
+  for (const item of comments) {
+    const parsedJob = parseJob(item.body);
+    if (parsedJob) void store.saveJob(parsedJob);
+    const parsedTask = parseTask(item.body);
+    if (parsedTask) void store.appendTask(parsedTask);
+  }
+  return store;
+};
+
+test('same task id remains scoped to its job', async () => {
+  const shared = 'shared-task';
+  const first = task('job-a', shared, 'SUCCEEDED');
+  first.result = { summary: 'first job' };
+  const second = task('job-b', shared);
+  const comments = [
+    githubComment(marker(JOB_MARKER, job('job-a'))),
+    githubComment(marker(JOB_MARKER, job('job-b'))),
+    githubComment(marker(TASK_MARKER, first)),
+    githubComment(marker(TASK_MARKER, second))
+  ];
+  const github = githubWithComments(comments);
+  const memory = memoryWithComments(comments);
+
+  assert.deepEqual((await github.load('job-a')).tasks.map(item => item.id), [shared]);
+  assert.deepEqual((await memory.load('job-a')).tasks.map(item => item.id), [shared]);
+  assert.deepEqual((await github.load('job-b')).tasks.map(item => item.id), [shared]);
+  assert.deepEqual((await memory.load('job-b')).tasks.map(item => item.id), [shared]);
+
+  const loaded = await github.load('job-a');
+  loaded.tasks[0].state = 'CANCELLED';
+  await github.saveTask(loaded.tasks[0]);
+  assert.equal((await github.load('job-a')).tasks[0].state, 'CANCELLED');
+  assert.equal((await github.load('job-b')).tasks[0].state, 'QUEUED');
+
+  const loadedMemory = await memory.load('job-a');
+  loadedMemory.tasks[0].state = 'CANCELLED';
+  await memory.saveTask(loadedMemory.tasks[0]);
+  assert.equal((await memory.load('job-a')).tasks[0].state, 'CANCELLED');
+  assert.equal((await memory.load('job-b')).tasks[0].state, 'QUEUED');
+
+  const updated = comments.find(item => item.body.includes('"jobId":"job-a"') && item.body.includes(shared));
+  assert.match(updated.body, /CANCELLED/);
+  assert.doesNotMatch(updated.body, /"jobId":"job-b"/);
+});
+
+test('legacy tasks join only one trusted job and are never guessed with multiple', async () => {
+  const legacyMarker = marker(TASK_MARKER, { ...task('', 'legacy', 'SUCCEEDED'), jobId: undefined });
+  const soleJob = [githubComment(marker(JOB_MARKER, job('solo'))), githubComment(legacyMarker)];
+  const multipleJobs = [githubComment(marker(JOB_MARKER, job('one'))), githubComment(marker(JOB_MARKER, job('two'))), githubComment(legacyMarker)];
+  const soleGithub = githubWithComments(soleJob);
+  const soleMemory = memoryWithComments(soleJob);
+  const multipleGithub = githubWithComments(multipleJobs);
+  const multipleMemory = memoryWithComments(multipleJobs);
+
+  assert.deepEqual((await soleGithub.load('solo')).tasks.map(item => item.id), ['legacy']);
+  assert.deepEqual((await soleMemory.load('solo')).tasks.map(item => item.id), ['legacy']);
+  assert.deepEqual((await multipleGithub.load('one')).tasks, []);
+  assert.deepEqual((await multipleMemory.load('one')).tasks, []);
+});
+
+test('untrusted task markers are ignored and updates survive a fresh store', async () => {
+  const durable = task('job-a', 'durable', 'SUCCEEDED');
+  durable.result = { summary: 'durable' };
+  const comments = [
+    githubComment(marker(JOB_MARKER, job('job-a'))),
+    githubComment(marker(TASK_MARKER, durable)),
+    githubComment(marker(TASK_MARKER, task('job-a', 'forged')), 'attacker', 999)
+  ];
+  const github = githubWithComments(comments);
+  const memory = memoryWithComments(comments.filter(item => item.user.login === 'bot'));
+  const loaded = await github.load('job-a');
+
+  assert.deepEqual(loaded.tasks.map(item => item.id), ['durable']);
+  assert.deepEqual((await memory.load('job-a')).tasks.map(item => item.id), ['durable']);
+  loaded.tasks[0].result.summary = 'updated';
+  await github.saveTask(loaded.tasks[0]);
+
+  const fresh = githubWithComments(comments);
+  const reloaded = await fresh.load('job-a');
+  assert.equal(reloaded.tasks[0].result.summary, 'updated');
+  assert.equal(reloaded.tasks.some(item => item.id === 'forged'), false);
+});
+
+class ManagedGitHubClient {
+  constructor(pulls = []) {
+    this.pulls = pulls;
+    this.comments = new Map();
+    this.nextPr = Math.max(0, ...pulls.map(item => item.number)) + 1;
+    this.nextComment = 1;
+  }
+  pulls;
+  comments;
+  nextPr;
+  nextComment;
+  async graphql(query, variables = {}) {
+    const pr = this.pulls.find(item => item.number === Number(variables.number)) ?? this.pulls[0];
+    if (query.includes('pullRequest(number:$number){id state merged mergedAt closedAt}')) return { repository:{ pullRequest: pr ? { id:'PR_'+pr.number, state:String(pr.state||'open').toUpperCase(), merged:false, mergedAt:null, closedAt:null } : null } };
+    if (query.includes('pullRequest(number:$number){number title body state headRefName baseRefName}')) return { repository:{ pullRequest: pr ? {number:pr.number,title:pr.title,body:pr.body,state:String(pr.state||'open').toUpperCase(),headRefName:pr.head.ref,baseRefName:pr.base.ref} : null } };
+    if (query.includes('pullRequests(first:20')) {
+      const nodes=this.pulls.filter(item=>item.state==='open'&&(!variables.head||item.head.ref===variables.head)&&(!variables.base||item.base.ref===variables.base)).map(item=>({number:item.number,title:item.title,body:item.body,state:'OPEN',headRefName:item.head.ref,baseRefName:item.base.ref}));
+      return {repository:{pullRequests:{nodes}}};
+    }
+    if (query.includes('query($owner:String!,$name:String!){repository(owner:$owner,name:$name){id}}')) return {repository:{id:'REPO_owner_repo'}};
+    if (query.includes('createPullRequest')) {
+      const pull={number:this.nextPr++,title:variables.title,body:variables.body,state:'open',head:{ref:variables.head},base:{ref:variables.base}};
+      this.pulls.push(pull);
+      return {createPullRequest:{pullRequest:{number:pull.number,title:pull.title,body:pull.body,state:'OPEN',headRefName:pull.head.ref,baseRefName:pull.base.ref}}};
+    }
+    if (query.includes('comments(first:100')) { const values=this.comments.get(Number(variables.number)) ?? []; return { repository:{ pullRequest:{ comments:{ nodes:values.map(item=>({id:'IC_'+item.id,databaseId:item.id,body:item.body,updatedAt:item.updated_at,author:{login:item.user.login}})), pageInfo:{hasNextPage:false,endCursor:null} } } } }; }
+    if (query.includes('addComment')) { const prNumber=Number(String(variables.subjectId).replace('PR_','')); const values=this.comments.get(prNumber) ?? []; const item=githubComment(variables.body,'bot',this.nextComment++); values.push(item); this.comments.set(prNumber,values); return { addComment:{commentEdge:{node:{id:'IC_'+item.id}}} }; }
+    if (query.includes('updateIssueComment')) { const id=Number(String(variables.id).replace('IC_','')); for(const values of this.comments.values()){const item=values.find(row=>row.id===id); if(item){item.body=variables.body; return {updateIssueComment:{issueComment:{id:variables.id}}};}} }
+    if (query.includes('deleteIssueComment')) { const id=Number(String(variables.id).replace('IC_','')); for(const values of this.comments.values()){const index=values.findIndex(row=>row.id===id); if(index>=0){values.splice(index,1); return {deleteIssueComment:{clientMutationId:null}};}} }
+    throw new Error('Unhandled fake GraphQL query: '+query);
+  }
+  async request(path, init = {}) {
+    const method = String(init.method ?? 'GET');
+    if (path.includes('/compare/')) return { ahead_by: 1 };
+    if (path.includes('/pulls?')) return this.pulls.filter(item => item.state === 'open');
+    const pullMatch = path.match(/\/pulls\/(\d+)$/);
+    if (method === 'GET' && pullMatch) return this.pulls.find(item => item.number === Number(pullMatch[1]));
+    if (method === 'POST' && path.endsWith('/pulls')) {
+      const body = JSON.parse(String(init.body));
+      const pull = { number: this.nextPr++, title: body.title, body: body.body, state: 'open', head: { ref: body.head }, base: { ref: body.base } };
+      this.pulls.push(pull);
+      return pull;
+    }
+    const commentsMatch = path.match(/\/issues\/(\d+)\/comments/);
+    if (method === 'GET' && commentsMatch) return this.comments.get(Number(commentsMatch[1])) ?? [];
+    if (method === 'POST' && commentsMatch) {
+      const pr = Number(commentsMatch[1]);
+      const values = this.comments.get(pr) ?? [];
+      const body = JSON.parse(String(init.body));
+      const comment = githubComment(body.body, 'bot', this.nextComment++);
+      values.push(comment);
+      this.comments.set(pr, values);
+      return comment;
+    }
+    const commentMatch = path.match(/\/issues\/comments\/(\d+)$/);
+    if (commentMatch) {
+      const id = Number(commentMatch[1]);
+      for (const values of this.comments.values()) {
+        const index = values.findIndex(item => item.id === id);
+        if (index < 0) continue;
+        if (method === 'DELETE') { values.splice(index, 1); return null; }
+        const body = JSON.parse(String(init.body));
+        values[index].body = body.body;
+        return values[index];
+      }
+    }
+    throw new Error('Unhandled fake GitHub request: ' + method + ' ' + path);
+  }
+}
+
+test('managed job creation creates one PR and one durable job marker idempotently', async () => {
+  const { ensureManagedGitHubJob } = await import('../dist/cli.js');
+  const client = new ManagedGitHubClient();
+  const trusted = new Set(['bot']);
+  const options = { id: 'managed', title: 'Managed work', head: 'feat/managed', base: 'main', body: 'body' };
+
+  const first = await ensureManagedGitHubJob(client, 'owner/repo', trusted, options);
+  const second = await ensureManagedGitHubJob(client, 'owner/repo', trusted, options);
+
+  assert.equal(first.pr.number, second.pr.number);
+  assert.equal(first.job.description, 'body');
+  assert.equal(second.job.description, 'body');
+  assert.equal(client.pulls.length, 1);
+  const comments = client.comments.get(first.pr.number) ?? [];
+  assert.equal(comments.filter(item => parseJob(item.body)?.id === 'managed').length, 1);
+});
+
+test('dashboard keeps every unfinished job and only the latest ten completed jobs', () => {
+  const overview = (id, state, completedAt) => ({ job: { ...job(id), state, prNumber: Number(id.replace('job-', '')) }, githubState: completedAt ? 'MERGED' : 'OPEN', draft: id === 'job-99', mergedAt: completedAt, closedAt: null });
+  const unfinished = [overview('job-1', 'OPEN', null), overview('job-2', 'FAILED', null)];
+  const completed = Array.from({ length: 12 }, (_, index) => overview(`job-${index + 10}`, 'COMPLETED', `2026-01-${String(index + 1).padStart(2, '0')}T00:00:00.000Z`));
+  const result = dashboardManagedJobs([...completed, ...unfinished]);
+  assert.deepEqual(result.slice(0, 2).map(item => item.job.id), ['job-1', 'job-2']);
+  assert.equal(result.length, 12);
+  assert.deepEqual(result.slice(2).map(item => item.job.id), ['job-21', 'job-20', 'job-19', 'job-18', 'job-17', 'job-16', 'job-15', 'job-14', 'job-13', 'job-12']);
+  assert.equal(result.some(item => item.job.id === 'job-10'), false);
+});
+
+test('managed job adoption initializes an existing PR with zero comments', async () => {
+  const { ensureManagedGitHubJob } = await import('../dist/cli.js');
+  const client = new ManagedGitHubClient([{ number: 6, title: 'Existing', body: '', state: 'open', head: { ref: 'feat/existing' }, base: { ref: 'main' } }]);
+  const result = await ensureManagedGitHubJob(client, 'owner/repo', new Set(['bot']), { id: 'adopted', prNumber: 6 });
+
+  assert.equal(result.pr.number, 6);
+  assert.equal(client.pulls.length, 1);
+  assert.equal((client.comments.get(6) ?? []).filter(item => parseJob(item.body)?.id === 'adopted').length, 1);
+});
+
+test('managed job repair removes duplicate markers without creating another', async () => {
+  const { ensureManagedGitHubJob } = await import('../dist/cli.js');
+  const client = new ManagedGitHubClient([{ number: 6, title: 'Existing', body: '', state: 'open', head: { ref: 'feat/existing' }, base: { ref: 'main' } }]);
+  const duplicate = marker(JOB_MARKER, job('repair'));
+  client.comments.set(6, [githubComment(duplicate, 'bot', 1), githubComment(duplicate, 'bot', 2)]);
+  client.nextComment = 3;
+
+  await ensureManagedGitHubJob(client, 'owner/repo', new Set(['bot']), { id: 'repair', prNumber: 6 });
+
+  assert.equal((client.comments.get(6) ?? []).filter(item => parseJob(item.body)?.id === 'repair').length, 1);
+});
+
+test('managed GitHub task submission is gated on a durable job marker', async () => {
+  const { ensureManagedGitHubJob } = await import('../dist/cli.js');
+  const client = new ManagedGitHubClient([{ number: 6, title: 'Existing', body: '', state: 'open', head: { ref: 'feat/existing' }, base: { ref: 'main' } }]);
+  const store = new GitHubStore(client, 'owner/repo', 6, new Set(['bot']));
+
+  await assert.rejects(() => store.load('gated'), /has no durable agents-relay:job:v1 marker/);
+  await assert.rejects(() => store.appendTask(task('gated', 'child')), /has no durable agents-relay:job:v1 marker/);
+  await ensureManagedGitHubJob(client, 'owner/repo', new Set(['bot']), { id: 'gated', prNumber: 6 });
+  const durable = await store.load('gated');
+  await store.appendTask(task(durable.id, 'child'));
+
+  const comments = client.comments.get(6) ?? [];
+  const jobIndex = comments.findIndex(item => parseJob(item.body)?.id === 'gated');
+  const taskIndex = comments.findIndex(item => parseTask(item.body)?.id === 'child');
+  assert.ok(jobIndex >= 0);
+  assert.ok(taskIndex > jobIndex);
+});
+
+test('agent registrations persist through trusted stores and ignore forged markers', async () => {
+  const agent = { id:'researcher', name:'Researcher', responsibility:'public research', role:'researcher', capabilities:['research'], boundaries:['no credentials'], endpoint:{kind:'adapter',target:'codex'}, runtime:{adapter:'codex'}, availability:'available', routing:{trustDomains:['public']}, evidence:{evaluations:[],outcomes:{succeeded:0,failed:0,timedOut:0},lastObservedAt:null}, registeredAt:now(), updatedAt:now() };
+  const comments = [githubComment(marker(JOB_MARKER, job('job-a'))), githubComment(marker(AGENT_MARKER, agent)), githubComment(marker(AGENT_MARKER, {...agent, id:'forged'}), 'attacker', 1001)];
+  const store = githubWithComments(comments);
+  assert.deepEqual((await store.listAgents()).map(item => item.id), ['researcher']);
+  agent.availability = 'degraded';
+  await store.saveAgent(agent);
+  const fresh = githubWithComments(comments);
+  assert.equal((await fresh.listAgents())[0].availability, 'degraded');
+  assert.equal(parseAgent(comments[1].body).id, 'researcher');
+});
+
+
+test('task append is idempotent by job id and task id and rejects conflicting replay', async () => {
+  const durableJob = job('idem');
+  const comments = [githubComment(marker(JOB_MARKER, durableJob), 'bot', 1)];
+  const store = githubWithComments(comments);
+  const first = task('idem', 'child');
+  first.capabilities = ['coding'];
+  await store.appendTask(first);
+  const replay = { ...first, createdAt: now(), updatedAt: now() };
+  await store.appendTask(replay);
+  assert.equal(comments.filter(item => parseTask(item.body)?.id === 'child').length, 1);
+
+  const conflict = { ...replay, input: 'different work' };
+  await assert.rejects(() => store.appendTask(conflict), /different definition/);
+  assert.equal(comments.filter(item => parseTask(item.body)?.id === 'child').length, 1);
+});
+
+test('saveTask collapses duplicate durable markers for one job and task id', async () => {
+  const durableJob = job('dedupe');
+  const child = task('dedupe', 'child');
+  const comments = [
+    githubComment(marker(JOB_MARKER, durableJob), 'bot', 1),
+    githubComment(marker(TASK_MARKER, child), 'bot', 2),
+    githubComment(marker(TASK_MARKER, child), 'bot', 3)
+  ];
+  const client = new ManagedGitHubClient([{ number: 6, title: 'Existing', body: '', state: 'open', head: { ref: 'feat/existing' }, base: { ref: 'main' } }]);
+  client.comments.set(6, comments);
+  client.nextComment = 4;
+  const store = new GitHubStore(client, 'owner/repo', 6, new Set(['bot']));
+  child.state = 'RUNNING';
+  await store.saveTask(child);
+  assert.equal((client.comments.get(6) ?? []).filter(item => parseTask(item.body)?.id === 'child').length, 1);
+  assert.equal((await store.load('dedupe')).tasks[0].state, 'RUNNING');
+});
+
+test('managed job creation proactively bootstraps a head branch with no ahead commits', async () => {
+  const { ensureManagedGitHubJob } = await import('../dist/cli.js');
+  const calls = [];
+  let bootstrapped = false;
+  let pr = null;
+  const comments = [];
+  const client = {
+    currentLogin: async () => 'bot',
+    request: async (path, init = {}) => {
+      calls.push(path);
+      if (path.includes('/compare/')) return { ahead_by: bootstrapped ? 1 : 0, behind_by: 5 };
+      if (path.endsWith('/git/commits') && init.method === 'POST') {
+        const body = JSON.parse(String(init.body));
+        assert.equal(body.tree, 'tree');
+        assert.deepEqual(body.parents, ['parent']);
+        return { sha: 'bootstrap' };
+      }
+      if (path.includes('/git/refs/heads/feat/empty') && init.method === 'PATCH') {
+        const body = JSON.parse(String(init.body));
+        assert.equal(body.sha, 'bootstrap');
+        assert.equal(body.force, false);
+        bootstrapped = true;
+        return { object: { sha: 'bootstrap' } };
+      }
+      throw new Error('Unhandled fake request: '+path);
+    },
+    graphql: async (query, variables = {}) => {
+      calls.push(query);
+      if (query.includes('pullRequests(first:20')) return {repository:{pullRequests:{nodes:pr?[{number:7,title:pr.title,body:pr.body,state:'OPEN',headRefName:pr.head.ref,baseRefName:pr.base.ref}]:[]}}};
+      if (query.includes('query($owner:String!,$name:String!){repository(owner:$owner,name:$name){id}}')) return {repository:{id:'REPO_owner_repo'}};
+      if (query.includes('createPullRequest')) {
+        if (!bootstrapped) throw new Error('createPullRequest must not run before bootstrap');
+        pr={number:7,title:variables.title,body:variables.body,state:'open',head:{ref:variables.head},base:{ref:variables.base}};
+        return {createPullRequest:{pullRequest:{number:7,title:pr.title,body:pr.body,state:'OPEN',headRefName:pr.head.ref,baseRefName:pr.base.ref}}};
+      }
+      if (query.includes('ref(qualifiedName:$qualified)')) return {repository:{ref:{target:{oid:'parent',tree:{oid:'tree'}}}}};
+      if (query.includes('pullRequest(number:$number){id state merged mergedAt closedAt}')) return {repository:{pullRequest:pr?{id:'PR_7',state:'OPEN',merged:false,mergedAt:null,closedAt:null}:null}};
+      if (query.includes('comments(first:100')) return {repository:{pullRequest:{comments:{nodes:comments.map(item=>({id:'IC_'+item.id,databaseId:item.id,body:item.body,updatedAt:item.updated_at,author:{login:item.user.login}})),pageInfo:{hasNextPage:false,endCursor:null}}}}};
+      if (query.includes('addComment')) { const item=githubComment(variables.body,'bot',comments.length+1); comments.push(item); return {addComment:{commentEdge:{node:{id:'IC_'+item.id}}}}; }
+      if (query.includes('updateIssueComment')) { const id=Number(String(variables.id).replace('IC_','')); const item=comments.find(row=>row.id===id); item.body=variables.body; return {updateIssueComment:{issueComment:{id:variables.id}}}; }
+      if (query.includes('deleteIssueComment')) { const id=Number(String(variables.id).replace('IC_','')); const index=comments.findIndex(row=>row.id===id); if(index>=0) comments.splice(index,1); return {deleteIssueComment:{clientMutationId:null}}; }
+      throw new Error('Unhandled fake GraphQL query: '+query);
+    },
+  };
+
+  const result = await ensureManagedGitHubJob(client, 'owner/repo', new Set(['bot']), {
+    id: 'empty-job', title: 'Empty branch work', head: 'feat/empty', base: 'main', body: 'body'
+  });
+
+  assert.equal(result.pr.number, 7);
+  assert.equal(bootstrapped, true);
+  assert.equal(calls.filter(call => String(call).endsWith('/git/commits')).length, 1);
+  assert.equal(comments.filter(item => parseJob(item.body)?.id === 'empty-job').length, 1);
+});

package/test/usage.test.js

@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile, utimes } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { CodexApiUsageReader, CodexSessionUsageReader, DeepSeekCreditReader, OpenRouterCreditReader, UsageRegistry } from '../dist/usage.js';
+
+function jsonl(value) { return JSON.stringify(value) + '\n'; }
+
+async function writeRateLimitTelemetry(root, used5h, usedWeek) {
+  const directory = join(root, 'sessions', '2026', '09', '18');
+  await mkdir(directory, { recursive: true });
+  const path = join(directory, 'rollout.jsonl');
+  await writeFile(path, jsonl({
+    timestamp: '2026-09-18T10:37:47.161Z',
+    type: 'event_msg',
+    payload: {
+      type: 'token_count',
+      rate_limits: {
+        primary: { used_percent: used5h, window_minutes: 300, resets_at: 1789745000 },
+        secondary: { used_percent: usedWeek, window_minutes: 10080, resets_at: 1789805365 }
+      }
+    }
+  }));
+  await utimes(path, new Date('2026-09-18T10:38:00Z'), new Date('2026-09-18T10:38:00Z'));
+}
+
+test('reader uses real account rate-limit percentages', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'relay-usage-'));
+  await writeRateLimitTelemetry(root, 2, 85);
+  const snapshot = await new CodexSessionUsageReader(root, 8, 0, () => new Date('2026-09-18T10:40:00Z')).read();
+  assert.equal(snapshot.available, true);
+  assert.equal(snapshot.fiveHour?.usedPercent, 2);
+  assert.equal(snapshot.weekly?.usedPercent, 85);
+});
+
+test('missing rate-limit telemetry stays unavailable', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'relay-usage-'));
+  const snapshot = await new CodexSessionUsageReader(root, 8, 0, () => new Date('2026-09-18T10:40:00Z')).read();
+  assert.equal(snapshot.available, false);
+  assert.equal(snapshot.fiveHour, null);
+  assert.equal(snapshot.weekly, null);
+});
+
+test('usage registry exposes only account limit state', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'relay-usage-'));
+  await writeRateLimitTelemetry(root, 31.5, 74);
+  const overview = await new UsageRegistry(new CodexSessionUsageReader(root, 8, 0, () => new Date('2026-09-18T10:40:00Z'))).snapshot();
+  const snapshot = overview.providers.find(provider => provider.id === 'openai').usage;
+  const zai = overview.providers.find(provider => provider.id === 'zai').usage;
+  assert.deepEqual(Object.keys(snapshot).sort(), ['available', 'fiveHour', 'generatedAt', 'reason', 'weekly']);
+});
+
+
+test('DeepSeek credit reader exposes configured account balances', async () => {
+  const fetchImpl = async url => {
+    assert.equal(url, 'https://api.deepseek.com/user/balance');
+    return new Response(JSON.stringify({ is_available: true, balance_infos: [
+      { currency: 'USD', total_balance: '12.34', granted_balance: '2.34', topped_up_balance: '10.00' },
+      { currency: 'CNY', total_balance: '56.78', granted_balance: '0', topped_up_balance: '56.78' }
+    ] }), { status: 200, headers: { 'content-type': 'application/json' } });
+  };
+  const snapshot = await new DeepSeekCreditReader('configured', undefined, fetchImpl, () => new Date('2026-09-18T10:40:00Z')).read();
+  assert.equal(snapshot.available, true);
+  assert.deepEqual(snapshot.balances.map(item => [item.currency, item.remaining]), [['USD', 12.34], ['CNY', 56.78]]);
+});
+
+test('OpenRouter credit reader exposes purchased, used, and remaining credits', async () => {
+  const fetchImpl = async url => {
+    assert.equal(url, 'https://openrouter.ai/api/v1/credits');
+    return new Response(JSON.stringify({ data: { total_credits: 100.5, total_usage: 25.75 } }), { status: 200, headers: { 'content-type': 'application/json' } });
+  };
+  const snapshot = await new OpenRouterCreditReader('configured', undefined, fetchImpl, () => new Date('2026-09-18T10:40:00Z')).read();
+  assert.equal(snapshot.available, true);
+  assert.equal(snapshot.balances[0].currency, 'USD');
+  assert.equal(snapshot.balances[0].total, 100.5);
+  assert.equal(snapshot.balances[0].used, 25.75);
+  assert.equal(snapshot.balances[0].remaining, 74.75);
+});
+
+test('usage registry includes credit providers only when readers are configured', async () => {
+  const usage = { read: async () => ({ available: false, generatedAt: 'x', fiveHour: null, weekly: null, reason: 'none' }) };
+  const credit = { read: async () => ({ available: true, generatedAt: 'x', balances: [{ currency: 'USD', total: 10, used: null, remaining: 10 }], reason: null }) };
+  const withoutCredits = await new UsageRegistry(usage, usage).snapshot();
+  assert.deepEqual(withoutCredits.credits, []);
+  const withCredits = await new UsageRegistry(usage, usage, credit, credit).snapshot();
+  assert.deepEqual(withCredits.credits.map(item => item.id), ['deepseek', 'openrouter']);
+});