agents-relay 2.0.37 → 2.0.39

package/README.md

@@ -42,6 +42,10 @@ RelayStore owns local operational execution facts; GitHub remains the human-read
 
 These paths always represent the current canonical graphs. Historical graph definitions are available through Git history, tags, and commits rather than parallel versioned files in `workflow/`. See [`docs/workflow-engine.md`](docs/workflow-engine.md) for the executable profile and runtime boundary.
 
+### Structured runtime observability
+
+`src/observability.ts` is the single structured logging/event boundary that records why a lifecycle or projection decision happened. One correlated record chain (`wake -> graph -> transition -> store commit -> projection outcome`) lets an operator reconstruct a representative task lifecycle without ad-hoc stderr parsing. Records are observational only, never a second durable store; they correlate by repository/PR/job/task/execution, classify failures as deterministic `conflict` vs `transient` retry vs `terminal`, redact secrets/prompts, bound large payloads, and keep routine idle/no-op cycles quiet at the default level. See [`docs/structured-observability.md`](docs/structured-observability.md) for the record contract, fields, noise policy, and redaction rules.
+
 ## 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.

package/dist/observability.js

@@ -0,0 +1,186 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
+export const OBSERVABILITY_MAX_STRING = 512;
+export const OBSERVABILITY_MAX_ITEMS = 20;
+export const OBSERVABILITY_MAX_DEPTH = 4;
+export const OBSERVABILITY_REDACTED = '[redacted]';
+const SENSITIVE_KEY = /(secret|token|password|passwd|authorization|cookie|credential|api[_-]?key|private[_-]?key|bearer|prompt)/i;
+const BULK_KEY = /^(payload|input|body|diff|patch|content|messages?)$/i;
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    if (error && typeof error === 'object') {
+        const message = error.message;
+        if (typeof message === 'string')
+            return message;
+    }
+    return String(error);
+}
+function failureStatus(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const value = error;
+    for (const candidate of [value.status, value.statusCode, value.response?.status]) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function failureRetryAfterMs(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const value = error;
+    const retryAfterSeconds = Number(value.retryAfter);
+    if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0)
+        return retryAfterSeconds * 1000;
+    const retryAfterMs = Number(value.retryAfterMs);
+    if (Number.isFinite(retryAfterMs) && retryAfterMs > 0)
+        return retryAfterMs;
+    for (const headers of [value.response?.headers, value.headers]) {
+        const raw = headerValue(headers, 'retry-after');
+        const seconds = Number(raw);
+        if (Number.isFinite(seconds) && seconds > 0)
+            return seconds * 1000;
+    }
+    return undefined;
+}
+function headerValue(headers, name) {
+    if (!headers || typeof headers !== 'object')
+        return null;
+    if (typeof headers.get === 'function')
+        return headers.get(name);
+    const record = headers;
+    const hit = Object.entries(record).find(([key]) => key.toLowerCase() === name);
+    return hit && hit[1] !== undefined ? String(hit[1]) : null;
+}
+/**
+ * Deterministic conflict vs transient retry classification.
+ *
+ * `conflict` means the durable record rejects a divergent definition and retrying
+ * will not help. `transient` means the same request may succeed later (rate limit,
+ * 5xx, network interruption, retry-after). `terminal` covers everything else.
+ */
+export function classifyFailure(error) {
+    const reason = errorMessage(error);
+    const status = failureStatus(error);
+    const retryAfterMs = failureRetryAfterMs(error);
+    const classified = { classification: 'terminal', reason };
+    if (status !== undefined)
+        classified.status = status;
+    if (retryAfterMs !== undefined)
+        classified.retryAfterMs = retryAfterMs;
+    if (/already exists with a different definition/i.test(reason) || status === 409) {
+        return { ...classified, classification: 'conflict' };
+    }
+    if (status === 429
+        || (status !== undefined && status >= 500)
+        || retryAfterMs !== undefined
+        || /\b(ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|ECONNREFUSED|EPIPE|UND_ERR)\b/.test(reason)
+        || /fetch failed|network|socket hang up|rate limit|secondary rate|temporarily unavailable/i.test(reason)) {
+        return { ...classified, classification: 'transient' };
+    }
+    return classified;
+}
+/** Bound and redact observation data so records never leak secrets or large payloads. */
+export function sanitizeObservationValue(value, depth = 0) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'string') {
+        return value.length > OBSERVABILITY_MAX_STRING
+            ? `${value.slice(0, OBSERVABILITY_MAX_STRING)}…(+${value.length - OBSERVABILITY_MAX_STRING})`
+            : value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'function')
+        return '[function]';
+    if (Array.isArray(value)) {
+        const items = value.slice(0, OBSERVABILITY_MAX_ITEMS).map(item => sanitizeObservationValue(item, depth + 1));
+        return value.length > OBSERVABILITY_MAX_ITEMS ? [...items, `+${value.length - OBSERVABILITY_MAX_ITEMS} more`] : items;
+    }
+    if (typeof value === 'object') {
+        if (depth >= OBSERVABILITY_MAX_DEPTH)
+            return '[truncated]';
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (SENSITIVE_KEY.test(key)) {
+                out[key] = OBSERVABILITY_REDACTED;
+                continue;
+            }
+            if (BULK_KEY.test(key) && typeof item === 'string' && item.length > OBSERVABILITY_MAX_STRING) {
+                out[key] = `[omitted ${item.length} chars]`;
+                continue;
+            }
+            out[key] = sanitizeObservationValue(item, depth + 1);
+        }
+        return out;
+    }
+    return '[unsupported]';
+}
+export function sanitizeObservationData(data) {
+    if (!data)
+        return undefined;
+    return sanitizeObservationValue(data, 0);
+}
+function writeStderrObservation(record) {
+    try {
+        process.stderr.write(`${JSON.stringify(record)}\n`);
+    }
+    catch { /* observability must never break execution */ }
+}
+const correlationStorage = new AsyncLocalStorage();
+export function withObservabilityCorrelation(correlation, work) {
+    return correlationStorage.run({ ...currentObservabilityCorrelation(), ...correlation }, work);
+}
+export function currentObservabilityCorrelation() {
+    return correlationStorage.getStore() ?? {};
+}
+export class RelayObservability {
+    sink;
+    minimumLevel;
+    constructor(sink = writeStderrObservation, minimumLevel = 'info') {
+        this.sink = sink;
+        this.minimumLevel = minimumLevel;
+    }
+    /** No-op observer used as the safe default until a runtime configures logging. */
+    static silent() { return new RelayObservability(() => undefined, 'error'); }
+    static stderr(minimumLevel = 'info') {
+        return new RelayObservability(writeStderrObservation, minimumLevel);
+    }
+    static fromEnvironment(env = process.env) {
+        const configured = (env.AGENTS_RELAY_OBSERVABILITY ?? env.RELAY_OBSERVABILITY_LEVEL ?? '').trim();
+        if (/^(silent|off|none|0|false)$/i.test(configured))
+            return RelayObservability.silent();
+        const level = /^(debug|info|warn|error)$/i.test(configured) ? configured.toLowerCase() : 'info';
+        return RelayObservability.stderr(level);
+    }
+    isEnabled(level) { return LEVEL_RANK[level] >= LEVEL_RANK[this.minimumLevel]; }
+    record(input) {
+        const level = input.level ?? 'info';
+        if (!this.isEnabled(level))
+            return;
+        const observation = {
+            ts: new Date().toISOString(),
+            stage: input.stage,
+            event: input.event,
+            level,
+            outcome: input.outcome ?? 'succeeded',
+            message: input.message,
+            correlation: { ...currentObservabilityCorrelation(), ...input.correlation },
+            ...(input.transition ? { transition: input.transition } : {}),
+            ...(input.data ? { data: sanitizeObservationData(input.data) } : {}),
+        };
+        this.sink(observation);
+    }
+}
+let activeObservability = RelayObservability.silent();
+export function observability() { return activeObservability; }
+export function setObservability(next) { activeObservability = next; }
+/** In-memory sink for tests and diagnostics. */
+export function collectObservations(records) {
+    return record => { records.push(record); };
+}

