agents-relay 2.0.152 → 2.0.154

package/README.md

@@ -138,7 +138,7 @@ retries and daemon restarts do not create duplicate work.
 Task producers must follow `skills/agents-relay/contracts/task-job-contract.md`; that shared skill contract defines story size, lifecycle events, review, and auto-merge semantics.
 
 Execution routing is code-driven: Relay builds complete executable worker+model routes from authoritative runtime/model/resource facts, merges profile defaults with the user's explicit `[choices]`, deduplicates them, removes only impossible routes via hard gates, then calls the generic typed `decide(request, contract)` boundary exactly once with one merged choice list and the `[routing-instruction]` text forwarded verbatim. Task/resource/capability signals and the routing instruction are soft decision facts; decision failure falls back deterministically to a usable Codex default route. See [Execution Router and typed decisions](docs/worker-model-routers.md).
-All task producers use the same story-size contract: `S`≈5 minutes, `M`≈15 minutes, and `L`≈45 minutes of normal-reasoning execution, with `M` as the default. `high` reasoning doubles that overall window. ChatGPT Browser Worker start-ack timeout is derived as one third of the effective overall timeout, clamped between 1 and 5 minutes. Orchestrators and planners should choose `storySize`, not raw timeout milliseconds; `--timeout` remains only as an explicit compatibility/debug override.
+All task producers use the same story-size contract: `S`≈5 minutes, `M`≈15 minutes, and `L`≈45 minutes of inactivity, with `M` as the default. `high` reasoning doubles that inactivity window. Accepted `task.started` and newer `task.progress` events from the exact current execution reset it. ChatGPT Browser Worker start-ack timeout is derived as one third of the effective inactivity timeout, clamped between 1 and 5 minutes. Orchestrators and planners should choose `storySize`, not raw timeout milliseconds; `--timeout` remains only as an explicit compatibility/debug override.
 
 Autonomous jobs can also be scheduled. The Job marker stores a five-field cron expression, IANA timezone, next run, and missed-run/concurrency policy. The daemon evaluates the SQLite-backed managed Job view and validates durable schedule facts before claiming a due slot. A repository heartbeat invokes `tick` at 10-minute resolution. See
 [Scheduled autonomous jobs](docs/scheduled-autonomous-jobs.md) for the exact

package/dist/cli-help.js

