agents-relay 2.0.92 → 2.0.94

package/README.md

@@ -58,7 +58,7 @@ These paths always represent the current canonical graphs. Historical graph defi
 
 ## Quick start
 
-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.
+For new work, create a local Job through Agents Relay. Use `job adopt` to bind a known legacy PR number without GitHub access; the external GitHub projection creates a display PR after the first meaningful code commit. Tasks are validated against the SQLite Job, not GitHub markers.
 
 ~~~sh
 cat > job.md <<'EOF'
@@ -67,7 +67,7 @@ cat > job.md <<'EOF'
 Standalone Job context. Put a Mermaid block first when a workflow/state/architecture diagram helps.
 EOF
 
-npx agents-relay job create --repo OWNER/REPO --head feat/example --base main \
+npx agents-relay job create --repo OWNER/REPO \
   --id job-1 --title "Objective" --objective-file job.md --mode fixed
 
 # The orchestrator decides the initial batch separately
@@ -76,10 +76,10 @@ cat > task.md <<'EOF'
 
 Implement this phase using the Job objective as context.
 EOF
-npx agents-relay task create --repo OWNER/REPO --pr 12 --id job-1 \
+npx agents-relay task create --repo OWNER/REPO --id job-1 \
   --task-id initial --output task-pr --input-file task.md
 
-npx agents-relay task create --repo OWNER/REPO --pr 12 --id job-1 \
+npx agents-relay task create --repo OWNER/REPO --id job-1 \
   --task-id child --output task-pr \
   --input "Implement the described child task and publish a terminal event."
 
@@ -142,12 +142,12 @@ Autonomous jobs can also be scheduled. The Job marker stores a five-field cron e
 [Scheduled autonomous jobs](docs/scheduled-autonomous-jobs.md) for the exact
 operational contract.
 
-job create first resolves an existing open PR with the same head/base, then creates it only when needed. Re-running it is idempotent: it reuses the PR and maintains exactly one trusted agents-relay:job:v1 marker. Job creation is always create-only and always enables auto-merge; `--no-auto-merge` is not a `job create` option. Existing Jobs can still change that setting with `job update`. Task execution options belong to `task create`, and the orchestrator may create zero, one, or multiple initial Tasks according to user intent.
+GitHub projection creates or reuses a display PR after a meaningful source-branch commit; `job adopt` is reserved for existing legacy PR bindings. Re-running it is idempotent: it reuses the PR and maintains exactly one trusted agents-relay:job:v1 marker. Job creation is always create-only and always enables auto-merge; `--no-auto-merge` is not a `job create` option. Existing Jobs can still change that setting with `job update`. Task execution options belong to `task create`, and the orchestrator may create zero, one, or multiple initial Tasks according to user intent.
 
-To create a Job on an existing unmanaged PR, use the same `job create` action with `--pr` instead of `--head`:
+To create a Job on an existing unmanaged PR, use the explicit `job adopt` compatibility action:
 
 ~~~sh
-npx agents-relay job create --repo OWNER/REPO --pr 6 --id job-6 --title "Existing objective"
+npx agents-relay job adopt --repo OWNER/REPO --pr 6 --id job-6 --title "Existing objective"
 ~~~
 
 Use `job update` for partial mutable metadata changes on an already healthy Job marker/binding:

package/dist/cli-help.js

@@ -56,15 +56,17 @@ 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 SQLite-authoritative Job.
+    'job create': `Create a SQLite-authoritative Job (objective-only).
 
-Required: --repo OWNER/REPO and a standalone Job objective (unless binding an existing PR). Job ID defaults to an auto-incrementing repository-scoped number; --id is optional for compatibility.
-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. Without either, create a local-first content Job; local Job completion still follows the configured Graph lifecycle.
-Common: --id JOB_ID (optional), --idempotency-key KEY (for retries), --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, --implementation-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.
+Required: --repo OWNER/REPO and a standalone Job objective. Job ID defaults to an auto-incrementing repository-scoped number; --id is optional for compatibility. Existing PR adoption is an explicit separate command: job adopt.
+Common: --id JOB_ID (optional), --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, --implementation-thread-id ID. --objective and --objective-file are mutually exclusive.
+Job creation always enables auto-merge. By default it is create-only; --initial-plan validates the first real Planner round before atomically creating the durable Job and Plan, then 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 --project-path vlog --title "Episode" --objective-file episode.md --idempotency-key submission-123 --initial-plan`,
+  npx agents-relay job create --repo OWNER/REPO --project-path vlog --title "Episode" --objective-file episode.md --initial-plan`,
+    'job adopt': `Adopt an existing legacy PR as a SQLite-authoritative Job.
+
+Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. This is the only creation path that binds an existing PR.`,
     'job update': `Partially update mutable metadata on a healthy existing Job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.

package/dist/cli-job-create.js

