agents-relay 2.0.54 → 2.0.56

package/dist/cli-escalation.js

@@ -1,37 +1,62 @@
 import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { textOption, arg } from './cli-support.js';
 import { runEscalationGraph } from './workflow/escalation.js';
-function runNeoEscalation(request) {
-    const args = ['escalation', '--intent', request.intent, '--blocked-on', request.blockedOn];
-    if (request.context)
-        args.push('--context', request.context);
-    if (request.onNeedsUser)
-        args.push('--on-needs-user', request.onNeedsUser);
-    if (request.cwd)
-        args.push('--cwd', request.cwd);
-    return new Promise((resolve, reject) => {
-        const child = spawn('neo', args, { cwd: request.cwd ?? process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
-        let stdout = '';
-        let stderr = '';
-        child.stdout.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
-        child.stderr.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
-        child.on('error', reject);
-        child.on('close', code => {
-            let parsed;
-            try {
-                parsed = JSON.parse(stdout.trim());
-            }
-            catch {
-                reject(new Error(`neo escalation returned invalid JSON (exit ${code ?? 'unknown'}): ${stderr || stdout}`));
-                return;
-            }
-            if (!['resolved', 'failed', 'needs_user'].includes(parsed.status)) {
-                reject(new Error(`neo escalation returned invalid status ${String(parsed.status)}`));
-                return;
-            }
-            resolve(parsed);
+export function neoEscalationArgs(handoffPath, policyPath, cwd) {
+    return [
+        'escalation', '--handoff-file', handoffPath,
+        ...(policyPath ? ['--on-needs-user-file', policyPath] : []),
+        ...(cwd ? ['--cwd', cwd] : []),
+    ];
+}
+function handoffText(request) {
+    return [
+        '# Intent', request.intent.trim(),
+        '', '# Blocked on', request.blockedOn.trim(),
+        ...(request.context?.trim() ? ['', '# Context', request.context.trim()] : []),
+        '',
+    ].join('\n');
+}
+export async function runNeoEscalation(request) {
+    const tempRoot = await mkdtemp(join(tmpdir(), 'agents-relay-escalation-'));
+    try {
+        const handoffPath = join(tempRoot, 'handoff.md');
+        await writeFile(handoffPath, handoffText(request), { encoding: 'utf8', mode: 0o600 });
+        let policyPath;
+        if (request.onNeedsUser) {
+            policyPath = join(tempRoot, 'on-needs-user.md');
+            await writeFile(policyPath, request.onNeedsUser, { encoding: 'utf8', mode: 0o600 });
+        }
+        const args = neoEscalationArgs(handoffPath, policyPath, request.cwd);
+        return await new Promise((resolve, reject) => {
+            const child = spawn('neo', args, { cwd: request.cwd ?? process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
+            child.stderr.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
+            child.on('error', reject);
+            child.on('close', code => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(stdout.trim());
+                }
+                catch {
+                    reject(new Error(`neo escalation returned invalid JSON (exit ${code ?? 'unknown'}): ${stderr || stdout}`));
+                    return;
+                }
+                if (!['resolved', 'failed', 'needs_user'].includes(parsed.status)) {
+                    reject(new Error(`neo escalation returned invalid status ${String(parsed.status)}`));
+                    return;
+                }
+                resolve(parsed);
+            });
         });
-    });
+    }
+    finally {
+        await rm(tempRoot, { recursive: true, force: true });
+    }
 }
 export async function runEscalationCommand(args) {
     const intent = await textOption(args, '--intent', '--intent-file');

package/dist/reconciler.js

@@ -14,7 +14,7 @@ import { executionEventSource, withExecutionBoundary } from './reconciler-runtim
 export { executionEventSource } from './reconciler-runtime.js';
 import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
 import { pendingTroubleshooterTasks } from './troubleshooter.js';
-import { prepareManagedExecutionWorktree } from './workspace.js';
+import { prepareManagedExecutionWorktree, taskUsesCanonicalProjectRun } from './workspace.js';
 import { createReviewChairExecutionPlan } from './review-chair.js';
 import { taskTagWorkerPrompt } from './task-tag.js';
 import { recoverExpiredExecutions, recoverStartupOrphans as recoverStartupExecutionOrphans } from './execution-recovery.js';
@@ -412,7 +412,8 @@ export class Reconciler extends ReconcilerReviewBase {
         try {
             const role = task.agentName === 'reviewer' ? 'reviewer' : task.agentName === 'troubleshooter' ? 'troubleshooter' : task.parentTaskId ? 'nested-worker' : 'worker';
             let projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(job) : task.routing?.cwd ?? process.cwd();
-            if (['codex', 'chatgpt'].includes(task.adapter) && this.store.pullRequestHead && task.executionId) {
+            const canonicalProjectRun = taskUsesCanonicalProjectRun(task, job.tasks);
+            if (['codex', 'chatgpt'].includes(task.adapter) && this.store.pullRequestHead && task.executionId && !canonicalProjectRun) {
                 managedHead = await this.store.pullRequestHead();
                 if (!managedHead)
                     throw new Error(`PR #${job.prNumber} has no resolvable head ref`);
@@ -435,9 +436,12 @@ export class Reconciler extends ReconcilerReviewBase {
         let execution;
         const sourceId = executionEventSource(job.id, task.id, durableExecutionId);
         const baseWorkerInput = await managedWorkerInput(job, task, executionContext);
+        const canonicalProjectRun = taskUsesCanonicalProjectRun(task, job.tasks);
         const workerInput = managedHead
             ? `${baseWorkerInput}\n\n[Managed PR checkout]\nExecution cwd: ${executionContext.project.path}\nExpected PR head: ${managedHead.ref} @ ${managedHead.sha}\nThis checkout is isolated from the user's primary checkout. Commit only here. Push durable changes with: git push origin HEAD:${managedHead.ref}\nDo not switch, reset, merge into, or commit on the primary checkout.`
-            : baseWorkerInput;
+            : canonicalProjectRun
+                ? `${baseWorkerInput}\n\n[Canonical Neo project run]\nExecution cwd: ${executionContext.project.path}\nThis Task owns or descends from a durable runs/ artifact. Work directly in this canonical project directory so all continuations, reviews, QA, and publication steps share the same runs/ evidence. Do not create or switch to an Agents Relay task worktree for this runtime work. Keep generated/private execution artifacts under runs/ and do not commit them.`
+                : baseWorkerInput;
         const workerTask = { ...task, input: workerInput, routing: task.routing ? { ...task.routing, cwd: executionContext.project.path } : task.routing };
         const startAckSetup = task.adapter === 'chatgpt' ? await this.startAck(job.id, task.id, sourceId, Date.now(), this.options.startAckTimeoutMs ?? chatGptStartAckTimeoutMs(task.timeoutMs)) : null;
         const closePolicy = task.chatgptTabClosePolicy ?? this.options.chatgptTabClosePolicy ?? adapter.tabClosePolicy ?? 'after-start';

package/dist/workspace.js

@@ -92,6 +92,24 @@ export function resolveRepositoryProjectPath(repositoryRoot, projectPath) {
         throw new Error('Job projectPath escapes repository root');
     return target;
 }
+export function isProjectRunPath(path) {
+    if (!path)
+        return false;
+    const normalized = path.replace(/\\/g, '/').replace(/^\.\//, '');
+    return normalized === 'runs' || normalized.startsWith('runs/');
+}
+export function taskUsesCanonicalProjectRun(task, tasks) {
+    const byId = new Map(tasks.map(item => [item.id, item]));
+    const seen = new Set();
+    let current = task;
+    while (current && !seen.has(current.id)) {
+        seen.add(current.id);
+        if (current.output?.kind === 'file' && isProjectRunPath(current.output.path))
+            return true;
+        current = current.parentTaskId ? byId.get(current.parentTaskId) : undefined;
+    }
+    return false;
+}
 async function git(path, args) {
     return (await execFileAsync('git', ['-C', path, ...args])).stdout.trim();
 }

package/package.json

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

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

@@ -125,6 +125,20 @@ The scheduler heartbeat filters cached managed Jobs, reloads each due Job to val
 
 ## Task evidence and head identity
 
+### Canonical Neo Project runs boundary
+
+`runs/` is durable runtime evidence, not source code and not temporary checkout state. When a Task's declared file output is under `runs/`, that Task and every semantic descendant execute directly in the canonical resolved project directory. Agents Relay MUST NOT create or switch those Tasks into per-execution Git worktrees.
+
+This is a strong execution boundary:
+
+- tracked source/code work may use a managed PR worktree;
+- Neo Project runtime work under `runs/` uses the canonical project directory;
+- continuations, reviews, QA, render, and publication Tasks beneath a `runs/` owner reuse that same canonical runtime directory;
+- `runs/` remains ignored/private and must not be committed merely to move evidence between Tasks;
+- a new Task/worktree must never make prior run evidence disappear.
+
+For example, a `neo-build-log` episode whose output is `runs/2026-10-02/package.md` executes in the canonical `neo/neo-build-log` project directory, and its review/render/publish descendants see the same `runs/2026-10-02/` tree.
+
 Task inputs must make evidence freshness and target identity explicit when those facts affect correctness. A Task may bind its own review, audit, or source evidence to an immutable SHA/version. That frozen target belongs to that Task; it must not be propagated mechanically into later dependent work. A downstream release, deploy, publication, or other Task that runs after dependencies complete must resolve the current durable Job/PR head at execution time unless the Job objective explicitly requires the earlier immutable target.
 
 When success depends on the actual current UI, browser state, store listing, runtime state, or another externally observable surface, the Task contract must require fresh evidence from that real current surface. Reusing an existing screenshot, prepared asset, cached observation, or older evidence is valid only when the Job explicitly permits it.