agents-relay 2.0.68 → 2.0.70

package/README.md

@@ -188,7 +188,7 @@ Pushes to `main` run `.github/workflows/publish.yml`: install, test, choose the
 
 Normal consumers should invoke the CLI with `npx agents-relay ...` (or `npx agents-relayd ...`).
 
-After a successful npm publish, the workflow records one idempotent `agents-relay:package-published:v1` marker comment on the originating managed PR. The existing GitHub `issue_comment` webhook resolves that PR back to its durable Job and emits a correlated `package.published` events-bus event containing repository, package, version, registry, commit SHA, PR number, and webhook delivery ID. Its source identity is the GitHub delivery (`github/<repository>/delivery/<delivery-id>`), not a worker execution identity.
+After a successful publish, the workflow records one idempotent `agents-relay:package-published:v1` marker comment using local-merge Job metadata. It uses the closed display PR when present, otherwise a reusable `[Agents Relay] Publication events` issue. The GitHub `issue_comment` webhook resolves the embedded Job ID back to its durable SQLite Job and emits a correlated `package.published` events-bus event containing repository, package, version, registry, commit SHA, PR number, and webhook delivery ID. Its source identity is the GitHub delivery (`github/<repository>/delivery/<delivery-id>`), not a worker execution identity.
 
 `package.published` is a release fact, not a service-management command. Agents Relay does not pull packages, restart PM2, or decide which local service consumes a package. An external deployment subscriber may listen for this event, verify that the exact version is pullable, update/restart the affected service, verify its running version and health, and publish its own deployment outcome event. This keeps publication, deployment, and healthy-running as separate facts and removes the need for an orchestrator thread to synchronously wait for npm readiness.
 
@@ -305,3 +305,34 @@ For autonomous Jobs, `UNBLOCKED` is historical: Relay does not retry that old Ta
 ### Browser Workspace product boundary
 
 Agents Relay owns the persistent `Relay` browser workspace as product infrastructure. At daemon startup it runs `browser-workspace status`, dynamically imports the returned absolute `admin_helper`, and calls `ensureWorkspace("Relay", 6)`. This bootstrap is best-effort: Browser Workspace discovery/helper failures are logged and skipped so they do not prevent `agents-relayd` from starting; ChatGPT browser work may remain unavailable until Browser Workspace recovers. Ordinary ChatGPT worker activity uses the public Browser Workspace one-shot `platform run ... --auto-session` command; orchestrator-owned self-healing flows may still use explicit session commands. Relay does not create or delete workspaces through CLI lifecycle commands.
+
+## Shared publication reporting
+
+Repositories with an existing verified publish/release workflow can report the final result back to Agents Relay with the reusable actions in this repository:
+
+```yaml
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+
+- name: Report verified publication
+  uses: lalalic/agents-relay/.github/actions/report-publication@publication-v1
+  with:
+    token: ${{ github.token }}
+    artifact: my-package-or-artifact
+    version: ${{ steps.release.outputs.version }}
+    channel: https://registry.npmjs.org
+
+- name: Report release failure
+  if: ${{ failure() }}
+  continue-on-error: true
+  uses: lalalic/agents-relay/.github/actions/report-publication-failure@publication-v1
+  with:
+    token: ${{ github.token }}
+    stage: release workflow
+```
+
+The caller must report only a release it has actually verified. For local-first Jobs, the action reads the Job ID and optional display PR from the authoritative local-merge commit message and posts the compatible `agents-relay:package-published:v1` or publish-failure marker to that display PR or to a reusable publication issue. Historical GitHub-merged PR correlation remains supported as a fallback. The marker and GitHub webhook are transport/correlation only: Agents Relay resolves the originating Job and persists publication facts through `RelayStore.recordPublication(...)` into the authoritative SQLite `publication_delivery` and `publication_state` tables. Publication success or failure never changes a completed Job's lifecycle state.
+
+`artifact` can identify an npm/PyPI package, Chrome extension, GitHub Release artifact, or a custom published artifact. `channel` identifies the registry/store/release channel and is displayed as publication metadata. Repeated reports of the same artifact/version are idempotent.

package/dist/adapters.js