@@ -4,8 +4,9 @@ import { createJobEntity } from './workflow/entity-creation.js';
 import { normalizeThreadId } from './reviewer-thread.js';
 import { discoverLocalRelayStoreSnapshots, relayStoreDirectory } from './relay-store.js';
 /**
- * Job lifecycle bootstrap: SQLite is authoritative. No GitHub request is
- * required; an explicit PR number is optional external metadata.
+ * Ordinary Job creation is local and objective-oriented. Legacy PR metadata is
+ * handled by adoptLegacyJob below so the normal contract cannot accidentally
+ * create a second external lifecycle.
  */
 export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAuthors, options) {
     const directory = options.storeDirectory ?? relayStoreDirectory();
@@ -46,7 +47,6 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
             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,
             title: options.title || pr.title || 'Agents Relay job',
@@ -57,7 +57,7 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
             executionMode: options.executionMode ?? 'fixed',
             tag: options.tag,
             autoMerge: true,
-            ...(localMergeSource && localMergeTarget ? { localMerge: { sourceRef: localMergeSource, targetRef: localMergeTarget, status: 'pending' } } : {}),
+            ...(localMergeSource ? { localMerge: { sourceRef: localMergeSource, targetRef: 'refs/heads/main', status: 'pending' } } : {}),
             reviewEnabled: options.reviewEnabled ?? true,
             ...(options.reviewerThreadId
                 ? { reviewerThreadId: normalizeThreadId(options.reviewerThreadId, 'reviewer thread ID') }
@@ -76,8 +76,43 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
             tasks: [],
             ...(options.schedule ? { schedule: options.schedule } : {}),
         }, { activate: Boolean(options.schedule) });