package/dist/pool.js

@@ -3,6 +3,7 @@ import { eventFor } from './events.js';
 import { runScheduledBucket } from './scheduled-jobs.js';
 import { scheduleBucket } from './scheduler.js';
 import { ReconcileCoordinator } from './reconcile-coordinator.js';
+import { errorMessage, observability, withObservabilityCorrelation } from './observability.js';
 const RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareJobPriority(a, b) { return RANK[a.priority ?? 'P2'] - RANK[b.priority ?? 'P2'] || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
 export function runnableManagedJobs(items) { return items.filter(item => item.githubState === 'OPEN' && item.job.state === 'ACTIVE').map(item => item.job).sort(compareJobPriority); }
@@ -47,7 +48,12 @@ export class RepositoryWorkerPool {
         this.makeStore = makeStore;
         this.repositories = [...new Set(typeof repository === 'string' ? [repository] : repository)];
         const reportCoordinatorError = (error, signal) => {
-            process.stderr.write(`warning: reconcile coordinator failed for ${signal.jobId} (${signal.reason}): ${error instanceof Error ? error.message : String(error)}\n`);
+            observability().record({
+                stage: 'reconcile', event: 'reconcile.coordinator_failed', level: 'error', outcome: 'failed',
+                message: `Reconcile coordinator failed for ${signal.jobId} (${signal.reason}): ${errorMessage(error)}`,
+                correlation: { repository: signal.repository, prNumber: signal.prNumber, jobId: signal.jobId },
+                data: { reason: signal.reason },
+            });
         };
         this.coordinator = new ReconcileCoordinator((jobId, signals) => this.consumeSignals(jobId, signals), reportCoordinatorError);
         this.githubSignalCoordinator = new ReconcileCoordinator((_key, signals) => this.consumeGitHubSignals(signals), reportCoordinatorError);
@@ -103,7 +109,12 @@ export class RepositoryWorkerPool {
         }
         const target = this.jobTargets.get(jobId);
         if (!target || !this.repositories.includes(target.repository)) {
-            process.stderr.write(`warning: reconcile signal target unknown for job ${jobId}\n`);
+            observability().record({
+                stage: 'reconcile', event: 'reconcile.signal_unrouted', level: 'warn', outcome: 'skipped',
+                message: `Reconcile signal target unknown for job ${jobId}`,
+                correlation: { jobId },
+                data: { reasons: signals.map(signal => signal.reason) },
+            });
             return;
         }
         const seedKey = `${target.repository}#${target.prNumber}:${jobId}`;
@@ -129,11 +140,24 @@ export class RepositoryWorkerPool {
             const result = await withGitHubRequestContext(this.client, `pool.coordinator-apply:${signal.reason}`, () => reconciler.applyEvent(signal.event));
             shouldReconcile ||= result.reconcile;
         }
-        if (!shouldReconcile)
+        if (!shouldReconcile) {
+            observability().record({
+                stage: 'wake', event: 'wake.signal', level: 'debug', outcome: 'noop',
+                message: `Wake for ${target.repository}#${target.prNumber} produced no reconcile work`,
+                correlation: { repository: target.repository, prNumber: target.prNumber, jobId },
+                data: { reasons: [...new Set(reasons)] },
+            });
             return;
+        }
         const reason = [...new Set(reasons)].join('+') || 'unknown';
+        observability().record({
+            stage: 'wake', event: 'wake.signal', outcome: 'started',
+            message: `Wake for ${target.repository}#${target.prNumber}: ${reason}`,
+            correlation: { repository: target.repository, prNumber: target.prNumber, jobId },
+            data: { reasons: [...new Set(reasons)] },
+        });
         await this.reconcileExclusive(jobId, async () => {
-            await withGitHubRequestContext(this.client, `pool.coordinator-reconcile:${reason}`, () => reconciler.reconcile(jobId));
+            await withObservabilityCorrelation({ repository: target.repository, prNumber: target.prNumber, jobId }, () => withGitHubRequestContext(this.client, `pool.coordinator-reconcile:${reason}`, () => reconciler.reconcile(jobId)));
         });
     }
     async reconcileDiscovered(discovered) {

package/dist/projected-store.js

@@ -1,6 +1,7 @@
 import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
 import { DurableDefinitionConflictError, isDurableDefinitionConflict, sameTaskDefinition } from './store-task-definition.js';
 import { decideProjectionFailure } from './workflow/projection-conflict-v2.js';
+import { classifyFailure, errorMessage, observability } from './observability.js';
 function taskKey(task) { return `task:${task.jobId ?? ''}:${task.id}`; }
 function planKey(plan) { return `plan:${plan.jobId}:${plan.id}`; }
 function retryHeader(error, name) {
@@ -92,19 +93,36 @@ export class GitHubProjectionWriter {
                 await this.apply(item);
                 await this.relay.completeProjection(item.id);
                 projected += 1;
+                observability().record({
+                    stage: 'projection', event: 'projection.completed', outcome: 'succeeded',
+                    message: `Projection ${item.operation} applied`,
+                    data: { operation: item.operation, idempotencyKey: item.idempotencyKey, coalesceKey: item.coalesceKey, attempts: item.attempts },
+                });
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = errorMessage(error);
                 const deterministic = isTerminalProjectionFailure(item, error);
+                const classified = classifyFailure(error);
                 const decision = decideProjectionFailure({ deterministicDefinitionConflict: deterministic });
                 if (decision.accepted && decision.target === 'conflict') {
                     const diagnostic = conflictDiagnostic(item, error, now.toISOString());
                     await this.relay.recordProjectionConflict(item.id, diagnostic);
                     await this.notifyConflict(diagnostic, message);
+                    observability().record({
+                        stage: 'projection', event: 'projection.conflict', level: 'error', outcome: 'failed',
+                        message: `Projection ${item.operation} has a deterministic conflict: ${message}`,
+                        data: { operation: item.operation, idempotencyKey: item.idempotencyKey, coalesceKey: item.coalesceKey, attempts: item.attempts, classification: 'conflict', reason: classified.reason },
+                    });
                 }
                 else {
-                    await this.relay.retryProjection(item.id, message, githubProjectionRetryAt(error, item.attempts, now));
+                    const retryAt = githubProjectionRetryAt(error, item.attempts, now);
+                    await this.relay.retryProjection(item.id, message, retryAt);
                     deferred += 1;
+                    observability().record({
+                        stage: 'projection', event: 'projection.retry_scheduled', level: 'warn', outcome: 'failed',
+                        message: `Projection ${item.operation} deferred for retry: ${message}`,
+                        data: { operation: item.operation, idempotencyKey: item.idempotencyKey, attempts: item.attempts, classification: classified.classification, retryAt: retryAt.toISOString(), status: classified.status, reason: classified.reason },
+                    });
                 }
             }
         }
@@ -195,6 +213,12 @@ export class ProjectedDurableStore {
             payload: { operation: 'save_job', value },
             priority: ['COMPLETED', 'CANCELLED'].includes(job.state) ? 100 : 20,
         });
+        observability().record({
+            stage: 'store', event: 'store.commit', outcome: 'succeeded',
+            message: `Job ${job.id} committed`,
+            correlation: { repository: job.repository, prNumber: job.prNumber, jobId: job.id },
+            data: { operation: 'save_job', state: job.state, tasks: job.tasks.length },
+        });
     }
     async appendPlan(plan) {
         const job = await this.load(plan.jobId);
@@ -246,6 +270,12 @@ export class ProjectedDurableStore {
             payload: { operation: 'append_task', value: task },
             priority: 40,
         });