@@ -2,6 +2,8 @@ import { readFile, writeFile, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { withTestInjection } from './e2e-injection.js';
 import { spawnOwnedProcess, terminateOwnedProcess, ownedProcessTerminationReason } from './owned-process.js';
 export function buildCodexArgs(route, input) {
     const args = ['exec', '--json'];
@@ -27,6 +29,21 @@ function parseThreadStarted(line) {
         return undefined;
     }
 }
+function parseCodexFailure(line) {
+    try {
+        const value = JSON.parse(line);
+        if (value.type === 'turn.failed' && value.error && typeof value.error === 'object' && !Array.isArray(value.error)) {
+            const message = value.error.message;
+            if (typeof message === 'string' && message.trim())
+                return { message: message.trim(), priority: 2 };
+        }
+        if (value.type === 'error' && typeof value.message === 'string' && value.message.trim()) {
+            return { message: value.message.trim(), priority: 1 };
+        }
+    }
+    catch { /* non-JSON output is not structured Codex failure evidence */ }
+    return undefined;
+}
 function appendTail(current, chunk, maxBytes = 16384) {
     const combined = current + chunk;
     return Buffer.byteLength(combined) <= maxBytes
@@ -42,6 +59,8 @@ export class CodexAdapter {
         this.command = command;
     }
     launch(task, signal, context = {}) {
+        if (context.testInjection?.method === 'worker.codex.launch')
+            return withTestInjection('worker.codex.launch', context.testInjection, () => this.launch(task, signal, { ...context, testInjection: undefined }));
         if (!task.routing)
             throw new Error(`Task ${task.id} requires routing metadata before Codex launch`);
         const child = spawnOwnedProcess(this.command, buildCodexArgs(task.routing, task.input), {
@@ -52,6 +71,7 @@ export class CodexAdapter {
         });
         let stdoutBuffer = '';
         let stderrTail = '';
+        let structuredFailure;
         let bufferedThreadId;
         let launchedResolve;
         let launchedReject;
@@ -59,6 +79,9 @@ export class CodexAdapter {
         launched.catch(() => { });
         let execution;
         const consumeLine = (line) => {
+            const failure = parseCodexFailure(line);
+            if (failure && (!structuredFailure || failure.priority >= structuredFailure.priority))
+                structuredFailure = failure;
             const threadId = parseThreadStarted(line);
             if (!threadId)
                 return;
@@ -89,7 +112,7 @@ export class CodexAdapter {
                     resolve({ summary: 'Codex runtime exited after task execution; terminal task state is event-owned' });
                 }
                 else {
-                    reject(new Error(stderrTail.trim() || `Codex exited ${code}`));
+                    reject(new Error(structuredFailure?.message || stderrTail.trim() || `Codex exited ${code}`));
                 }
             });
         });
@@ -148,7 +171,11 @@ export function parseDriverJson(output) {
 function browserWorkspaceCli(override = process.env.AGENTS_RELAY_BROWSER_WORKSPACE_COMMAND) {
     return override ? { command: override, prefix: [] } : { command: 'uvx', prefix: ['browser-workspace'] };
 }
+const browserWorkspaceInjection = new AsyncLocalStorage();
 function browserWorkspaceCommand(cli, args, stdin, signal) {
+    return Promise.resolve(withTestInjection('browserWorkspace.command', browserWorkspaceInjection.getStore(), () => rawBrowserWorkspaceCommand(cli, args, stdin, signal)));
+}
+function rawBrowserWorkspaceCommand(cli, args, stdin, signal) {
     return new Promise((resolve, reject) => {
         const child = spawnOwnedProcess(cli.command, [...cli.prefix, ...args], {
             invocation: 'browser-workspace.command',
@@ -344,14 +371,23 @@ export class ChatGptAdapter {
             if (controller.signal.aborted)
                 throw new Error('browser-worker execution aborted');
             const policy = chatGptTabClosePolicy(task.chatgptTabClosePolicy, this.tabClosePolicy);
-            const run = (this.runner ?? browserWorkerRunner())(definition, {
+            const submit = () => (this.runner ?? browserWorkerRunner())(definition, {
                 prompt: task.input,
                 ...(task.attachments?.length ? { files: task.attachments } : {}),
                 ...(task.chatgptThreadDelivery ? { thread: task.chatgptThreadDelivery } : {}),
                 tabClosePolicy: policy,
             }, route, controller.signal);
+            const run = context.testInjection?.method === 'browserWorkspace.command'
+                ? browserWorkspaceInjection.run(context.testInjection, submit) : submit();
             try {
-                const output = await (run.submitted ?? run.promise);
+                // Start acknowledgement may expire while browser submission is still pending.
+                // Race its rejection with delivery so a hung browser cannot hold a QUEUED
+                // execution until the full lease expires. A successful ack never shortcuts delivery.
+                const submission = run.submitted ?? run.promise;
+                const startAckFailure = context.waitForWorkerStart?.then(() => new Promise(() => { }), error => Promise.reject(error));
+                const output = await (startAckFailure
+                    ? Promise.race([submission, startAckFailure])
+                    : submission);
                 const response = parseBrowserWorkerResponse(output);
                 if (task.chatgptThreadDelivery && (typeof response.thread_id !== 'string' || response.thread_id !== task.chatgptThreadDelivery.threadId)) {
                     throw new Error('browser-worker submitted to an unexpected ChatGPT thread');

package/dist/blockers.js

@@ -38,10 +38,23 @@ export async function registerBlockerDependency(options) {
     }
     if (blocker.blockerResolutionMode && blocker.blockerResolutionMode !== requestedMode)
         throw new Error(`Blocker ${blocker.id} already uses ${blocker.blockerResolutionMode} resolution`);
-    blocker.blockerResolutionMode = requestedMode;
-    blocker.unblocks = [...(blocker.unblocks ?? []), relation];
-    blocker.updatedAt = now;
-    await options.blockerStore.saveJob(blocker);
+    if (options.blockerStore.mutateJob) {
+        await options.blockerStore.mutateJob(blocker.id, current => {
+            if (current.blockerResolutionMode && current.blockerResolutionMode !== requestedMode)
+                throw new Error(`Blocker ${current.id} already uses ${current.blockerResolutionMode} resolution`);
+            current.blockerResolutionMode = requestedMode;
+            if (!(current.unblocks ?? []).some(item => dependentKey(item) === dependentKey(relation)))
+                current.unblocks = [...(current.unblocks ?? []), relation];
+            current.updatedAt = now;
+            return current;
+        });
+    }
+    else {
+        blocker.blockerResolutionMode = requestedMode;
+        blocker.unblocks = [...(blocker.unblocks ?? []), relation];
+        blocker.updatedAt = now;
+        await options.blockerStore.saveJob(blocker);
+    }
     task.blockedBy = taskBlocker;
     task.updatedAt = now;
     await options.dependentStore.saveTask(task);

package/dist/cli-blocker.js

@@ -1,43 +1,27 @@
-import { openLocalManagedStore } from './local-managed-store.js';
-import { registerBlockerDependency } from './blockers.js';
-import { arg, publishDependentUnblocked, repository, withEventBus } from './cli-support.js';
+import { arg, relayControlCommand, relayControlJob, repository } from './cli-support.js';
 import { usage } from './cli-help.js';
 export async function runBlockerCommand(action, args) {
     if (!['add', 'resolve', 'show'].includes(action))
         throw new Error(usage);
-    const repo = repository(args);
+    repository(args);
     const id = arg(args, '--id');
-    const pr = Number(arg(args, '--pr'));
-    if (!id || !Number.isInteger(pr) || pr <= 0)
-        throw new Error('blocker commands require --repo, --pr, and --id for the blocker Job');
-    const blockerStore = openLocalManagedStore(repo, pr).store;
+    if (!id)
+        throw new Error('blocker commands require --repo and --id for the blocker Job');
     if (action === 'show') {
-        console.log(JSON.stringify(await blockerStore.load(id), null, 2));
+        console.log(JSON.stringify(await relayControlJob(args, id), null, 2));
         return;
     }
     if (action === 'resolve') {
-        const summary = await blockerStore.resolveBlockerDependents(id, 'verified');
-        await withEventBus(args, bus => publishDependentUnblocked(bus, summary.unblocked, `Blocker Job ${id} resolved (verified)`));
-        console.log(JSON.stringify({ blocker: id, resolution: 'verified', ...summary }, null, 2));
+        const result = await relayControlCommand(args, { command: 'blocker.resolve', jobId: id, resolution: 'verified' });
+        console.log(JSON.stringify({ blocker: id, resolution: 'verified', ...result }, null, 2));
         return;
     }
-    const dependentRepo = arg(args, '--dependent-repo');
-    const dependentPr = Number(arg(args, '--dependent-pr'));
-    const dependentJob = arg(args, '--dependent-job');
-    const dependentTask = arg(args, '--dependent-task');
-    if (!dependentRepo || !Number.isInteger(dependentPr) || dependentPr <= 0 || !dependentJob || !dependentTask) {
-        throw new Error('blocker add requires --dependent-repo, --dependent-pr, --dependent-job, and --dependent-task');
-    }
+    const dependentJobId = arg(args, '--dependent-job');
+    const dependentTaskId = arg(args, '--dependent-task');
+    if (!dependentJobId || !dependentTaskId)
+        throw new Error('blocker add requires --dependent-job and --dependent-task');
     const modeValue = arg(args, '--resolution', 'merge');
     if (!['merge', 'verified'].includes(modeValue))
         throw new Error('--resolution must be merge or verified');
-    const relation = await registerBlockerDependency({
-        blockerStore,
-        blockerJobId: id,
-        dependentStore: openLocalManagedStore(dependentRepo, dependentPr).store,
-        dependentJobId: dependentJob,
-        dependentTaskId: dependentTask,
-        resolutionMode: modeValue,
-    });
-    console.log(JSON.stringify(relation, null, 2));
+    console.log(JSON.stringify(await relayControlCommand(args, { command: 'blocker.add', jobId: id, dependentJobId, dependentTaskId, resolutionMode: modeValue }), null, 2));
 }

package/dist/cli-help.js

@@ -59,12 +59,12 @@ Optional: --thread-id THREAD_ID persists a reviewer override; omitted uses Job r
     'job create': `Create a SQLite-authoritative Job.
 
 Required: --repo OWNER/REPO, --id JOB_ID, and either --head BRANCH or --pr NUMBER.
-With --head, reuse/create the PR for that head. With --pr, bind an external PR reference locally without a GitHub query.
-Common: --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --mode fixed|autonomous, --no-review, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
-Job creation always enables auto-merge and never creates executable tasks. The orchestrator decides the initial task batch separately. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
+With --head, bind the local source branch and use --base as its local merge target without a GitHub query. With --pr, bind an existing external PR reference as optional metadata without a GitHub query.
+Common: --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --mode fixed|autonomous, --initial-plan, --no-review, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
+Job creation always enables auto-merge. By default it is create-only; --initial-plan follows durable Job creation with the first real Planner round, activates the Job, and publishes the normal wake so Relay can continue without a second orchestrator command. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
 
 Example:
-  npx agents-relay job create --repo OWNER/REPO --head feat/example --base main --id job-1 --title "Objective" --objective-file job.md`,
+  npx agents-relay job create --repo OWNER/REPO --head feat/example --base main --id job-1 --title "Objective" --objective-file job.md --initial-plan`,
     'job update': `Partially update mutable metadata on a healthy existing Job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
@@ -144,6 +144,9 @@ Required: --task-id ID, --summary TEXT, and the normal Job storage options. The
     'task retry': `Retry one durable Task.
 
 Required: --task-id ID and the normal Job storage options.`,
+    'task recover': `Retry one failed/blocked durable Task from its active automatic Troubleshooter without cancelling that recovery Task.
+
+Required: --task-id ID, --recovery-task-id TROUBLESHOOTER_ID, and the normal Job storage options. The recovery Task must be an active Troubleshooter whose parentTaskId is the original Task.`,
     'task cancel': `Cancel one durable Task.
 
 Required: --task-id ID and the normal Job storage options.`,
@@ -216,7 +219,7 @@ Example:
   npx agents-relay serve --repo OWNER/REPO --pr 12 --id job-1`,
     'agent-register': `Register an agent role and its execution endpoint.
 
-Required: --file PATH or managed GitHub options, plus --name NAME --responsibility TEXT --role ROLE --endpoint TARGET.
+Required for durable service mode: --repo OWNER/REPO --id JOB_ID plus --name NAME --responsibility TEXT --role ROLE --endpoint TARGET. Use --file only for explicit demo mode.
 Common: --capabilities a,b, --runtime shell|codex|chatgpt, --provider NAME, --model NAME.
 
 Example:
@@ -224,8 +227,8 @@ Example:
     projection: `Inspect and explicitly repair deterministic V2 GitHub projection conflicts.
 
 Usage:
-  npx agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER [--store PATH]
-  npx agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local
+  npx agents-relay projection conflicts --repo OWNER/REPO --id JOB_ID
+  npx agents-relay projection resolve --repo OWNER/REPO --id JOB_ID --projection-id ID --action requeue|discard-local
 
 A deterministic same-id/different-definition append conflict is classified once, stops
 consuming retry budget, and retains structured diagnostic evidence. It is never
@@ -234,7 +237,7 @@ auto-overwritten: an operator resolves it after reconciling the divergent defini
   discard-local  Drop the blocked local mutation so a fresh one can be enqueued`,
     'agent-discover': `Find registered agents using hard filters.
 
-Required: --file PATH or managed GitHub options.
+Required for durable service mode: --repo OWNER/REPO --id JOB_ID. Use --file only for explicit demo mode.
 Common: --capabilities a,b, --runtime NAME, --availability available,busy, --task-kind NAME, --explore.
 
 Example:

package/dist/cli-job-create.js

@@ -1,31 +1,31 @@
 import { openLocalManagedStore } from './local-managed-store.js';
 import { createJobEntity } from './workflow/entity-creation.js';
 import { normalizeThreadId } from './reviewer-thread.js';
-import { discoverLocalRelayStoreSnapshots } from './relay-store.js';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { discoverLocalRelayStoreSnapshots, relayStoreDirectory } from './relay-store.js';
 /**
- * Job lifecycle bootstrap: SQLite is authoritative. PR creation is an
- * optional one-time external adapter; an explicit PR number is offline-safe.
+ * Job lifecycle bootstrap: SQLite is authoritative. No GitHub request is
+ * required; an explicit PR number is optional external metadata.
  */
 export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAuthors, options) {
     if (!options.id)
         throw new Error('--id is required for managed local Jobs');
-    const number = options.prNumber ?? 0;
-    if (!Number.isInteger(number) || number < 0)
+    const requestedNumber = options.prNumber ?? 0;
+    if (!Number.isInteger(requestedNumber) || requestedNumber < 0)
         throw new Error('Invalid external PR binding number');
-    const pr = { number, title: options.title ?? options.id,
-        body: options.body ?? options.objective ?? '', state: 'OPEN', head: '', base: options.base ?? '' };
-    const directory = options.storeDirectory ?? join(homedir(), '.agents-relay', 'stores');
+    const placeholder = { number: requestedNumber, title: options.title ?? options.id,
+        body: options.body ?? options.objective ?? '', state: 'OPEN', head: options.head ?? '', base: options.base ?? '' };
+    const directory = options.storeDirectory ?? relayStoreDirectory();
     const alreadyKnown = (await discoverLocalRelayStoreSnapshots(directory)).flatMap(snapshot => snapshot.jobs.filter(job => job.id === options.id).map(job => ({ job, path: snapshot.path })));
     if (alreadyKnown.length > 1)
         throw new Error('Duplicate immutable Job ID across SQLite stores: ' + options.id);
     if (alreadyKnown.length === 1) {
         const existing = alreadyKnown[0].job;
-        if (existing.repository !== repositoryName || (options.prNumber !== undefined && existing.prNumber !== number))
+        if (existing.repository !== repositoryName || (options.prNumber !== undefined && existing.prNumber !== requestedNumber))
             throw new Error('Immutable Job ID is already bound to a different repository or external PR');
-        return { job: existing, pr: { ...pr, number: existing.prNumber } };
+        return { job: existing, pr: { ...placeholder, number: existing.prNumber } };
     }
+    const pr = placeholder;
+    const number = pr.number;
     const local = openLocalManagedStore(repositoryName, number, {
         directory, jobId: options.id, noGitHub: true,
     });
@@ -34,6 +34,12 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
         if (existing)
             return { job: existing, pr };
         const now = new Date().toISOString();
+        const localMergeSource = options.localMergeSource ?? (options.head ? `refs/heads/${options.head}` : undefined);
+        if (options.localMergeTarget && options.localMergeTarget !== 'refs/heads/main')
+            throw new Error('Local merge target must always be main');
+        if (options.base && options.base !== 'main')
+            throw new Error('Job base must always be main');
+        const localMergeTarget = localMergeSource ? 'refs/heads/main' : undefined;
         const job = createJobEntity({
             id: options.id,
             title: options.title || pr.title || 'Agents Relay job',
@@ -44,7 +50,7 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
             executionMode: options.executionMode ?? 'fixed',
             tag: options.tag,
             autoMerge: true,
-            ...(options.localMergeSource && options.localMergeTarget ? { localMerge: { sourceRef: options.localMergeSource, targetRef: options.localMergeTarget, status: 'pending' } } : {}),
+            ...(localMergeSource && localMergeTarget ? { localMerge: { sourceRef: localMergeSource, targetRef: localMergeTarget, status: 'pending' } } : {}),
             reviewEnabled: options.reviewEnabled ?? true,
             ...(options.reviewerThreadId
                 ? { reviewerThreadId: normalizeThreadId(options.reviewerThreadId, 'reviewer thread ID') }

package/dist/cli-local-merge-config.js

@@ -1,8 +1,10 @@
 export function configureLocalGitMerge(job, source, target, localOnly) {
     // The GitHub integration is observational; local merge applies in either mode.
     void localOnly;
-    if (!source || !target)
-        throw new Error('Supply both --local-merge-source and --local-merge-target');
+    if (!source)
+        throw new Error('Local merge source is required');
+    if (target !== 'refs/heads/main')
+        throw new Error('Local Git merge target must always be refs/heads/main');
     if (!['ACTIVE', 'DRAFT'].includes(job.state))
         throw new Error('Cannot reconfigure merge of a terminal Job');
     job.localMerge = { sourceRef: source, targetRef: target, status: 'pending' };

package/dist/cli-projection.js

@@ -1,61 +1,29 @@
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { SQLiteRelayStore, relayStorePath } from './relay-store.js';
-import { arg, integerArg, pullRequest, repository } from './cli-support.js';
-const DEFAULT_STORE_DIR = join(homedir(), '.agents-relay', 'stores');
-function storePath(args) {
-    const explicit = arg(args, '--store');
-    if (explicit)
-        return explicit;
-    return relayStorePath(arg(args, '--store-dir', DEFAULT_STORE_DIR), repository(args), pullRequest(args));
-}
+import { arg, integerArg, relayControlCommand } from './cli-support.js';
 export async function runProjectionCommand(action, args) {
-    const store = new SQLiteRelayStore(storePath(args));
-    try {
-        if (action === 'conflicts' || action === 'list') {
-            const conflicts = await store.listProjectionConflicts();
-            console.log(JSON.stringify(conflicts, null, 2));
-            return;
-        }
-        if (action === 'resolve') {
-            const id = integerArg(args, '--projection-id', 0);
-            if (id <= 0)
-                throw new Error('projection resolve requires --projection-id ID');
-            const raw = arg(args, '--action', 'requeue');
-            if (raw !== 'requeue' && raw !== 'discard-local' && raw !== 'discard_local')
-                throw new Error('--action must be requeue or discard-local');
-            const resolution = raw === 'requeue' ? 'requeue' : 'discard_local';
-            const note = arg(args, '--note') || undefined;
-            const resolved = await store.resolveProjectionConflict(id, { action: resolution, ...(note ? { note } : {}) });
-            if (!resolved)
-                throw new Error(`Projection ${id} is not in a resolvable conflict state`);
-            console.log(`Resolved projection ${id} with ${resolution}`);
-            return;
-        }
-        throw new Error(`projection ${action || '<action>'} is not supported; use conflicts or resolve`);
+    const jobId = arg(args, '--id');
+    if (!jobId)
+        throw new Error('projection commands require --id JOB_ID');
+    if (action === 'conflicts' || action === 'list') {
+        console.log(JSON.stringify(await relayControlCommand(args, { command: 'projection.conflicts', jobId }), null, 2));
+        return;
     }
-    finally {
-        store.close();
+    if (action === 'resolve') {
+        const id = integerArg(args, '--projection-id', 0);
+        if (id <= 0)
+            throw new Error('projection resolve requires --projection-id ID');
+        const raw = arg(args, '--action', 'requeue');
+        if (!['requeue', 'discard-local', 'discard_local'].includes(raw))
+            throw new Error('--action must be requeue or discard-local');
+        const resolution = raw === 'requeue' ? 'requeue' : 'discard_local';
+        const note = arg(args, '--note') || undefined;
+        const result = await relayControlCommand(args, { command: 'projection.resolve', jobId, projectionId: id, action: resolution, ...(note ? { note } : {}) });
+        console.log(JSON.stringify(result, null, 2));
+        return;
     }
+    throw new Error(`projection ${action || '<action>'} is not supported; use conflicts or resolve`);
 }
 export function projectionHelp(action) {
-    if (action === 'resolve') {
-        return `Explicitly repair one classified projection conflict.
-
-Required: --projection-id ID --action requeue|discard-local, plus --store PATH or --repo OWNER/REPO --pr NUMBER.
-Actions:
-  requeue        Re-arm the recorded projection after the divergent side is reconciled
-  discard-local  Drop the blocked local mutation so a fresh one can be enqueued
-
-Never silently overwrites either side. The recorded diagnostic remains until resolution.`;
-    }
-    return `Inspect and explicitly repair deterministic V2 GitHub projection conflicts.
-
-Usage:
-  npx agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER [--store PATH]
-  npx agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local
-
-A deterministic same-id/different-definition append conflict is classified once, stops
-consuming retry budget, and retains structured diagnostic evidence. It is never
-auto-overwritten: an operator resolves it after reconciling the divergent definition.`;
+    if (action === 'resolve')
+        return `Explicitly repair one classified projection conflict.\n\nRequired: --repo OWNER/REPO --id JOB_ID --projection-id ID --action requeue|discard-local.`;
+    return `Inspect and explicitly repair deterministic V2 GitHub projection conflicts.\n\nUsage:\n  npx agents-relay projection conflicts --repo OWNER/REPO --id JOB_ID\n  npx agents-relay projection resolve --repo OWNER/REPO --id JOB_ID --projection-id ID --action requeue|discard-local`;
 }

package/dist/cli-review.js

@@ -1,5 +1,5 @@
-import { storeFor, arg, hasArg, withEventBus, requestManagedReconciliation } from './cli-support.js';
-import { normalizeThreadId, resolveReviewerThreadDestination } from './reviewer-thread.js';
+import { arg, hasArg, relayControlCommand } from './cli-support.js';
+import { normalizeThreadId } from './reviewer-thread.js';
 export function reviewRequestThreadOverride(args) {
     const values = [...args];
     return hasArg(values, '--thread-id')
@@ -9,27 +9,10 @@ export function reviewRequestThreadOverride(args) {
 export async function runReviewCommand(action, reviewArgs) {
     if (action !== 'request')
         throw new Error('review supports: request');
-    if (!arg(reviewArgs, '--repo') || !arg(reviewArgs, '--pr') || !arg(reviewArgs, '--id'))
-        throw new Error('review request requires --repo, --pr and --id');
+    const jobId = arg(reviewArgs, '--id');
+    if (!arg(reviewArgs, '--repo') || !jobId)
+        throw new Error('review request requires --repo and --id');
     const threadId = reviewRequestThreadOverride(reviewArgs);
-    const { store, job, localFile } = await storeFor(reviewArgs);
-    if (localFile)
-        throw new Error('review request requires a managed GitHub Job');
-    if (job.state === 'CANCELLED' || job.state === 'COMPLETED')
-        throw new Error('Cannot request review for terminal Job');
-    if (!job.reviewEnabled)
-        throw new Error('Review disabled for this Job');
-    if (job.tasks.some(task => task.agentName === 'reviewer' && ['RUNNING', 'QUEUED', 'DRAFT'].includes(task.state)))
-        throw new Error('Review already queued or running; refusing duplicate request');
-    if (job.review?.outcome === 'approved')
-        throw new Error('Current head already approved; review request not needed');
-    if (threadId !== undefined) {
-        job.reviewerThreadId = threadId;
-        job.updatedAt = new Date().toISOString();
-        await store.saveJob(job);
-    }
-    const destination = resolveReviewerThreadDestination(job);
-    await withEventBus(reviewArgs, async (bus) => requestManagedReconciliation(bus, job));
-    console.log(JSON.stringify({ jobId: job.id, pr: job.prNumber, reviewerThreadId: destination?.threadId ?? null, status: 'requested', note: 'Relay graph will create the review Task once eligible; this is not a delivery receipt.' }, null, 2));
-    return;
+    const job = await relayControlCommand(reviewArgs, { command: 'review.request', jobId, ...(threadId !== undefined ? { threadId } : {}) });
+    console.log(JSON.stringify({ jobId: job.id, pr: job.externalPrNumber ?? job.prNumber ?? 0, reviewerThreadId: job.reviewerThreadId ?? null, status: 'requested', note: 'Relay graph will create the review Task once eligible; this is not a delivery receipt.' }, null, 2));
 }

package/dist/cli-support.js

@@ -4,8 +4,7 @@ import { githubAuthContext } from './github-auth.js';
 import { noGitHubMode } from './no-github.js';
 import { basename } from 'node:path';
 import { createJobIdRegistryResolver } from './local-job-registry.js';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { relayStoreDirectory } from './relay-store.js';
 import { NatsEventBus, eventFor } from './events.js';
 import { parseJobSchedule } from './scheduler.js';
 import { parseJobTagJson } from './task-tag.js';
@@ -73,12 +72,13 @@ export async function storeFor(args) {
     const jobId = arg(args, '--id');
     if (!repo || !jobId)
         throw new Error('Local Job requires --repo and --id (or explicit --file)');
-    const directory = arg(args, '--store-dir') || join(homedir(), '.agents-relay', 'stores');
+    const directory = arg(args, '--store-dir') || relayStoreDirectory();
     const binding = await createJobIdRegistryResolver(directory, new Map())(jobId);
     if (!binding || binding.job.repository !== repo)
         throw new Error('Immutable local Job not found for repository: ' + jobId);
     const suppliedPr = arg(args, '--pr');
-    if (suppliedPr && binding.job.prNumber !== Number(suppliedPr))
+    const boundPr = binding.job.externalPrNumber ?? (binding.job.prNumber > 0 ? binding.job.prNumber : 0);
+    if (suppliedPr && boundPr !== Number(suppliedPr))
         throw new Error('Local Job external PR binding mismatch');
     return { store: binding.store, job: await binding.store.load(jobId), localFile: null };
 }
@@ -107,6 +107,61 @@ export async function relayControlJob(args, jobId) {
         throw new Error(`Agents Relay job request failed: ${await response.text() || `HTTP ${response.status}`}`);
     return await response.json();
 }
+export async function relayControlCommand(args, body) {
+    const host = arg(args, '--host', '127.0.0.1');
+    const port = Number(arg(args, '--port', String(SERVICE_DEFAULTS.port)));
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        throw new Error('--port must be an integer between 1 and 65535');
+    let response;
+    try {
+        response = await fetch(`http://${host}:${port}/api/control`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+    }
+    catch (error) {
+        throw new Error(`Agents Relay service unavailable at ${host}:${port}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok)
+        throw new Error(`Agents Relay control command failed: ${await response.text() || `HTTP ${response.status}`}`);
+    return await response.json();
+}
+export async function relayJobList(args) {
+    const host = arg(args, '--host', '127.0.0.1');
+    const port = Number(arg(args, '--port', String(SERVICE_DEFAULTS.port)));
+    const repo = arg(args, '--repo');
+    let response;
+    try {
+        response = await fetch(`http://${host}:${port}/api/jobs`);
+    }
+    catch (error) {
+        throw new Error(`Agents Relay service unavailable at ${host}:${port}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok)
+        throw new Error(`Agents Relay jobs request failed: ${await response.text() || `HTTP ${response.status}`}`);
+    const jobs = await response.json();
+    return repo ? jobs.filter(job => job.repository === repo) : jobs;
+}
+export async function relayJobStateCommand(args, jobId, state) {
+    const host = arg(args, '--host', '127.0.0.1');
+    const port = Number(arg(args, '--port', String(SERVICE_DEFAULTS.port)));
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        throw new Error('--port must be an integer between 1 and 65535');
+    const params = new URLSearchParams({ id: jobId, state });
+    const repo = arg(args, '--repo');
+    const pr = Number(arg(args, '--pr'));
+    if (repo)
+        params.set('repo', repo);
+    if (Number.isInteger(pr) && pr > 0)
+        params.set('pr', String(pr));
+    let response;
+    try {
+        response = await fetch(`http://${host}:${port}/api/job-state?${params.toString()}`, { method: 'POST' });
+    }
+    catch (error) {
+        throw new Error(`Agents Relay service unavailable at ${host}:${port}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok)
+        throw new Error(`Agents Relay job state command failed: ${await response.text() || `HTTP ${response.status}`}`);
+    return await response.json();
+}
 export async function relayTaskCommand(args, body) {
     const host = arg(args, '--host', '127.0.0.1');
     const port = Number(arg(args, '--port', String(SERVICE_DEFAULTS.port)));