@@ -135,7 +135,8 @@ Example:
     'task update': `Update mutable durable Task fields in place.
 
 Required: --task-id ID and the normal Job storage options.
-Mutable while not RUNNING/SUCCEEDED/CANCELLED: --title, --adapter, --priority, --story-size, --input-file PATH|- or --input MARKDOWN, --project, --agent, --agent-graph-file PATH|-, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy, --draft, --queue.
+Mutable while not RUNNING/SUCCEEDED/CANCELLED: --title, --adapter, --priority, --story-size, --input-file PATH|- or --input MARKDOWN, --project, --agent, --agent-graph-file PATH|-, --parent, --deps, --capabilities, --timeout (inactivity window), --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy, --draft, --queue.
+Accepted task.started and newer current-execution task.progress events reset --timeout.
 Use --clear-routing to remove routing metadata.
 
 Example:

package/dist/dashboard-html.js

@@ -34,6 +34,7 @@ ${dashboardStyles}
     <button id="jobs-tab" type="button" role="tab" aria-selected="true" aria-controls="jobs-view">Jobs</button>
     <button id="usage-tab" type="button" role="tab" aria-selected="false" aria-controls="usage-view">Usage</button>
     <button id="rules-tab" type="button" role="tab" aria-selected="false" aria-controls="rules-view">Router Rules</button>
+    <button id="qa-tab" type="button" role="tab" aria-selected="false" aria-controls="qa-view">Troubleshooter Q&A</button>
     <button id="shortcuts-tab" type="button" role="tab" aria-selected="false" aria-controls="shortcuts-view">Shortcuts</button>
     <button id="graphs-tab" type="button" role="tab" aria-selected="false" aria-controls="graphs-view">Workflow</button>
   </nav>
@@ -83,6 +84,14 @@ ${dashboardStyles}
   </section>
   <dialog id="graph-dialog" class="graph-dialog" aria-label="Workflow graph viewer"><div class="graph-dialog-header"><strong id="graph-dialog-title">Workflow graph</strong><div class="graph-navigation"><button type="button" id="graph-zoom-out" class="refresh-button" aria-label="Zoom out">−</button><span id="graph-zoom-level" aria-live="polite">100%</span><button type="button" id="graph-zoom-in" class="refresh-button" aria-label="Zoom in">+</button><button type="button" id="graph-zoom-reset" class="refresh-button">Fit</button><button type="button" id="graph-dialog-close" class="refresh-button">Close</button></div></div><div id="graph-dialog-viewport" class="graph-dialog-viewport"></div></dialog>
   <section id="rules-view" role="tabpanel" aria-labelledby="rules-tab" hidden><div class="panel"><div class="panel-head"><h2>Router Rules</h2><span id="rules-meta" class="subtle"></span></div><div class="panel-body"><div class="router-rules-workspace"><div class="router-rules-pane rules-editor"><h3>Rules Editor</h3><p class="rules-help">Execution Router rules with an explicit <code>[choices]</code> section (provider: model [reasoning] entries, additive to profile defaults) and a <code>[routing-instruction]</code> section forwarded verbatim to Laya. Relay deduplicates, applies hard gates, and sends one merged choice list; impossible routes remain excluded by code and Codex stays the deterministic fallback.</p><textarea id="rules-text" class="rules-textarea" spellcheck="true" aria-label="Execution router rules" placeholder="[choices]\nopenai: sol medium, luna high\nzai: glm-5.3-flash high\n\n[routing-instruction]\nPrefer zai until its quota resets; otherwise use the openai default."></textarea><div class="rules-footer"><span id="rules-status" class="subtle" aria-live="polite"></span><div><button id="rules-test" class="rules-save" type="button">Test Router</button> <button id="rules-save" class="rules-save" type="button">Save rules</button></div></div></div><div class="router-rules-pane"><div class="panel-head"><h3>Audit Log</h3><button id="audit-refresh" type="button">Refresh</button></div><div id="audit-log" class="audit-log" aria-live="polite"><p class="empty">Loading latest routing decisions…</p></div></div></div><div class="router-test-panel"><h3>Test Router Result</h3><div id="router-test-results" class="router-test-results" aria-live="polite"><p class="empty">Select a Job and Task, then run Test Router.</p></div></div></div></div></section>
+  <section id="qa-view" role="tabpanel" aria-labelledby="qa-tab" hidden>
+    <div class="panel"><div class="panel-head"><h2>Troubleshooter Q&A</h2><span class="subtle">skills/agents-relay/troubleshooter-qa.md</span></div>
+      <div class="panel-body"><div class="rules-editor">
+        <p class="rules-help">Edit Markdown directly. Troubleshooter reads this file as guidance, not workflow policy.</p>
+        <textarea id="qa-text" class="rules-textarea" spellcheck="true" aria-label="Troubleshooter Q&A Markdown"></textarea>
+        <div class="rules-footer"><span id="qa-status" class="subtle" aria-live="polite"></span><div><button id="qa-reload" class="rules-save" type="button">Reload</button> <button id="qa-save" class="rules-save" type="button">Save Q&A</button></div></div>
+      </div></div></div>
+  </section>
   <section id="shortcuts-view" role="tabpanel" aria-labelledby="shortcuts-tab" hidden>
     <div class="panel">
       <div class="panel-head"><h2>ChatGPT Shortcuts</h2><span class="subtle">One per line · %1 = current repo/pr</span></div>
@@ -117,6 +126,13 @@ const usageTab=document.querySelector('#usage-tab');
 const graphsTab=document.querySelector('#graphs-tab');
 const rulesTab=document.querySelector('#rules-tab');
 const shortcutsTab=document.querySelector('#shortcuts-tab');
+const qaTab=document.querySelector('#qa-tab');
+const qaView=document.querySelector('#qa-view');
+const qaText=document.querySelector('#qa-text');
+const qaStatus=document.querySelector('#qa-status');
+const qaSave=document.querySelector('#qa-save');
+let qaRevision='';
+
 const jobsView=document.querySelector('#jobs-view');
 const usageView=document.querySelector('#usage-view');
 const graphsView=document.querySelector('#graphs-view');
@@ -318,7 +334,9 @@ async function testRouter(){rulesTest.disabled=true;routerTestResults.replaceChi
 async function saveRules(){rulesSave.disabled=true;rulesStatus.textContent='Saving…';try{const response=await fetch('/api/execution-router-rules',{method:'PUT',headers:{'content-type':'text/plain; charset=utf-8'},body:rulesText.value});if(!response.ok)throw new Error(response.status+' '+await response.text());const rules=await response.json();rulesMeta.textContent='Saved · '+rules.hash.slice(0,12);rulesStatus.textContent='Saved. New routing decisions will load these rules.';}catch(error){rulesStatus.textContent='Save failed: '+error.message;}finally{rulesSave.disabled=false;}}
 async function drawShortcuts(){shortcutsStatus.textContent='';shortcutsText.value=chatShortcutText();}
 function saveShortcuts(){const value=shortcutsText.value.trim();if(value)localStorage.setItem(CHAT_SHORTCUTS_KEY,value);else localStorage.removeItem(CHAT_SHORTCUTS_KEY);shortcutsText.value=chatShortcutText();shortcutsStatus.textContent='Saved.';}
-function showView(view){const isJobs=view==='jobs';const isUsage=view==='usage';const isGraphs=view==='graphs';const isRules=view==='rules';const isShortcuts=view==='shortcuts';jobsView.hidden=!isJobs;jobsWorkspace.hidden=!isJobs;usageView.hidden=!isUsage;graphsView.hidden=!isGraphs;rulesView.hidden=!isRules;shortcutsView.hidden=!isShortcuts;jobsTab.setAttribute('aria-selected',String(isJobs));usageTab.setAttribute('aria-selected',String(isUsage));graphsTab.setAttribute('aria-selected',String(isGraphs));rulesTab.setAttribute('aria-selected',String(isRules));shortcutsTab.setAttribute('aria-selected',String(isShortcuts));if(isJobs)void refresh();else if(isUsage)void drawUsage();else if(isGraphs)void drawGraphs();else if(isRules)void drawRules();else void drawShortcuts();}
+async function drawQa(){qaStatus.textContent='Loading…';try{const result=await loadJSON('/api/troubleshooter-qa');qaText.value=result.text;qaRevision=result.hash;qaStatus.textContent='Loaded';}catch(error){qaStatus.textContent='Load failed: '+error.message;}}
+async function saveQa(){qaSave.disabled=true;qaStatus.textContent='Saving…';try{const response=await fetch('/api/troubleshooter-qa',{method:'PUT',headers:{'content-type':'application/json'},body:JSON.stringify({text:qaText.value,hash:qaRevision})});if(!response.ok)throw new Error(response.status+' '+await response.text());const saved=await response.json();qaRevision=saved.hash;qaStatus.textContent='Saved to Markdown file';}catch(error){qaStatus.textContent='Save failed: '+error.message;}finally{qaSave.disabled=false;}}
+function showView(view){const isJobs=view==='jobs';const isUsage=view==='usage';const isGraphs=view==='graphs';const isRules=view==='rules';const isShortcuts=view==='shortcuts';const isQa=view==='qa';qaView.hidden=!isQa;qaTab.setAttribute('aria-selected',String(isQa));jobsView.hidden=!isJobs;jobsWorkspace.hidden=!isJobs;usageView.hidden=!isUsage;graphsView.hidden=!isGraphs;rulesView.hidden=!isRules;shortcutsView.hidden=!isShortcuts;jobsTab.setAttribute('aria-selected',String(isJobs));usageTab.setAttribute('aria-selected',String(isUsage));graphsTab.setAttribute('aria-selected',String(isGraphs));rulesTab.setAttribute('aria-selected',String(isRules));shortcutsTab.setAttribute('aria-selected',String(isShortcuts));if(isJobs)void refresh();else if(isUsage)void drawUsage();else if(isGraphs)void drawGraphs();else if(isRules)void drawRules();else if(isQa)void drawQa();else void drawShortcuts();}
 jobsTab.addEventListener('click',()=>{location.hash=selectedJob?'#/jobs/'+encodeURIComponent(selectedJob):'#/jobs';showView('jobs');});
 jobsRefresh.addEventListener('click',()=>void refresh(true));
 eventsAllTasks.addEventListener('click',()=>{eventTaskId=null;clearEvents();renderEventScope();void loadEventHistory();});
@@ -337,15 +355,18 @@ document.querySelector('#graph-entry').addEventListener('click',()=>navigateGrap
 const graphDialog=document.querySelector('#graph-dialog');const graphViewport=document.querySelector('#graph-dialog-viewport');let graphZoom=1;const graphCanvasHome=graphCanvas.parentNode;function setGraphZoom(value){graphZoom=Math.min(4,Math.max(.35,value));const svg=graphCanvas.querySelector('svg');if(svg){svg.style.width=(Number(svg.getAttribute('width'))||Math.max(900,svg.viewBox.baseVal.width))*graphZoom+'px';svg.style.maxWidth='none';}document.querySelector('#graph-zoom-level').textContent=Math.round(graphZoom*100)+'%';}document.querySelector('#graph-maximize').addEventListener('click',()=>{graphDialog.showModal();graphViewport.append(graphCanvas);document.querySelector('#graph-dialog-title').textContent=graphTitle.textContent;setGraphZoom(1);});function closeGraphViewer(){graphCanvasHome.insertBefore(graphCanvas,graphCanvasHome.querySelector('.graph-source-details'));setGraphZoom(1);}graphDialog.addEventListener('close',closeGraphViewer);document.querySelector('#graph-dialog-close').addEventListener('click',()=>graphDialog.close());document.querySelector('#graph-zoom-in').addEventListener('click',()=>setGraphZoom(graphZoom*1.25));document.querySelector('#graph-zoom-out').addEventListener('click',()=>setGraphZoom(graphZoom/1.25));document.querySelector('#graph-zoom-reset').addEventListener('click',()=>setGraphZoom(1));graphViewport.addEventListener('wheel',event=>{if(!event.ctrlKey&&!event.metaKey)return;event.preventDefault();setGraphZoom(graphZoom*(event.deltaY<0?1.15:1/1.15));},{passive:false});let drag=null;graphViewport.addEventListener('pointerdown',event=>{if(event.target.closest('.drillable'))return;drag={x:event.clientX,y:event.clientY,left:graphViewport.scrollLeft,top:graphViewport.scrollTop};graphViewport.setPointerCapture(event.pointerId);});graphViewport.addEventListener('pointermove',event=>{if(!drag)return;graphViewport.scrollLeft=drag.left-(event.clientX-drag.x);graphViewport.scrollTop=drag.top-(event.clientY-drag.y);});graphViewport.addEventListener('pointerup',()=>drag=null);graphViewport.addEventListener('pointercancel',()=>drag=null);
 document.querySelector('#graph-back').addEventListener('click',()=>history.back());
 document.querySelector('#graph-forward').addEventListener('click',()=>history.forward());
-window.addEventListener('popstate',()=>{if(graphFromHash()){renderGraphNavigation();showView('graphs');}else if(location.hash==='#/usage')showView('usage');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/shortcuts')showView('shortcuts');else showView('jobs');});
-window.addEventListener('hashchange',()=>{if(graphFromHash()){renderGraphNavigation();showView('graphs');}else if(location.hash==='#/usage')showView('usage');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/shortcuts')showView('shortcuts');else showView('jobs');});
+window.addEventListener('popstate',()=>{if(graphFromHash()){renderGraphNavigation();showView('graphs');}else if(location.hash==='#/usage')showView('usage');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/shortcuts')showView('shortcuts');else if(location.hash==='#/troubleshooter-qa')showView('qa');else showView('jobs');});
+window.addEventListener('hashchange',()=>{if(graphFromHash()){renderGraphNavigation();showView('graphs');}else if(location.hash==='#/usage')showView('usage');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/shortcuts')showView('shortcuts');else if(location.hash==='#/troubleshooter-qa')showView('qa');else showView('jobs');});
 rulesTab.addEventListener('click',()=>{location.hash='#/execution-router-rules';showView('rules');});
+qaTab.addEventListener('click',()=>{location.hash='#/troubleshooter-qa';showView('qa');});
+qaSave.addEventListener('click',()=>void saveQa());
+document.querySelector('#qa-reload').addEventListener('click',()=>{if(!qaText.value||confirm('Discard unsaved Q&A edits and reload?'))void drawQa();});
 shortcutsTab.addEventListener('click',()=>{location.hash='#/shortcuts';showView('shortcuts');});
 rulesSave.addEventListener('click',()=>void saveRules());
 rulesTest.addEventListener('click',()=>void testRouter());
 auditRefresh.addEventListener('click',()=>void drawAudit());
 shortcutsSave.addEventListener('click',saveShortcuts);
-window.addEventListener('keydown',event=>{if(event.key==='Tab'&&event.altKey){event.preventDefault();const views=['jobs','usage','graphs','rules','shortcuts'];const current=location.hash==='#/usage'?'usage':graphFromHash()?'graphs':location.hash==='#/execution-router-rules'?'rules':location.hash==='#/shortcuts'?'shortcuts':'jobs';const next=views[(views.indexOf(current)+1)%views.length];location.hash=next==='usage'?'#/usage':next==='graphs'?'#/graphs':next==='rules'?'#/execution-router-rules':next==='shortcuts'?'#/shortcuts':(selectedJob?'#/jobs/'+encodeURIComponent(selectedJob):'#/jobs');showView(next);}});
+window.addEventListener('keydown',event=>{if(event.key==='Tab'&&event.altKey){event.preventDefault();const views=['jobs','usage','graphs','rules','qa','shortcuts'];const current=location.hash==='#/usage'?'usage':graphFromHash()?'graphs':location.hash==='#/execution-router-rules'?'rules':location.hash==='#/shortcuts'?'shortcuts':location.hash==='#/troubleshooter-qa'?'qa':'jobs';const next=views[(views.indexOf(current)+1)%views.length];location.hash=next==='usage'?'#/usage':next==='graphs'?'#/graphs':next==='rules'?'#/execution-router-rules':next==='shortcuts'?'#/shortcuts':next==='qa'?'#/troubleshooter-qa':(selectedJob?'#/jobs/'+encodeURIComponent(selectedJob):'#/jobs');showView(next);}});
 function parseMessage(message){try{return JSON.parse(message.data);}catch{return null;}}
 function isFreshEnough(incoming,current){const a=Date.parse(incoming||''),b=Date.parse(current||'');return !Number.isFinite(b)||!Number.isFinite(a)||a>=b;}
 function applyStatePatch(patch){if(!patch?.jobId)return false;const job=jobs.find(candidate=>candidate.id===patch.jobId);if(!job)return false;if(patch.jobState&&isFreshEnough(patch.jobUpdatedAt,job.updatedAt)){job['state']=patch.jobState;if(patch.jobUpdatedAt)job.updatedAt=patch.jobUpdatedAt;}if(patch.taskId&&patch.taskState){const task=(job.tasks||[]).find(candidate=>candidate.id===patch.taskId);if(task&&isFreshEnough(patch.taskUpdatedAt,task.updatedAt)){task['state']=patch.taskState;if(patch.taskUpdatedAt)task.updatedAt=patch.taskUpdatedAt;}}return true;}
@@ -355,7 +376,7 @@ stream.onopen=()=>{connection.textContent='';connection.setAttribute('aria-label
 stream.onerror=()=>{connection.textContent='';connection.setAttribute('aria-label','Event stream reconnecting');connection.className='status-pill warn';};
 stream.onmessage=message=>{const payload=parseMessage(message);if(payload?.job){upsertFreshJob(payload.job);renderAll();void drawRuntimeSummary();}};
 stream.addEventListener('relay',message=>{const payload=parseMessage(message);if(payload?.job)upsertFreshJob(payload.job);else if(payload?.statePatch)applyStatePatch(payload.statePatch);if(payload?.event)addEvent(payload.event);renderAll();void drawRuntimeSummary();});
-if(location.hash==='#/usage')showView('usage');else if(graphFromHash())showView('graphs');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/shortcuts')showView('shortcuts');else showView('jobs');
+if(location.hash==='#/usage')showView('usage');else if(graphFromHash())showView('graphs');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/shortcuts')showView('shortcuts');else if(location.hash==='#/troubleshooter-qa')showView('qa');else showView('jobs');
 setInterval(()=>{if(location.hash==='#/usage')void drawUsage();},30000);
 setInterval(()=>void refreshVersion(),30000);
 async function refreshSelected(){const job=selected();if(!job){await refresh();return;}selectedJobRefresh.disabled=true;selectedJobRefresh.textContent='Refreshing…';try{const params=new URLSearchParams({id:job.id,repo:job.repository,pr:String(job.prNumber)});const updated=await loadJSON('/api/job?'+params.toString());const index=jobs.findIndex(candidate=>jobSelectionKey(candidate)===jobSelectionKey(job));if(index>=0)jobs[index]=updated;else jobs.push(updated);selectedJob=jobSelectionKey(updated);rememberSelection();renderAll();connection.textContent='';connection.setAttribute('aria-label','Live durable state connected');connection.className='status-pill ok';}catch(error){connection.textContent='';connection.setAttribute('aria-label','Durable state unavailable');connection.className='status-pill bad';}finally{selectedJobRefresh.disabled=false;selectedJobRefresh.textContent='Refresh';}}

package/dist/dashboard.js

@@ -1,6 +1,7 @@
 import { inspectWorkflowSymbol } from './dashboard-workflow-inspection.js';
 import { createServer } from 'node:http';
 import { subscribeLocalCommits } from './local-commit-events.js';
+import { handleTroubleshooterQa } from './troubleshooter-qa-api.js';
 import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -192,6 +193,10 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             }
             return;
         }
+        if (req.url === '/api/troubleshooter-qa') {
+            await handleTroubleshooterQa(req, res);
+            return;
+        }
         if (req.url === '/api/graphs') {
             try {
                 const graphs = await dashboardWorkflowGraphs();

package/dist/managed-worker-input.js

@@ -70,7 +70,7 @@ As your FIRST execution action, before reading files, editing code, running comm
 you MUST publish exactly one canonical task.started event for this exact Job/Task.
 Immediately after task.started, BEFORE reading task context or doing any implementation/review/recovery work, read the full authoritative Relay event contract at absolute path /Users/chengli/Workspace/agents-relay/skills/agents-relay/contracts/event-contract.md. If it cannot be read, publish task.failed with the blocker and stop. Do not rely only on this prompt summary or a relative path.
 
-${task.adapter === 'chatgpt' ? `Because ChatGPT execution continues asynchronously after the submit process exits, you MUST keep reporting liveness while the task is active. Publish meaningful progress/milestone events when there is real progress to report. If no meaningful milestone has been published for 30 seconds during active work, publish a non-terminal task.heartbeat event with status running, visibility orchestrator, this exact source.id, and a concise description of the current operation. Continue heartbeats after each further 30 seconds of active silence until a terminal task event is published. Do not invent percentage progress.` : `You MAY publish progress events while working. For long silent active work, follow the events-bus heartbeat policy.`}
+Publish task.progress only for meaningful work milestones. It is nonterminal; do not fabricate progress. Relay's Task.timeoutMs is an inactivity timeout reset only by accepted task.started or newer task.progress events for this exact execution.
 Before returning or allowing the worker process to exit, you MUST publish exactly one canonical terminal event:
 - task.completed only after the declared output is durable;
 - task.failed for implementation, tool, command, test, patch, commit, push, runtime, or other execution failure that prevents completion;

package/dist/pool.js

@@ -232,7 +232,7 @@ export class RepositoryWorkerPool {
                 return;
             if (routedWebhook)
                 return;
-            const lifecycle = ['task.started', 'task.completed', 'task.failed', 'task.blocked', 'task.unblocked', 'task.cancelled', 'review.started', 'review.approved', 'review.changes_required', 'review.blocked'].includes(event.type);
+            const lifecycle = ['task.started', 'task.progress', 'task.completed', 'task.failed', 'task.blocked', 'task.unblocked', 'task.cancelled', 'review.started', 'review.approved', 'review.changes_required', 'review.blocked'].includes(event.type);
             // GitHub transport is observational. It must never wake lifecycle execution.
             if (event.type === 'github.webhook')
                 return;

package/dist/reconciler-runtime.js

@@ -9,12 +9,12 @@ import { eventFor } from './events.js';
 import { WorkflowEffectExecutor } from './workflow/effects.js';
 import { ReconcileCoordinator } from './reconcile-coordinator.js';
 import { acceptedReportedTag, eventDataWithoutTag } from './task-tag.js';
-import { rearmTerminalEventDeadline } from './terminal-event-watchdog.js';
 import { createWorkerStartAck } from './worker-start-ack.js';
 import { monitorExecutionProcess } from './execution-process-tracker.js';
 import { HostInteractiveInvocationCoordinator, hostInvocationPorts } from './interactive-invocation.js';
 import { resumeInteractiveTask } from './interactive-resume.js';
 import { codexFallbackCompatible, persistChatGptPlatformFailure } from './chatgpt-platform-fallback.js';
+import { acceptTaskProgress, armInactivityWatchdog, inactivityDeadline, isCorrelatedWorkerEvent, isRecoverableWatchdogFailure } from './task-inactivity-watchdog.js';
 const activeExecutionOwners = new Map();
 import { withExecutionBoundary } from './execution-boundary.js';
 export { withExecutionBoundary } from './execution-boundary.js';
@@ -84,6 +84,8 @@ export class ReconcilerRuntimeBase {
             return activeOwner.applyEvent(event);
         if (event.type === 'task.started')
             return this.markWorkerStarted(event);
+        if (event.type === 'task.progress')
+            return this.markWorkerProgress(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;
@@ -176,14 +178,8 @@ export class ReconcilerRuntimeBase {
         owner.clearExecution(taskId, executionId);
         return true;
     }
-    clearTerminalTimer(taskId, executionId) {
-        const live = this.live.get(taskId);
-        if (!live || live.executionId !== executionId)
-            return;
-        const timer = this.terminalTimers.get(taskId);
-        if (timer)
-            clearTimeout(timer);
-        this.terminalTimers.delete(taskId);
+    armInactivityWatchdog(task, executionId) {
+        armInactivityWatchdog(task, executionId, this.terminalTimers, this.options.postExitTerminalGraceMs ?? 15_000, () => this.detach(this.timeoutTask(task.jobId, task.id, executionId), task.jobId, task.id, 'worker inactivity timeout'));
     }
     clearExecution(taskId, executionId) {
         const live = this.live.get(taskId);
@@ -206,16 +202,19 @@ export class ReconcilerRuntimeBase {
             eligible: (job, task) => {
                 if (!task.executionId || eventSourceId(event) !== executionEventSource(job.id, task.id, task.executionId))
                     return false;
+                if (!Number.isFinite(Date.parse(event.timestamp)) || Date.parse(event.timestamp) > Date.now())
+                    return false;
                 const claimedExecution = task.executionId !== null && task.leaseOwner !== null;
                 const exactLiveExecution = live && event.job_id === live.jobId && task.executionId === live.executionId;
-                return Boolean(exactLiveExecution || claimedExecution || this.isRecoverableWatchdogFailure(task));
+                return Boolean(exactLiveExecution || claimedExecution || isRecoverableWatchdogFailure(task));
             },
             facts: (_job, task) => ({
-                recoverableExecution: this.isRecoverableWatchdogFailure(task)
+                recoverableExecution: isRecoverableWatchdogFailure(task)
                     && Boolean(task.executionId && eventSourceId(event) === executionEventSource(event.job_id, task.id, task.executionId)),
             }),
             mutate: (_job, task) => {
-                task.updatedAt = new Date().toISOString();
+                task.updatedAt = task.lastProgressAt = new Date().toISOString();
+                task.lastProgressEventAt = event.timestamp;
             },
         });
         if (!transition?.decision.accepted)
@@ -227,21 +226,11 @@ export class ReconcilerRuntimeBase {
         }
         if (live?.executionId === transition.task.executionId)
             live.workerStarted = true;
+        this.armInactivityWatchdog(transition.task, transition.task.executionId);
         return { applied: true, reconcile: transition.from === 'FAILED', reason: transition.from === 'FAILED' ? 'task.started.recovery' : 'task.started', reconcileMode: transition.from === 'FAILED' ? 'detached' : undefined };
     }
-    isRecoverableWatchdogFailure(task) {
-        if (['worker_start_timeout', 'terminal_event_timeout', 'worker_exit_before_start', 'worker_exit_without_terminal_event', 'worker_delivery_after_start'].includes(task.failureReason ?? ''))
-            return true;
-        const error = task.error ?? '';
-        return error.includes('worker_start_timeout')
-            || error.includes('timed out waiting for the mandatory terminal worker event')
-            || error.includes('exited before publishing task.started')
-            || error.includes('exited after task.started without publishing a terminal task event')
-            || error.includes('Worker delivery failed after task.started');
-    }
-    isCorrelatedWorkerEvent(task, event) {
-        return task.executionId !== null && eventSourceId(event) === executionEventSource(event.job_id, task.id, task.executionId);
-    }
+    async markWorkerProgress(event) { const task = await acceptTaskProgress(this.taskTransitions, event); if (!task?.executionId)
+        return { applied: false, reconcile: false, reason: 'task.progress.ignored' }; this.armInactivityWatchdog(task, task.executionId); return { applied: true, reconcile: false, reason: 'task.progress' }; }
     finalizeReviewExecution(jobId, task, event, afterCommit = true) {
         if (!task.executionId)
             return true;
@@ -331,29 +320,38 @@ export class ReconcilerRuntimeBase {
         const task = job.tasks.find(item => item.id === taskId);
         if (!task)
             return;
+        if (task.adapter !== 'chatgpt') {
+            const exited = await this.taskTransitions.updateFact(jobId, taskId, current => current.executionId === executionId && ['RUNNING', 'QUEUED'].includes(current.state), current => { current.processExitedAt = new Date().toISOString(); });
+            if (exited)
+                this.armInactivityWatchdog(exited, executionId);
+        }
         const correlated = task.executionId === executionId || task.executionHistory?.some(item => item.id === executionId);
         if (!correlated)
             return;
         if (task.adapter !== 'chatgpt' && (task.executionId !== executionId || terminalExecutionClaimed(jobId, taskId, executionId)))
             return;
-        if (task.adapter !== 'chatgpt' && task.executionId === executionId && live?.executionId === executionId)
-            rearmTerminalEventDeadline(this.terminalTimers, taskId, task.timeoutMs - (Date.now() - live.launchBarrier), this.options.postExitTerminalGraceMs ?? 15_000, () => this.detach(this.timeoutTask(jobId, taskId, executionId), jobId, taskId, 'post-exit terminal event timeout'));
         await this.emit(eventFor(jobId, taskId, task.parentTaskId, task.adapter === 'chatgpt' ? 'task.process.async_exited' : 'task.process.exited', live?.execution.processExit ? (live.execution.processExit.exitCode === 0 ? 'succeeded' : 'failed') : (error ? 'failed' : 'succeeded'), result?.summary ?? (live?.execution.processExit?.terminationReason === 'parent-shutdown' ? 'Worker interrupted by daemon shutdown' : error ? `Worker exited: ${error}${live?.execution.processExit ? ` (exit=${live.execution.processExit.exitCode ?? 'null'}${live.execution.processExit.signal ? ` signal=${live.execution.processExit.signal}` : ''})` : ''}` : 'Worker runtime exited'), 'orchestrator', { authoritative: false, waitingForTerminalEvent: true, exitCode: live?.execution.processExit?.exitCode ?? null,
             signal: live?.execution.processExit?.signal ?? null, terminationReason: live?.execution.processExit?.terminationReason ?? null, stderr: live?.execution.processExit?.stderr ?? '', processError: error, executionId, pid: live?.execution.pid ?? null }, { id: executionEventSource(jobId, taskId, executionId), agent: 'relay', component: 'agents-relay' }));
     }
     async timeoutTask(jobId, taskId, executionId) {
-        const live = this.live.get(taskId);
-        if (live?.executionId === executionId) {
-            live.controller.abort();
-            live.execution.cancel();
+        const current = (await this.store.load(jobId)).tasks.find(task => task.id === taskId);
+        if (!current || current.executionId !== executionId || !['QUEUED', 'RUNNING'].includes(current.state))
+            return;
+        const deadline = inactivityDeadline(current, executionId, this.options.postExitTerminalGraceMs ?? 15_000);
+        if (deadline > Date.now()) {
+            this.armInactivityWatchdog(current, executionId);
+            return;
         }
+        const live = this.live.get(taskId);
+        // Do not cancel before the serialized watchdog transition rechecks the
+        // deadline: a concurrent accepted progress event may have extended it.
         const exit = live?.executionId === executionId && live.processSettled ? live.execution.processExit : undefined;
         const rawError = live?.executionId === executionId && live.processSettled ? (live.processError || exit?.stderr || '').trim() : '';
         const failedExit = Boolean(exit && (exit.exitCode !== 0 || exit.signal));
         const failureReason = failedExit ? classifyWorkerRejection(rawError) : 'terminal_event_timeout';
-        const failureMessage = failedExit ? (rawError || `Worker exited with code ${exit?.exitCode ?? 'null'}${exit?.signal ? `, signal ${exit.signal}` : ''}`) : `Task ${taskId} timed out waiting for the mandatory terminal worker event`;
+        const failureMessage = failedExit ? (rawError || `Worker exited with code ${exit?.exitCode ?? 'null'}${exit?.signal ? `, signal ${exit.signal}` : ''}`) : `Task ${taskId} exceeded its inactivity timeout without a terminal event`;
         const transition = await this.taskTransitions.apply(jobId, taskId, 'watchdog.failed', {
-            eligible: (_job, task) => task.executionId === executionId,
+            eligible: (_job, task) => task.executionId === executionId && inactivityDeadline(task, executionId, this.options.postExitTerminalGraceMs ?? 15_000) <= Date.now(),
             mutate: (_job, task) => {
                 this.clearExecution(task.id, executionId);
                 task.error = failureMessage;
@@ -363,9 +361,15 @@ export class ReconcilerRuntimeBase {
             },
         });
         if (!transition?.decision.accepted) {
-            this.clearExecution(taskId, executionId);
+            const latest = (await this.store.load(jobId)).tasks.find(task => task.id === taskId);
+            if (latest?.executionId === executionId && ['QUEUED', 'RUNNING'].includes(latest.state))
+                this.armInactivityWatchdog(latest, executionId);
             return;
         }
+        if (live?.executionId === executionId) {
+            live.controller.abort();
+            live.execution.cancel();
+        }
         let reroutedTask = null;
         if (reroutableWorkerRejections.has(failureReason) && transition.task.attempt < transition.task.maxAttempts) {
             const current = (await this.store.load(jobId)).tasks.find(task => task.id === taskId);
@@ -410,19 +414,19 @@ export class ReconcilerRuntimeBase {
                 if (event.type === 'task.completed' && task.interactiveInvocation?.status !== undefined && task.interactiveInvocation.status !== 'approved')
                     return false; // current interactive revision requires durable approval
                 const modelBacked = task.adapter === 'codex' || task.adapter === 'chatgpt';
-                if (!trustedInternal && modelBacked && !this.isCorrelatedWorkerEvent(task, event)) {
+                if (!trustedInternal && modelBacked && !isCorrelatedWorkerEvent(task, event)) {
                     const eventExecutionId = executionIdFromSource(eventSourceId(event), _job.id, task.id);
                     const prior = eventExecutionId ? task.executionHistory?.find(item => item.id === eventExecutionId) : undefined;
                     if (!prior || prior.attempt !== task.attempt)
                         return false;
                 }
                 const terminalWaiter = this.terminalWaiters.get(task.id);
-                return !terminalWaiter || Boolean(task.executionId && terminalWaiter.executionId === task.executionId && this.isCorrelatedWorkerEvent(task, event));
+                return !terminalWaiter || Boolean(task.executionId && terminalWaiter.executionId === task.executionId && isCorrelatedWorkerEvent(task, event));
             },
             facts: (_job, task) => {
                 const processExitedAfterPublishedTerminal = task.failureReason === 'worker_exit_without_terminal_event';
-                const freshEnough = processExitedAfterPublishedTerminal || this.isCorrelatedWorkerEvent(task, event);
-                return { recoverableExecution: this.isRecoverableWatchdogFailure(task) && freshEnough };
+                const freshEnough = processExitedAfterPublishedTerminal || isCorrelatedWorkerEvent(task, event);
+                return { recoverableExecution: isRecoverableWatchdogFailure(task) && freshEnough };
             },
             mutate: (job, task) => {
                 const modelBacked = task.adapter === 'codex' || task.adapter === 'chatgpt';

package/dist/reconciler.js

@@ -180,6 +180,9 @@ export class Reconciler extends ReconcilerReviewBase {
             const taskStatesBeforeSchedule = new Map(beforeSchedule.tasks.map(task => [task.id, task.state]));
             const scheduleBefore = JSON.stringify(beforeSchedule.schedule ?? null);
             let scheduled = schedule(beforeSchedule);
+            for (const task of scheduled.tasks)
+                if (task.executionId && ['QUEUED', 'RUNNING'].includes(task.state))
+                    this.armInactivityWatchdog(task, task.executionId);
             for (const task of scheduled.tasks) {
                 if (taskStatesBeforeSchedule.get(task.id) !== task.state)
                     await this.store.saveTask(task);
@@ -366,6 +369,9 @@ export class Reconciler extends ReconcilerReviewBase {
             freshTask.leaseOwner = this.options.owner;
             freshTask.leaseExpiresAt = new Date(startedAt + leaseMs).toISOString();
             freshTask.executionId = randomUUID();
+            delete freshTask.lastProgressAt;
+            delete freshTask.lastProgressEventAt;
+            delete freshTask.processExitedAt;
             freshTask.executionHistory = [...(freshTask.executionHistory ?? []), {
                     id: freshTask.executionId,
                     attempt: freshTask.attempt,
@@ -396,6 +402,9 @@ export class Reconciler extends ReconcilerReviewBase {
                     durable.leaseOwner = this.options.owner;
                     durable.leaseExpiresAt = new Date(startedAt + leaseMs).toISOString();
                     durable.executionId = randomUUID();
+                    delete durable.lastProgressAt;
+                    delete durable.lastProgressEventAt;
+                    delete durable.processExitedAt;
                     durable.executionHistory = [...(durable.executionHistory ?? []), {
                             id: durable.executionId, attempt: durable.attempt, startedAt: new Date(startedAt).toISOString(),
                         }].slice(-8);
@@ -514,10 +523,7 @@ export class Reconciler extends ReconcilerReviewBase {
             transition: { graph: 'task-lifecycle', from: 'QUEUED', to: 'QUEUED', actions: ['effect.launchTask'] },
             data: { adapter: adapter.id, attempt: task.attempt, model: task.routing?.model ?? null },
         });
-        const terminalTimer = setTimeout(() => {
-            this.detach(this.timeoutTask(job.id, task.id, durableExecutionId), job.id, task.id, 'worker terminal-event timeout');
-        }, Math.max(1, task.timeoutMs));
-        this.terminalTimers.set(task.id, terminalTimer);
+        this.armInactivityWatchdog(task, durableExecutionId);
         this.detach(execution.promise.then(result => this.runtimeSettled(job.id, task.id, durableExecutionId, result, null), error => error instanceof StartAckTimeout
             ? this.failLaunch(job.id, task.id, durableExecutionId, error, 'start-ack')
             : error instanceof LaunchFailure || error instanceof PreSubmissionRejection

package/dist/task-context.js

@@ -45,5 +45,5 @@ THEN read the entire authoritative event contract from /Users/chengli/Workspace/
 THEN retrieve the authoritative Task Context:
   agents-relay task context --repo ${repository} --id ${jobId} --task-id ${taskId} --execution-id ${executionId}
 Verify the execution ID. Read Task input, dependencies, Plan, project context, and output requirements from that response. Never guess or create a new Job. Continue in this thread; Relay owns completion and review.
-Follow the file's lifecycle contract, including progress/heartbeat and exactly one task.completed or task.failed before exiting. If context is unavailable publish task.failed with the blocker.`;
+Follow the file's lifecycle contract, including optional meaningful progress and exactly one task.completed or task.failed before exiting. Accepted current-execution task.started and newer task.progress events reset Task.timeoutMs; duplicate, stale, or out-of-order progress does not. If context is unavailable publish task.failed with the blocker.`;
 }

