agents-relay 2.0.67 → 2.0.69

package/README.md

@@ -1,8 +1,9 @@
 # Agents Relay
 
-Agents Relay is a generic TypeScript runtime for durable asynchronous agent jobs coordinated through GitHub pull requests. The PR body stores the durable Job marker plus human-readable Job objective, while PR comments store durable Task and other append-friendly records; correlated terminal events are authoritative for model-backed task lifecycle transitions.
+Agents Relay is a TypeScript runtime for durable asynchronous agent Jobs driven locally by SQLite and canonical workflow Graphs. The EventBus wakes reconciliation; an EventBus message or GitHub PR comment is never the lifecycle authority. Job, Plan, Task, Review, Execution, Lease and Recovery state survive daemon restarts in SQLite.
+
+V2 uses a read-only local SQLite Job Registry for discovery. The immutable jobId selects the Job Store even when prNumber is zero; scheduled slot claims are atomic across processes. GitHub is **audit-only**: its PR/head/publish events are persisted for reporting, never consulted to start, stop, or complete local Workflows. Local Git delivery and its confirmed merge receipt—not a remote PR MERGED fact—gate Graph completion. Job creation and local Task operations require no GitHub authentication or PR.
 
-V2 separates **operational execution state** from that collaboration record. A local RelayStore may use SQLite/WAL for runtime snapshots, event idempotency and a durable GitHub projection outbox. ProjectedDurableStore bootstraps from the existing GitHub representation, commits Job/Plan/Task runtime changes locally, and lets GitHubProjectionWriter project them asynchronously. GitHub therefore remains the human-readable durable Job/Plan/Task/Review surface without being required for every high-frequency runtime transition.
 
 The canonical V2 architecture contract is
 [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md). README sections below describe
@@ -10,23 +11,27 @@ the runtime; they do not replace that contract.
 
 ## V2 architecture
 
-```mermaid
+\`\`\`mermaid
 flowchart LR
-    Human[Human / orchestrator] --> GH[GitHub PR + comments<br/>collaboration + audit surface]
-    GH --> Inbound[Typed inbound GitHub facts]
-    Worker[Workers / adapters] --> Events[Event Bus<br/>lifecycle + progress facts]
-    Inbound --> Coord[ReconcileCoordinator]
-    Events --> Coord
-    Coord --> Graphs[Executable Mermaid graphs<br/>workflow authority]
-    Graphs --> Runtime[TypeScript primitives<br/>facts + guards + effects]
-    Runtime --> Store[(SQLite/WAL RelayStore<br/>operational execution truth)]
-    Store --> Outbox[Projection outbox]
-    Outbox --> Writer[GitHubProjectionWriter]
-    Writer --> GH
-    Store --> Views[Dashboard / scheduler / recovery]
-```
-
-RelayStore owns local operational execution facts; GitHub remains the human-readable collaboration and audit projection. Worker events are authoritative lifecycle inputs for model-backed tasks, but they are not a separate durable database. The graph engine owns workflow branching; TypeScript owns facts, persistence, locking/claims, I/O, and primitive guard/action implementations.
+    Human[Human / orchestrator] --> CLI[CLI / Dashboard]
+    CLI --> Store[(SQLite / WAL<br/>Job Task Plan Review truth)]
+    Worker[Workers / adapters] --> Events[EventBus<br/>wake + observations]
+    Events --> Coordinator[ReconcileCoordinator]
+    Store --> Coordinator
+    Coordinator --> Graphs[Canonical Mermaid Graph Engine]
+    Graphs --> Effects[Stateless actions / effects]
+    Effects --> Store
+    Store --> Views[Dashboard / Scheduler / Recovery]
+    Effects --> Outbox[Durable external-action outbox]
+    Outbox --> GH[GitHub Commit / PR / Review / Merge API]
+    GH --> Facts[Confirmed external facts]
+    Facts --> Store
+\`\`\`
+
+SQLite holds the sole lifecycle authority; the Graph Engine selects every transition.
+GitHub operations are explicitly requested and confirmed by adapters, never used to
+discover or reconstruct Job/Task state. EventBus delivery wakes reconciliation;
+it cannot replace the durable SQLite record.
 
 ### Workflow graph navigation
 
@@ -53,7 +58,7 @@ These paths always represent the current canonical graphs. Historical graph defi
 
 ## Quick start
 
-For GitHub-backed work, create or adopt the PR through Agents Relay itself. This guarantees the durable job marker exists before any managed task is submitted.
+For new work, create a local Job through Agents Relay. The CLI can bind a known PR number without GitHub access; creating a new PR head uses the external GitHub adapter. Tasks are validated against the SQLite Job, not GitHub markers.
 
 ~~~sh
 cat > job.md <<'EOF'
@@ -183,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.
 
@@ -300,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,45 +1,27 @@
-import { GitHubStore } from './store.js';
-import { githubAuthContext } from './github-auth.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 auth = await githubAuthContext(args);
-    const blockerStore = new GitHubStore(auth.client, repo, pr, auth.trustedAuthors);
+    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: new GitHubStore(auth.client, dependentRepo, dependentPr, auth.trustedAuthors),
-        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

@@ -1,12 +1,14 @@
 export const usage = 'agents-relay <job|task|review|plan|blocker|projection|escalation|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
 const help = {
-    root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
+    root: `Agents Relay coordinates durable asynchronous agent jobs through local SQLite and workflow graphs.
 
 Usage:
-  npx agents-relay <command> [options]
+  npx agents-relay <command> [options] [--no-github]
+
+--no-github: SQLite/Graph-only mode. GitHub auth/API, PR creation, merge and fetch are disabled. Local completion is Graph-owned.
 
 Commands:
-  job create|update|show|list|merge|unblock|cancel  Manage durable GitHub-backed jobs
+  job create|update|show|list|merge|unblock|cancel  Manage SQLite-authoritative jobs with optional GitHub PRs
   task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
   review request           Request graph-owned review (optional thread override)
   plan                     Invoke the Planner for an existing managed Job
@@ -24,7 +26,7 @@ Commands:
 
 Run 'npx agents-relay <command> --help' for command options and examples.
 Use 'node dist/cli.js' only for explicit local development/demo mode.`,
-    job: `Manage GitHub-backed durable jobs.
+    job: `Manage SQLite-authoritative durable jobs.
 
 Usage:
   npx agents-relay job <create|update|show|list|merge|unblock|cancel> [options]
@@ -34,7 +36,7 @@ Actions:
   update  Partially update mutable metadata on a healthy existing Job
   show    Show one durable Job
   list    List managed Jobs in a repository
-  merge   Merge the backing PR and complete the Job
+  merge   Queue a retryable external PR merge; Graph completes the Job only after confirmation
   unblock Authoritatively invalidate current BLOCKED decisions and trigger replanning/resume
   cancel  Close the backing PR and cancel the Job
 
@@ -54,20 +56,20 @@ When provided, --thread-id persists a reviewer destination; otherwise the Job re
 
 Required: --repo OWNER/REPO --pr NUMBER --id JOB_ID.
 Optional: --thread-id THREAD_ID persists a reviewer override; omitted uses Job reviewer/creator thread or legacy route. Rejects pending reviews and wakes managed reconciliation.`,
-    'job create': `Create a durable Job and its trusted marker.
+    '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 existing unmanaged PR.
-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.
-Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --project-path RELATIVE_PATH, --priority, --mode fixed|autonomous, --schedule, --tag JSON, --auto-merge|--no-auto-merge, --review|--no-review, --reviewer-thread-id ID, --creator-thread-id ID, and continuation options. Updating the objective also updates the PR body.
-Unspecified fields are preserved. Marker/binding corruption is never repaired implicitly; update fails with a precise diagnostic instead.
+Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --project-path RELATIVE_PATH, --priority, --mode fixed|autonomous, --schedule, --tag JSON, --auto-merge|--no-auto-merge, --review|--no-review, --reviewer-thread-id ID, --creator-thread-id ID, and continuation options. The objective updates local SQLite; PR body changes are independent external actions.
+Unspecified fields are preserved. Local Job/PR identity mismatch is rejected.
 
 Example:
   npx agents-relay job update --repo OWNER/REPO --pr 12 --id job-1 --priority P0 --no-auto-merge`,
@@ -83,7 +85,7 @@ Required: --repo OWNER/REPO.
 
 Example:
   npx agents-relay job list --repo OWNER/REPO`,
-    'job merge': `Merge the backing pull request and complete the durable Job.
+    'job merge': `Request an idempotent external pull-request merge; return QUEUED until confirmed, when the Graph Engine completes the Job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. The current PR head SHA is pinned into the merge request.`,
     'job unblock': `Authoritatively unblock the effective BLOCKED work Tasks in one Job.\n\nRequired: --repo OWNER/REPO --pr NUMBER --id JOB_ID --reason TEXT. Autonomous Jobs transition blocked work to historical UNBLOCKED state and wake Planner with unblock facts as Plan trigger/context; fixed Jobs record UNBLOCKED first and then resume according to fixed-job retry semantics.`,
@@ -142,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.`,
@@ -214,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:
@@ -222,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
@@ -232,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

@@ -0,0 +1,77 @@
+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';
+/**
+ * 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 requestedNumber = options.prNumber ?? 0;
+    if (!Number.isInteger(requestedNumber) || requestedNumber < 0)
+        throw new Error('Invalid external PR binding number');
+    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 ?? join(homedir(), '.agents-relay', 'stores');
+    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 !== requestedNumber))
+            throw new Error('Immutable Job ID is already bound to a different repository or external PR');
+        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,
+    });
+    try {
+        const existing = await local.relay.loadJob(options.id);
+        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',
+            objective: options.objective || pr.body || undefined,
+            projectPath: options.projectPath,
+            description: pr.body || undefined,
+            priority: options.priority ?? 'P2',
+            executionMode: options.executionMode ?? 'fixed',
+            tag: options.tag,
+            autoMerge: true,
+            ...(localMergeSource && localMergeTarget ? { localMerge: { sourceRef: localMergeSource, targetRef: localMergeTarget, status: 'pending' } } : {}),
+            reviewEnabled: options.reviewEnabled ?? true,
+            ...(options.reviewerThreadId
+                ? { reviewerThreadId: normalizeThreadId(options.reviewerThreadId, 'reviewer thread ID') }
+                : {}),
+            ...(options.creatorThreadId
+                ? { creatorThreadId: normalizeThreadId(options.creatorThreadId, 'creator thread ID') }
+                : {}),
+            prNumber: pr.number,
+            repository: repositoryName,
+            continuation: options.continuation ?? null,
+            createdAt: now,
+            updatedAt: now,
+            tasks: [],
+            ...(options.schedule ? { schedule: options.schedule } : {}),
+        }, { activate: Boolean(options.schedule) });
+        await local.store.saveJob(job);
+        return { job: await local.store.load(options.id), pr };
+    }
+    finally {
+        local.relay.close();
+    }
+}

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

@@ -0,0 +1,11 @@
+export function configureLocalGitMerge(job, source, target, localOnly) {
+    // The GitHub integration is observational; local merge applies in either mode.
+    void localOnly;
+    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`;
 }