-        await local.store.saveJob(job);
-        return { job: await local.store.load(id), pr };
+        if (options.persist !== false) {
+            if (local.store.createJobIfAbsent)
+                await local.store.createJobIfAbsent(job);
+            else
+                await local.store.saveJob(job);
+        }
+        return { job: options.persist === false ? job : await local.store.load(id), pr };
+    }
+    finally {
+        local.relay.close();
+    }
+}
+/** Explicit compatibility path for adopting an already-existing PR. */
+export async function adoptLegacyJob(_client, repositoryName, _trustedAuthors, options) {
+    if (!options.id || !Number.isInteger(options.prNumber) || options.prNumber <= 0)
+        throw new Error('job adopt requires --id and a positive --pr');
+    const directory = options.storeDirectory ?? relayStoreDirectory();
+    const matches = (await discoverLocalRelayStoreSnapshots(directory)).flatMap(snapshot => snapshot.jobs).filter(job => job.id === options.id);
+    if (matches.length > 1)
+        throw new Error(`Ambiguous existing immutable Job ID ${options.id}`);
+    if (matches.length === 1) {
+        const existing = matches[0];
+        if (existing.repository !== repositoryName || existing.prNumber !== options.prNumber)
+            throw new Error(`Job ID ${options.id} is already bound to another repository or PR`);
+        return { job: existing, pr: { number: existing.prNumber, title: existing.title, body: existing.objective ?? '', state: 'OPEN', head: '', base: 'main' } };
+    }
+    const local = openLocalManagedStore(repositoryName, options.prNumber, { directory, jobId: options.id, noGitHub: true });
+    try {
+        const existing = await local.relay.loadJob(options.id);
+        if (existing)
+            return { job: existing, pr: { number: existing.prNumber, title: existing.title, body: existing.objective ?? '', state: 'OPEN', head: '', base: '' } };
+        const now = new Date().toISOString();
+        const job = createJobEntity({ id: options.id, title: options.title ?? options.id, objective: options.objective, projectPath: options.projectPath,
+            description: options.objective, priority: 'P2', executionMode: 'fixed', autoMerge: true, reviewEnabled: true,
+            prNumber: options.prNumber, repository: repositoryName, continuation: null, createdAt: now, updatedAt: now, tasks: [] });
+        const created = local.store.createJobIfAbsent ? await local.store.createJobIfAbsent(job) : (await local.store.saveJob(job), job);
+        return { job: created, pr: { number: options.prNumber, title: created.title, body: created.objective ?? '', state: 'OPEN', head: '', base: 'main' } };
     }
     finally {
         local.relay.close();

package/dist/cli.js

@@ -23,7 +23,7 @@ import { applyJobActivateAction, applyJobCancelAction } from './job-actions.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { startServiceExternalActionFlusher } from './service-external-actions.js';
 import { handleServicePublication } from './service-publication.js';
-import { defaultWorkspaceRoot, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
+import { defaultWorkspaceRoot, ensureLocalJobSourceBranch, jobRequiresManagedWorktree, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
 import { runBlockerCommand } from './cli-blocker.js';
 import { runEscalationCommand } from './cli-escalation.js';
 import { runProjectionCommand } from './cli-projection.js';
@@ -363,7 +363,7 @@ async function runContextCommand(action, args) {
     console.log(JSON.stringify(context, null, 2));
 }
 async function runJobCommand(action, args) {
-    if (!['create', 'update', 'show', 'list', 'merge', 'unblock', 'cancel'].includes(action))
+    if (!['create', 'adopt', 'update', 'show', 'list', 'merge', 'unblock', 'cancel'].includes(action))
         throw new Error(usage);
     const repo = repository(args);
     let createObjective;
@@ -375,8 +375,23 @@ async function runJobCommand(action, args) {
         if (invalid)
             throw new Error(`job create does not accept task execution option ${invalid}; create the job first, then let the orchestrator create the initial plan/task batch`);
         createObjective = await textOption(args, '--objective', '--objective-file');
-        if ((!arg(args, '--pr') || noGitHubMode(args)) && !createObjective.trim())
-            throw new Error('job create with --head requires --objective-file PATH|- or --objective MARKDOWN containing the complete standalone Job context');
+        if (!createObjective.trim())
+            throw new Error('job create requires --objective-file PATH|- or --objective MARKDOWN containing the complete standalone Job context');
+        const legacy = ['--pr', '--head', '--base', '--body', '--local-merge-source', '--local-merge-target', '--idempotency-key'].find(flag => hasArg(args, flag));
+        if (legacy)
+            throw new Error(`job create does not accept ${legacy}; use job adopt only for existing PR bindings`);
+    }
+    if (action === 'adopt') {
+        const adoptId = arg(args, '--id');
+        const adoptPr = Number(arg(args, '--pr'));
+        if (!adoptId || !Number.isInteger(adoptPr) || adoptPr <= 0)
+            throw new Error('job adopt requires --id and a positive --pr');
+        const objective = await textOption(args, '--objective', '--objective-file');
+        const result = await relayControlCommand(args, { command: 'job.adopt', repository: repo, options: {
+                id: adoptId, prNumber: adoptPr, title: arg(args, '--title') || undefined, objective: objective || undefined, projectPath: arg(args, '--project-path') || undefined,
+            } });
+        console.log(JSON.stringify(result, null, 2));
+        return;
     }
     if (action === 'list') {
         console.log(JSON.stringify(await relayJobList(args), null, 2));
@@ -397,8 +412,6 @@ async function runJobCommand(action, args) {
                 id: id || undefined, idempotencyKey: arg(args, '--idempotency-key') || undefined, title: arg(args, '--title') || undefined, objective: objective || undefined, projectPath: arg(args, '--project-path') || undefined,
                 priority: priority(args), executionMode: requestedExecutionMode(args), schedule: scheduleFromArgs(args), tag: jobTagFromArgs(args), reviewEnabled: !hasArg(args, '--no-review'), continuation: continuation(args),
                 reviewerThreadId: hasArg(args, '--reviewer-thread-id') ? arg(args, '--reviewer-thread-id') : undefined, creatorThreadId: hasArg(args, '--creator-thread-id') ? arg(args, '--creator-thread-id') : undefined, implementationThreadId: hasArg(args, '--implementation-thread-id') ? arg(args, '--implementation-thread-id') : undefined,
-                prNumber, head: arg(args, '--head') || undefined, base: arg(args, '--base', 'main'), body: arg(args, '--body') || objective || undefined,
-                localMergeSource: arg(args, '--local-merge-source') || undefined, localMergeTarget: arg(args, '--local-merge-target') || undefined,
             } });
         console.log(JSON.stringify(result, null, 2));
         return;
@@ -478,7 +491,25 @@ async function runJobCommand(action, args) {
     console.log(JSON.stringify(await relayControlCommand(args, { command: 'job.update', jobId: id, patch }), null, 2));
 }
 export function runtimePlanner(args) { const plannerCommand = arg([...args], '--planner-command'); const modelRuntime = arg([...args], '--codex', 'codex'); return plannerCommand ? new CommandObjectivePlanner(plannerCommand) : new AgentObjectivePlanner(modelRuntime); }
-export function runtime(store, args, bus, usageRegistry = codexAndZaiUsageRegistry()) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const policy = chatGptTabClosePolicy(args); const planner = runtimePlanner(args); return new Reconciler(store, { noGitHub: noGitHubMode(args), owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, usageSnapshotProvider: () => usageRegistry.snapshot(), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), reviewer: runtimeReviewer(args), eventBus: bus, emit, chatgptTabClosePolicy: policy, projectPathForJob: async (job) => { const workspaceRoot = arg(args, '--workspace-root') || defaultWorkspaceRoot(); const canonical = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : job.repository, arg(args, '--project-path'), workspaceRoot); return job.prNumber === 0 && job.localMerge?.sourceRef ? prepareLocalJobExecutionWorktree(canonical, job, workspaceRoot) : resolveRepositoryProjectPath(canonical, job.projectPath); } }); }
+export function runtime(store, args, bus, usageRegistry = codexAndZaiUsageRegistry()) {
+    const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); };
+    const modelRuntime = arg(args, '--codex', 'codex');
+    const policy = chatGptTabClosePolicy(args);
+    const planner = runtimePlanner(args);
+    return new Reconciler(store, { noGitHub: noGitHubMode(args), owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, usageSnapshotProvider: () => usageRegistry.snapshot(), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), reviewer: runtimeReviewer(args), eventBus: bus, emit, chatgptTabClosePolicy: policy, projectPathForJob: async (job) => {
+            const workspaceRoot = arg(args, '--workspace-root') || defaultWorkspaceRoot();
+            const canonical = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : job.repository, arg(args, '--project-path'), workspaceRoot);
+            if (!jobRequiresManagedWorktree(job))
+                return resolveRepositoryProjectPath(canonical, job.projectPath);
+            const sourceRef = await ensureLocalJobSourceBranch(canonical, job);
+            if (!job.localMerge?.sourceRef) {
+                if (!store.mutateJob)
+                    throw new Error('Managed worktree requires atomic SQLite Job mutation');
+                await store.mutateJob(job.id, current => current.localMerge ? current : ({ ...current, localMerge: { sourceRef, targetRef: 'refs/heads/main', status: 'pending' }, updatedAt: new Date().toISOString() }));
+            }
+            return prepareLocalJobExecutionWorktree(canonical, await store.load(job.id), workspaceRoot);
+        } });
+}
 export function dashboardJobAction(store, reconciler, action) {
     return async (jobId) => {
         const job = await store.load(jobId);

package/dist/local-authority-store.js

@@ -221,6 +221,15 @@ export class LocalAuthorityDurableStore {
             return job;
         });
     }