package/dist/task-inactivity-watchdog.js

@@ -0,0 +1,45 @@
+import { executionEventSource, eventSourceId } from './execution-event-identity.js';
+export function isRecoverableWatchdogFailure(task) {
+    if (['worker_start_timeout', 'terminal_event_timeout', 'worker_exit_before_start', 'worker_exit_without_terminal_event', 'worker_delivery_after_start'].includes(task.failureReason ?? ''))
+        return true;
+    const error = task.error ?? '';
+    return error.includes('worker_start_timeout') || error.includes('timed out waiting for the mandatory terminal worker event') || error.includes('exceeded its inactivity timeout')
+        || error.includes('exited before publishing task.started') || error.includes('exited after task.started without publishing a terminal task event')
+        || error.includes('Worker delivery failed after task.started');
+}
+export function isCorrelatedWorkerEvent(task, event) {
+    return task.executionId !== null && eventSourceId(event) === executionEventSource(event.job_id, task.id, task.executionId);
+}
+export function inactivityDeadline(task, executionId, postExitGraceMs) {
+    const progressAt = Date.parse(task.lastProgressAt ?? task.executionHistory?.find(item => item.id === executionId)?.startedAt ?? task.updatedAt);
+    const timeoutAt = (Number.isFinite(progressAt) ? progressAt : Date.now()) + Math.max(1, task.timeoutMs);
+    const exitAt = task.adapter !== 'chatgpt' && task.processExitedAt ? Date.parse(task.processExitedAt) : NaN;
+    return Number.isFinite(exitAt) ? Math.min(timeoutAt, exitAt + postExitGraceMs) : timeoutAt;
+}
+export function armInactivityWatchdog(task, executionId, timers, postExitGraceMs, expire) {
+    const existing = timers.get(task.id);
+    if (existing)
+        clearTimeout(existing);
+    timers.delete(task.id);
+    if (!task.jobId || task.executionId !== executionId || !['QUEUED', 'RUNNING'].includes(task.state))
+        return;
+    const timer = setTimeout(expire, Math.max(1, inactivityDeadline(task, executionId, postExitGraceMs) - Date.now()));
+    timer.unref();
+    timers.set(task.id, timer);
+}
+export async function acceptTaskProgress(transitions, event) {
+    const parsedAt = Date.parse(event.timestamp);
+    const receivedAt = Date.now();
+    const transition = await transitions.apply(event.job_id, event.task_id, 'task.progress', {
+        eligible: (job, task) => task.state === 'RUNNING'
+            && Boolean(task.executionId && eventSourceId(event) === executionEventSource(job.id, task.id, task.executionId))
+            && Number.isFinite(parsedAt) && parsedAt <= receivedAt
+            && (!task.lastProgressEventAt || parsedAt > Date.parse(task.lastProgressEventAt)),
+        mutate: (_job, task) => {
+            task.lastProgressAt = new Date(receivedAt).toISOString();
+            task.lastProgressEventAt = event.timestamp;
+            task.updatedAt = task.lastProgressAt;
+        },
+    });
+    return transition?.decision.accepted ? transition.task : null;
+}