+        observability().record({
+            stage: 'store', event: 'store.commit', outcome: 'succeeded',
+            message: `Task ${task.id} appended`,
+            correlation: { repository: job.repository, prNumber: job.prNumber, jobId: task.jobId, taskId: task.id },
+            data: { operation: 'append_task', agentName: task.agentName, storySize: task.storySize },
+        });
     }
     async saveTask(task) {
         if (!task.jobId)
@@ -267,6 +297,12 @@ export class ProjectedDurableStore {
             payload: { operation: 'save_task', value },
             priority: terminal ? 100 : 50,
         });
+        observability().record({
+            stage: 'store', event: 'store.commit', outcome: 'succeeded',
+            message: `Task ${task.id} committed (${task.state})`,
+            correlation: { repository: job.repository, prNumber: job.prNumber, jobId: task.jobId, taskId: task.id, executionId: task.executionId ?? undefined },
+            data: { operation: 'save_task', state: task.state, attempt: task.attempt },
+        });
     }
     async listAgents() {
         const local = await this.relay.loadAgents();

package/dist/projection-outbox.js

@@ -140,11 +140,13 @@ export class ProjectionOutbox {
     }
     enqueue(request, now) {
         const operationKey = logicalOperationKey(request.idempotencyKey);
+        let coalesced = false;
         if (request.coalesceKey) {
-            this.db.prepare(`
+            const removed = this.db.prepare(`
         DELETE FROM projection_outbox
         WHERE coalesce_key=? AND status='pending' AND operation_key<>?
       `).run(request.coalesceKey, operationKey);
+            coalesced = Number(removed.changes) > 0;
         }
         const existing = this.db.prepare('SELECT status FROM projection_outbox WHERE operation_key=? ORDER BY id DESC LIMIT 1')
             .get(operationKey);
@@ -171,6 +173,7 @@ export class ProjectionOutbox {
         last_error=NULL,
         updated_at=excluded.updated_at
     `).run(idempotencyKey, operationKey, request.coalesceKey ?? null, request.operation, JSON.stringify(request.payload), request.priority ?? 0, now, now);
+        return coalesced;
     }
     claimDue(limit, now) {
         const observedAt = now.toISOString();

package/dist/reconciler.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { storySizeTimeoutMs, chatGptStartAckTimeoutMs } from './types.js';
-import { dependencyReady, schedule, transitionJobEvent, transitionTaskEvent } from './scheduler.js';
+import { dependencyReady, schedule, transitionTaskEvent } from './scheduler.js';
 import { applyTaskCancelAction } from './task-actions.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
@@ -13,7 +13,6 @@ import { executeManualPlan } from './manual-plan.js';
 import { executionEventSource, withExecutionBoundary } from './reconciler-runtime.js';
 export { executionEventSource } from './reconciler-runtime.js';
 import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
-import { applyHistoricalJobCompatibilityRepair } from './workflow/runtime.js';
 import { pendingTroubleshooterTasks } from './troubleshooter.js';
 import { prepareManagedExecutionWorktree } from './workspace.js';
 import { createReviewChairExecutionPlan } from './review-chair.js';
@@ -21,6 +20,7 @@ import { taskTagWorkerPrompt } from './task-tag.js';
 import { recoverExpiredExecutions, recoverStartupOrphans as recoverStartupExecutionOrphans } from './execution-recovery.js';
 import { dispatchJobReconcile } from './workflow/job-reconcile-v2.js';
 import { launchPlanExecution } from './planner-runtime.js';
+import { classifyFailure, errorMessage, observability, withObservabilityCorrelation } from './observability.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
 export async function managedWorkerInput(job, task, context) {
@@ -106,6 +106,8 @@ export class Reconciler extends ReconcilerReviewBase {
         try {
             const job = await this.store.load(jobId);
             const previousState = job.state;
+            const lifecycleFingerprint = (value) => `${value.state}|${value.tasks.map(task => `${task.id}:${task.state}`).join(',')}`;
+            const beforeFingerprint = lifecycleFingerprint(job);
             const prState = await this.store.pullRequestState?.() ?? 'OPEN';
             const headSha = prState === 'OPEN' ? await this.currentHeadSha(job) : null;
             if (headSha && job.headSha !== headSha) {
@@ -116,23 +118,10 @@ export class Reconciler extends ReconcilerReviewBase {
             await this.invalidateStaleReview(job, headSha);
             const now = (this.options.now ?? new Date()).getTime();
             if (prState !== 'OPEN') {
-                const reason = prState === 'MERGED' ? 'Pull request merged' : 'Pull request closed';
-                const terminalState = prState === 'MERGED' ? 'COMPLETED' : 'CANCELLED';
-                if (job.state !== terminalState) {
-                    if (!['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'].includes(job.state)) {
-                        // Compatibility repair boundary for historical records that persisted runtime status as lifecycle.
-                        applyHistoricalJobCompatibilityRepair(job, terminalState);
-                        await this.store.saveJob(job);
-                        const outcomes = await this.workflowEffects.execute(['effect.cancelActiveTasks'], { jobId: job.id, transitionKey: `compatibility:${prState}`, data: { reason } });
-                        await this.applyJobEffectOutcomes(job, outcomes);
-                    }
-                    else {
-                        await transitionJobEvent(job, prState === 'MERGED' ? 'pr.merged' : 'pr.closed', prState === 'CLOSED' ? { notMerged: true } : {}, async (actionId) => {
-                            const outcomes = await this.workflowEffects.execute([actionId], { jobId: job.id, transitionKey: `terminal:${prState}`, data: { reason } });
-                            await this.applyJobEffectOutcomes(job, outcomes);
-                        }, async () => { await this.store.saveJob(job); });
-                    }
-                }
+                await dispatchJobReconcile(job, { prState, headSha, mergeCapable: Boolean(this.store.mergePullRequest) }, async (actionId) => {
+                    const outcomes = await this.workflowEffects.execute([actionId], { jobId: job.id, transitionKey: `terminal:${prState}`, data: { reason: `Pull request ${prState.toLowerCase()}` } });
+                    await this.applyJobEffectOutcomes(job, outcomes);
+                }, async () => { await this.store.saveJob(job); });
                 if (prState === 'MERGED' && this.store.resolveBlockerDependents) {
                     const resolved = await this.store.resolveBlockerDependents(job.id, 'merge');
                     for (const target of resolved.unblocked)
@@ -201,7 +190,33 @@ export class Reconciler extends ReconcilerReviewBase {
                 const outcomes = await this.workflowEffects.execute([actionId], { jobId: finalState.id, transitionKey: `reconcile:${headSha ?? 'no-head'}`, data: { headSha } });
                 await this.applyJobEffectOutcomes(finalState, outcomes);
             }, async () => { await this.store.saveJob(finalState); });
-            return this.store.load(jobId);
+            const settled = await this.store.load(jobId);
+            const changed = lifecycleFingerprint(settled) !== beforeFingerprint;
+            observability().record({
+                stage: 'reconcile',
+                event: 'reconcile',
+                level: changed ? 'info' : 'debug',
+                outcome: changed ? 'succeeded' : 'noop',
+                message: changed
+                    ? `Reconcile updated ${settled.repository}#${settled.prNumber} lifecycle`
+                    : `Reconcile ${settled.repository}#${settled.prNumber} made no lifecycle change`,
+                correlation: { repository: settled.repository, prNumber: settled.prNumber, jobId: settled.id },
+                transition: { graph: 'job-lifecycle', from: previousState, to: settled.state },
+                data: { prState, tasks: settled.tasks.length },
+            });
+            return settled;
+        }
+        catch (error) {
+            observability().record({
+                stage: 'reconcile',
+                event: 'reconcile.failed',
+                level: 'error',
+                outcome: 'failed',
+                message: `Reconcile failed for ${jobId}: ${errorMessage(error)}`,
+                correlation: { jobId },
+                data: { classification: classifyFailure(error).classification, reason: errorMessage(error) },
+            });
+            throw error;
         }
         finally {
             this.reconciling = false;
@@ -343,6 +358,9 @@ export class Reconciler extends ReconcilerReviewBase {
         });
     }
     async launch(job, task) {
+        return withObservabilityCorrelation({ repository: job.repository, prNumber: job.prNumber, jobId: job.id, taskId: task.id }, () => this.launchCorrelated(job, task));
+    }
+    async launchCorrelated(job, task) {
         const adapter = this.options.adapters.find(x => x.name === task.adapter);
         if (!adapter) {
             await transitionTaskEvent(task, 'fail');
@@ -436,6 +454,13 @@ export class Reconciler extends ReconcilerReviewBase {
             void startAckSetup.ack.finally(() => { void startAckSetup.stop(); }).catch(() => { });
         this.live.set(task.id, { jobId: job.id, taskId: task.id, executionId: durableExecutionId, execution, controller, launchBarrier: Date.now(), workerStarted: false, processSettled: false });
         this.registerExecutionOwner(job.id, task.id, durableExecutionId);
+        observability().record({
+            stage: 'transition', event: 'task.dispatch', outcome: 'succeeded',
+            message: `Task ${task.id} dispatched to ${task.adapter}`,
+            correlation: { repository: job.repository, prNumber: job.prNumber, jobId: job.id, taskId: task.id, executionId: durableExecutionId },
+            transition: { graph: 'task-lifecycle', from: 'QUEUED', to: 'QUEUED', actions: ['effect.launchTask'] },
+            data: { adapter: adapter.id, attempt: task.attempt, model: task.routing?.model ?? null },
+        });
         const terminalTimer = setTimeout(() => {
             this.detach(this.timeoutTask(job.id, task.id, durableExecutionId), job.id, task.id, 'worker terminal-event timeout');
         }, Math.max(1, task.timeoutMs));

package/dist/relay-store.js

@@ -2,6 +2,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { dirname } from 'node:path';
 import { mkdirSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
+import { observability } from './observability.js';
 import { ProjectionOutbox, SCHEMA_VERSION, } from './projection-outbox.js';
 function newerRecord(local, remote) {
     if (!local)
@@ -117,8 +118,16 @@ export class SQLiteRelayStore {
         this.db.exec('BEGIN IMMEDIATE');
         try {
             this.writeJobSnapshot(job, now);
-            this.enqueueProjectionInTransaction(request, now);
+            const coalesced = this.enqueueProjectionInTransaction(request, now);
             this.db.exec('COMMIT');
+            observability().record({
+                stage: 'projection', event: 'projection.enqueued', outcome: coalesced ? 'deduplicated' : 'succeeded',
+                message: coalesced
+                    ? `Projection ${request.operation} coalesced`
+                    : `Projection ${request.operation} enqueued`,
+                correlation: { repository: job.repository, prNumber: job.prNumber, jobId: job.id },
+                data: { operation: request.operation, idempotencyKey: request.idempotencyKey, coalesceKey: request.coalesceKey, priority: request.priority ?? 0, coalesced },
+            });
         }
         catch (error) {
             this.db.exec('ROLLBACK');
@@ -199,14 +208,21 @@ export class SQLiteRelayStore {
         return Number(result.changes) === 1;
     }
     enqueueProjectionInTransaction(request, now) {
-        this.outbox.enqueue(request, now);
+        return this.outbox.enqueue(request, now);
     }
     async enqueueProjection(request) {
         const now = new Date().toISOString();
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            this.outbox.enqueue(request, now);
+            const coalesced = this.enqueueProjectionInTransaction(request, now);
             this.db.exec('COMMIT');
+            observability().record({
+                stage: 'projection', event: 'projection.enqueued', outcome: coalesced ? 'deduplicated' : 'succeeded',
+                message: coalesced
+                    ? `Projection ${request.operation} coalesced`
+                    : `Projection ${request.operation} enqueued`,
+                data: { operation: request.operation, idempotencyKey: request.idempotencyKey, coalesceKey: request.coalesceKey, priority: request.priority ?? 0, coalesced },
+            });
         }
         catch (error) {
             this.db.exec('ROLLBACK');

package/dist/relayd.js

@@ -27,6 +27,13 @@ import { summarizeRuntime } from './runtime-summary.js';
 import { executionRouterRulesPath } from './routing-policy.js';
 import { workerCandidates } from './worker-routing.js';
 import { routeExecution } from './execution-routing.js';
+import { RelayObservability, classifyFailure, errorMessage, observability, setObservability } from './observability.js';
+/** Initialize the process-wide structured observability sink once, from environment. */
+export function configureDaemonObservability(env = process.env) {
+    const configured = RelayObservability.fromEnvironment(env);
+    setObservability(configured);
+    return configured;
+}
 export async function overlayOperationalOverviews(overviews, storeFor) {
     return await Promise.all(overviews.map(async (item) => {
         const store = storeFor(item.job.repository, item.job.prNumber);
@@ -128,6 +135,7 @@ export async function runDaemon(argv) {
         console.log(daemonHelp);
         return;
     }
+    configureDaemonObservability();
     configureExecutionRouterRulesPath(argv);
     await ensureChatGptBrowserWorkspace();
     const normalized = normalizeDaemonArguments(argv);
@@ -198,7 +206,7 @@ export async function runDaemon(argv) {
             return cachedOverviews;
         }
         catch (error) {
-            process.stderr.write(`warning: workspace job refresh unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+            observability().record({ stage: 'daemon', event: 'daemon.refresh_failed', level: 'warn', outcome: 'failed', message: `Workspace job refresh unavailable: ${errorMessage(error)}`, data: { classification: classifyFailure(error).classification, reason: errorMessage(error) } });
             return cachedOverviews;
         }
     };
@@ -364,7 +372,7 @@ export async function runDaemon(argv) {
             return { ...refreshed.job, githubState: refreshed.githubState, runtimeStatus: deriveJobRuntimeStatus(refreshed.job, refreshed.githubState), mergedAt: refreshed.mergedAt, closedAt: refreshed.closedAt, draft: refreshed.draft, publication: refreshed.publication };
         }
         catch (error) {
-            process.stderr.write(`warning: selected job refresh unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+            observability().record({ stage: 'daemon', event: 'daemon.refresh_failed', level: 'warn', outcome: 'failed', message: `Selected job refresh unavailable: ${errorMessage(error)}`, data: { classification: classifyFailure(error).classification, reason: errorMessage(error) } });
             return cachedJob();
         }
     };
@@ -448,7 +456,7 @@ export async function runDaemon(argv) {
             await pool.reconcile();
         }
         catch (error) {
-            process.stderr.write(`warning: workspace reconcile unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+            observability().record({ stage: 'daemon', event: 'daemon.reconcile_failed', level: 'warn', outcome: 'failed', message: `Workspace reconcile unavailable: ${errorMessage(error)}`, data: { classification: classifyFailure(error).classification, reason: errorMessage(error) } });
         }
     };
     const scheduleHeartbeatSafely = async () => {
@@ -458,7 +466,7 @@ export async function runDaemon(argv) {
                 await pool.scheduleTickSignal(bus, item.job, now);
             }
             catch (error) {
-                process.stderr.write(`warning: scheduled heartbeat unavailable for ${item.job.repository}#${item.job.prNumber}: ${error instanceof Error ? error.message : String(error)}\n`);
+                observability().record({ stage: 'daemon', event: 'daemon.schedule_heartbeat_failed', level: 'warn', outcome: 'failed', message: `Scheduled heartbeat unavailable: ${errorMessage(error)}`, correlation: { repository: item.job.repository, prNumber: item.job.prNumber, jobId: item.job.id }, data: { classification: classifyFailure(error).classification, reason: errorMessage(error) } });
             }
         }
     };
@@ -468,7 +476,7 @@ export async function runDaemon(argv) {
                 await writer.flushOnce();
             }
             catch (error) {
-                process.stderr.write(`warning: GitHub projection flush unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+                observability().record({ stage: 'daemon', event: 'daemon.projection_flush_failed', level: 'warn', outcome: 'failed', message: `GitHub projection flush unavailable: ${errorMessage(error)}`, data: { classification: classifyFailure(error).classification, reason: errorMessage(error) } });
             }
         }
     };
@@ -495,7 +503,7 @@ export async function runDaemon(argv) {
     console.log('Dashboard listening; repository worker pool active');
     void refreshAll(true)
         .then(items => pool.reconcileKnown(items))
-        .catch(error => process.stderr.write('warning: startup remote refresh unavailable: ' + (error instanceof Error ? error.message : String(error)) + '\n'));
+        .catch(error => observability().record({ stage: 'daemon', event: 'daemon.startup_refresh_failed', level: 'warn', outcome: 'failed', message: 'Startup remote refresh unavailable: ' + errorMessage(error), data: { classification: classifyFailure(error).classification, reason: errorMessage(error) } }));
 }
 if (isEntrypoint(import.meta.url))
     runDaemon(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });

package/dist/scheduler.js

@@ -3,6 +3,7 @@ import { dispatchJobLifecycle, dispatchTaskLifecycle, dispatchTaskLifecycleSync
 import { reconcileTaskDependencies } from './workflow/task-reconcile.js';
 export { dependencyReady, detectCycles } from './workflow/task-reconcile.js';
 import { dispatchScheduleCycle } from './workflow/schedule-cycle-v2.js';
+import { observability } from './observability.js';
 export function completionGateSatisfied(job) {
     if (job.schedule)
         return false;
@@ -52,14 +53,31 @@ export async function transitionTaskEvent(task, event, context = {}, executeEffe
         throw new Error(decision.reason === 'ambiguous'
             ? `Ambiguous workflow transition from ${from} on ${event}`
             : `No enabled workflow transition from ${from} on ${event}`);
+    observability().record({
+        stage: 'transition',
+        event,
+        outcome: 'succeeded',
+        message: `Task ${task.id} ${from} -> ${decision.target}`,
+        correlation: { jobId: task.jobId, taskId: task.id, executionId: task.executionId ?? undefined },
+        transition: { graph: 'task-lifecycle', from, to: decision.target, actions: decision.actions },
+    });
     return decision;
 }
 export async function transitionJobEvent(job, event, context = {}, executeEffect, persist) {
+    const from = job.state;
     const decision = await dispatchJobLifecycle(job, event, context, executeEffect, persist);
     if (!decision.accepted || !decision.target)
         throw new Error(decision.reason === 'ambiguous'
-            ? `Ambiguous workflow transition from ${job.state} on ${event}`
-            : `No enabled workflow transition from ${job.state} on ${event}`);
+            ? `Ambiguous workflow transition from ${from} on ${event}`
+            : `No enabled workflow transition from ${from} on ${event}`);
+    observability().record({
+        stage: 'transition',
+        event,
+        outcome: 'succeeded',
+        message: `Job ${job.id} ${from} -> ${decision.target}`,
+        correlation: { repository: job.repository, prNumber: job.prNumber, jobId: job.id },
+        transition: { graph: 'job-lifecycle', from, to: decision.target, actions: decision.actions },
+    });
     return decision;
 }
 export const SCHEDULE_RESOLUTION_MS = 600_000;

package/dist/workflow/authoritative-unblock-v2.js

@@ -13,8 +13,8 @@ export const authoritativeUnblockV2 = new GraphRuntime(source, {
     events: { 'task.authoritative_unblock': { id: 'task.authoritative_unblock' } },
 });
 export async function dispatchAuthoritativeUnblock(autonomousJob, executeAction) {
-    return dispatchWorkflowGraph(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, durableFacts: { autonomousJob }, executeAction });
+    return dispatchWorkflowGraph(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, graphName: 'authoritative-unblock', durableFacts: { autonomousJob }, executeAction });
 }
 export function decideAuthoritativeUnblock(autonomousJob) {
-    return dispatchWorkflowGraphSync(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, durableFacts: { autonomousJob } });
+    return dispatchWorkflowGraphSync(authoritativeUnblockV2, { initialState: 'blocked', input: { transport: 'event', id: 'task.authoritative_unblock', payload: {} }, graphName: 'authoritative-unblock', durableFacts: { autonomousJob } });
 }

package/dist/workflow/blocker-resolution-v2.js

@@ -26,8 +26,8 @@ export const blockerResolutionV2 = new GraphRuntime(source, {
     events: { 'blocker.resolved': { id: 'blocker.resolved' } },
 });
 export async function dispatchBlockerResolution(facts, executeAction) {
-    return dispatchWorkflowGraph(blockerResolutionV2, { initialState: 'waiting', input: { transport: 'event', id: 'blocker.resolved', payload: {} }, durableFacts: facts, isTransientState: state => state.startsWith('check_'), maxSteps: 10, executeAction });
+    return dispatchWorkflowGraph(blockerResolutionV2, { initialState: 'waiting', input: { transport: 'event', id: 'blocker.resolved', payload: {} }, durableFacts: facts, graphName: 'blocker-resolution', isTransientState: state => state.startsWith('check_'), maxSteps: 10, executeAction });
 }
 export function decideBlockerResolution(facts) {
-    return dispatchWorkflowGraphSync(blockerResolutionV2, { initialState: 'waiting', input: { transport: 'event', id: 'blocker.resolved', payload: {} }, durableFacts: facts, isTransientState: state => state.startsWith('check_'), maxSteps: 10 });
+    return dispatchWorkflowGraphSync(blockerResolutionV2, { initialState: 'waiting', input: { transport: 'event', id: 'blocker.resolved', payload: {} }, durableFacts: facts, graphName: 'blocker-resolution', isTransientState: state => state.startsWith('check_'), maxSteps: 10 });
 }

package/dist/workflow/dispatcher.js

@@ -1,4 +1,54 @@
 import { GraphDispatcher } from './graph-v2.js';
+import { observability } from '../observability.js';
+/**
+ * Record graph/decision identity and selected transition/action.
+ *
+ * `no_transition` is emitted at debug so normal idle watchdog cycles stay quiet;
+ * accepted transitions and ambiguous paths are visible at info/warn.
+ */
+function observeDecision(graphName, input, decision) {
+    if (decision.accepted) {
+        const noOp = decision.source === decision.target && decision.actions.length === 0;
+        observability().record({
+            stage: 'graph',
+            event: input.id,
+            level: noOp ? 'debug' : undefined,
+            outcome: noOp ? 'noop' : 'succeeded',
+            message: noOp
+                ? `Graph ${graphName ?? 'workflow'} accepted no-op ${decision.source} -> ${decision.target}`
+                : `Graph ${graphName ?? 'workflow'} accepted ${decision.source} -> ${decision.target}`,
+            transition: {
+                graph: graphName ?? null,
+                from: decision.source,
+                to: decision.target,
+                actions: decision.actions.map(action => action.id),
+            },
+            data: { transport: input.transport },
+        });
+        return;
+    }
+    if (decision.reason === 'ambiguous') {
+        observability().record({
+            stage: 'graph',
+            event: input.id,
+            level: 'warn',
+            outcome: 'failed',
+            message: `Graph ${graphName ?? 'workflow'} found ambiguous path from ${decision.source}`,
+            transition: { graph: graphName ?? null, from: decision.source, to: null },
+            data: { transport: input.transport, reason: decision.reason },
+        });
+        return;
+    }
+    observability().record({
+        stage: 'graph',
+        event: input.id,
+        level: 'debug',
+        outcome: 'noop',
+        message: `Graph ${graphName ?? 'workflow'} has no transition from ${decision.source} on ${input.id}`,
+        transition: { graph: graphName ?? null, from: decision.source, to: null },
+        data: { transport: input.transport, reason: decision.reason },
+    });
+}
 /**
  * The single production graph execution boundary.
  * Ingress adapters normalize input/facts, while GraphDispatcher alone evaluates,
@@ -18,6 +68,8 @@ export async function dispatchWorkflowGraph(runtime, options) {
             input: options.input,
             durableFacts: options.durableFacts ?? {},
         });
+        if (options.observe !== false)
+            observeDecision(options.graphName, options.input, result.decision);
         if (!result.decision.accepted)
             return result.decision;
         current = result.decision.target;
@@ -39,6 +91,8 @@ export function dispatchWorkflowGraphSync(runtime, options) {
                 throw new Error('sync workflow publishEvent returned Promise'); },
         });
         const result = dispatcher.dispatchSync({ currentState: current, input: options.input, durableFacts: options.durableFacts ?? {} });
+        if (options.observe !== false)
+            observeDecision(options.graphName, options.input, result.decision);
         if (!result.decision.accepted)
             return result.decision;
         current = result.decision.target;
@@ -52,5 +106,12 @@ export async function dispatchWorkflowTargetOverride(runtime, options) {
     // It intentionally executes no workflow actions/effects: this is a state repair, not an event replay.
     const { assertV2StateTransition } = await import('./definitions-v2.js');
     assertV2StateTransition(runtime.graph, options.currentState, options.targetState, options.kind);
+    observability().record({
+        stage: 'graph',
+        event: 'target.override',
+        outcome: 'succeeded',
+        message: `Administrative ${options.kind} state repair ${options.currentState} -> ${options.targetState}`,
+        transition: { graph: `${options.kind}.override`, from: options.currentState, to: options.targetState, actions: [] },
+    });
     await options.persistTransition(options.currentState, options.targetState);
 }

package/dist/workflow/durable-transition.js

@@ -1,4 +1,5 @@
 import { tryTransitionTaskEvent } from '../scheduler.js';
+import { observability } from '../observability.js';
 /**
  * Runtime primitive for applying one canonical Task-graph event to fresh durable state.
  *
@@ -15,14 +16,30 @@ export class DurableTaskTransitionRuntime {
         return this.withLock(`${jobId}/${taskId}`, async () => {
             const job = await this.store.load(jobId);
             const task = job.tasks.find(item => item.id === taskId);
-            if (!task || (options.eligible && !options.eligible(job, task)))
+            if (!task || (options.eligible && !options.eligible(job, task))) {
+                observability().record({
+                    stage: 'transition', event, level: 'debug', outcome: 'skipped',
+                    message: `Task ${taskId} transition ${event} not eligible`,
+                    correlation: { repository: job.repository, prNumber: job.prNumber, jobId, taskId },
+                    transition: { graph: 'task-lifecycle', from: task?.state ?? null, to: null },
+                });
                 return null;
+            }
             const from = task.state;
             const decision = tryTransitionTaskEvent(task, event, options.facts?.(job, task) ?? {});
-            if (!decision.accepted || !decision.target)
+            if (!decision.accepted || !decision.target) {
                 return { job, task, from, decision };
+            }
             await options.mutate?.(job, task, decision);
             await this.store.saveTask(task);
+            observability().record({
+                stage: 'transition',
+                event,
+                outcome: 'succeeded',
+                message: `Task ${taskId} ${from} -> ${decision.target}`,
+                correlation: { repository: job.repository, prNumber: job.prNumber, jobId, taskId, executionId: task.executionId ?? undefined },
+                transition: { graph: 'task-lifecycle', from, to: decision.target, actions: decision.actions },
+            });
             return { job, task, from, decision };
         });
     }

package/dist/workflow/effects.js

@@ -1,3 +1,4 @@
+import { classifyFailure, observability } from '../observability.js';
 export class MemoryWorkflowEffectReceiptStore {
     completed = new Set();
     async has(key) { return this.completed.has(key); }
@@ -48,6 +49,7 @@ export class WorkflowEffectExecutor {
             if (await this.receipts.has(key)) {
                 const outcome = { effect, key, status: 'deduplicated' };
                 outcomes.push(outcome);
+                this.recordEffect(context, outcome);
                 await onOutcome?.(outcome);
                 continue;
             }
@@ -56,6 +58,7 @@ export class WorkflowEffectExecutor {
                 await this.receipts.markCompleted(key);
                 const outcome = { effect, key, status: 'completed' };
                 outcomes.push(outcome);
+                this.recordEffect(context, outcome);
                 await onOutcome?.(outcome);
             }
             catch (error) {
@@ -66,9 +69,29 @@ export class WorkflowEffectExecutor {
                     error: error instanceof Error ? error.message : String(error),
                 };
                 outcomes.push(outcome);
+                this.recordEffect(context, outcome, error);
                 await onOutcome?.(outcome);
             }
         }
         return outcomes;
     }
+    recordEffect(context, outcome, error) {
+        observability().record({
+            stage: 'transition',
+            event: outcome.status === 'failed' ? 'workflow.effect.failed' : 'workflow.effect',
+            level: outcome.status === 'failed' ? 'error' : 'info',
+            outcome: outcome.status === 'deduplicated' ? 'deduplicated' : outcome.status === 'failed' ? 'failed' : 'succeeded',
+            message: outcome.status === 'failed'
+                ? `Effect ${outcome.effect} failed: ${outcome.error ?? 'unknown error'}`
+                : `Effect ${outcome.effect} ${outcome.status}`,
+            correlation: { jobId: context.jobId, taskId: context.taskId },
+            transition: { graph: 'workflow.effect', from: null, to: null, actions: [outcome.effect] },
+            data: {
+                effect: outcome.effect,
+                idempotencyKey: outcome.key,
+                transitionKey: context.transitionKey,
+                ...(error ? { classification: classifyFailure(error).classification } : {}),
+            },
+        });
+    }
 }

package/dist/workflow/job-reconcile-v2.js

@@ -1,19 +1,65 @@
 import { decideJobLifecycle, dispatchJobLifecycle } from './lifecycle.js';
 import { implementationComplete } from '../runtime-status.js';
-export function decideJobReconcile(job, facts) {
-    return decideJobLifecycle(job, 'reconcile', {
-        prOpen: facts.prState === 'OPEN',
+import { applyHistoricalJobCompatibilityRepair } from './runtime.js';
+function lifecycleInput(facts) {
+    if (facts.prState === 'MERGED')
+        return { event: 'pr.merged', context: {} };
+    if (facts.prState === 'CLOSED')
+        return { event: 'pr.closed', context: { notMerged: true } };
+    return {
+        event: 'reconcile',
+        context: {
+            prOpen: true,
+            headAvailable: Boolean(facts.headSha),
+            mergeCapable: facts.mergeCapable,
+        },
+    };
+}
+function graphFacts(job, facts) {
+    const input = lifecycleInput(facts);
+    if (input.event !== 'reconcile')
+        return input.context;
+    return {
+        ...input.context,
         reviewDisabled: job.reviewEnabled === false,
         implementationComplete: implementationComplete(job),
         autoMerge: job.autoMerge !== false,
-        headAvailable: Boolean(facts.headSha),
-        mergeCapable: facts.mergeCapable,
-    });
+    };
+}
+/**
+ * Historical compatibility only. Normal Job lifecycle is always decided by
+ * workflow/job-lifecycle.mmd from the PR fact-derived event.
+ */
+function repairHistoricalTerminalState(job, facts) {
+    if (['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'].includes(job.state))
+        return null;
+    if (facts.prState === 'MERGED')
+        applyHistoricalJobCompatibilityRepair(job, 'COMPLETED');
+    else if (facts.prState === 'CLOSED')
+        applyHistoricalJobCompatibilityRepair(job, 'CANCELLED');
+    else
+        return null;
+    return job.state;
+}
+export function decideJobReconcile(job, facts) {
+    const input = lifecycleInput(facts);
+    return decideJobLifecycle(job, input.event, graphFacts(job, facts));
 }
 export async function dispatchJobReconcile(job, facts, executeEffect, persist) {
-    return dispatchJobLifecycle(job, 'reconcile', {
-        prOpen: facts.prState === 'OPEN', reviewDisabled: job.reviewEnabled === false,
-        implementationComplete: implementationComplete(job), autoMerge: job.autoMerge !== false,
-        headAvailable: Boolean(facts.headSha), mergeCapable: facts.mergeCapable,
-    }, executeEffect, persist);
+    const repaired = repairHistoricalTerminalState(job, facts);
+    if (repaired) {
+        await persist?.();
+        await executeEffect?.('effect.cancelActiveTasks');
+        return {
+            accepted: true,
+            target: repaired,
+            guard: null,
+            actions: ['effect.cancelActiveTasks'],
+            mutations: [],
+            effects: ['effect.cancelActiveTasks'],
+            reason: 'accepted',
+        };
+    }
+    const input = lifecycleInput(facts);
+    return dispatchJobLifecycle(job, input.event, graphFacts(job, facts), executeEffect, persist);
 }

package/dist/workflow/lifecycle.js

@@ -3,11 +3,14 @@ import { jobLifecycleV2, taskLifecycleV2 } from './definitions-v2.js';
 import { dispatchWorkflowGraph, dispatchWorkflowGraphSync } from './dispatcher.js';
 import { applyJobGraphTarget, applyTaskGraphTarget, applyTaskMutation } from './runtime.js';
 function v2WorkflowDecision(runtime, from, event, facts = {}) {
+    // Pure lifecycle predicates still enter through the dispatcher facade, but
+    // suppress observability because no durable transition is being applied.
     const actions = [];
     const decision = dispatchWorkflowGraphSync(runtime, {
         initialState: from,
         input: { transport: 'event', id: event, payload: {} },
         durableFacts: facts,
+        observe: false,
         executeAction: actionId => { actions.push(actionId); return {}; },
     });
     if (!decision.accepted)
@@ -34,6 +37,7 @@ export function dispatchTaskLifecycleSync(task, event, facts = {}) {
         initialState: task.state,
         input: { transport: 'event', id: event, payload: {} },
         durableFacts: facts,
+        graphName: 'task-lifecycle',
         persistTransition: (_source, target) => applyTaskGraphTarget(task, target),
         executeAction: actionId => { actions.push(actionId); if (actionId.startsWith('mutation.'))
             applyTaskMutation(task, actionId); return {}; },
@@ -46,6 +50,7 @@ export async function dispatchTaskLifecycle(task, event, facts = {}, executeEffe
     const actions = [];
     const result = await dispatchWorkflowGraph(taskLifecycleV2, {
         initialState: task.state, input: { transport: 'event', id: event, payload: {} }, durableFacts: facts,
+        graphName: 'task-lifecycle',
         persistTransition: async (_source, target) => { applyTaskGraphTarget(task, target); await persist?.(); },
         executeAction: async (actionId) => {
             actions.push(actionId);
@@ -66,6 +71,7 @@ export function dispatchJobLifecycleSync(job, event, facts = {}) {
         initialState: job.state,
         input: { transport: 'event', id: event, payload: {} },
         durableFacts: facts,
+        graphName: 'job-lifecycle',
         persistTransition: (_source, target) => applyJobGraphTarget(job, target),
         executeAction: actionId => { actions.push(actionId); return {}; },
     });
@@ -77,6 +83,7 @@ export async function dispatchJobLifecycle(job, event, facts = {}, executeEffect
     const actions = [];
     const result = await dispatchWorkflowGraph(jobLifecycleV2, {
         initialState: job.state, input: { transport: 'event', id: event, payload: {} }, durableFacts: facts,
+        graphName: 'job-lifecycle',
         persistTransition: async (_source, target) => { applyJobGraphTarget(job, target); await persist?.(); },
         executeAction: async (actionId) => { actions.push(actionId); await executeEffect?.(actionId); return {}; },
     });

package/dist/workflow/planner-orchestration-v2.js

@@ -27,10 +27,10 @@ export const plannerOrchestrationV2 = new GraphRuntime(source, {
     events: { 'planner.reconcile': { id: 'planner.reconcile' } },
 });
 export async function dispatchPlannerOrchestration(facts, executeAction) {
-    return dispatchWorkflowGraph(plannerOrchestrationV2, { initialState: 'idle', input: { transport: 'event', id: 'planner.reconcile', payload: {} }, durableFacts: facts, isTransientState: state => state.startsWith('check_'), maxSteps: 9, executeAction });
+    return dispatchWorkflowGraph(plannerOrchestrationV2, { initialState: 'idle', input: { transport: 'event', id: 'planner.reconcile', payload: {} }, durableFacts: facts, graphName: 'planner-orchestration', isTransientState: state => state.startsWith('check_'), maxSteps: 9, executeAction });
 }
 export function decidePlannerOrchestration(facts) {
-    return dispatchWorkflowGraphSync(plannerOrchestrationV2, { initialState: 'idle', input: { transport: 'event', id: 'planner.reconcile', payload: {} }, durableFacts: facts, isTransientState: state => state.startsWith('check_'), maxSteps: 9 });
+    return dispatchWorkflowGraphSync(plannerOrchestrationV2, { initialState: 'idle', input: { transport: 'event', id: 'planner.reconcile', payload: {} }, durableFacts: facts, graphName: 'planner-orchestration', isTransientState: state => state.startsWith('check_'), maxSteps: 9 });
 }
 export function plannerOrchestrationFacts(job, recoverablePendingPlan) {
     const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;

package/dist/workflow/planner-trigger-v2.js

@@ -16,7 +16,7 @@ export const plannerTriggerV2 = new GraphRuntime(source, {
 });
 export function dispatchPlannerTrigger(facts) {
     return dispatchWorkflowGraphSync(plannerTriggerV2, {
-        initialState: 'idle', input: { transport: 'event', id: 'plan.requested', payload: {} }, durableFacts: facts,
+        initialState: 'idle', input: { transport: 'event', id: 'plan.requested', payload: {} }, durableFacts: facts, graphName: 'planner-trigger',
         isTransientState: state => state.startsWith('check_'), maxSteps: 4,
     });
 }

package/dist/workflow/review-v2.js

@@ -35,8 +35,8 @@ export function reviewOutcome(state) {
     return state.toLowerCase();
 }
 export async function dispatchReviewLifecycle(outcome, event, facts = {}, executeAction) {
-    return dispatchWorkflowGraph(reviewLifecycleV2, { initialState: reviewGraphState(outcome), input: { transport: 'event', id: event, payload: {} }, durableFacts: facts, executeAction });
+    return dispatchWorkflowGraph(reviewLifecycleV2, { initialState: reviewGraphState(outcome), input: { transport: 'event', id: event, payload: {} }, durableFacts: facts, graphName: 'review-lifecycle', executeAction });
 }
 export function decideReviewLifecycle(outcome, event, facts = {}) {
-    return dispatchWorkflowGraphSync(reviewLifecycleV2, { initialState: reviewGraphState(outcome), input: { transport: 'event', id: event, payload: {} }, durableFacts: facts });
+    return dispatchWorkflowGraphSync(reviewLifecycleV2, { initialState: reviewGraphState(outcome), input: { transport: 'event', id: event, payload: {} }, durableFacts: facts, graphName: 'review-lifecycle' });
 }

package/dist/workflow/schedule-cycle-v2.js

@@ -14,7 +14,7 @@ export const scheduleCycleV2 = new GraphRuntime(source, {
 });
 export function dispatchScheduleCycle(facts, onFinish) {
     return dispatchWorkflowGraphSync(scheduleCycleV2, {
-        initialState: 'idle', input: { transport: 'event', id: 'schedule.reconcile', payload: {} }, durableFacts: facts,
+        initialState: 'idle', input: { transport: 'event', id: 'schedule.reconcile', payload: {} }, durableFacts: facts, graphName: 'schedule-cycle',
         isTransientState: state => state.startsWith('check_'), maxSteps: 2,
         executeAction: actionId => { if (actionId === 'schedule.finishSlot')
             onFinish();

package/dist/workflow/scheduled-run-v2.js

@@ -23,8 +23,8 @@ export const scheduledRunV2 = new GraphRuntime(source, {
     events: { 'schedule.tick': { id: 'schedule.tick' } },
 });
 export async function dispatchScheduledRun(facts, executeAction) {
-    return dispatchWorkflowGraph(scheduledRunV2, { initialState: 'idle', input: { transport: 'event', id: 'schedule.tick', payload: {} }, durableFacts: facts, isTransientState: state => state.startsWith('check_'), maxSteps: 8, executeAction });
+    return dispatchWorkflowGraph(scheduledRunV2, { initialState: 'idle', input: { transport: 'event', id: 'schedule.tick', payload: {} }, durableFacts: facts, graphName: 'scheduled-run', isTransientState: state => state.startsWith('check_'), maxSteps: 8, executeAction });
 }
 export function decideScheduledRun(facts) {
-    return dispatchWorkflowGraphSync(scheduledRunV2, { initialState: 'idle', input: { transport: 'event', id: 'schedule.tick', payload: {} }, durableFacts: facts, isTransientState: state => state.startsWith('check_'), maxSteps: 8 });
+    return dispatchWorkflowGraphSync(scheduledRunV2, { initialState: 'idle', input: { transport: 'event', id: 'schedule.tick', payload: {} }, durableFacts: facts, graphName: 'scheduled-run', isTransientState: state => state.startsWith('check_'), maxSteps: 8 });
 }

package/dist/workflow/task-related-action-v2.js

@@ -36,6 +36,7 @@ export function decideRelatedTaskAction(task, candidate, actionId) {
         initialState: 'evaluate',
         input: { transport: 'action', id: actionId, payload: {} },
         durableFacts: relatedTaskActionFacts(task, candidate),
+        graphName: 'task-related-action',
         isTransientState: state => state === 'check_other' || state === 'check_recovery',
         maxSteps: 3,
     });

package/dist/workflow/troubleshooter-v2.js

@@ -18,7 +18,7 @@ export const troubleshooterV2 = new GraphRuntime(source, {
 });
 export function dispatchTroubleshooter(facts, onCreate) {
     return dispatchWorkflowGraphSync(troubleshooterV2, {
-        initialState: 'idle', input: { transport: 'event', id: 'troubleshooter.reconcile', payload: {} }, durableFacts: facts,
+        initialState: 'idle', input: { transport: 'event', id: 'troubleshooter.reconcile', payload: {} }, durableFacts: facts, graphName: 'troubleshooter',
         isTransientState: state => state.startsWith('check_'), maxSteps: 6,
         executeAction: actionId => { if (actionId === 'troubleshooter.create')
             onCreate();

package/package.json

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

package/skills/agents-relay/contracts/orchestrator-workflows.md

@@ -37,3 +37,11 @@ A **P0 job** (alias: **self job**) is executed directly by the current active or
 6. After implementation and local verification, the orchestrator merges the job itself and completes normal post-merge reconciliation.
 
 `job create` still only creates durable job state; the P0 workflow requires the orchestrator to follow it immediately with task creation and execution.
+
+## Merge completion vs deployment evidence
+
+For a normal one-shot managed Job, the canonical Job lifecycle graph owns completion: a durable `pr.merged` fact transitions the Job to `COMPLETED`. Reconciler and deployment code must not invent a second completion gate after merge.
+
+Post-merge publication and deployment activity is separate from Job lifecycle. Events or evidence such as `package.published`, published version metadata, service restart, and deployment verification may be attached after the Job is already `COMPLETED`; they must not hold the Job open, reopen it, or redefine completion. If post-merge deployment needs remediation, record that as separate deployment/recovery work rather than mutating the completed implementation Job lifecycle.
+
+A PR closed without merge follows the same graph-owned rule through `pr.closed -> CANCELLED`.