agents-relay 2.0.79 → 2.0.81

package/README.md

@@ -336,3 +336,7 @@ permissions:
 The caller must report only a release it has actually verified. For local-first Jobs, the action reads the Job ID and optional display PR from the authoritative local-merge commit message and posts the compatible `agents-relay:package-published:v1` or publish-failure marker to that display PR or to a reusable publication issue. Historical GitHub-merged PR correlation remains supported as a fallback. The marker and GitHub webhook are transport/correlation only: Agents Relay resolves the originating Job and persists publication facts through `RelayStore.recordPublication(...)` into the authoritative SQLite `publication_delivery` and `publication_state` tables. Publication success or failure never changes a completed Job's lifecycle state.
 
 `artifact` can identify an npm/PyPI package, Chrome extension, GitHub Release artifact, or a custom published artifact. `channel` identifies the registry/store/release channel and is displayed as publication metadata. Repeated reports of the same artifact/version are idempotent.
+
+### Project-scoped agent Markdown inheritance
+
+Agent lookup has exactly two layers: Relay built-in `skills/agents-relay/agents/` and `<job-context-root>/agents/`. `job.projectPath` selects the context root within the repository (including monorepo content projects); no workspace/global agent fallback is searched. Project agent frontmatter can specify `extends: relay/planner`, `mode: extend`, and `sections: { replace: [Heading/Subheading], extend: [Other Heading] }` using heading paths, or `mode: replace` for a full behavioral replacement. Relay-owned lifecycle, Job/Task and events contracts are injected separately and cannot be replaced by a project agent. An unextended local agent is a standalone definition. The resolver emits a deterministic SHA-256 of composed Markdown; a missing section or unsupported parent fails instead of silently dropping instructions.

package/dist/agent-content-resolver.js