package/dist/troubleshooter-qa-api.js

@@ -0,0 +1,61 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+const FILE = fileURLToPath(new URL('../skills/agents-relay/troubleshooter-qa.md', import.meta.url));
+const qaHash = (content) => createHash('sha256').update(content).digest('hex');
+export async function handleTroubleshooterQa(req, res) {
+    try {
+        const current = await readFile(FILE, 'utf8');
+        if (req.method === 'GET') {
+            res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+            res.end(JSON.stringify({ text: current, hash: qaHash(current) }));
+            return;
+        }
+        if (req.method === 'PUT') {
+            if (req.headers['content-type']?.split(';')[0] !== 'application/json') {
+                res.writeHead(415);
+                res.end('Expected JSON');
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of req) {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                size += buffer.length;
+                if (size > 128 * 1024) {
+                    res.writeHead(413);
+                    res.end('Q&A too large');
+                    return;
+                }
+                chunks.push(buffer);
+            }
+            const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            if (!body || typeof body !== 'object' || !('text' in body) || !('hash' in body) || typeof body.text !== 'string' || typeof body.hash !== 'string') {
+                res.writeHead(400);
+                res.end('Invalid Q&A payload');
+                return;
+            }
+            if (body.hash !== qaHash(current)) {
+                res.writeHead(409);
+                res.end('Q&A changed on disk; reload before saving');
+                return;
+            }
+            if (Buffer.byteLength(body.text) > 128 * 1024) {
+                res.writeHead(413);
+                res.end('Q&A too large');
+                return;
+            }
+            await writeFile(FILE, body.text, 'utf8');
+            res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+            res.end(JSON.stringify({ hash: qaHash(body.text) }));
+            return;
+        }
+        res.writeHead(405, { allow: 'GET, PUT' });
+        res.end('Method not allowed');
+    }
+    catch (error) {
+        res.writeHead(500);
+        res.end(error instanceof Error ? error.message : String(error));
+    }
+    return;
+}

