agents-relay 2.0.171 → 2.0.172

package/dist/agent-content-resolver.js

@@ -95,53 +95,92 @@ function mergeSections(base, child) {
     }
     return result.trim();
 }
-/** Exactly two lookup layers: Relay built-ins and a single job context agents directory. */
-export async function resolveAgentMarkdown(name, builtinsRoot, contextRoot) {
+/** Resolve the visible agent through Relay, Neo shared, then project-local layers. */
+export async function resolveAgentMarkdown(name, builtinsRoot, contextRoot, neoRoot) {
     if (!/^[a-zA-Z0-9_-]+$/.test(name))
         throw new Error(`Invalid agent name ${name}`);
-    const builtin = join(builtinsRoot, `${name}.agent.md`);
-    const local = join(contextRoot, 'agents', `${name}.agent.md`);
-    const sources = [];
     const load = async (path, root) => {
         const canonical = await realpath(path);
         const canonicalRoot = await realpath(root);
         if (!(canonical === canonicalRoot || canonical.startsWith(canonicalRoot + '/')))
             throw new Error('Agent file escapes context root');
-        const source = parseDocument(await readFile(canonical, 'utf8'));
+        const raw = await readFile(canonical, 'utf8');
+        const source = parseDocument(raw);
         if (source.name && source.name !== name)
             throw new Error(`Agent name mismatch ${source.name} != ${name}`);
-        sources.push(canonical);
-        return source;
+        return { ...source, path: canonical, metadata: Object.fromEntries(raw.match(/^---\r?\n([\s\S]*?)\r?\n---/m)?.[1].split(/\r?\n/).flatMap(line => {
+                const field = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+                return field ? [[field[1], field[2].trim().replace(/^['"]|['"]$/g, '')]] : [];
+            }) ?? []) };
+    };
+    const loadLayer = async (root) => {
+        for (const suffix of ['.agent.md', '.md']) {
+            try {
+                return await load(join(root, `${name}${suffix}`), root);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        throw Object.assign(new Error('Agent file not found'), { code: 'ENOENT' });
     };
     let base;
     try {
-        base = await load(builtin, builtinsRoot);
-    }
-    catch (e) {
-        if (e.code !== 'ENOENT')
-            throw e;
-    }
-    let overlay;
-    try {
-        overlay = await load(local, contextRoot + '/agents');
+        base = await loadLayer(builtinsRoot);
     }
     catch (e) {
         if (e.code !== 'ENOENT')
             throw e;
     }
-    if (!base && !overlay)
-        throw new Error(`Unknown agent ${name}`);
-    if (overlay && (overlay.replace.length || overlay.extend.length) && !overlay.extendsAgent)
-        throw new Error('Section operations require extends');
-    if (overlay?.extendsAgent && overlay.extendsAgent !== `relay/${name}`)
-        throw new Error(`Only extends: relay/${name} is supported`);
-    if (overlay?.extendsAgent && !base)
-        throw new Error(`Missing Relay base for agent ${name}`);
-    if (overlay && base && !overlay.extendsAgent) { // explicit local definition without inheritance
-        if (overlay.replace.length || overlay.extend.length)
+    let effective = base;
+    let shared;
+    let sharedSources = [];
+    let sources = base ? [base.path] : [];
+    let metadata = { ...(base?.metadata ?? {}) };
+    for (const [layer, root] of [['neo', neoRoot], ['project', contextRoot]]) {
+        if (!root)
+            continue;
+        let overlay;
+        try {
+            overlay = await loadLayer(join(root, 'agents'));
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        if (!overlay)
+            continue;
+        const hasOperations = overlay.replace.length || overlay.extend.length;
+        if (hasOperations && !overlay.extendsAgent)
             throw new Error('Section operations require extends');
-        return { content: overlay.body, sources: [sources[sources.length - 1]], hash: createHash('sha256').update(overlay.body).digest('hex') };
+        if (overlay.extendsAgent && ![`relay/${name}`, `neo/${name}`].includes(overlay.extendsAgent))
+            throw new Error(`Only extends: relay/${name} or neo/${name} is supported`);
+        if (layer === 'neo' && overlay.extendsAgent === `neo/${name}`)
+            throw new Error(`Missing Neo base for agent ${name}`);
+        if (overlay.extendsAgent === `relay/${name}` && !base)
+            throw new Error(`Missing Relay base for agent ${name}`);
+        if (overlay.extendsAgent === `neo/${name}` && !shared)
+            throw new Error(`Missing Neo base for agent ${name}`);
+        if (!overlay.extendsAgent) {
+            effective = overlay;
+            metadata = {};
+            sources = [overlay.path];
+        }
+        else {
+            const parent = overlay.extendsAgent === `relay/${name}` ? base : overlay.extendsAgent === `neo/${name}` ? shared : effective;
+            effective = { ...overlay, body: mergeSections(parent.body, overlay) };
+            metadata = { ...parent.metadata };
+            sources = [...(overlay.extendsAgent === `relay/${name}` ? [base.path] : overlay.extendsAgent === `neo/${name}` ? sharedSources : sources), overlay.path];
+        }
+        Object.assign(metadata, overlay.metadata);
+        if (layer === 'neo') {
+            shared = effective;
+            sharedSources = [...sources];
+        }
     }
-    const content = overlay ? mergeSections(base?.body ?? '', overlay) : base.body;
-    return { content, sources, hash: createHash('sha256').update(content).digest('hex') };
+    if (!effective)
+        throw new Error(`Unknown agent ${name}`);
+    const content = effective.body;
+    return { content, metadata, sources, hash: createHash('sha256').update(content).digest('hex') };
 }

package/dist/cli.js

@@ -27,7 +27,7 @@ import { classifyFailedTask } from './task-actions.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { startServiceExternalActionFlusher } from './service-external-actions.js';
 import { handleServicePublication } from './service-publication.js';
-import { defaultWorkspaceRoot, ensureLocalJobSourceBranch, jobRequiresManagedWorktree, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
+import { ensureLocalJobSourceBranch, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath, resolveWorkspaceRoot, taskRequiresManagedWorktree } from './workspace.js';
 import { runBlockerCommand } from './cli-blocker.js';
 import { runEscalationCommand } from './cli-escalation.js';
 import { runProjectionCommand } from './cli-projection.js';
@@ -404,10 +404,8 @@ async function runContextCommand(action, args) {
     const roles = ['orchestrator', 'planner', 'reviewer', 'worker', 'nested-worker'];
     if (!roles.includes(roleValue))
         throw new Error('--role must be orchestrator, planner, reviewer, worker, or nested-worker');
-    const neoRootArg = arg(args, '--neo-root');
     const context = await resolveExecutionContext(projectPath, roleValue, {
         workspaceRoot: arg(args, '--workspace-root') || undefined,
-        neoRoot: neoRootArg === 'none' ? null : neoRootArg || undefined,
         globalRoot: arg(args, '--global-root') || undefined,
         explicitSkills: arg(args, '--skills').split(',').filter(Boolean),
         explicitAgents: arg(args, '--agents').split(',').filter(Boolean),
@@ -559,16 +557,23 @@ export function runtime(store, args, bus, usageRegistry = codexAndZaiUsageRegist
     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();
+    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, executionContextRoots: { workspaceRoot: arg(args, '--workspace-root') || process.env.AGENTS_RELAY_WORKSPACE_ROOT }, projectPathForJob: async (job, task) => {
+            const workspaceRoot = await resolveWorkspaceRoot(arg(args, '--workspace-root') || undefined);
             const canonical = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : job.repository, arg(args, '--project-path'), workspaceRoot);
-            if (!jobRequiresManagedWorktree(job))
+            if (!(task ? taskRequiresManagedWorktree(job, task) : Boolean(job.localMerge?.sourceRef)))
                 return resolveRepositoryProjectPath(canonical, job.projectPath);
-            const sourceRef = await ensureLocalJobSourceBranch(canonical, job);
+            const sourceRef = job.localMerge?.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() }));
+                if (!task || !store.mutateJob)
+                    throw new Error('Managed source branch binding requires an executing code Task and atomic SQLite mutation');
+                const bound = await store.mutateJob(job.id, current => {
+                    const activeTask = current.tasks.find(item => item.id === task.id);
+                    if (current.localMerge || current.state !== 'ACTIVE' || !activeTask || !['QUEUED', 'RUNNING'].includes(activeTask.state) || !taskRequiresManagedWorktree(current, activeTask))
+                        return current;
+                    return { ...current, localMerge: { sourceRef, targetRef: 'refs/heads/main', status: 'pending' }, updatedAt: new Date().toISOString() };
+                });
+                if (!bound.localMerge?.sourceRef)
+                    throw new Error('Job changed before managed source branch binding');
             }
             return prepareLocalJobExecutionWorktree(canonical, await store.load(job.id), workspaceRoot);
         } });

package/dist/execution-context.js

@@ -1,4 +1,5 @@
 import { resolveAgentMarkdown } from './agent-content-resolver.js';
+import { resolveWorkspaceRoot } from './workspace.js';
 import { access, readFile, readdir, realpath, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -25,22 +26,6 @@ async function directory(path) {
         return false;
     }
 }
-function configuredWorkspaceRoot(projectPath, explicit) {
-    const configured = explicit ?? process.env.AGENTS_RELAY_WORKSPACE_ROOT ?? process.env.XCHAT_WORKSPACE_ROOT;
-    if (configured)
-        return resolve(configured);
-    const conventional = join(homedir(), 'Workspace');
-    return isWithin(projectPath, conventional) ? conventional : dirname(projectPath);
-}
-async function configuredNeoRoot(workspaceRoot, explicit) {
-    if (explicit === null)
-        return null;
-    const configured = explicit ?? process.env.NEO_SHARED_ROOT;
-    if (configured)
-        return await directory(resolve(configured)) ? await realpath(resolve(configured)) : null;
-    const candidate = join(workspaceRoot, 'neo');
-    return await directory(candidate) ? await realpath(candidate) : null;
-}
 function configuredGlobalRoot(explicit) {
     return resolve(explicit ?? process.env.AGENTS_HOME ?? join(homedir(), '.agents'));
 }
@@ -176,9 +161,9 @@ export async function resolveExecutionContext(projectPath, role, options = {}) {
     const project = await realpath(resolve(projectPath)).catch(() => { throw new Error(`Project path not found: ${projectPath}`); });
     if (!await directory(project))
         throw new Error(`Project path is not a directory: ${projectPath}`);
-    const workspaceCandidate = configuredWorkspaceRoot(project, options.workspaceRoot);
-    const workspaceRoot = await realpath(workspaceCandidate).catch(() => workspaceCandidate);
-    const neoRoot = await configuredNeoRoot(workspaceRoot, options.neoRoot);
+    const workspaceRoot = await resolveWorkspaceRoot(options.workspaceRoot);
+    const neoCandidate = join(workspaceRoot, 'neo');
+    const neoRoot = await directory(neoCandidate) ? await realpath(neoCandidate) : neoCandidate;
     const globalCandidate = configuredGlobalRoot(options.globalRoot);
     const globalRoot = await realpath(globalCandidate).catch(() => globalCandidate);
     const layerRoots = [
@@ -197,28 +182,26 @@ export async function resolveExecutionContext(projectPath, role, options = {}) {
     }
     const skills = selectByName([...skillMap.values()].sort((a, b) => a.name.localeCompare(b.name)), options.explicitSkills, 'skill');
     const agentMap = new Map();
-    for (const agent of await agentFiles(dirname(BUNDLED_AGENTS_ROOT), 'builtin', []))
-        agentMap.set(agent.name, agent);
-    for (const agent of await agentFiles(project, 'project', [])) {
-        // An extending agent inherits the builtin identity metadata unless the project
-        // explicitly supplies a value. Local-only agents retain their own metadata.
-        const builtin = agentMap.get(agent.name);
-        if (builtin && agent.path) {
-            const { fields } = await metadata(agent.path);
-            if (fields.extends === `relay/${agent.name}`) {
-                agentMap.set(agent.name, {
-                    ...builtin, ...agent,
-                    description: fields.description === undefined ? builtin.description : agent.description,
-                    capabilities: fields.capabilities === undefined ? builtin.capabilities : agent.capabilities,
-                    runtime: fields.runtime === undefined && fields.runtimes === undefined ? builtin.runtime : agent.runtime,
-                    trustDomains: fields.trustDomains === undefined && fields.trust_domains === undefined && fields.trust === undefined ? builtin.trustDomains : agent.trustDomains,
-                    delegation: fields.delegation === undefined ? builtin.delegation : agent.delegation,
-                    restrictions: fields.restrictions === undefined && fields.boundaries === undefined ? builtin.restrictions : agent.restrictions,
-                });
-                continue;
-            }
-        }
-        agentMap.set(agent.name, agent);
+    const agentNames = new Set();
+    for (const [root, source] of [[dirname(BUNDLED_AGENTS_ROOT), 'builtin'], [neoRoot, 'neo'], [project, 'project']]) {
+        for (const agent of await agentFiles(root, source, []))
+            agentNames.add(agent.name);
+    }
+    for (const name of agentNames) {
+        const resolved = await resolveAgentMarkdown(name, BUNDLED_AGENTS_ROOT, project, neoRoot);
+        const fields = resolved.metadata;
+        const sourcePath = resolved.sources[resolved.sources.length - 1];
+        const source = sourcePath?.startsWith(project + '/') ? 'project'
+            : sourcePath?.startsWith(neoRoot + '/') ? 'neo' : 'builtin';
+        agentMap.set(name, {
+            name, path: sourcePath, source,
+            description: fields.description,
+            capabilities: listValue(fields.capabilities),
+            runtime: fields.runtime || listValue(fields.runtimes)[0] || undefined,
+            trustDomains: listValue(fields.trustDomains ?? fields.trust_domains ?? fields.trust),
+            delegation: listValue(fields.delegation),
+            restrictions: listValue(fields.restrictions ?? fields.boundaries),
+        });
     }
     for (const registration of options.registeredAgents ?? []) {
         if (agentMap.has(registration.name))
@@ -252,7 +235,7 @@ export async function resolveAgentContract(context, agentName) {
         throw new Error(`Agent ${agentName} is not visible in the resolved execution context`);
     if (!agent.path)
         throw new Error(`Agent ${agentName} has no readable Markdown contract`);
-    const resolved = await resolveAgentMarkdown(agentName, BUNDLED_AGENTS_ROOT, context.project.path);
+    const resolved = await resolveAgentMarkdown(agentName, BUNDLED_AGENTS_ROOT, context.project.path, context.project.neoRoot);
     const definition = resolved.content;
     if (!definition.trim())
         throw new Error(`Agent ${agentName} Markdown contract is empty`);

package/dist/reconciler-runtime.js

@@ -282,6 +282,7 @@ export class ReconcilerRuntimeBase {
                     ? 'worker_outcome_unknown' : platformFailure ? 'worker_platform_failure' : failureReason;
                 task.leaseOwner = null;
                 task.leaseExpiresAt = null;
+                task.executionId = null;
             },
         });
         if (!transition)

package/dist/reconciler.js

@@ -442,17 +442,11 @@ export class Reconciler extends ReconcilerReviewBase {
         let executionContext;
         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();
-            const canonicalProjectRun = taskUsesCanonicalProjectRun(task, job.tasks);
+            const projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(job, task) : task.routing?.cwd ?? process.cwd();
             executionContext = await this.resolvedContext(job, task, role, projectPath);
         }
         catch (error) {
-            task.leaseOwner = null;
-            task.leaseExpiresAt = null;
-            task.executionId = null;
-            await transitionTaskEvent(task, 'block');
-            task.error = `Execution checkout unavailable: ${error instanceof Error ? error.message : String(error)}`;
-            await this.store.saveTask(task);
+            await this.failLaunch(job.id, task.id, task.executionId, `Execution context unavailable: ${error instanceof Error ? error.message : String(error)}`);
             return;
         }
         const startedAt = Date.now();
@@ -460,7 +454,14 @@ export class Reconciler extends ReconcilerReviewBase {
         const controller = new AbortController();
         let execution;
         const sourceId = executionEventSource(job.id, task.id, durableExecutionId);
-        const baseWorkerInput = await managedWorkerInput(job, task, executionContext);
+        let baseWorkerInput;
+        try {
+            baseWorkerInput = await managedWorkerInput(job, task, executionContext);
+        }
+        catch (error) {
+            await this.failLaunch(job.id, task.id, task.executionId, `Execution contract unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
         const canonicalProjectRun = taskUsesCanonicalProjectRun(task, job.tasks);
         const workerInput = canonicalProjectRun
             ? `${baseWorkerInput}\n\n[Canonical Neo project run]\nExecution cwd: ${executionContext.project.path}\nKeep generated artifacts under runs/.`

package/dist/relayd-utilities.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { defaultWorkspaceRoot } from './workspace.js';
+import { resolve } from 'node:path';
 import { executionRouterRulesPath } from './routing-policy.js';
 import { RelayObservability, setObservability } from './observability.js';
 /** Initialize the process-wide structured observability sink once, from environment. */
@@ -37,7 +37,8 @@ Usage:
 Options:
   --no-github             Local-only mode: no GitHub auth, transport, PR, merge, or fetch
   --repo OWNER/REPO       Watch one repository
-  --workspace PATH        Discover repositories below PATH (default: ~/Workspace)
+  --workspace-root PATH  Workspace Root (default: AGENTS_RELAY_WORKSPACE_ROOT, shared Neo config, or ~/Workspace)
+  --workspace PATH       Legacy alias for --workspace-root
   --port PORT             Dashboard port (default: 8787)
   --concurrency N         Maximum concurrent workers (default: 4)
   --interval MS           Recovery interval
@@ -50,7 +51,7 @@ Legacy single-job mode also accepts --repo OWNER/REPO --pr NUMBER --id JOB_ID.
 
 Examples:
   npx agents-relayd --repo OWNER/REPO
-  npx agents-relayd --workspace ~/Workspace`;
+  npx agents-relayd --workspace-root ~/Workspace`;
 export function firstStageChoices(decisionInput) {
     const stages = decisionInput?.stages;
     if (!Array.isArray(stages) || stages.length === 0)
@@ -61,7 +62,10 @@ export function firstStageChoices(decisionInput) {
 export function value(args, name, fallback = '') { const index = args.indexOf(name); return index >= 0 ? args[index + 1] ?? fallback : fallback; }
 export function normalizeDaemonArguments(argv) {
     const repository = value(argv, '--repo') || null;
-    const workspaceRoot = value(argv, '--workspace', defaultWorkspaceRoot()) || null;
+    if (argv.includes('--workspace-root') && argv.includes('--workspace'))
+        throw new Error('--workspace-root and --workspace cannot both be supplied');
+    const workspaceRootValue = value(argv, '--workspace-root') || value(argv, '--workspace') || process.env.AGENTS_RELAY_WORKSPACE_ROOT;
+    const workspaceRoot = workspaceRootValue ? resolve(workspaceRootValue) : null;
     const prValue = value(argv, '--pr');
     const id = value(argv, '--id');
     if ((prValue && !id) || (!prValue && id))
@@ -73,7 +77,7 @@ export function normalizeDaemonArguments(argv) {
     const pullRequest = prValue ? Number(prValue) : null;
     if (pullRequest !== null && (!Number.isInteger(pullRequest) || pullRequest <= 0))
         throw new Error('--pr must be positive');
-    return { repository, workspaceRoot: repository ? null : workspaceRoot, pullRequest, jobId: id || null, serviceArguments: [...argv] };
+    return { repository, workspaceRoot, pullRequest, jobId: id || null, serviceArguments: [...argv] };
 }
 export function recoveryScanRepositories(repositories, cached, dormantProbeIndex = 0) {
     const byRepository = new Map();

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, jobRequiresManagedWorktree, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
+import { discoverWorkspaceRepositories, ensureLocalJobSourceBranch, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath, resolveWorkspaceRoot, taskRequiresManagedWorktree } from './workspace.js';
 import { deriveJobRuntimeStatus } from './runtime-status.js';
 import { createRuntimeStatusPublisher } from './runtime-status-events.js';
 import { subscribeLocalCommits } from './local-commit-events.js';
@@ -97,15 +97,16 @@ export async function runDaemon(argv) {
     const bus = eventResolution.bus;
     const stopRuntimeStatusEvents = bus ? subscribeLocalCommits(createRuntimeStatusPublisher(bus)) : () => { };
     process.stderr.write(`${eventBusResolutionMessage(eventResolution)}\n`);
-    const workspaceRoot = noGitHub ? (value(argv, '--project-path') || value(argv, '--workspace') || process.cwd())
-        : normalized.workspaceRoot ?? defaultWorkspaceRoot();
+    const workspaceRoot = await resolveWorkspaceRoot(normalized.workspaceRoot ?? undefined);
+    const explicitProjectPath = value(argv, '--project-path');
+    const localProjectPath = noGitHub && !explicitProjectPath && !argv.includes('--workspace') && !argv.includes('--workspace-root') && !process.env.AGENTS_RELAY_WORKSPACE_ROOT
+        ? process.cwd() : explicitProjectPath || workspaceRoot;
     const discoveredRepositories = normalized.repository || noGitHub ? [] : await discoverWorkspaceRepositories(workspaceRoot).catch(() => []);
-    const repositories = noGitHub && !normalized.repository ? [`local/${basename(workspaceRoot)}`] : normalized.repository ? [normalized.repository] : discoveredRepositories.map(item => item.repository);
+    const repositories = noGitHub && !normalized.repository ? [`local/${basename(localProjectPath)}`] : normalized.repository ? [normalized.repository] : discoveredRepositories.map(item => item.repository);
     const repositoryPaths = new Map(discoveredRepositories.map(item => [item.repository, item.path]));
     if (noGitHub)
         for (const repo of repositories)
-            repositoryPaths.set(repo, value(argv, '--project-path') || workspaceRoot);
-    const explicitProjectPath = value(argv, '--project-path');
+            repositoryPaths.set(repo, localProjectPath);
     const usageRegistry = codexAndZaiUsageRegistry();
     const decisionAuditStore = new JsonlDecisionAuditStore(process.env.AGENTS_RELAY_DECISION_AUDIT_PATH ?? join(homedir(), '.agents-relay', 'decision-audit.jsonl'));
     let cachedOverviews = [];
@@ -152,15 +153,24 @@ export async function runDaemon(argv) {
         return dashboardManagedJobs(entries.filter(item => !['COMPLETED', 'CANCELLED'].includes(item.job.state) || counts.get(item.job.id) !== 1));
     };
     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, escalationNotifier: escalationNotifierFromEnvironment(), reviewer: runtimeReviewer(argv), projectPathForJob: async (job) => {
+    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, escalationNotifier: escalationNotifierFromEnvironment(), reviewer: runtimeReviewer(argv), executionContextRoots: { workspaceRoot }, projectPathForJob: async (job, task) => {
             const canonical = repositoryPaths.get(job.repository) ?? await resolveManagedProjectPath(job.repository, explicitProjectPath, workspaceRoot);
-            if (!jobRequiresManagedWorktree(job))
+            if (!(task ? taskRequiresManagedWorktree(job, task) : Boolean(job.localMerge?.sourceRef)))
                 return resolveRepositoryProjectPath(canonical, job.projectPath);
-            const sourceRef = await ensureLocalJobSourceBranch(canonical, job);
-            if (!store.mutateJob)
-                throw new Error('Local Job branch binding requires atomic SQLite mutation');
-            const bound = 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, bound, workspaceRoot);
+            const sourceRef = job.localMerge?.sourceRef ?? await ensureLocalJobSourceBranch(canonical, job);
+            if (!job.localMerge?.sourceRef) {
+                if (!task || !store.mutateJob)
+                    throw new Error('Managed source branch binding requires an executing code Task and atomic SQLite mutation');
+                const bound = await store.mutateJob(job.id, current => {
+                    const activeTask = current.tasks.find(item => item.id === task.id);
+                    if (current.localMerge || current.state !== 'ACTIVE' || !activeTask || !['QUEUED', 'RUNNING'].includes(activeTask.state) || !taskRequiresManagedWorktree(current, activeTask))
+                        return current;
+                    return { ...current, localMerge: { sourceRef, targetRef: 'refs/heads/main', status: 'pending' }, updatedAt: new Date().toISOString() };
+                });
+                if (!bound.localMerge?.sourceRef)
+                    throw new Error('Job changed before managed source branch binding');
+            }
+            return prepareLocalJobExecutionWorktree(canonical, await store.load(job.id), workspaceRoot);
         } });
     const refreshAll = async (_full = false) => {
         cachedOverviews = await inventoryFromLocal();

package/dist/workspace.js

@@ -1,4 +1,4 @@
-import { lstat, mkdir, readdir, realpath, stat } from 'node:fs/promises';
+import { lstat, mkdir, readFile, readdir, realpath, stat } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
@@ -17,6 +17,46 @@ async function gitOutput(args) {
 export function defaultWorkspaceRoot() {
     return join(homedir(), 'Workspace');
 }
+export async function resolveWorkspaceRoot(explicit) {
+    let configured = explicit ?? process.env.AGENTS_RELAY_WORKSPACE_ROOT;
+    if (configured === undefined) {
+        const configPath = process.env.NEO_WORKSPACE_CONFIG ?? join(homedir(), '.config', 'neo', 'workspace.json');
+        let configText;
+        try {
+            configText = await readFile(configPath, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new Error(`Cannot read workspace configuration: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (configText !== undefined) {
+            let config;
+            try {
+                config = JSON.parse(configText);
+            }
+            catch {
+                throw new Error(`Invalid workspace configuration at ${configPath}: expected valid JSON`);
+            }
+            if (typeof config !== 'object' || config === null || !('schemaVersion' in config) || config.schemaVersion !== 1 || !('workspaceRoot' in config) || typeof config.workspaceRoot !== 'string' || !isAbsolute(config.workspaceRoot)) {
+                throw new Error(`Invalid workspace configuration at ${configPath}`);
+            }
+            configured = config.workspaceRoot;
+        }
+    }
+    // On first launch the default workspace may not exist yet. Only user-selected
+    // or saved roots are mandatory existing directories.
+    if (configured === undefined)
+        return defaultWorkspaceRoot();
+    const candidate = resolve(configured);
+    try {
+        if (!(await stat(candidate)).isDirectory())
+            throw new Error('not a directory');
+        return await realpath(candidate);
+    }
+    catch {
+        throw new Error(`Configured Workspace Root is not an accessible directory: ${candidate}`);
+    }
+}
 export function githubRepositoryFromRemote(remote) {
     const value = remote.trim().replace(/\.git$/, '');
     const match = value.match(/github\.com[/:]([^/]+)\/([^/]+)$/i);
@@ -193,6 +233,9 @@ export function managedLocalJobWorktreePath(repository, jobId, workspaceRoot = d
 export function jobRequiresManagedWorktree(job) {
     return !(job.prNumber > 0) && (Boolean(job.localMerge?.sourceRef) || job.tasks.some(task => task.output?.kind === 'task_pr'));
 }
+export function taskRequiresManagedWorktree(job, task) {
+    return jobRequiresManagedWorktree(job) && !(task && taskUsesCanonicalProjectRun(task, job.tasks));
+}
 /** 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.171",
+  "version": "2.0.172",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",

package/skills/agents-relay/contracts/event-contract.md

@@ -4,13 +4,15 @@
 
 ## Execution event source
 
-Every Task lifecycle event must identify the exact current Relay execution with:
+The Common Events Bus protocol (`<workspace>/neo/skills/events-bus/references/protocol.md`) owns the public `events.publish` input format. Its `source` field is a **string** identifying the exact current Relay execution:
 
 ```text
-source.id = job/<job-id>/task/<task-id>/execution/<execution-id>
+source = "job/<job-id>/task/<task-id>/execution/<execution-id>"
 ```
 
-Relay supplies this complete identity in the managed Task context. Agents must copy it unchanged; they must not infer a Job/Task ID, generate an execution ID, or reuse an identity from a previous attempt. The Neo `events.publish` tool accepts this value as its string `source` argument; the Events Bus event envelope represents it as `source.id`. Transport acceptance alone does not establish that Relay accepted the event for the current execution.
+When calling the Neo MCP command facade, pass `command: "publish"` and nest `type`, `source`, and `data` under `args`. Do not pass an object such as `{ "source": { "id": "..." } }`; `source.id` belongs only to the internal Events Bus envelope.
+
+Relay supplies the complete source string in the managed Task context. Agents must copy it unchanged; they must not infer a Job/Task ID, generate an execution ID, or reuse an identity from a previous attempt. Transport acceptance alone does not establish that Relay accepted the event for the current execution.
 
 ## Producer contract