+    async createJobIfAbsent(job) {
+        if (this.authority.createJobIfAbsent)
+            return this.authority.createJobIfAbsent(job);
+        const existing = await this.authority.loadJob(job.id);
+        if (existing)
+            return existing;
+        await this.authority.saveJob(job);
+        return structuredClone(job);
+    }
     async savePlan(plan) {
         await this.mutate(plan.jobId, job => {
             const plans = [...(job.plans ?? [])];

package/dist/projected-store.js

@@ -81,11 +81,13 @@ export class GitHubProjectionWriter {
     github;
     onConflict;
     externalOnly;
-    constructor(relay, github, onConflict, externalOnly = false) {
+    externalEffect;
+    constructor(relay, github, onConflict, externalOnly = false, externalEffect) {
         this.relay = relay;
         this.github = github;
         this.onConflict = onConflict;
         this.externalOnly = externalOnly;
+        this.externalEffect = externalEffect;
     }
     async flushOnce(limit = 50, now = new Date()) {
         const items = await this.relay.claimDueProjections(limit, now);
@@ -93,7 +95,7 @@ export class GitHubProjectionWriter {
         let deferred = 0;
         for (const item of items) {
             try {
-                if (this.externalOnly && !['merge_pull_request', 'close_pull_request', 'update_pr_body'].includes(item.operation)) {
+                if (this.externalOnly && !['merge_pull_request', 'close_pull_request', 'update_pr_body', 'create_pull_request'].includes(item.operation)) {
                     // Drop legacy lifecycle projections; GitHub may not override SQLite truth.
                     await this.relay.completeProjection(item.id);
                     continue;
@@ -110,6 +112,7 @@ export class GitHubProjectionWriter {
                     });
                 }
                 await this.relay.completeProjection(item.id);
+                await this.relay.recordProjectionReceipt?.(item.operationKey, 'succeeded', item.attempts, { operation: item.operation });
                 projected += 1;
                 observability().record({
                     stage: 'projection', event: 'projection.completed', outcome: 'succeeded',
@@ -135,6 +138,7 @@ export class GitHubProjectionWriter {
                 else {
                     const retryAt = githubProjectionRetryAt(error, item.attempts, now);
                     await this.relay.retryProjection(item.id, message, retryAt);
+                    await this.relay.recordProjectionReceipt?.(item.operationKey, 'failed', item.attempts + 1, { operation: item.operation, error: message });
                     deferred += 1;
                     observability().record({
                         stage: 'projection', event: 'projection.retry_scheduled', level: 'warn', outcome: 'failed',
@@ -157,6 +161,12 @@ export class GitHubProjectionWriter {
         }
     }
     async apply(item) {
+        if (item.operation === 'create_pull_request') {
+            if (!this.externalEffect)
+                throw new Error('GitHub PR creation effect is unavailable');
+            await this.externalEffect(item);
+            return;
+        }
         const payload = item.payload;
         switch (payload.operation) {
             case 'save_job':

package/dist/projection-outbox.js

@@ -87,6 +87,15 @@ export class ProjectionOutbox {
       CREATE INDEX IF NOT EXISTS projection_coalesce_idx ON projection_outbox(coalesce_key, status);
     `;
     }
+    static createReceiptTableSql() {
+        return `CREATE TABLE IF NOT EXISTS projection_receipt (
+      operation_key TEXT PRIMARY KEY,
+      status TEXT NOT NULL CHECK(status IN ('succeeded','failed')),
+      attempts INTEGER NOT NULL,
+      detail_json TEXT,
+      recorded_at TEXT NOT NULL
+    );`;
+    }
     /** Rebuild a pre-v5 outbox, backfill logical operation keys, and classify legacy dead conflicts. */
     static upgrade(db, previousVersion) {
         const schema = db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='projection_outbox'").get();
@@ -220,6 +229,11 @@ export class ProjectionOutbox {
       WHERE id=?
     `).run(error, new Date().toISOString(), id);
     }
+    recordReceipt(operationKey, status, attempts, detail, now) {
+        this.db.prepare(`INSERT INTO projection_receipt(operation_key,status,attempts,detail_json,recorded_at)
+      VALUES(?,?,?,?,?) ON CONFLICT(operation_key) DO UPDATE SET status=excluded.status, attempts=excluded.attempts,
+      detail_json=excluded.detail_json, recorded_at=excluded.recorded_at`).run(operationKey, status, attempts, JSON.stringify(detail ?? null), now);
+    }
     recordConflict(id, diagnostic) {
         const evidence = JSON.stringify({
             kind: diagnostic.kind,

package/dist/relay-create.js

@@ -0,0 +1,18 @@
+import { normalizeLegacyJobPrNumber } from './job-pr-number-migration.js';
+export function createJobIfAbsent(db, job) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const row = db.prepare('SELECT json FROM job_snapshot WHERE job_id=?').get(job.id);
+        if (row?.json) {
+            db.exec('COMMIT');
+            return normalizeLegacyJobPrNumber(JSON.parse(row.json));
+        }
+        db.prepare('INSERT INTO job_snapshot(job_id,json,updated_at) VALUES(?,?,?)').run(job.id, JSON.stringify(job), new Date().toISOString());
+        db.exec('COMMIT');
+        return structuredClone(job);
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}

package/dist/relay-store.js

@@ -5,6 +5,7 @@ import { mkdirSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { recordPublicationInDatabase, loadPublicationFromDatabase, listPublicationEventsFromDatabase } from './publication-store.js';
 import { observability } from './observability.js';
+import { createJobIfAbsent } from './relay-create.js';
 import { migrateLegacyJobPrNumbers, normalizeLegacyJobPrNumber } from './job-pr-number-migration.js';
 import { hostInvocationTablesSql, recordHostInvocationEvent, hasHostInvocationDecision, recordHostInvocationDecision } from './host-invocation-store.js';
 import { ProjectionOutbox, SCHEMA_VERSION, logicalOperationKey, } from './projection-outbox.js';
@@ -101,6 +102,7 @@ export class SQLiteRelayStore {
       );
       ${hostInvocationTablesSql}
       ${ProjectionOutbox.createTableSql()}
+      ${ProjectionOutbox.createReceiptTableSql()}
       ${ProjectionOutbox.createIndexSql()}
     `);
         migrateLegacyJobPrNumbers(this.db);
@@ -133,6 +135,9 @@ export class SQLiteRelayStore {
     async saveJob(job) {
         this.writeJobSnapshot(job, new Date().toISOString());
     }
+    async createJobIfAbsent(job) {
+        return createJobIfAbsent(this.db, job);
+    }
     /** Atomic read/modify/write for local authoritative Task and Plan updates. */
     async mutateJob(jobId, mutation) {
         this.db.exec('BEGIN IMMEDIATE');
@@ -343,13 +348,13 @@ export class SQLiteRelayStore {
      * must never reset backoff or queue a second merge while a first one runs.
      */
     async enqueueExternalActionOnce(request) {
-        if (!['merge_pull_request', 'close_pull_request', 'update_pr_body'].includes(request.operation)) {
+        if (!['merge_pull_request', 'close_pull_request', 'update_pr_body', 'create_pull_request'].includes(request.operation)) {
             throw new Error('Lifecycle projection is forbidden in external-only outbox');
         }
         const key = logicalOperationKey(request.idempotencyKey);
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            const existing = this.db.prepare('SELECT id FROM projection_outbox WHERE operation_key=? LIMIT 1').get(key);
+            const existing = this.db.prepare('SELECT id FROM projection_outbox WHERE operation_key=? LIMIT 1').get(key) ?? this.db.prepare('SELECT operation_key FROM projection_receipt WHERE operation_key=?').get(key);
             if (existing) {
                 this.db.exec('COMMIT');
                 return false;
@@ -375,6 +380,7 @@ export class SQLiteRelayStore {
     async conflictProjectionCount() { return this.outbox.conflictCount(); }
     async pendingProjectionCount() { return this.outbox.pendingCount(); }
     async terminalProjectionCount() { return this.outbox.terminalCount(); }
+    async recordProjectionReceipt(operationKey, status, attempts, detail) { this.outbox.recordReceipt(operationKey, status, attempts, detail, new Date().toISOString()); }
     close() { this.db.close(); }
 }
 /** Canonical on-disk Relay Store location for one managed GitHub pull request. */

package/dist/relayd-control.js

@@ -1,6 +1,10 @@
 import { appendTaskComment } from './task-comments.js';
+import { InMemoryStore } from './store.js';
+import { openLocalManagedStore } from './local-managed-store.js';
+import { relayStoreDirectory } from './relay-store.js';
 import { normalizeThreadId } from './reviewer-thread.js';
 import { supersedeCancelledTask } from './task-actions.js';
+import { adoptLegacyJob } from './cli-job-create.js';
 export function createWorkspaceControl(deps) {
     const { client, trusted, noGitHub, repositories, refreshAll, requireLocalJobBinding, makeReconciler, concurrency, pool, bus, isEffectivelyBlocked, unblockAutonomousTasks, unblockTask, publishTaskUnblocked, dispatchTaskAction, registerBlockerDependency, discoverAgents, ensureManagedGitHubJob } = deps;
     const workspaceControl = async (body) => {
@@ -25,31 +29,36 @@ export function createWorkspaceControl(deps) {
                 tag: options.tag,
                 reviewEnabled: typeof options.reviewEnabled === 'boolean' ? options.reviewEnabled : undefined,
                 continuation: options.continuation,
-                prNumber: typeof options.prNumber === 'number' ? options.prNumber : undefined,
-                head: typeof options.head === 'string' ? options.head : undefined,
-                base: typeof options.base === 'string' ? options.base : undefined,
-                body: typeof options.body === 'string' ? options.body : undefined,
                 reviewerThreadId: typeof options.reviewerThreadId === 'string' ? options.reviewerThreadId : undefined,
                 creatorThreadId: typeof options.creatorThreadId === 'string' ? options.creatorThreadId : undefined,
                 implementationThreadId: typeof options.implementationThreadId === 'string' ? options.implementationThreadId : undefined,
                 noGitHub,
-                localMergeSource: typeof options.localMergeSource === 'string' ? options.localMergeSource : undefined,
-                localMergeTarget: typeof options.localMergeTarget === 'string' ? options.localMergeTarget : undefined,
+                persist: body.initialPlan !== true,
             });
             if (!repositories.includes(repository))
                 repositories.push(repository);
             await refreshAll();
             if (body.initialPlan === true) {
-                const binding = await requireLocalJobBinding(result.job.id);
-                const current = await binding.store.load(result.job.id);
+                const current = result.job;
                 const existingPlan = current.plans?.at(-1);
                 if (existingPlan)
                     return { repository, pr: result.pr.number, job: current.id, executionMode: current.executionMode, state: current.state, initialPlan: existingPlan.id, reused: true };
-                const reconciler = makeReconciler(binding.store, concurrency);
+                const unpublished = new InMemoryStore(current);
+                const reconciler = makeReconciler(unpublished, concurrency);
                 try {
                     const planned = await reconciler.planJob(result.job.id);
+                    const unpublishedStore = openLocalManagedStore(repository, 0, { directory: relayStoreDirectory(), jobId: result.job.id, noGitHub: true });
+                    let committed = planned.job;
+                    try {
+                        committed = unpublishedStore.store.createJobIfAbsent
+                            ? await unpublishedStore.store.createJobIfAbsent(planned.job)
+                            : (await unpublishedStore.store.saveJob(planned.job), planned.job);
+                    }
+                    finally {
+                        unpublishedStore.relay.close();
+                    }
                     await pool.reconcileLocalJob(result.job.id, 'control.job.create.initial-plan');
-                    return { repository, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state, initialPlan: planned.round.id };
+                    return { repository, pr: committed.prNumber, job: committed.id, executionMode: committed.executionMode, state: committed.state, initialPlan: committed.plans?.at(-1)?.id };
                 }
                 finally {
                     await reconciler.close();
@@ -57,6 +66,22 @@ export function createWorkspaceControl(deps) {
             }
             return { repository, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state };
         }
+        if (command === 'job.adopt') {
+            const repository = typeof body.repository === 'string' ? body.repository : '';
+            const options = (body.options && typeof body.options === 'object' ? body.options : {});
+            if (!repository || typeof options.id !== 'string' || typeof options.prNumber !== 'number')
+                throw new Error('job.adopt requires repository, id, and prNumber');
+            const result = await adoptLegacyJob(client, repository, trusted, {
+                id: options.id, title: typeof options.title === 'string' ? options.title : undefined,
+                objective: typeof options.objective === 'string' ? options.objective : undefined,
+                projectPath: typeof options.projectPath === 'string' ? options.projectPath : undefined,
+                prNumber: options.prNumber,
+            });
+            if (!repositories.includes(repository))
+                repositories.push(repository);
+            await refreshAll();
+            return { repository, pr: result.pr.number, job: result.job.id, state: result.job.state };
+        }
         if (!jobId)
             throw new Error(command + ' requires jobId');
         const binding = await requireLocalJobBinding(jobId);

package/dist/relayd.js

@@ -34,7 +34,7 @@ import { applyJobActivateAction } from './job-actions.js';
 import { managedTaskUpdateHandler } from './task-update.js';
 import { dashboardJobSetState, dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
-import { defaultWorkspaceRoot, discoverWorkspaceRepositories, ensureLocalJobSourceBranch, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
+import { defaultWorkspaceRoot, discoverWorkspaceRepositories, ensureLocalJobSourceBranch, jobRequiresManagedWorktree, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
 import { deriveJobRuntimeStatus } from './runtime-status.js';
 import { createRuntimeStatusPublisher } from './runtime-status-events.js';
 import { subscribeLocalCommits } from './local-commit-events.js';
@@ -154,7 +154,7 @@ export async function runDaemon(argv) {
     cachedOverviews = await inventoryFromLocal();
     const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { noGitHub, owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter()], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), usageSnapshotProvider: () => usageRegistry.snapshot(), runtimeSummaryProvider: () => ({ chatgptRunning: summarizeRuntime(cachedOverviews.map(item => item.job)).workers.chatgpt }), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), decisionAuditStore, eventBus: bus, reviewer: runtimeReviewer(argv), projectPathForJob: async (job) => {
             const canonical = repositoryPaths.get(job.repository) ?? await resolveManagedProjectPath(job.repository, explicitProjectPath, workspaceRoot);
-            if (!job.localMerge?.sourceRef || job.schedule)
+            if (!jobRequiresManagedWorktree(job))
                 return resolveRepositoryProjectPath(canonical, job.projectPath);
             const sourceRef = await ensureLocalJobSourceBranch(canonical, job);
             if (!store.mutateJob)
@@ -244,62 +244,69 @@ export async function runDaemon(argv) {
                 if (discovered.state === 'COMPLETED' && discovered.localMerge?.status === 'succeeded'
                     && discovered.prNumber <= 0) {
                     const published = projectAuthoritativeLocalMerge(canonical, discovered);
+                    if (relay.mutateJob && (discovered.githubProjection?.status !== 'merged_without_pr' || discovered.githubProjection.sourceSha !== published.localMergedCommitSha))
+                        await relay.mutateJob(discovered.id, current => ({ ...current, githubProjection: { status: 'merged_without_pr', sourceSha: published.localMergedCommitSha, observedAt: new Date().toISOString() } }));
                     if (published.status === 'projected')
                         await bus?.publish(eventFor(discovered.id, 'projection', null, 'projection.delivered', 'succeeded', `GitHub main synchronization ${published.status}`, 'orchestrator', { operation: 'github.syncMain', deliveryStatus: published.status, mergedCommitSha: published.localMergedCommitSha }, { agent: 'relay', component: 'github-projection' }));
                     continue;
                 }
                 const existingPrNumber = discovered.prNumber > 0 ? discovered.prNumber : 0;
                 const terminal = ['COMPLETED', 'CANCELLED'].includes(discovered.state);
-                if (terminal && existingPrNumber <= 0)
-                    continue;
                 const sourceSha = await gitText(canonical, ['rev-parse', '--verify', sourceRef]).catch(() => '');
                 if (!sourceSha)
                     continue;
-                const facts = await relay.loadPullRequestFacts();
-                if (facts?.head?.sha !== sourceSha) {
-                    await gitText(canonical, ['fetch', '--no-tags', 'origin',
-                        '+refs/heads/main:refs/remotes/origin/main']);
-                    await gitText(canonical, ['fetch', '--no-tags', 'origin',
-                        `+refs/heads/${branch}:refs/remotes/origin/${branch}`]).catch(() => '');
-                    const remoteRef = `refs/remotes/origin/${branch}`;
-                    const remoteHeadSha = await gitText(canonical, ['rev-parse', '--verify', remoteRef]).catch(() => '');
-                    const remoteTreeMatchesBase = remoteHeadSha
-                        ? await gitText(canonical, ['diff', '--quiet', 'refs/remotes/origin/main', remoteRef]).then(() => true, () => false)
-                        : false;
-                    await gitText(canonical, authoritativeBranchPushArgs({
-                        sourceRef,
-                        branch,
-                        remoteHeadSha: remoteHeadSha || null,
-                        remoteTreeMatchesBase,
-                    }));
-                }
                 let job = (await relay.loadJob(discovered.id)) ?? discovered;
                 let prNumber = job.prNumber > 0 ? job.prNumber : 0;
-                if (prNumber === 0 && ['COMPLETED', 'CANCELLED'].includes(job.state))
-                    continue;
                 if (prNumber === 0) {
                     // Do not bootstrap an empty remote-only PR commit: it would diverge from
                     // the real local Job branch before its first Worker commit. Publish the
                     // review-only PR when there is an actual diff against main.
                     const ahead = Number(await gitText(canonical, ['rev-list', '--count', `${targetRef}..${sourceRef}`]));
-                    if (!Number.isFinite(ahead) || ahead <= 0)
+                    if (!Number.isFinite(ahead) || ahead <= 0) {
+                        if (terminal && relay.mutateJob && job.githubProjection?.sourceSha !== sourceSha)
+                            await relay.mutateJob(job.id, current => ({ ...current, githubProjection: { status: current.localMerge?.status === 'succeeded' ? 'merged_without_pr' : 'no_diff', sourceSha, observedAt: new Date().toISOString() } }));
                         continue;
+                    }
                     // GitHub compares origin/main, not local main. Do not invoke the legacy
                     // empty-PR bootstrap path when the published base already contains the
                     // source head (for example when main was pushed by another Job).
                     await gitText(canonical, ['fetch', '--no-tags', 'origin', `+refs/heads/main:refs/remotes/origin/main`]);
                     const remoteAhead = Number(await gitText(canonical, ['rev-list', '--count', `refs/remotes/origin/main..${sourceRef}`]));
-                    if (!Number.isFinite(remoteAhead) || remoteAhead <= 0)
+                    if (!Number.isFinite(remoteAhead) || remoteAhead <= 0) {
+                        if (terminal && relay.mutateJob && job.githubProjection?.sourceSha !== sourceSha)
+                            await relay.mutateJob(job.id, current => ({ ...current, githubProjection: { status: 'merged_without_pr', sourceSha, observedAt: new Date().toISOString() } }));
                         continue;
-                    const pr = await resolvePullRequest(client, job.repository, { head: branch, base, title: job.title, body: job.objective ?? job.description ?? '' });
-                    if (!relay.mutateJob)
-                        throw new Error('Atomic SQLite mutation is required for GitHub PR binding');
-                    job = await relay.mutateJob(job.id, current => ({ ...current, prNumber: pr.number, updatedAt: new Date().toISOString() }));
-                    prNumber = pr.number;
-                    observability().record({ stage: 'projection', event: 'github.pr_bound', outcome: 'succeeded', message: `Bound local Job ${job.id} to GitHub PR #${pr.number}`, correlation: { repository: job.repository, prNumber: pr.number, jobId: job.id }, data: { head: branch, base } });
+                    }
+                    const effect = async (item) => {
+                        const payload = item.payload;
+                        await gitText(canonical, ['fetch', '--no-tags', 'origin', `+refs/heads/${payload.base}:refs/remotes/origin/${payload.base}`]);
+                        const remoteRef = `refs/remotes/origin/${payload.head}`;
+                        const remoteHeadSha = await gitText(canonical, ['rev-parse', '--verify', remoteRef]).catch(() => '');
+                        const remoteTreeMatchesBase = remoteHeadSha ? await gitText(canonical, ['diff', '--quiet', `refs/remotes/origin/${payload.base}`, remoteRef]).then(() => true, () => false) : false;
+                        await gitText(canonical, authoritativeBranchPushArgs({ sourceRef: payload.sourceRef, branch: payload.head, remoteHeadSha: remoteHeadSha || null, remoteTreeMatchesBase }));
+                        const pr = await resolvePullRequest(client, payload.repository, { head: payload.head, base: payload.base, title: payload.title, body: payload.body });
+                        if (!relay.mutateJob)
+                            throw new Error('Atomic SQLite mutation is required for GitHub PR binding');
+                        await relay.mutateJob(job.id, current => ({ ...current, prNumber: pr.number, githubProjection: { status: 'pr_bound', sourceSha, observedAt: new Date().toISOString() }, updatedAt: new Date().toISOString() }));
+                        observability().record({ stage: 'projection', event: 'github.pr_bound', outcome: 'succeeded', message: `Bound local Job ${job.id} to GitHub PR #${pr.number}`, correlation: { repository: job.repository, prNumber: pr.number, jobId: job.id }, data: { head: branch, base } });
+                    };
+                    projectionWriters.set(`job:${job.id}`, new GitHubProjectionWriter(relay, new InMemoryStore(job), undefined, true, effect));
+                    if (relay.enqueueExternalActionOnce)
+                        await relay.enqueueExternalActionOnce({ idempotencyKey: `create_pull_request:${job.id}:${sourceSha}`, operation: 'create_pull_request', payload: { operation: 'create_pull_request', repository: job.repository, head: branch, base, title: job.title, body: job.objective ?? job.description ?? '', sourceRef, targetRef }, priority: 100 });
+                    if (terminal)
+                        continue;
+                    continue;
                 }
                 if (prNumber <= 0)
                     continue;
+                if ((await relay.loadPullRequestFacts())?.head?.sha !== sourceSha) {
+                    await gitText(canonical, ['fetch', '--no-tags', 'origin', '+refs/heads/main:refs/remotes/origin/main']);
+                    const remoteRef = `refs/remotes/origin/${branch}`;
+                    await gitText(canonical, ['fetch', '--no-tags', 'origin', `+refs/heads/${branch}:${remoteRef}`]).catch(() => '');
+                    const remoteHeadSha = await gitText(canonical, ['rev-parse', '--verify', remoteRef]).catch(() => '');
+                    const sameTree = remoteHeadSha ? await gitText(canonical, ['diff', '--quiet', 'refs/remotes/origin/main', remoteRef]).then(() => true, () => false) : false;
+                    await gitText(canonical, authoritativeBranchPushArgs({ sourceRef, branch, remoteHeadSha: remoteHeadSha || null, remoteTreeMatchesBase: sameTree }));
+                }
                 const latestFacts = await relay.loadPullRequestFacts();
                 if (latestFacts?.state !== 'MERGED' && (latestFacts?.head?.sha !== sourceSha || latestFacts?.head?.ref !== branch)) {
                     await relay.savePullRequestFacts({ state: latestFacts?.state === 'CLOSED' ? 'CLOSED' : 'OPEN', head: { ref: branch, sha: sourceSha }, observedAt: new Date().toISOString() });

package/dist/workspace.js

@@ -189,6 +189,10 @@ export function managedLocalJobWorktreePath(repository, jobId, workspaceRoot = d
     const digest = createHash('sha256').update(jobId).digest('hex').slice(0, 12);
     return join(workspaceRoot, '.worktrees', 'agents-relay', `${repository.replace('/', '-')}-job-${safeJob}-${digest}`, 'job');
 }
+/** Only code artifacts need an isolated Git source branch and worktree. */
+export function jobRequiresManagedWorktree(job) {
+    return !(job.prNumber > 0) && !job.schedule && (Boolean(job.localMerge?.sourceRef) || job.tasks.some(task => task.output?.kind === 'task_pr'));
+}
 /** Bind an ordinary SQLite Job to one deterministic local work branch.
  * The target is always main, and branch creation never switches the user's checkout.
  * This is a Git-local operation and never needs GitHub credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.92",
+  "version": "2.0.94",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/skills/agents-relay/SKILL.md

@@ -61,7 +61,7 @@ For repository work, create/adopt/repair the PR-backed job through the Agents Re
 Example:
 
 ~~~sh
-npx agents-relay job create --repo OWNER/REPO --head feat/example --base main   --id JOB_ID --title "Objective"
+npx agents-relay job create --repo OWNER/REPO --id JOB_ID --title "Objective" --objective-file job.md --initial-plan
 
 npx agents-relay task create --repo OWNER/REPO --pr 12 --id JOB_ID   --task-id implement   --output task-pr   --input "Implement the requested change, validate it, and update the managed task/PR."
 

package/skills/agents-relay/contracts/task-job-contract.md

@@ -15,7 +15,7 @@ For long-form content, use files instead of shell-quoted arguments:
 
 When creating a new Job from an active discussion, the orchestrator must consolidate **all context needed to finish the Job without the originating thread** into the Job objective before creation. Include, as applicable: goal, relevant background, decisions already made, requirements, constraints, lifecycle/workflow semantics, non-goals, implementation boundaries, acceptance criteria, delivery/review instructions, and any important known issues. Do not create a Job whose objective is only a one-line summary when the discussion contains material implementation context.
 
-For a newly created PR (`job create --head`), standalone objective Markdown is required. The PR body is the single durable Job surface: one hidden `agents-relay:job:v1` marker followed by the objective Markdown. Updating Job metadata or objective updates that same body. New Jobs must not create a separate Job comment that repeats the objective. Readers must remain backward-compatible with legacy Job-comment markers, and a successful Job save may migrate such a legacy marker into the PR body only after validating the replacement before deleting the redundant legacy Job comment.
+Ordinary `job create` requires standalone objective Markdown. An external display PR is projected after the first meaningful code commit; existing PRs are adopted with `job adopt`. The PR body is the single durable Job surface: one hidden `agents-relay:job:v1` marker followed by the objective Markdown. Updating Job metadata or objective updates that same body. New Jobs must not create a separate Job comment that repeats the objective. Readers must remain backward-compatible with legacy Job-comment markers, and a successful Job save may migrate such a legacy marker into the PR body only after validating the replacement before deleting the redundant legacy Job comment.
 
 ## Task producers