package/dist/workflow/contracts.js

@@ -35,6 +35,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'task.cancelled',
     'task.completed',
     'task.failed',
+    'task.progress',
     'task.started',
     'task.unblocked',
     'watchdog.failed',

package/dist/workflow/durable-transition.js

@@ -52,6 +52,32 @@ export class DurableTaskTransitionRuntime {
             return { job, task, from, decision };
         });
     }
+    /** Persist a non-lifecycle fact without racing the serialized terminal transitions. */
+    async updateFact(jobId, taskId, eligible, mutate) {
+        return this.withLock(`${jobId}/${taskId}`, async () => {
+            let accepted = false;
+            const apply = (job) => {
+                const task = job.tasks.find(item => item.id === taskId);
+                if (!task || !eligible(task))
+                    return job;
+                const previous = Date.parse(task.updatedAt);
+                mutate(task);
+                task.updatedAt = new Date(Math.max(Date.now(), Number.isFinite(previous) ? previous + 1 : 0)).toISOString();
+                accepted = true;
+                return job;
+            };
+            if (this.store.mutateJob) {
+                const updated = await this.store.mutateJob(jobId, apply);
+                return accepted ? updated.tasks.find(item => item.id === taskId) ?? null : null;
+            }
+            const job = apply(await this.store.load(jobId));
+            if (!accepted)
+                return null;
+            const task = job.tasks.find(item => item.id === taskId);
+            await this.store.saveTask(task);
+            return task;
+        });
+    }
     async withLock(key, work) {
         const previous = this.locks.get(key);
         let release;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.152",
+  "version": "2.0.154",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",

package/skills/agents-relay/SKILL.md

@@ -56,9 +56,9 @@ Agents Relay maps those terminal events to durable state:
 - `task.failed` → `FAILED`
 Relay may authoritatively move a Task to `BLOCKED` for an external condition and may resume it only through an authorized unblock operation. A human response is an append-only Task Comment and resumes the blocked Troubleshooter, not the failed original Task. Task input remains stable; recovery agents receive current authoritative state and relevant comments as execution context.
 
-A model-backed task must not launch without an event bus. If no terminal event arrives before the task timeout, Relay records an explicit timeout failure. A Codex process exit or ChatGPT submission receipt alone never changes the task to a terminal state.
+A model-backed task must not launch without an event bus. If no accepted `task.started` or newer current-execution `task.progress` arrives within `Task.timeoutMs`, Relay records an inactivity timeout failure. A Codex process exit or ChatGPT submission receipt alone never changes the task to a terminal state.
 
-Worker process exit is observational only. Relay does not perform an exit-time terminal check or synthesize task failure from process exit; semantic terminal state comes from the worker event contract or the normal task timeout.
+Worker process exit is observational only. Relay does not perform an exit-time terminal check or synthesize task failure from process exit; for synchronous workers it caps the remaining inactivity wait at the shorter post-exit terminal grace.
 
 ## Managed GitHub jobs
 

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

@@ -15,6 +15,8 @@ Your goal is not to explain the failure. Your goal is to make the original task
 
 Read and follow the shared Task / Job contract and orchestrator P0/self-job workflow before acting.
 
+Read `skills/agents-relay/troubleshooter-qa.md` for user-editable best practices before diagnosis. Treat its answers as guidance only, below current evidence and authoritative contracts. After a verified recovery, add or refine a concise Q&A entry when it provides reusable knowledge; never include secrets or unverified claims.
+
 ## Recovery loop
 
 1. Retrieve the durable original Job and Task from the authoritative Relay store with `agents-relay task context`; GitHub is only an optional projection and is never lifecycle authority.

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

@@ -4,7 +4,9 @@
 
 ## Producer contract
 
-Every Implementation, Reviewer, and Troubleshooter execution publishes `task.started`, optional `task.progress` or `task.heartbeat`, then **exactly one** agent terminal event:
+Every Implementation, Reviewer, and Troubleshooter execution publishes `task.started`, optional `task.progress`, then **exactly one** agent terminal event:
+
+`task.started` and `task.progress` reset the Task inactivity timeout only when Relay accepts the event for the exact current execution. Progress is nonterminal, must be newer than the last accepted progress event, and cannot extend a terminal or stale execution.
 
 - `task.completed`: assigned responsibility finished and its role-specific output is durable, regardless of whether a reviewed artifact passed.
 - `task.failed`: assigned responsibility could not be fulfilled; include failure phase, reason, and evidence in `data`.

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

@@ -22,6 +22,8 @@ Ordinary `job create` requires standalone objective Markdown. An external displa
 Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.
 Task producers choose semantic task properties such as objective, dependencies, worker requirements, priority, and `storySize`. They do not normally choose an adapter, provider/model, or raw timeout milliseconds.
 
+`Task.timeoutMs` is the inactivity window. Only an accepted `task.started` or newer `task.progress` event for the exact current execution resets it; duplicate, stale, and out-of-order progress does not.
+
 ### Planning graph and semantic Task tree
 
 The planning graph expresses execution flow. The Task tree expresses semantic ownership. `dependencies` answer which durable outcomes must succeed before a Task can run; `parentTaskId` answers which durable artifact or milestone owns the Task. These are independent relationships.

package/skills/agents-relay/troubleshooter-qa.md

@@ -0,0 +1,25 @@
+# Troubleshooter Q&A
+
+A simple, user-editable reference for recurring failures and proven recovery practices.
+
+Troubleshooter: read this file before diagnosis, but always inspect current task events and logs. Answers are guidance, not authority to retry, unblock, change routing, or change workflow state. The canonical workflow graphs and contracts remain authoritative.
+
+Users can add or edit entries directly. After a recovery is verified, the Troubleshooter may add a short entry or improve an existing answer. Do not write secrets, tokens, or private log contents here. Keep unverified hypotheses clearly labeled.
+
+## Q: Browser Workspace validation says COMPOSER_NOT_READY. Does that mean the user is logged out?
+
+**A:** No. This code reports UI readiness, not authentication. Use the platform's validated session and inspect worker authentication and delivery evidence separately. Do not infer login failure from a disabled Send button or DOM snapshot.
+
+## Q: A worker fails or times out. Should Troubleshooter immediately retry?
+
+**A:** No. Read the original task's correlated lifecycle events, attempts, routing, and relevant logs. Diagnose the actual cause first. Only recover the original Task after verifying that the blocker is resolved, using the canonical recovery path.
+
+## Q: A shared runtime or tool defect blocks several tasks. What should Troubleshooter do?
+
+**A:** Reuse an existing blocker Job when possible. Otherwise create the owning P0/self-job through Agents Relay. Verify the repair and any required release or deployment before recovering dependent tasks. For deferred repair, register the durable blocker relation instead of keeping a worker alive.
+
+## Q: When can a BLOCKED task resume?
+
+**A:** Only after an authoritative unblock operation or verified blocker-Job resolution. A Q&A answer cannot unblock a task.
+
+<!-- Add more entries below using: ## Q: ... / **A:** ... -->

package/workflow/task-lifecycle.mmd

@@ -151,6 +151,7 @@ leaseFailQueuedClearExecution --> failed
 queued -->|on: cancel| cancelled
 
 running -->|on: task.blocked| blocked
+running -->|on: task.progress| running
 running -->|on: review.approved| reviewApproveRunningClearError
 reviewApproveRunningClearError --> reviewApproveRunningClearReason
 reviewApproveRunningClearReason --> succeeded

package/dist/terminal-event-watchdog.js

@@ -1,11 +0,0 @@
-/**
- * Replace the overall worker deadline with a shorter post-exit deadline.
- * Execution outcomes remain owned by the authoritative task lifecycle graph.
- * Never extend the original overall timeout.
- */
-export function rearmTerminalEventDeadline(timers, taskId, overallRemainingMs, graceMs, expire) {
-    const existing = timers.get(taskId);
-    if (existing)
-        clearTimeout(existing);
-    timers.set(taskId, setTimeout(expire, Math.max(1, Math.min(overallRemainingMs, graceMs))));
-}