@@ -0,0 +1,147 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+const parseList = (raw) => raw.trim().replace(/^\[/, '').replace(/\]$/, '').split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+/** Restrict the frontmatter grammar to the explicitly supported scalar/list fields. */
+function parseDocument(raw) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
+    if (!match)
+        return { body: raw.trim(), name: undefined, extendsAgent: undefined, mode: undefined, replace: [], extend: [] };
+    const lines = match[1].split(/\r?\n/);
+    let name, extendsAgent, mode;
+    const sections = { replace: [], extend: [] };
+    let inSections = false;
+    for (const line of lines) {
+        const field = /^(name|extends|mode|sections):\s*(.*)$/.exec(line);
+        if (field) {
+            inSections = field[1] === 'sections';
+            if (field[1] === 'name')
+                name = field[2].trim();
+            if (field[1] === 'extends')
+                extendsAgent = field[2].trim();
+            if (field[1] === 'mode') {
+                if (!['extend', 'replace'].includes(field[2].trim()))
+                    throw new Error(`Invalid agent mode: ${field[2]}`);
+                mode = field[2].trim();
+            }
+        }
+        else if (inSections) {
+            const entry = /^  (replace|extend):\s*(.+)$/.exec(line);
+            if (entry)
+                sections[entry[1]] = parseList(entry[2]);
+            else if (/^\S/.test(line))
+                inSections = false;
+        }
+    }
+    return { body: raw.slice(match[0].length).trim(), name, extendsAgent, mode, replace: sections.replace, extend: sections.extend };
+}
+function indexSections(lines) {
+    const sections = new Map();
+    const stack = [];
+    let fence = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*(```|~~~)/.test(lines[i])) {
+            fence = !fence;
+            continue;
+        }
+        if (fence)
+            continue;
+        const heading = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(lines[i]);
+        if (!heading)
+            continue;
+        const level = heading[1].length;
+        while (stack.length && stack[stack.length - 1].level >= level)
+            stack.pop();
+        const path = [...stack.map(x => x.title), heading[2].trim()].join('/');
+        if (sections.has(path))
+            throw new Error(`Ambiguous Markdown section ${path}`);
+        for (const section of sections.values())
+            if (section.end === lines.length && section.level >= level)
+                section.end = i;
+        sections.set(path, { path, start: i, end: lines.length, level });
+        stack.push({ title: heading[2].trim(), level });
+    }
+    return sections;
+}
+function mergeSections(base, child) {
+    if (child.mode === 'replace') {
+        if (child.replace.length || child.extend.length)
+            throw new Error('Whole-agent replace cannot contain sections overrides');
+        return child.body;
+    }
+    const operations = [...child.replace.map(path => ({ path, mode: 'replace' })), ...child.extend.map(path => ({ path, mode: 'extend' }))];
+    const seen = new Set();
+    for (const op of operations) {
+        if (seen.has(op.path))
+            throw new Error(`Conflicting section operation: ${op.path}`);
+        seen.add(op.path);
+    }
+    if (!operations.length)
+        return `${base.trim()}\n\n${child.body}`.trim();
+    let result = base;
+    for (const op of operations) {
+        const originalLines = result.split('\n');
+        const childLines = child.body.split('\n');
+        const target = indexSections(originalLines).get(op.path);
+        const source = indexSections(childLines).get(op.path);
+        if (!target || !source)
+            throw new Error(`Section ${op.path} missing in ${!target ? 'base' : 'overlay'} contract`);
+        const subsection = childLines.slice(source.start, source.end);
+        if (op.mode === 'replace')
+            originalLines.splice(target.start, target.end - target.start, ...subsection);
+        else
+            originalLines.splice(target.end, 0, ...subsection.slice(1));
+        result = originalLines.join('\n');
+    }
+    return result.trim();
+}
+/** Exactly two lookup layers: Relay built-ins and a single job context agents directory. */
+export async function resolveAgentMarkdown(name, builtinsRoot, contextRoot) {
+    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'));
+        if (source.name && source.name !== name)
+            throw new Error(`Agent name mismatch ${source.name} != ${name}`);
+        sources.push(canonical);
+        return source;
+    };
+    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');
+    }
+    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)
+            throw new Error('Section operations require extends');
+        return { content: overlay.body, sources: [sources[sources.length - 1]], hash: createHash('sha256').update(overlay.body).digest('hex') };
+    }
+    const content = overlay ? mergeSections(base?.body ?? '', overlay) : base.body;
+    return { content, sources, hash: createHash('sha256').update(content).digest('hex') };
+}

package/dist/cli-help.js

@@ -58,13 +58,13 @@ Required: --repo OWNER/REPO --pr NUMBER --id JOB_ID.
 Optional: --thread-id THREAD_ID persists a reviewer override; omitted uses Job reviewer/creator thread or legacy route. Rejects pending reviews and wakes managed reconciliation.`,
     'job create': `Create a SQLite-authoritative Job.
 
-Required: --repo OWNER/REPO, --id JOB_ID, and either --head BRANCH or --pr NUMBER.
-With --head, bind the local source branch and use --base as its local merge target without a GitHub query. With --pr, bind an existing external PR reference as optional metadata without a GitHub query.
-Common: --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --mode fixed|autonomous, --initial-plan, --no-review, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID, --implementation-thread-id ID. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
+Required: --repo OWNER/REPO and a standalone Job objective (unless binding an existing PR). Job ID defaults to an auto-incrementing repository-scoped number; --id is optional for compatibility.
+With --head, bind the local source branch and use --base as its local merge target without a GitHub query. With --pr, bind an existing external PR reference as optional metadata without a GitHub query. Without either, create a local-first content Job; local Job completion still follows the configured Graph lifecycle.
+Common: --id JOB_ID (optional), --idempotency-key KEY (for retries), --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --mode fixed|autonomous, --initial-plan, --no-review, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID, --implementation-thread-id ID. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
 Job creation always enables auto-merge. By default it is create-only; --initial-plan follows durable Job creation with the first real Planner round, activates the Job, and publishes the normal wake so Relay can continue without a second orchestrator command. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
 
 Example:
-  npx agents-relay job create --repo OWNER/REPO --head feat/example --base main --id job-1 --title "Objective" --objective-file job.md --initial-plan`,
+  npx agents-relay job create --repo OWNER/REPO --project-path vlog --title "Episode" --objective-file episode.md --idempotency-key submission-123 --initial-plan`,
     'job update': `Partially update mutable metadata on a healthy existing Job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
@@ -116,11 +116,11 @@ Actions:
     'task create': `Create one durable Task under an existing Job.
 
 Required: normal Job storage options plus --input-file PATH|- (preferred) or --input MARKDOWN, and --output task-pr|file. --input and --input-file are mutually exclusive.
-Common: --task-id ID, --priority P0|P1|P2|P3, --story-size S|M|L, --agent NAME, --agent-graph-file PATH|-, --deps a,b, --parent ID, --draft. Normal model-backed Tasks omit adapter/provider/model so Relay runs one Execution Router decision over complete worker+model routes. Use --adapter orchestrator only for synchronous self-work; explicit adapter/provider/model remain compatibility/debug constraints.\nTasks with dependencies start DRAFT; tasks without dependencies start QUEUED unless --draft is given.
+Common: --task-id ID (optional; Relay auto-assigns repository-scoped task number), --idempotency-key KEY, --priority P0|P1|P2|P3, --story-size S|M|L, --agent NAME, --agent-graph-file PATH|-, --deps a,b, --parent ID, --draft. Normal model-backed Tasks omit adapter/provider/model so Relay runs one Execution Router decision over complete worker+model routes. Use --adapter orchestrator only for synchronous self-work; explicit adapter/provider/model remain compatibility/debug constraints.\nTasks with dependencies start DRAFT; tasks without dependencies start QUEUED unless --draft is given.
 Directly-created Tasks are not wrapped in a synthetic Plan. Planner-generated Tasks are created internally by Relay from planner output.
 
 Example:
-  npx agents-relay task create --repo OWNER/REPO --pr 12 --id job-1 --task-id build --output task-pr --input-file task.md`,
+  npx agents-relay task create --repo OWNER/REPO --id j-5-owner-repo-1 --output file --output-path story.md --input-file task.md`,
     'task update': `Update mutable durable Task fields in place.
 
 Required: --task-id ID and the normal Job storage options.

package/dist/cli-job-create.js

@@ -1,3 +1,4 @@
+import { allocateEntityId, isGeneratedEntityId } from './job-task-id-sequence.js';
 import { openLocalManagedStore } from './local-managed-store.js';
 import { createJobEntity } from './workflow/entity-creation.js';
 import { normalizeThreadId } from './reviewer-thread.js';
@@ -7,30 +8,36 @@ import { discoverLocalRelayStoreSnapshots, relayStoreDirectory } from './relay-s
  * required; an explicit PR number is optional external metadata.
  */
 export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAuthors, options) {
-    if (!options.id)
-        throw new Error('--id is required for managed local Jobs');
+    const directory = options.storeDirectory ?? relayStoreDirectory();
+    const knownJobs = (await discoverLocalRelayStoreSnapshots(directory)).flatMap(snapshot => snapshot.jobs);
+    const id = options.id || allocateEntityId(directory, repositoryName, 'job', options.idempotencyKey, new Set(knownJobs.map(job => job.id)));
     const requestedNumber = options.prNumber ?? 0;
     if (!Number.isInteger(requestedNumber) || requestedNumber < 0)
         throw new Error('Invalid external PR binding number');
-    const placeholder = { number: requestedNumber, title: options.title ?? options.id,
+    const placeholder = { number: requestedNumber, title: options.title ?? id,
         body: options.body ?? options.objective ?? '', state: 'OPEN', head: options.head ?? '', base: options.base ?? '' };
-    const directory = options.storeDirectory ?? relayStoreDirectory();
-    const alreadyKnown = (await discoverLocalRelayStoreSnapshots(directory)).flatMap(snapshot => snapshot.jobs.filter(job => job.id === options.id).map(job => ({ job, path: snapshot.path })));
+    const alreadyKnown = knownJobs.filter(job => job.id === id);
     if (alreadyKnown.length > 1)
-        throw new Error('Duplicate immutable Job ID across SQLite stores: ' + options.id);
+        throw new Error('Duplicate immutable Job ID across SQLite stores: ' + id);
     if (alreadyKnown.length === 1) {
-        const existing = alreadyKnown[0].job;
+        const existing = alreadyKnown[0];
         if (existing.repository !== repositoryName || (options.prNumber !== undefined && existing.prNumber !== requestedNumber))
             throw new Error('Immutable Job ID is already bound to a different repository or external PR');
+        if (!options.id && !options.idempotencyKey)
+            throw new Error('Automatically allocated Job ID unexpectedly belongs to an existing Job');
+        if (options.idempotencyKey && ((options.objective && options.objective !== existing.objective) || (options.projectPath && options.projectPath !== existing.projectPath) || (options.title && options.title !== existing.title)))
+            throw new Error('Job idempotency key reused for a different Job definition');
         return { job: existing, pr: { ...placeholder, number: existing.prNumber } };
     }
+    if (options.id && isGeneratedEntityId(id, repositoryName, 'job'))
+        throw new Error('Reserved auto-generated Job ID cannot be assigned manually');
     const pr = placeholder;
     const number = pr.number;
     const local = openLocalManagedStore(repositoryName, number, {
-        directory, jobId: options.id, noGitHub: true,
+        directory, jobId: id, noGitHub: true,
     });
     try {
-        const existing = await local.relay.loadJob(options.id);
+        const existing = await local.relay.loadJob(id);
         if (existing)
             return { job: existing, pr };
         const now = new Date().toISOString();
@@ -41,7 +48,7 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
             throw new Error('Job base must always be main');
         const localMergeTarget = localMergeSource ? 'refs/heads/main' : undefined;
         const job = createJobEntity({
-            id: options.id,
+            id,
             title: options.title || pr.title || 'Agents Relay job',
             objective: options.objective || pr.body || undefined,
             projectPath: options.projectPath,
@@ -70,7 +77,7 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
             ...(options.schedule ? { schedule: options.schedule } : {}),
         }, { activate: Boolean(options.schedule) });
         await local.store.saveJob(job);
-        return { job: await local.store.load(options.id), pr };
+        return { job: await local.store.load(id), pr };
     }
     finally {
         local.relay.close();

package/dist/cli.js

@@ -45,8 +45,8 @@ async function runManagedTaskCommand(action, args) {
     const jobId = arg(args, '--id');
     if (!jobId)
         throw new Error('--id is required for managed task commands');
-    const id = arg(args, '--task-id', action === 'create' ? randomUUID() : '');
-    if (!id)
+    let id = arg(args, '--task-id');
+    if (!id && action !== 'create')
         throw new Error(`task ${action} requires --task-id`);
     let result;
     if (action === 'create') {
@@ -55,7 +55,9 @@ async function runManagedTaskCommand(action, args) {
             throw new Error(`Cannot create task on terminal job ${job.id} (${job.state})`);
         const task = await workerTaskFromArgs(job, args, new Date().toISOString());
         task.id = id;
-        result = await relayTaskCommand(args, { jobId, action, task });
+        result = await relayTaskCommand(args, { jobId, action, task, idempotencyKey: arg(args, '--idempotency-key') || undefined });
+        if (!id)
+            id = result.createdTaskId ?? '';
     }
     else if (action === 'complete') {
         const summary = arg(args, '--summary');
@@ -81,7 +83,7 @@ async function runTaskCommand(action, args) {
             console.log(JSON.stringify(job.tasks, null, 2));
             return;
         }
-        const taskId = arg(args, '--task-id', action === 'create' ? randomUUID() : '');
+        const taskId = arg(args, '--task-id');
         if (action === 'show') {
             if (!taskId)
                 throw new Error('task show requires --task-id');
@@ -367,7 +369,7 @@ async function runJobCommand(action, args) {
         return;
     }
     const id = arg(args, '--id');
-    if (!id)
+    if (!id && action !== 'create')
         throw new Error('--id is required for managed local Jobs');
     const prValue = arg(args, '--pr');
     const prNumber = prValue ? Number(prValue) : 0;
@@ -378,7 +380,7 @@ async function runJobCommand(action, args) {
         if (hasArg(args, '--local-merge-source') !== hasArg(args, '--local-merge-target'))
             throw new Error('Supply both --local-merge-source and --local-merge-target');
         const result = await relayControlCommand(args, { command: 'job.create', repository: repo, initialPlan: hasArg(args, '--initial-plan'), options: {
-                id, title: arg(args, '--title') || undefined, objective: objective || undefined, projectPath: arg(args, '--project-path') || undefined,
+                id: id || undefined, idempotencyKey: arg(args, '--idempotency-key') || undefined, title: arg(args, '--title') || undefined, objective: objective || undefined, projectPath: arg(args, '--project-path') || undefined,
                 priority: priority(args), executionMode: requestedExecutionMode(args), schedule: scheduleFromArgs(args), tag: jobTagFromArgs(args), reviewEnabled: !hasArg(args, '--no-review'), continuation: continuation(args),
                 reviewerThreadId: hasArg(args, '--reviewer-thread-id') ? arg(args, '--reviewer-thread-id') : undefined, creatorThreadId: hasArg(args, '--creator-thread-id') ? arg(args, '--creator-thread-id') : undefined, implementationThreadId: hasArg(args, '--implementation-thread-id') ? arg(args, '--implementation-thread-id') : undefined,
                 prNumber, head: arg(args, '--head') || undefined, base: arg(args, '--base', 'main'), body: arg(args, '--body') || objective || undefined,

package/dist/dashboard-html.js

@@ -335,7 +335,7 @@ function field(label,input){const box=element('div','detail-group');box.append(e
 function markdownField(label,input){const box=element('div','detail-group');box.append(element('p','detail-label',text(label)),markdownValue(input));return box;}
 function rememberSelection(){if(selectedJob)sessionStorage.setItem('agents-relay:selected-job',selectedJob);else sessionStorage.removeItem('agents-relay:selected-job');if(selectedTaskId)sessionStorage.setItem('agents-relay:selected-task',selectedTaskId);else sessionStorage.removeItem('agents-relay:selected-task');}
 function syncMobileJobsView(){const detail=mobileJobs.matches&&Boolean(selectedJob)&&location.hash.startsWith('#/jobs/');document.body.dataset.mobileJobsView=detail?'detail':'list';}
-function jobSelectionKey(job){return job?String(job.repository||'')+'|'+String(job.prNumber||'')+'|'+String(job.id||''):'';}
+function shortManagedId(id,repository,kind){const parts=String(repository||'').split('/');if(parts.length!==2)return String(id||'');const prefix=kind+'-'+parts[0].length+'-'+parts[0]+'-'+parts[1]+'-';const value=String(id||'');const suffix=value.startsWith(prefix)?value.slice(prefix.length):'';return /^[0-9]+$/.test(suffix)?'#'+suffix:value;}function jobSelectionKey(job){return job?String(job.repository||'')+'|'+String(job.prNumber||'')+'|'+String(job.id||''):'';}
 function jobForSelection(selection){return jobs.find(job=>jobSelectionKey(job)===selection)||jobs.find(job=>job.id===selection)||null;}
 function selected(){return jobForSelection(selectedJob)||jobs[0]||null;}
 function counts(tasks){const out={};for(const task of Array.isArray(tasks)?tasks:[])out[task.state]=(out[task.state]||0)+1;return out;}
@@ -355,7 +355,7 @@ async function loadEventHistory(){const job=selected();if(!job){clearEvents();re
 function copySelectedJobIdentity(job){if(!job||!navigator.clipboard?.writeText)return;void navigator.clipboard.writeText(jobChatRef(job)).catch(()=>{});}
 function selectJob(job){selectedJob=jobSelectionKey(job);selectedTaskId=null;eventTaskId=null;rememberSelection();clearEvents();location.hash=selectedJob?'#/jobs/'+encodeURIComponent(selectedJob):'#/jobs';copySelectedJobIdentity(job);renderAll();void loadEventHistory();}
 function matchesQuickFilter(job){if(quickMode==='autonomous')return job.executionMode==='autonomous';if(quickMode==='draft')return job.draft||job.state==='DRAFT';if(quickMode==='status')return !!selectedRuntimeStatus&&(job.runtimeStatus||'IDLE')===selectedRuntimeStatus;return true;}
-function matchesSearch(job){const query=searchQuery.trim().toLowerCase();if(!query)return true;const pr=String(job.prNumber||'');const normalized=query.replace(/^pr\s*#?/,'').replace(/^#/,'');return String(job.title||job.id||'').toLowerCase().includes(query)||pr.includes(normalized);}
+function matchesSearch(job){const query=searchQuery.trim().toLowerCase();if(!query)return true;const pr=String(job.prNumber||'');const normalized=query.replace(/^pr\s*#?/,'').replace(/^#/,'');return String(job.title||job.id||'').toLowerCase().includes(query)||String(job.id||'').toLowerCase().includes(query)||shortManagedId(job.id,job.repository,'j').toLowerCase().includes(query)||pr.includes(normalized);}
 function filteredJobs(){return jobs.filter(job=>(!selectedRepo||job.repository===selectedRepo)&&matchesQuickFilter(job)&&matchesSearch(job));}
 function setQuickMode(mode,status=''){quickMode=mode;selectedRuntimeStatus=mode==='status'?status:'';sessionStorage.setItem('agents-relay:quick-filter',quickMode);if(selectedRuntimeStatus)sessionStorage.setItem('agents-relay:runtime-status-filter',selectedRuntimeStatus);else sessionStorage.removeItem('agents-relay:runtime-status-filter');syncFilters();renderJobList();}
 function toggleQuickMode(mode){setQuickMode(quickMode===mode?'jobs':mode);}
@@ -388,10 +388,10 @@ function jobChatRef(job){const pr=Number(job?.externalPrNumber||job?.prNumber||0
 function chatShortcutUrl(prompt){return 'https://chatgpt.com/?prompt='+encodeURIComponent(prompt);}
 const CHAT_SHORTCUT_TARGET='agents-relay-shortcut';
 function chatShortcutField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('ChatGPT shortcut')));const select=document.createElement('select');select.className='job-filter job-chat-shortcut-select';select.setAttribute('aria-label','ChatGPT shortcut');select.append(new Option('',''));for(const item of parseChatShortcuts(chatShortcutText()))select.append(new Option(item.name,item.prompt));select.value='';select.addEventListener('change',()=>{if(!select.value)return;const prompt=select.value.replaceAll('%1',jobChatRef(job));window.open(chatShortcutUrl(prompt),CHAT_SHORTCUT_TARGET,'noopener');select.value='';});box.append(select);return box;}
-function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected repo.')));return;}for(const job of visible){const row=element('div','job-row'+(isCompleteUnmerged(job)?' complete-unmerged':''));row.setAttribute('aria-current',String(jobSelectionKey(job)===selectedJob));row.addEventListener('click',()=>selectJob(job));const content=element('div','job-content');const select=document.createElement('button');select.type='button';select.className='job-button';select.setAttribute('aria-current',String(jobSelectionKey(job)===selectedJob));select.title=job.title||job.id;select.addEventListener('click',event=>{event.stopPropagation();selectJob(job);});select.append(element('span','job-title',text(repoName(job.repository)+'/'+(Number(job.externalPrNumber||job.prNumber||0)>0?'PR#'+value(job.externalPrNumber||job.prNumber):'Job '+value(job.id))+': '+value(job.title||job.id))));const states=element('span','job-status-line');states.append(element('span','badge '+value(job.state),text(value(job.state))),element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))));if(job.publicationFailure)states.append(element('span','badge FAILED',text('PUBLISH FAILED: '+value(job.publicationFailure.stage))));else if(job.publication?.version)states.append(element('span','badge SUCCEEDED',text('v'+job.publication.version)));else if(Number(job.externalPrNumber||0)>0&&job.githubState==='MERGED')states.append(element('span','badge MERGED',text('PR Merged')));else if(job.state==='COMPLETED'&&job.githubState==='CLOSED')states.append(element('span','badge SUCCEEDED',text('PR Archived')));if(job.executionMode==='autonomous')states.append(element('span','badge flag-autonomous',text('AUTONOMOUS')));if(job.state==='ACTIVE'&&job.reviewEnabled!==false)states.append(element('span','badge flag-review',text('REVIEW REQUIRED')));if(isCompleteUnmerged(job))states.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));const primary=element('div','job-primary');primary.append(states);const lastLine=element('div','job-last-line');lastLine.append(element('span','subtle',text(compactCounts(counts(job.tasks)))),element('span','subtle',text(relativeTime(job.updatedAt))));content.append(select,primary,lastLine);row.append(content);jobList.append(element('li','',row));}}
+function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected repo.')));return;}for(const job of visible){const row=element('div','job-row'+(isCompleteUnmerged(job)?' complete-unmerged':''));row.setAttribute('aria-current',String(jobSelectionKey(job)===selectedJob));row.addEventListener('click',()=>selectJob(job));const content=element('div','job-content');const select=document.createElement('button');select.type='button';select.className='job-button';select.setAttribute('aria-current',String(jobSelectionKey(job)===selectedJob));select.title=job.title||job.id;select.addEventListener('click',event=>{event.stopPropagation();selectJob(job);});select.append(element('span','job-title',text(repoName(job.repository)+'/'+(Number(job.externalPrNumber||job.prNumber||0)>0?'PR#'+value(job.externalPrNumber||job.prNumber):'Job '+shortManagedId(job.id,job.repository,'j'))+': '+value(job.title||job.id))));const states=element('span','job-status-line');states.append(element('span','badge '+value(job.state),text(value(job.state))),element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))));if(job.publicationFailure)states.append(element('span','badge FAILED',text('PUBLISH FAILED: '+value(job.publicationFailure.stage))));else if(job.publication?.version)states.append(element('span','badge SUCCEEDED',text('v'+job.publication.version)));else if(Number(job.externalPrNumber||0)>0&&job.githubState==='MERGED')states.append(element('span','badge MERGED',text('PR Merged')));else if(job.state==='COMPLETED'&&job.githubState==='CLOSED')states.append(element('span','badge SUCCEEDED',text('PR Archived')));if(job.executionMode==='autonomous')states.append(element('span','badge flag-autonomous',text('AUTONOMOUS')));if(job.state==='ACTIVE'&&job.reviewEnabled!==false)states.append(element('span','badge flag-review',text('REVIEW REQUIRED')));if(isCompleteUnmerged(job))states.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));const primary=element('div','job-primary');primary.append(states);const lastLine=element('div','job-last-line');lastLine.append(element('span','subtle',text(compactCounts(counts(job.tasks)))),element('span','subtle',text(relativeTime(job.updatedAt))));content.append(select,primary,lastLine);row.append(content);jobList.append(element('li','',row));}}
 function taskTagDisplay(job,task){const display=task.tag&&job?.tag?.values?.[task.tag];return typeof display==='string'&&display?display:null;}
 function taskSubtreeComplete(task,children){return ['SUCCEEDED','CANCELLED'].includes(task.state)&&(children.get(task.id)||[]).every(child=>taskSubtreeComplete(child,children));}
-function taskNode(task,children,depth){const li=element('li');const nested=children.get(task.id)||[];const line=element('div','task-line');if(nested.length){const key=(selectedJob||'')+':'+task.id;const collapsed=collapsedTasks.has(key)||(!expandedTasks.has(key)&&taskSubtreeComplete(task,children));const fold=document.createElement('button');fold.type='button';fold.className='task-fold';fold.setAttribute('aria-expanded',String(!collapsed));fold.setAttribute('aria-label',(collapsed?'Expand ':'Collapse ')+task.id);fold.textContent=collapsed?'▸':'▾';line.append(fold);const ul=element('ul','tree');ul.hidden=collapsed;for(const child of nested)ul.append(taskNode(child,children,depth+1));fold.addEventListener('click',()=>{const next=!ul.hidden;ul.hidden=next;fold.setAttribute('aria-expanded',String(!next));fold.setAttribute('aria-label',(next?'Expand ':'Collapse ')+task.id);fold.textContent=next?'▸':'▾';if(next){collapsedTasks.add(key);expandedTasks.delete(key);}else{collapsedTasks.delete(key);expandedTasks.add(key);}});li.append(line,ul);}else li.append(line);const row=document.createElement('button');row.type='button';row.className='task-row';row.setAttribute('aria-current',String(task.id===selectedTaskId));row.title=task.id;row.addEventListener('click',()=>{const deselect=selectedTaskId===task.id;selectedTaskId=deselect?null:task.id;eventTaskId=deselect?null:task.id;rememberSelection();clearEvents();renderAll();void loadEventHistory();});const id=element('span','task-id',text(task.id));id.style.paddingLeft=Math.min(depth,4)*6+'px';row.append(id,element('span','badge '+value(task.state),text(task.state)));const tag=taskTagDisplay(selected(),task);if(tag){const badge=element('span','task-tag',text(tag));badge.title=(selected()?.tag?.description||'Task tag')+': '+task.tag;row.append(badge);}line.append(row);return li;}
+function taskNode(task,children,depth){const li=element('li');const nested=children.get(task.id)||[];const line=element('div','task-line');if(nested.length){const key=(selectedJob||'')+':'+task.id;const collapsed=collapsedTasks.has(key)||(!expandedTasks.has(key)&&taskSubtreeComplete(task,children));const fold=document.createElement('button');fold.type='button';fold.className='task-fold';fold.setAttribute('aria-expanded',String(!collapsed));fold.setAttribute('aria-label',(collapsed?'Expand ':'Collapse ')+task.id);fold.textContent=collapsed?'▸':'▾';line.append(fold);const ul=element('ul','tree');ul.hidden=collapsed;for(const child of nested)ul.append(taskNode(child,children,depth+1));fold.addEventListener('click',()=>{const next=!ul.hidden;ul.hidden=next;fold.setAttribute('aria-expanded',String(!next));fold.setAttribute('aria-label',(next?'Expand ':'Collapse ')+task.id);fold.textContent=next?'▸':'▾';if(next){collapsedTasks.add(key);expandedTasks.delete(key);}else{collapsedTasks.delete(key);expandedTasks.add(key);}});li.append(line,ul);}else li.append(line);const row=document.createElement('button');row.type='button';row.className='task-row';row.setAttribute('aria-current',String(task.id===selectedTaskId));row.title=task.id;row.addEventListener('click',()=>{const deselect=selectedTaskId===task.id;selectedTaskId=deselect?null:task.id;eventTaskId=deselect?null:task.id;rememberSelection();clearEvents();renderAll();void loadEventHistory();});const id=element('span','task-id',text(shortManagedId(task.id,selected()?.repository,'t')));id.style.paddingLeft=Math.min(depth,4)*6+'px';row.append(id,element('span','badge '+value(task.state),text(task.state)));const tag=taskTagDisplay(selected(),task);if(tag){const badge=element('span','task-tag',text(tag));badge.title=(selected()?.tag?.description||'Task tag')+': '+task.tag;row.append(badge);}line.append(row);return li;}
 function buildTree(tasks){taskTree.replaceChildren();if(!Array.isArray(tasks)||!tasks.length){taskTree.append(element('li','empty',text('No tasks in durable state.')));return;}const work=tasks.filter(task=>task.kind!=='planner');if(!work.length){taskTree.append(element('li','empty',text('No work tasks in durable state.')));return;}const known=new Set(work.map(task=>task.id));const children=new Map();const roots=[];for(const task of work){if(!task.parentTaskId||!known.has(task.parentTaskId))roots.push(task);else{const siblings=children.get(task.parentTaskId)||[];siblings.push(task);children.set(task.parentTaskId,siblings);}}for(const task of roots)taskTree.append(taskNode(task,children,0));}
 function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Number(task?.maxAttempts)||0;if(max>=3&&max%3===0){const effectiveMax=Math.max(max,Math.ceil(attempt/3)*3);return attempt+' / 3×'+(effectiveMax/3);}return attempt+' / '+max;}
 const JOB_STATES=['DRAFT','ACTIVE','COMPLETED','CANCELLED'];

package/dist/dashboard.js

@@ -268,7 +268,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             const requestedJobId = url.searchParams.get('id') ?? '';
             const action = url.searchParams.get('action') ?? '';
             const handler = action === 'start' ? resolvedActions?.start : action === 'reconcile' ? resolvedActions?.reconcile : action === 'cancel' ? resolvedActions?.cancel : undefined;
-            if (req.method !== 'POST' || !/^[A-Za-z0-9_-]+$/.test(requestedJobId) || !handler) {
+            if (req.method !== 'POST' || !/^[A-Za-z0-9_.-]+$/.test(requestedJobId) || !handler) {
                 res.writeHead(404);
                 res.end('Job action unavailable');
                 return;
@@ -301,11 +301,11 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
                 const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
                 const requestedJobId = typeof body.jobId === 'string' ? body.jobId : '';
                 const requestedTaskId = typeof body.taskId === 'string' ? body.taskId : '';
-                if (!/^[A-Za-z0-9_-]+$/.test(requestedJobId))
+                if (!/^[A-Za-z0-9_.-]+$/.test(requestedJobId))
                     throw new Error('Invalid job id');
                 let result;
                 if (body.action === 'create' && body.task && resolvedActions?.taskCreate)
-                    result = await resolvedActions.taskCreate(requestedJobId, body.task);
+                    result = await resolvedActions.taskCreate(requestedJobId, body.task, body.idempotencyKey);
                 else if (body.action === 'update' && isTaskId(requestedTaskId) && body.task && body.expectedUpdatedAt && resolvedActions?.taskUpdate)
                     result = await resolvedActions.taskUpdate(requestedJobId, requestedTaskId, body.task, body.expectedUpdatedAt);
                 else if (body.action === 'start' && isTaskId(requestedTaskId) && resolvedActions?.taskStart)
@@ -337,7 +337,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             const requestedTaskId = url.searchParams.get('task') ?? '';
             const action = url.searchParams.get('action') ?? '';
             const handler = action === 'retry' ? resolvedActions?.taskRetry : action === 'cancel' ? resolvedActions?.taskCancel : undefined;
-            if (req.method !== 'POST' || !/^[A-Za-z0-9_-]+$/.test(requestedJobId) || !isTaskId(requestedTaskId) || !handler) {
+            if (req.method !== 'POST' || !/^[A-Za-z0-9_.-]+$/.test(requestedJobId) || !isTaskId(requestedTaskId) || !handler) {
                 res.writeHead(404);
                 res.end('Task action unavailable');
                 return;
@@ -365,7 +365,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             const parsedPr = Number(url.searchParams.get('pr'));
             const prNumber = Number.isInteger(parsedPr) && parsedPr > 0 ? parsedPr : undefined;
             const validState = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'].includes(requestedState);
-            if (req.method !== 'POST' || !/^[A-Za-z0-9_-]+$/.test(requestedJobId) || !validState || !resolvedActions?.jobSetState) {
+            if (req.method !== 'POST' || !/^[A-Za-z0-9_.-]+$/.test(requestedJobId) || !validState || !resolvedActions?.jobSetState) {
                 res.writeHead(404);
                 res.end('Job state override unavailable');
                 return;
@@ -394,7 +394,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             const parsedPr = Number(url.searchParams.get('pr'));
             const prNumber = Number.isInteger(parsedPr) && parsedPr > 0 ? parsedPr : undefined;
             const validState = ['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'].includes(requestedState);
-            if (req.method !== 'POST' || !/^[A-Za-z0-9_-]+$/.test(requestedJobId) || !isTaskId(requestedTaskId) || !validState || !resolvedActions?.taskSetState) {
+            if (req.method !== 'POST' || !/^[A-Za-z0-9_.-]+$/.test(requestedJobId) || !isTaskId(requestedTaskId) || !validState || !resolvedActions?.taskSetState) {
                 res.writeHead(404);
                 res.end('Task state override unavailable');
                 return;
@@ -440,7 +440,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             const requestedJobId = url.searchParams.get('job') ?? '';
             const requestedTaskId = url.searchParams.get('task');
             const requestedLimit = Number(url.searchParams.get('limit') ?? '60');
-            if (!/^[A-Za-z0-9_-]+$/.test(requestedJobId)) {
+            if (!/^[A-Za-z0-9_.-]+$/.test(requestedJobId)) {
                 res.writeHead(400);
                 res.end('Invalid job id');
                 return;

package/dist/execution-context.js

@@ -1,8 +1,9 @@
+import { resolveAgentMarkdown } from './agent-content-resolver.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';
 import { fileURLToPath } from 'node:url';
-const BUNDLED_AGENTS_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'agents-relay', 'agents');
+export const BUNDLED_AGENTS_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'agents-relay', 'agents');
 async function exists(path) {
     try {
         await access(path);
@@ -198,9 +199,26 @@ export async function resolveExecutionContext(projectPath, role, options = {}) {
     const agentMap = new Map();
     for (const agent of await agentFiles(dirname(BUNDLED_AGENTS_ROOT), 'builtin', []))
         agentMap.set(agent.name, agent);
-    for (const layer of uniqueLayers) {
-        for (const agent of await agentFiles(layer.root, layer.source, skillsByLayer.get(layer.root) ?? []))
-            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);
     }
     for (const registration of options.registeredAgents ?? []) {
         if (agentMap.has(registration.name))
@@ -234,16 +252,19 @@ 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 definition = await readFile(agent.path, 'utf8');
+    const resolved = await resolveAgentMarkdown(agentName, BUNDLED_AGENTS_ROOT, context.project.path);
+    const definition = resolved.content;
     if (!definition.trim())
         throw new Error(`Agent ${agentName} Markdown contract is empty`);
-    return { agent, definition };
+    return { agent, definition, hash: resolved.hash, sources: resolved.sources };
 }
 export async function agentContractPrompt(context, agentName) {
-    const { agent, definition } = await resolveAgentContract(context, agentName);
+    const { agent, definition, hash, sources } = await resolveAgentContract(context, agentName);
     return `[Selected task agent contract]
 Agent: ${agent.name}
 Source: ${agent.path ?? agent.source}
+Effective contract SHA-256: ${hash}
+Contract layers: ${sources.join(' -> ')}
 
 The following Markdown is the authoritative behavioral contract for this Task agent.
 Follow it in addition to the shared Job/Task and events-bus contracts. Worker/model routing
@@ -277,7 +298,7 @@ ${instructions}
 Visible skills (already de-duplicated with project-local > Neo shared > global precedence):
 ${skills}
 
-Visible agents:
+Visible agents (Relay built-in + Job context only; registered agents may supplement):
 ${agents}
 
 Runtime capabilities:

package/dist/job-task-id-sequence.js

@@ -0,0 +1,53 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export function generatedEntityPrefix(repository, kind) {
+    const [owner, repo] = repository.split('/');
+    if (!owner || !repo || !/^[\w.-]+$/.test(owner) || !/^[\w.-]+$/.test(repo) || owner === '..' || repo === '..')
+        throw new Error('Invalid repository');
+    return `${kind === 'job' ? 'j' : 't'}-${owner.length}-${owner}-${repo}-`;
+}
+export function isGeneratedEntityId(id, repository, kind) {
+    const prefix = generatedEntityPrefix(repository, kind);
+    return id.startsWith(prefix) && /^[0-9]+$/.test(id.slice(prefix.length));
+}
+/** Repository-scoped, monotonically increasing IDs. Allocation is serialized by SQLite. */
+export function allocateEntityId(directory, repository, kind, requestKey, occupied = new Set()) {
+    const prefix = generatedEntityPrefix(repository, kind);
+    if (requestKey !== undefined && (!requestKey || requestKey.length > 512))
+        throw new Error('Invalid idempotency key');
+    mkdirSync(directory, { recursive: true });
+    const db = new DatabaseSync(join(directory, 'entity-id-sequences.sqlite'));
+    try {
+        db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=10000;');
+        db.exec('CREATE TABLE IF NOT EXISTS sequences (repository TEXT NOT NULL, kind TEXT NOT NULL, value INTEGER NOT NULL, PRIMARY KEY(repository,kind)); CREATE TABLE IF NOT EXISTS idempotency (repository TEXT NOT NULL, kind TEXT NOT NULL, request_key TEXT NOT NULL, entity_id TEXT NOT NULL, PRIMARY KEY(repository,kind,request_key));');
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            if (requestKey) {
+                const row = db.prepare('SELECT entity_id FROM idempotency WHERE repository=? AND kind=? AND request_key=?').get(repository, kind, requestKey);
+                if (row) {
+                    db.exec('COMMIT');
+                    return row.entity_id;
+                }
+            }
+            const old = db.prepare('SELECT value FROM sequences WHERE repository=? AND kind=?').get(repository, kind);
+            let next = (old?.value ?? 0) + 1;
+            while (occupied.has(prefix + next))
+                next++;
+            db.prepare('INSERT INTO sequences VALUES (?,?,?) ON CONFLICT(repository,kind) DO UPDATE SET value=excluded.value').run(repository, kind, next);
+            // Length prefix keeps repository names unambiguous while satisfying dashboard ID validation.
+            const id = prefix + next;
+            if (requestKey)
+                db.prepare('INSERT INTO idempotency VALUES (?,?,?,?)').run(repository, kind, requestKey, id);
+            db.exec('COMMIT');
+            return id;
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/planner-runtime.js

@@ -1,3 +1,4 @@
+import { assignPlannerTaskIds } from './planner-task-ids.js';
 import { randomUUID } from 'node:crypto';
 import { jobHasActiveExecution } from './job-execution-slot.js';
 import { eventFor } from './events.js';
@@ -119,7 +120,8 @@ async function finishPlanner(ports, jobId, planId, executionId, error, raw) {
     }
     let planCommitted = false;
     try {
-        const result = parsePlannerResult(raw);
+        const parsed = parsePlannerResult(raw);
+        const result = assignPlannerTaskIds(parsed, job.repository, job.id, plan.id);
         const executionContext = await ports.plannerContext(job, plan);
         validatePlannerHierarchy(job.tasks, result.next_tasks);
         validatePlannerResolutionMaterialization(job.tasks, result.next_tasks);

package/dist/planner-task-ids.js

@@ -0,0 +1,15 @@
+import { allocateEntityId } from './job-task-id-sequence.js';
+import { relayStoreDirectory } from './relay-store.js';
+/** Planner labels are local to its plan. Durable Task IDs are allocated by Relay. */
+export function assignPlannerTaskIds(result, repository, jobId, planId, directory = relayStoreDirectory()) {
+    const aliases = new Map(result.next_tasks.map(spec => [spec.id, allocateEntityId(directory, repository, 'task', `plan:${jobId}:${planId}:${spec.id}`)]));
+    return {
+        ...result,
+        next_tasks: result.next_tasks.map(spec => ({
+            ...spec,
+            id: aliases.get(spec.id),
+            parentTaskId: spec.parentTaskId ? (aliases.get(spec.parentTaskId) ?? spec.parentTaskId) : spec.parentTaskId,
+            dependencies: spec.dependencies?.map(dep => aliases.get(dep) ?? dep),
+        })),
+    };
+}

package/dist/planner.js

@@ -4,7 +4,8 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
 import { validateResolutionProposal, unresolvedTask } from './workflow/task-resolution.js';
-import { executionContextPrompt } from './execution-context.js';
+import { executionContextPrompt, BUNDLED_AGENTS_ROOT } from './execution-context.js';
+import { resolveAgentMarkdown } from './agent-content-resolver.js';
 import { parseAgentGraph, validateAgentSelection } from './agent-graph.js';
 import { dispatchPlannerTrigger } from './workflow/planner-trigger-v2.js';
 import { createTaskEntity } from './workflow/entity-creation.js';
@@ -495,10 +496,11 @@ export class AgentObjectivePlanner {
     }
     async plan(context, signal) {
         const resolvedPlanner = context.executionContext?.agents.find(agent => agent.name === 'planner')?.path;
-        const instructions = await readFile(resolvedPlanner ?? this.agentFile, 'utf8');
+        const effectivePlanner = context.executionContext ? await resolveAgentMarkdown('planner', BUNDLED_AGENTS_ROOT, context.executionContext.project.path) : undefined;
+        const instructions = effectivePlanner?.content ?? await readFile(this.agentFile, 'utf8');
         const contract = await readFile(DEFAULT_TASK_JOB_CONTRACT, 'utf8');
         const resolvedContext = context.executionContext ? executionContextPrompt(context.executionContext) + '\n\n' : '';
-        const prompt = instructions.trim() + '\n\n## Shared Task / Job Contract\n\n' + contract.trim() + '\n\n' + resolvedContext + '## Durable planner input\n\n' + plannerInput(context);
+        const prompt = (effectivePlanner ? `[Effective planner contract SHA-256: ${effectivePlanner.hash}]\n\n` : '') + instructions.trim() + '\n\n## Shared Task / Job Contract\n\n' + contract.trim() + '\n\n' + resolvedContext + '## Durable planner input\n\n' + plannerInput(context);
         return await new Promise((resolve, reject) => {
             const child = spawnOwnedProcess(this.command, ['exec', '--json', '--', prompt], { invocation: 'planner.agent', signal, correlation: { jobId: context.job.id }, spawn: { cwd: context.executionContext?.project.path, stdio: ['ignore', 'pipe', 'pipe'] } });
             let stdoutBuffer = '';

package/dist/reconciler-review.js

@@ -325,7 +325,10 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
             return { applied: false, reconcile: false, reason: event.type + '.stale' };
         // Planner-created reviewer tasks predate the final-review Job gate. Bind
         // their first trustworthy review event to PENDING before dispatching it.
-        const initialReviewOutcome = !job.review && task.planningDecisionId ? 'pending' : job.review?.outcome;
+        const freshAfterStale = job.review?.outcome === 'stale'
+            && job.review.headSha !== headSha && Boolean(task.planningDecisionId);
+        const initialReviewOutcome = (!job.review || freshAfterStale) && task.planningDecisionId
+            ? 'pending' : job.review?.outcome;
         const taskDecision = this.store.mutateJob
             ? dispatchTaskLifecycleSync(structuredClone(task), event.type)
             : tryTransitionTaskEvent(task, event.type);
@@ -395,7 +398,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
                 Object.assign(freshTask, candidate);
                 // Bind the first Planner review only after the generation fence has
                 // checked the unmodified outer snapshot and authoritative SQLite state.
-                if (!current.review && freshTask.planningDecisionId) {
+                if ((!current.review || (current.review.outcome === 'stale' && current.review.headSha !== headSha)) && freshTask.planningDecisionId) {
                     current.review = { outcome: 'pending', headSha, taskId: freshTask.id, evidence: null, updatedAt: reviewUpdatedAt };
                 }
                 freshTask.error = null;

package/dist/reconciler-runtime.js

@@ -1,3 +1,4 @@
+import { normalizeReviewerTerminalEvent } from './review-terminal-normalization.js';
 import { applyJobEffectOutcomes, applyTaskEffectOutcomes } from './workflow-effect-failures.js';
 import { classifyWorkerRejection, reroutableWorkerRejections } from './worker-rejection.js';
 import { applyTaskRetryAction } from './task-actions.js';
@@ -89,6 +90,12 @@ export class ReconcilerRuntimeBase {
             return activeOwner.applyEvent(event);
         if (event.type === 'task.started')
             return this.markWorkerStarted(event);
+        if (event.type === 'task.completed') {
+            const task = (await this.store.load(event.job_id)).tasks.find(item => item.id === event.task_id);
+            const normalized = task?.agentName === 'reviewer' ? normalizeReviewerTerminalEvent(event) : null;
+            if (normalized)
+                return this.applyReviewEvent(normalized);
+        }
         if (['task.completed', 'task.failed', 'task.blocked', 'task.cancelled'].includes(event.type)) {
             const result = await this.applyTerminalEvent(event);
             if (event.type !== 'task.failed' || event.source?.watchdog !== true || event.data?.workflowEvent !== 'watchdog.failed' || result.reconcile)

package/dist/relayd-control.js

@@ -9,10 +9,11 @@ export function createWorkspaceControl(deps) {
         if (command === 'job.create') {
             const repository = typeof body.repository === 'string' ? body.repository : '';
             const options = (body.options && typeof body.options === 'object' ? body.options : {});
-            if (!repository || typeof options.id !== 'string' || !options.id)
-                throw new Error('job.create requires repository and id');
+            if (!repository)
+                throw new Error('job.create requires repository');
             const result = await ensureManagedGitHubJob(client, repository, trusted, {
-                id: options.id,
+                id: typeof options.id === 'string' && options.id ? options.id : undefined,
+                idempotencyKey: typeof options.idempotencyKey === 'string' ? options.idempotencyKey : undefined,
                 title: typeof options.title === 'string' ? options.title : undefined,
                 objective: typeof options.objective === 'string' ? options.objective : undefined,
                 projectPath: typeof options.projectPath === 'string' ? options.projectPath : undefined,
@@ -38,6 +39,10 @@ export function createWorkspaceControl(deps) {
             await refreshAll();
             if (body.initialPlan === true) {
                 const binding = await requireLocalJobBinding(result.job.id);
+                const current = await binding.store.load(result.job.id);
+                const existingPlan = current.plans?.at(-1);
+                if (existingPlan)
+                    return { repository, pr: result.pr.number, job: current.id, executionMode: current.executionMode, state: current.state, initialPlan: existingPlan.id, reused: true };
                 const reconciler = makeReconciler(binding.store, concurrency);
                 try {
                     const planned = await reconciler.planJob(result.job.id);

package/dist/relayd-dashboard-actions.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { allocateEntityId, isGeneratedEntityId } from './job-task-id-sequence.js';
+import { relayStoreDirectory } from './relay-store.js';
 import { dispatchJobLifecycleSync } from './workflow/lifecycle.js';
 export function createDashboardActions(deps) {
-    const { getOverviews, requireLocalJobBinding, pool, dashboardJobAction, makeReconciler, concurrency, dashboardJobSetState, refreshAll, applyJobActivateAction, applyOrchestratorStartAction, applyOrchestratorCompleteAction, publishOrchestratorTaskStarted, publishOrchestratorTaskCompletion, bus, dashboardTaskAction, dashboardTaskSetState } = deps;
+    const { getOverviews, requireLocalJobBinding, pool, dashboardJobAction, makeReconciler, concurrency, dashboardJobSetState, refreshAll, applyJobActivateAction, applyOrchestratorStartAction, applyOrchestratorCompleteAction, publishOrchestratorTaskStarted, publishOrchestratorTaskCompletion, bus, dashboardTaskAction, dashboardTaskSetState, storeDirectory } = deps;
     const currentOverviews = () => getOverviews();
     const dashboardOverview = (jobId, target) => currentOverviews().find((item) => item.job.id === jobId
         && (!target?.repository || item.job.repository === target.repository)
@@ -26,7 +28,7 @@ export function createDashboardActions(deps) {
         await refreshAll();
         return result;
     };
-    const workspaceTaskCreate = async (jobId, task) => {
+    const workspaceTaskCreate = async (jobId, task, idempotencyKey) => {
         const overview = currentOverviews().find((item) => item.job.id === jobId);
         if (!overview)
             throw new Error(`Managed job ${jobId} not found`);
@@ -36,12 +38,22 @@ export function createDashboardActions(deps) {
         const job = await store.load(jobId);
         if (['COMPLETED', 'CANCELLED'].includes(job.state))
             throw new Error(`Cannot create task on terminal job ${job.id} (${job.state})`);
+        if (task.id && isGeneratedEntityId(task.id, job.repository, 'task'))
+            throw new Error('Reserved auto-generated Task ID cannot be assigned manually');
+        if (!task.id)
+            task.id = allocateEntityId(storeDirectory ?? relayStoreDirectory(), job.repository, 'task', idempotencyKey ? `${jobId}:${idempotencyKey}` : undefined);
+        let alreadyCreated = false;
         if (store.mutateJob) {
             await store.mutateJob(jobId, (current) => {
                 if (['COMPLETED', 'CANCELLED'].includes(current.state))
                     throw new Error(`Cannot create task on terminal job ${current.id}`);
-                if (current.tasks.some((item) => item.id === task.id))
-                    throw new Error(`Task ${task.id} already exists`);
+                const existing = current.tasks.find((item) => item.id === task.id);
+                if (existing) {
+                    if (!idempotencyKey || existing.input !== task.input || JSON.stringify(existing.output) !== JSON.stringify(task.output))
+                        throw new Error(`Task ${task.id} already exists with a different definition or no retry key`);
+                    alreadyCreated = true;
+                    return current;
+                }
                 current.tasks.push(structuredClone(task));
                 if (current.state === 'DRAFT') {
                     const activation = dispatchJobLifecycleSync(current, 'activate');
@@ -53,6 +65,14 @@ export function createDashboardActions(deps) {
             });
         }
         else {
+            if (idempotencyKey) {
+                const existing = job.tasks.find((item) => item.id === task.id);
+                if (existing) {
+                    if (existing.input !== task.input || JSON.stringify(existing.output) !== JSON.stringify(task.output))
+                        throw new Error(`Task ${task.id} already exists with a different definition`);
+                    return { ...job, createdTaskId: task.id };
+                }
+            }
             await store.appendTask(task);
             const refreshed = await store.load(jobId);
             if (refreshed.state === 'DRAFT') {
@@ -60,8 +80,9 @@ export function createDashboardActions(deps) {
                 await store.saveJob(refreshed);
             }
         }
-        await pool.reconcileLocalJob(jobId, 'control.task.create');
-        return await store.load(jobId);
+        if (!alreadyCreated)
+            await pool.reconcileLocalJob(jobId, 'control.task.create');
+        return { ...(await store.load(jobId)), createdTaskId: task.id };
     };
     const workspaceTaskStart = async (jobId, taskId) => {
         const overview = currentOverviews().find((item) => item.job.id === jobId);

package/dist/review-generation-fence.js

@@ -5,6 +5,14 @@ export function reviewGenerationMatches(current, original, task, headSha) {
         || (current.headSha && current.headSha !== headSha)
         || fresh.executionId !== task.executionId)
         return false;
+    // A fresh Planner reviewer for a new head replaces the old STALE review
+    // generation. Reject competing reviewers of that same head deterministically.
+    if (current.review?.outcome === 'stale' && original.review?.outcome === 'stale'
+        && current.review.headSha !== headSha && task.planningDecisionId) {
+        const currentHeadReviewers = current.tasks.filter(item => item.agentName === 'reviewer'
+            && item.reviewHeadSha === headSha && item.state !== 'CANCELLED');
+        return currentHeadReviewers.at(-1)?.id === task.id;
+    }
     if (current.review)
         return current.review.taskId === task.id && current.review.headSha === headSha
             && current.review.outcome === (original.review?.outcome ?? 'pending');

package/dist/review-terminal-normalization.js

@@ -0,0 +1,27 @@
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+/** Translate an authenticated reviewer terminal verdict without losing canonical review evidence. */
+export function normalizeReviewerTerminalEvent(event) {
+    if (event.type !== 'task.completed')
+        return null;
+    const data = record(event.data);
+    const raw = data.verdict;
+    const type = raw === 'approved' || raw === 'pass' ? 'review.approved'
+        : raw === 'changes-required' || raw === 'changes_required' ? 'review.changes_required'
+            : raw === 'blocked' ? 'review.blocked' : null;
+    if (!type)
+        return null;
+    const outcome = record(data.outcome);
+    const review = record(data.review);
+    // Match canonical review head resolution: outcome > review > top-level data.
+    const head = [outcome.head_sha, outcome.headSha, review.head_sha, review.headSha,
+        data.head_sha, data.headSha]
+        .find(value => typeof value === 'string' && value.length > 0);
+    const existingFindings = outcome.blocking_findings ?? outcome.blockingFindings;
+    const findings = existingFindings ?? (Array.isArray(data.findings) ? data.findings : undefined);
+    return { ...event, type, data: { ...data, outcome: {
+                ...outcome, ...(head ? { head_sha: head } : {}),
+                ...(findings !== undefined && existingFindings === undefined ? { blocking_findings: findings } : {}),
+            } } };
+}

package/dist/workspace.js

@@ -224,6 +224,9 @@ export async function prepareLocalJobExecutionWorktree(projectPath, job, workspa
         throw new Error('Local Job execution requires a valid refs/heads sourceRef');
     const primary = await git(projectPath, ['rev-parse', '--show-toplevel']);
     const projectRelative = (await git(projectPath, ['rev-parse', '--show-prefix'])).replace(/\/$/, '');
+    const effectiveProject = (checkoutRoot) => job.projectPath
+        ? resolveRepositoryProjectPath(checkoutRoot, job.projectPath)
+        : (projectRelative ? join(checkoutRoot, projectRelative) : checkoutRoot);
     let remote = '';
     try {
         remote = await git(primary, ['config', '--get', 'remote.origin.url']);
@@ -242,7 +245,7 @@ export async function prepareLocalJobExecutionWorktree(projectPath, job, workspa
         const primaryHead = await git(primary, ['rev-parse', 'HEAD']);
         if (primaryHead !== sourceSha)
             throw new Error(`Canonical source branch ${sourceRef} changed while preparing execution checkout`);
-        return projectRelative ? join(primary, projectRelative) : primary;
+        return effectiveProject(primary);
     }
     const worktree = managedLocalJobWorktreePath(job.repository, job.id, workspaceRoot);
     await mkdir(dirname(worktree), { recursive: true });
@@ -262,7 +265,7 @@ export async function prepareLocalJobExecutionWorktree(projectPath, job, workspa
                 throw new Error(`Local Job worktree has non-fast-forward history; preserve commits: ${worktree}`);
             await git(worktree, ['merge', '--ff-only', sourceSha]);
         }
-        return projectRelative ? join(worktree, projectRelative) : worktree;
+        return effectiveProject(worktree);
     }
     catch (error) {
         try {
@@ -270,7 +273,7 @@ export async function prepareLocalJobExecutionWorktree(projectPath, job, workspa
         }
         catch {
             await git(primary, ['worktree', 'add', worktree, sourceRef.slice('refs/heads/'.length)]);
-            return projectRelative ? join(worktree, projectRelative) : worktree;
+            return effectiveProject(worktree);
         }
         throw error;
     }

package/package.json

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

package/skills/agents-relay/agents/reviewer.agent.md

@@ -0,0 +1,18 @@
+---
+name: reviewer
+description: Independently evaluate one immutable review target against the complete Job objective and acceptance criteria.
+capabilities: [review, evidence-verification]
+restrictions: [no-artifact-edits, no-merge, preserve-review-target]
+---
+
+# Relay Reviewer Agent
+
+Review exactly the immutable target/version specified by the Review Task. Do not silently substitute newer content or a different commit, document, artifact, or SHA.
+
+## Review Scope
+
+Reconstruct all material acceptance requirements from the durable Job objective and Task, then evaluate each with direct evidence. Check correctness, completeness, provenance, quality, regressions, explicit approvals and externally observable outcomes where applicable. Missing evidence is BLOCKED, not PASS. Keep review independent of implementation work.
+
+## Review Decision
+
+Return a concrete approved, changes-required or blocked verdict tied to the declared immutable target, with attributed findings, severity and remediation steps. Do not alter artifacts, generate approvals on behalf of users, or perform publication, merges or external actions. Relay owns the review lifecycle and Task/Job completion.