Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix([issue-13265]): distinguish CoS delivery from execution success
[._.]/ Adam Eivye25ef08a8c03
diff --git a/client/src/components/cos/AgentResultLine.jsx b/client/src/components/cos/AgentResultLine.jsxindex fbff69f35a..5a6ff296b2 100644--- a/client/src/components/cos/AgentResultLine.jsx+++ b/client/src/components/cos/AgentResultLine.jsx@@ -2,25 +2,16 @@ import { Fragment } from 'react';import { Link } from 'react-router';import { CheckCircle, AlertCircle, RotateCcw } from 'lucide-react';import { formatCount, formatUsd } from '../../utils/formatters';-import { isAgentHandoff, agentHandoffReason } from '../../lib/agentOutcome';+import { isAgentHandoff, agentHandoffReason, normalizeTaskOutcome, isTaskDeliveryComplete } from '../../lib/agentOutcome';-/**- * The one-line verdict on a finished agent run — THREE outcomes, not two.- *- * A run retired by Resume/Relaunch carries `success: false` because it never- * reached a verdict: its task was handed to a continuation, usually because the- * user swapped providers after hitting a usage limit. Rendering that red said the- * run failed, for something the user did on purpose.- *- * Shared by the run card and the Resume dialog. They had the same two-way ternary- * copy-pasted, so going from two states to three meant editing both — and the- * copies had already drifted on the fallback text. One component instead, so the- * next state costs one edit and the two surfaces cannot disagree about what the- * same record says.- */+/** Shared delivery and execution verdict for cards and the Resume dialog. */export default function AgentResultLine({ agent, className = '' }) {if (!agent?.result) return null;const handoff = isAgentHandoff(agent);+ const outcome = normalizeTaskOutcome(agent.result.taskOutcome);+ const deliveryHeld = ['blocked', 'incomplete'].includes(outcome?.status);+ const deliveryComplete = isTaskDeliveryComplete(agent);+ const executionSuccess = agent.result.executionSuccess ?? agent.result.success;const assessment = [agent.metadata?.auditAssessment, agent.result.auditAssessment].find(value => value?.status === 'recorded') || agent.metadata?.auditAssessment || agent.result.auditAssessment;const assessmentUnverified = assessment && assessment.status !== 'recorded';@@ -34,19 +25,23 @@ export default function AgentResultLine({ agent, className = '' }) {const cleanupRecovery = agent.metadata?.recoveryOrigin?.subsystem === 'repository-cleanup';const cleanupPending = (cleanupRecovery || cleanup) && cleanup?.status !== 'verified';const incomplete = cleanupPending || interruption || scanIncomplete || assessmentUnverified || validationFailed || publicationIncomplete;- const tone = handoff ? 'text-port-accent' : agent.result.success ? incomplete ? 'text-port-warning' : 'text-port-success' : 'text-port-error';+ const tone = handoff ? 'text-port-accent' : !executionSuccess ? 'text-port-error' : incomplete || deliveryHeld ? 'text-port-warning'+ : deliveryComplete ? 'text-port-success' : executionSuccess ? 'text-port-text-muted' : 'text-port-error';return (<div className={`text-sm ${tone} ${className}`.trim()}><span className="flex items-center gap-2">{handoff ? (<><RotateCcw size={14} aria-hidden="true" /> {agentHandoffReason(agent)}</>- ) : agent.result.success ? (- <><CheckCircle size={14} aria-hidden="true" /> {incomplete || assessment ? 'Execution completed' : 'Completed successfully'}</>+ ) : deliveryHeld && executionSuccess ? (+ <><AlertCircle size={14} aria-hidden="true" /> {outcome.status === 'blocked' ? 'Task blocked' : 'Task incomplete'}</>+ ) : executionSuccess ? (+ <><CheckCircle size={14} aria-hidden="true" /> {incomplete || !deliveryComplete ? 'Execution completed' : outcome.status === 'no-action-needed' ? 'No action needed' : 'Completed successfully'}</>) : (<><AlertCircle size={14} aria-hidden="true" /> {agent.result.error || 'Failed'}</>)}</span>+ {!handoff && outcome?.reason && <div>{outcome.reason}</div>}{interruption && <div>Execution interrupted: {interruption.category === 'content-refusal' ? 'provider safety refusal; automatic retry stopped' : interruption.category}</div>}{cleanupPending && <div>Cleanup {cleanup?.status === 'already-absent' ? 'already absent; preservation unverified' : cleanup?.status === 'blocked' ? 'blocked' : 'unverified/pending'}{cleanup?.reason ? `: ${cleanup.reason}` : ''}<CleanupHolders owners={cleanup?.owners} /></div>}<SecurityScanEvidence scanner={scanner} control={agent.metadata?.securityScanControl} />diff --git a/client/src/components/cos/AgentResultLine.test.jsx b/client/src/components/cos/AgentResultLine.test.jsxindex 03c584fb7b..419aeb5a2c 100644--- a/client/src/components/cos/AgentResultLine.test.jsx+++ b/client/src/components/cos/AgentResultLine.test.jsx@@ -20,7 +20,7 @@ it('separates clean execution, assessment persistence and delivery validation',it('does not invent assessment or delivery validation for ordinary successful runs', () => {render(<AgentResultLine agent={{ result: { success: true, validationPassed: null } }} />);- expect(screen.getByText('Completed successfully')).toBeInTheDocument();+ expect(screen.getByText('Execution completed')).toBeInTheDocument();expect(screen.queryByText('Assessment saved')).not.toBeInTheDocument();expect(screen.queryByText('Delivery validation failed')).not.toBeInTheDocument();});@@ -112,7 +112,7 @@ it('does not promote historical cleanup process success to verified cleanup', ()expect(screen.getByText(/Cleanup already absent; preservation unverified/)).toBeInTheDocument();expect(screen.queryByText('Completed successfully')).not.toBeInTheDocument();view.rerender(<AgentResultLine agent={{ ...agent, metadata: { ...agent.metadata, cleanupOutcome: { status: 'verified' } } }} />);- expect(screen.getByText('Completed successfully')).toBeInTheDocument();+ expect(screen.getByText('Execution completed')).toBeInTheDocument();});it('names the live runs a claim-owner cleanup hold is waiting on', async () => {@@ -124,3 +124,16 @@ it('names the live runs a claim-owner cleanup hold is waiting on', async () => {expect(first).toHaveAttribute('href', '/cos/agents/agent-aaa');expect(screen.getByRole('link', { name: 'agent-bbb' })).toHaveAttribute('href', '/cos/agents/agent-bbb');});+++it('renders delivery separately from normal execution, including historical prose', () => {+ const agent = { result: { success: true }, metadata: { taskSummary: 'Status: BLOCKED - invented contradictory instructions' } };+ const view = render(<AgentResultLine agent={agent} />);+ expect(screen.getByText('Execution completed')).toBeInTheDocument();+ expect(screen.queryByText('Completed successfully')).not.toBeInTheDocument();+ for (const [status, label] of [['blocked', 'Task blocked'], ['incomplete', 'Task incomplete'], ['no-action-needed', 'No action needed'], ['completed', 'Completed successfully']]) {+ view.rerender(<AgentResultLine agent={{ result: { success: true, executionSuccess: true, taskOutcome: { status, reason: 'Invented evidence.' } } }} />);+ expect(screen.getByText(label)).toBeInTheDocument();+ expect(screen.getByText('Invented evidence.')).toBeInTheDocument();+ }+});diff --git a/client/src/lib/README.md b/client/src/lib/README.mdindex 0424c62684..220760096e 100644--- a/client/src/lib/README.md+++ b/client/src/lib/README.md@@ -149,7 +149,7 @@ grep -i "what you want to do" client/src/lib/README.md| Module | Purpose ||---|---|| `a11yKeyboard.js` | `clickableProps(handler, { role?, disabled? })` → `{ role, tabIndex, onKeyDown }` and `onActivateKeyDown(handler)` — make a non-`<button>` element with an `onClick` keyboard-accessible (Enter/Space activation, focusable, `role="button"`). Spread `clickableProps` next to the existing `onClick`. Use instead of hand-rolling `role`/`tabIndex`/`onKeyDown` on clickable `<div>`/`<span>`/`<li>`. Also the shared predicate every app-global key handler consults: `shouldIgnoreGlobalKey(event, { enabledInDialog?, ignoreRepeat?, allowChords? })` — the single "must this handler stand down?" answer (editable target, native Space button activation, ⌘/Ctrl/Alt chord, OS auto-repeat, open `aria-modal` dialog), used by `useKeyboardShortcuts`, `useKeyCapture` AND the voice widget's push-to-talk hotkey so their guard lists can't drift. Add a new guard there, not at one caller. Its parts are exported too: `isEditableTarget(el)`, `isButtonActivation(event)` (true when Space would natively activate the focused button) and `isPressKey(event)` (Enter or Space by either `key` or `code`). Also `isFocusEscapeKey(event)` — the shared "leave this widget" gesture (Shift+Tab backtab) that a key-capturing widget must release to the browser; the Shell terminal's `attachCustomKeyEventHandler` consults it so focus can escape the xterm trap. Plus `noPointerFocusSurfaceProps` — spread on the ROOT of a surface that owns a key globally (a Space-scored drill, the Morse keyer, RapidReader, the OpenWorld HUD); one capture-phase handler stops a mouse click anywhere inside from parking focus on a button and taking that key over via native activation, covering controls added later too. |-| `agentOutcome.js` | Re-export of `server/lib/agentOutcome.js`: `isAgentHandoff(agent)` — `result.resumed === true` — tells a record retired to hand its task to a continuation, a Resume or a provider Relaunch, from one that reached a verdict, and `agentHandoffReason(agent)` gives the line such a card should show. Cards reading `result.success` alone rendered a red "Failed" run for a swap the user made deliberately, and the needs-feedback filter asked them to rate it. Imported rather than copied so the run card and the daily report cannot disagree about whether a swap was a failure. |+| `agentOutcome.js` | Re-export of `server/lib/agentOutcome.js`: `isAgentHandoff(agent)` — `result.resumed === true` — tells a record retired to hand its task to a continuation, a Resume or a provider Relaunch, from one that reached a verdict, and `agentHandoffReason(agent)` gives the line such a card should show. Cards reading `result.success` alone rendered a red "Failed" run for a swap the user made deliberately, and the needs-feedback filter asked them to rate it. Imported rather than copied so the run card and the daily report cannot disagree about whether a swap was a failure. `normalizeTaskOutcome` validates explicit delivery evidence; `isTaskDeliveryComplete` admits completed/no-action-needed delivery only, and the server also resolves reported evidence against delivery checks with `resolveTaskOutcome`. || `cosAgentFeedback.js` | Client mirror of the server-owned CoS feedback eligibility, rating, legacy-update-target, and archive-locator predicates. || `agentResumeOutcome.js` | `agentResumeMessage(result, messages, fallback)` — the toast wording for a CoS agent resume/relaunch result. The server answers with a `mode` (what it did to the task) plus `spawned`/`spawnHold` (whether it also STARTED it — a resumed task is force-spawned when a slot is free, and `spawnHold` names the refusal when it isn't). `messages` is keyed by mode as `{ queued, running? }`; a mode with no `running` variant is one that deliberately queues nothing, so it can never be reported as started. Shared by the Resume dialog (`cos/tabs/AgentsTab.jsx`) and `cos/tabs/RelaunchAgentModal.jsx` so neither can say "queued" for a run that already started, or omit the reason it didn't. || `appIdentity.js` | `PORTOS_APP_ID` — stable id of the baseline PortOS app. Re-exported from `server/lib/appIdentity.js`; dependency-free so a module reachable from a server test can import it. |diff --git a/client/src/lib/agentOutcome.js b/client/src/lib/agentOutcome.jsindex 4ffbc117c0..864673b75b 100644--- a/client/src/lib/agentOutcome.js+++ b/client/src/lib/agentOutcome.js@@ -6,4 +6,4 @@* digest cannot drift on whether a provider swap was a failure. The file stays so* every `lib/agentOutcome` import path in the client is unchanged.*/-export { isAgentHandoff, agentHandoffReason } from '../../../server/lib/agentOutcome.js';+export { isAgentHandoff, agentHandoffReason, normalizeTaskOutcome, isTaskDeliveryComplete } from '../../../server/lib/agentOutcome.js';diff --git a/docs/features/chief-of-staff.md b/docs/features/chief-of-staff.mdindex ab3bb3b57c..f53f0f6d1a 100644--- a/docs/features/chief-of-staff.md+++ b/docs/features/chief-of-staff.md@@ -11,6 +11,23 @@ Autonomous agent manager that works the task queues, spawns sub-agents, and main- **CoS Routes** (`server/routes/cos.js`): REST API endpoints- **CoS UI** (`client/src/pages/ChiefOfStaff.jsx`): Tasks, Agents, Health, Config tabs+### Execution and delivery outcomes++A normal process exit or completion sentinel ends execution; it does not prove+that the task was achieved. Completion envelopes carry a markdown `summary`, an+optional task-specific `payload`, and `taskOutcome: { status, reason }`. The status+is `completed`, `no-action-needed`, `blocked`, or `incomplete`. Reasons describe+the delivery evidence, remaining work, or unmet prerequisite. A reported no-op+requires the task's existing delivery checks or permitted empty-branch proof.++Agent results and run history retain `executionSuccess` independently of the+validated `taskOutcome`; task metadata retains the outcome too. Blocked or+incomplete delivery parks the task and preserves work for continuation. Cards+and Resume show the same verdict, while old records without delivery evidence+say “Execution completed.” Historical user feedback is unchanged. GitHub+notification resolution requires explicit completed or verified no-action-needed+delivery; exit success alone cannot mark a thread done.+## Features1. **Dual Task Lists**: User tasks and system tasks, both stored in `cos_tasks`diff --git a/server/lib/README.md b/server/lib/README.mdindex fc35265e2e..4386134007 100644--- a/server/lib/README.md+++ b/server/lib/README.md@@ -78,7 +78,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub| `spriteAnimationTracks.js` | The animation-track registry (`ANIMATION_TRACKS`, `WALK_TRACK`, `TRACK_BOUND_TRIPLES`, `AUTHORED_TRACK_FIELDS`) — a zero-import table of per-track frame/fps bounds. || `spriteAnimationTrackStore.js` | The EFFECTIVE track table — compiled built-ins plus the user-defined store read from one small JSON config, so sprite schemas stay module-load constants rather than lazily-built. || `agentFinalVerdict.js` | `resolveAgentFinalVerdict` — the completion outcome `finalizeAgent` persists, as one pure function of its evidence: the drift > PR > goal-fidelity > output-hook > reported precedence ladder, returned as a frozen `{ source, success, errorAnalysis, error, completionReason }`. A permanent hook rejection escalates an already-failed run only through the caller's pure `failureIsTerminal` predicate, so the side-effecting retry resolution runs once. |-| `agentOutcome.js` | Is a completed CoS agent record an OUTCOME, or a HANDOFF to its own continuation? `isAgentHandoff(agent)` — `result.resumed === true`, what `resumeAgent`/`relaunchAgent` stamps when it retires a record and requeues the SAME task, typically because the user swapped providers after a usage limit. Every consumer that read `result.success` as the verdict booked a phantom failure per swap — a red history card, a failed task in the daily report and weekly digest, a dented success rate, a quota-burn denial recorded against "Relaunched by user", a feature agent flipped to `error` — so the rule task-learning already applied lives here once. Reads only `result`, so `completeAgent`'s stats writer can ask it before the record exists. Keyed on a field `resumeAgent` has always written, so archived relaunches reclassify retroactively with no migration. Also carries `agentHandoffReason(agent)` — `metadata.pauseReason` when a continuation was queued, else `result.error`, so an abandoned run is not captioned as a deliberate provider swap — and `isQueuedContinuation(agent)`, the narrower check for a caller about to SKIP its own completion handling because it expects a continuation run to fire it instead: `isAgentHandoff` alone is not proof a continuation exists (a stranded pause retirement also stamps `resumed: true` with nothing requeued), so use this one there. `client/src/lib/agentOutcome.js` re-exports this file rather than copying it. |+| `agentOutcome.js` | Is a completed CoS agent record an OUTCOME, or a HANDOFF to its own continuation? `isAgentHandoff(agent)` — `result.resumed === true`, what `resumeAgent`/`relaunchAgent` stamps when it retires a record and requeues the SAME task, typically because the user swapped providers after a usage limit. Every consumer that read `result.success` as the verdict booked a phantom failure per swap — a red history card, a failed task in the daily report and weekly digest, a dented success rate, a quota-burn denial recorded against "Relaunched by user", a feature agent flipped to `error` — so the rule task-learning already applied lives here once. Reads only `result`, so `completeAgent`'s stats writer can ask it before the record exists. Keyed on a field `resumeAgent` has always written, so archived relaunches reclassify retroactively with no migration. Also carries `agentHandoffReason(agent)` — `metadata.pauseReason` when a continuation was queued, else `result.error`, so an abandoned run is not captioned as a deliberate provider swap — and `isQueuedContinuation(agent)`, the narrower check for a caller about to SKIP its own completion handling because it expects a continuation run to fire it instead: `isAgentHandoff` alone is not proof a continuation exists (a stranded pause retirement also stamps `resumed: true` with nothing requeued), so use this one there. `client/src/lib/agentOutcome.js` re-exports this file rather than copying it. `normalizeTaskOutcome` validates explicit delivery evidence; `isTaskDeliveryComplete` admits completed/no-action-needed delivery only, and the server also resolves reported evidence against delivery checks with `resolveTaskOutcome`. || `cosAgentCompletionOrder.js` | Wire format + projection rule for the CoS archive completion-order sidecar (`data/cos/agents/index.order.json`). `projectArchivedAgent` reduces an archived record to its completion timestamp plus a completed / still-needs-feedback bitfield; `encodeCompletionOrder` / `decodeCompletionOrder` round-trip the versioned document, decoding anything unrecognized as empty so the readers repair it by re-reading the day. Shared by the runtime index and the one-shot backfill migration so the two cannot drift. || `cosAgentFeedback.js` | Pure shared eligibility, rating, update-target, and archive-locator predicates for durable CoS feedback actions; mirrored to the client so the queue and Agents tab use the server contract. || `agentOutputMarkers.js` | Status lines PortOS itself appends to an agent's output buffer: `SENTINEL_COMPLETION_MARKER` (the line `ingestDoneSentinel` writes just before the agent's `.agent-done` summary), `LIFECYCLE_LINES` (every TUI lifecycle line, declared once as a tagged template — the emitter writes `LIFECYCLE_LINES.<id>(values)` and the reader's pattern derives from the same text), plus `isAgentLifecycleLine(line)`/`stripLifecycleLines(lines)`, which match PortOS's telemetry on its actual message shapes rather than on a leading emoji (an agent's own summary may well start a line with `✅`). Pure — shared by the emitters (`services/agentTuiSpawning.js` and its `agentTuiSpawning/` modules) and by readers that must show only the agent's own words (notably the generated PR description). |diff --git a/server/lib/agentOutcome.js b/server/lib/agentOutcome.jsindex 7202f29487..24d933f352 100644--- a/server/lib/agentOutcome.js+++ b/server/lib/agentOutcome.js@@ -90,3 +90,31 @@ export function agentHandoffReason(agent) {const handedOn = !!agent?.result?.resumedTaskId;return (handedOn ? pauseReason || error : error || pauseReason) || 'Handed off to a new run';}+++/** Explicit delivery evidence, separate from a process ending normally. */+export function normalizeTaskOutcome(value) {+ if (!value || typeof value !== 'object' || Array.isArray(value)) return null;+ if (!['completed', 'no-action-needed', 'blocked', 'incomplete'].includes(value.status)) return null;+ if (typeof value.reason !== 'string' || !value.reason.trim()) return null;+ return { status: value.status, reason: value.reason.trim() };+}++/** Only evidenced delivery may resolve external work; legacy exits are unknown. */+export function isTaskDeliveryComplete(agent) {+ const outcome = normalizeTaskOutcome(agent?.result?.taskOutcome);+ return !isAgentHandoff(agent) && agent?.result?.success === true+ && agent.result.validationPassed !== false+ && ['completed', 'no-action-needed'].includes(outcome?.status);+}++export function resolveTaskOutcome({ reported, success, validationPassed, branchProvenEmpty, noChangeAllowed }) {+ if (reported && ['blocked', 'incomplete'].includes(reported.status)) return reported;+ if (!success || validationPassed === false) return { status: 'incomplete', reason: 'Delivery checks did not pass.' };+ if (branchProvenEmpty && noChangeAllowed) return { status: 'no-action-needed', reason: 'The permitted no-change result was verified against the repository.' };+ if (reported?.status === 'no-action-needed' && validationPassed !== true) {+ return { status: 'incomplete', reason: 'The reported no-action-needed result was not verified.' };+ }+ if (reported) return reported;+ return validationPassed === true ? { status: 'completed', reason: 'The task delivery criteria passed.' } : null;+}diff --git a/server/lib/agentSentinel.js b/server/lib/agentSentinel.jsindex 08e1f3619b..4d62d775c8 100644--- a/server/lib/agentSentinel.js+++ b/server/lib/agentSentinel.js@@ -21,6 +21,7 @@*/import { join } from 'path';+import { normalizeTaskOutcome } from './agentOutcome.js';import { safeJSONParse, sanitizeFilename } from './fileUtils.js';@@ -154,7 +155,8 @@ export function parseSentinelPayload(contents) {if (parsed && typeof parsed === 'object') {const summary = typeof parsed.summary === 'string' ? parsed.summary : '';const payload = 'payload' in parsed ? parsed.payload : null;- return { summary, payload };+ const taskOutcome = normalizeTaskOutcome(parsed.taskOutcome);+ return { summary, payload, ...(taskOutcome ? { taskOutcome } : {}) };}return { summary: trimmed, payload: null };diff --git a/server/services/agentFinalization.js b/server/services/agentFinalization.jsindex 70e04dddea..eea165080c 100644--- a/server/services/agentFinalization.js+++ b/server/services/agentFinalization.js@@ -23,6 +23,7 @@ import { isPrivateSecurityTask } from '../lib/privateSecurityPolicy.js';*/import { join } from 'path';+import { normalizeTaskOutcome, resolveTaskOutcome } from '../lib/agentOutcome.js';import { execGit } from '../lib/execGit.js';import { PATHS, safeJSONParse, tryReadFile } from '../lib/fileUtils.js';import { cosEvents, emitLog } from './cosEvents.js';@@ -246,6 +247,7 @@ export async function evaluateSuccessCriteria({ task, terminatedByUser, workspac* null = undeclared, SKIP_LEARNING_VERDICT = do not record this run*/export function resolveProgrammaticIoVerdict({ success, hookResult }) {+ if (hookResult?.alreadyDispatched && typeof hookResult.validationPassed === 'boolean') return hookResult.validationPassed;if (!hookResult?.ran) return null;// A thrown hook rejected the output. Classified FIRST: it carries no outcome (so// it must precede the outcome-shape guard), and a rejection shouldn't hinge on@@ -1071,7 +1073,8 @@ export function dispatchTaskOutputHookOnce({// fails, while the in-flight promise still protects concurrent callers// this cycle.await updateAgent(agentId, {- metadata: { outputHookDispatchedAt: new Date().toISOString() }+ metadata: { outputHookDispatchedAt: new Date().toISOString(),+ outputHookValidationPassed: resolveProgrammaticIoVerdict({ success, hookResult: result }) }}).catch(err => {emitLog('warn', `⚠️ Failed to persist output-hook dispatch marker for ${agentId}: ${err.message}`, { agentId });});@@ -1089,7 +1092,9 @@ export function dispatchTaskOutputHookOnce({...(Number(task.metadata?.auditDispositionVersion) === 1 ? { auditDisposition: { status: 'complete' } } : {}) };}if (agent?.metadata?.outputHookDispatchedAt) {- return { ran: false, alreadyDispatched: true, ...(agent.metadata?.deepAudit ? { deepAudit: agent.metadata.deepAudit } : {}) };+ return { ran: false, alreadyDispatched: true,+ ...(typeof agent.metadata.outputHookValidationPassed === 'boolean' ? { validationPassed: agent.metadata.outputHookValidationPassed } : {}),+ ...(agent.metadata?.deepAudit ? { deepAudit: agent.metadata.deepAudit } : {}) };}const hookDispatch = dispatchTaskOutputHook({@@ -1189,7 +1194,7 @@ export function dispatchRecoveredTaskOutputHook({ agentId, task, success, worksp* @param {object} [params.agentResultExtra] caller-specific fields merged into the agent-record* result (e.g. the sweep's `interruptedByRestart` telemetry) — kept out of the shared shape so* one caller's bookkeeping detail doesn't leak an unused field onto the other's records- * @returns {Promise<{ success: boolean }>} the effective success used for the retirement (post+ * @returns {Promise<{ success: boolean, taskOutcome: object|null, deliveryHeld: boolean }>} the effective success used for the retirement (post* private-security override), so callers that branch on it don't have to re-derive it*/export async function retireDeadAgent({ agent, task, success, exitCode, duration, errorMessage, category, agentResultExtra = {} }) {@@ -1202,7 +1207,11 @@ export async function retireDeadAgent({ agent, task, success, exitCode, durationconst isPrivateSecurity = isPrivateSecurityTask(task) || isPrivateSecurityTask(agent);const interruption = agent.metadata?.executionInterruption;const refused = ['content-refusal', 'content-filtered'].includes(interruption?.category);- let effectiveSuccess = isPrivateSecurity || refused ? false : success;+ const reportedOutcome = !isPrivateSecurity && !refused+ ? await persistCompletionSummary(agent.id, { workspacePath: agent.metadata?.workspacePath, existingRecord: agent }) : null;+ const reportedHold = ['blocked', 'incomplete'].includes(reportedOutcome?.status);+ const executionSuccess = success && exitCode === 0;+ let effectiveSuccess = isPrivateSecurity || refused || reportedHold ? false : success;const errorAnalysis = refused ? {category: interruption.category, origin: interruption.source || 'provider',message: 'Provider safety refusal; automatic continuation, retries and provider fallback are disabled.',@@ -1217,15 +1226,13 @@ export async function retireDeadAgent({ agent, task, success, exitCode, duration});if (Number(task?.metadata?.auditDispositionVersion) === 1 && recoveredHook?.auditDisposition?.status !== 'complete') effectiveSuccess = false;-- // Recovery retires the run without reaching finalizeAgent's completion- // cleanup, so the sentinel has no other owner — and the hook above was the- // last thing to read it. Keep this recovery-only dependency lazy: the- // completion-cleanup module also imports worktree/PR orchestration, while- // agentFinalization is on the static path of nearly every agent service.- const { removeCompletionSentinel } = await import('./agentCompletionCleanup.js');- await removeCompletionSentinel({ agentId: agent.id, agentState: agent })- .catch(err => emitLog('warn', `Completion sentinel removal failed for ${agent.id}: ${err.message}`, { agentId: agent.id }));+ const validationPassed = isProgrammaticIoTaskType(resolveTaskHookType(task))+ ? resolveProgrammaticIoVerdict({ success: effectiveSuccess, hookResult: recoveredHook })+ : agent.result?.validationPassed ?? null;+ const taskOutcome = reportedOutcome ? resolveTaskOutcome({ reported: reportedOutcome,+ success: effectiveSuccess, validationPassed }) : null;+ const deliveryHeld = ['blocked', 'incomplete'].includes(taskOutcome?.status);+ if (deliveryHeld) effectiveSuccess = false;if (agent.metadata?.runId) {const bufferedOutput = Array.isArray(agent.output)@@ -1238,12 +1245,23 @@ export async function retireDeadAgent({ agent, task, success, exitCode, durationexitCode,duration,errorAnalysis,- ...(Number(task?.metadata?.auditDispositionVersion) === 1 ? [effectiveSuccess ? null : false] : []),+ effectiveSuccess ? null : false,+ { executionSuccess, taskOutcome },);}+ if (deliveryHeld && task?.id && task.status !== 'completed') {+ const update = await updateTask(task.id, { status: 'blocked', metadata: { ...task.metadata,+ taskOutcome, blockedCategory: `task-${taskOutcome.status}`, blockedReason: taskOutcome.reason,+ blockedAt: new Date().toISOString(),+ } }, task.taskType || 'user');+ if (update?.error) throw new Error(`Could not persist recovered task outcome: ${update.error}`);+ }await completeAgent(agent.id, {success: effectiveSuccess,+ executionSuccess,+ taskOutcome,+ validationPassed,exitCode,duration,orphaned: true,@@ -1254,7 +1272,17 @@ export async function retireDeadAgent({ agent, task, success, exitCode, duration...(refused ? { success: false, error: errorAnalysis.message, errorAnalysis, executionInterruption: interruption } : {}),});- return { success: effectiveSuccess };+ // Recovery retires the run without reaching finalizeAgent's completion+ // cleanup, so the sentinel has no other owner — and the hook above was the+ // last consumer of its payload. Persist the outcome before removing evidence.+ // Keep this recovery-only dependency lazy: the+ // completion-cleanup module also imports worktree/PR orchestration, while+ // agentFinalization is on the static path of nearly every agent service.+ const { removeCompletionSentinel } = await import('./agentCompletionCleanup.js');+ await removeCompletionSentinel({ agentId: agent.id, agentState: agent })+ .catch(err => emitLog('warn', `Completion sentinel removal failed for ${agent.id}: ${err.message}`, { agentId: agent.id }));++ return { success: effectiveSuccess, taskOutcome, deliveryHeld };}/**@@ -1643,6 +1671,16 @@ export async function finalizeAgent({prExpected = false,startedAt = null,}) {+ const executionSuccess = reportedSuccess && (typeof exitCode !== 'number' || exitCode === 0);+ const reportedTaskOutcome = !terminatedByUser && !isPrivateSecurityTask(task)+ ? await persistCompletionSummary(agentId, { workspacePath, finalSummary }) : null;+ const deliveryHeld = ['blocked', 'incomplete'].includes(reportedTaskOutcome?.status);+ if (deliveryHeld) {+ reportedSuccess = false;+ error = reportedTaskOutcome.reason;+ reportedErrorAnalysis = { category: `task-${reportedTaskOutcome.status}`, message: error,+ permanent: true, actionable: false, requiresFallback: false };+ }if (resolveTaskHookType(task) === 'security') {const { settleAgentSecurityScan } = await import('./agentSecurityScan.js');const scanner = await settleAgentSecurityScan(agentId);@@ -1795,9 +1833,6 @@ export async function finalizeAgent({const judgedVerdict = resolveAgentFinalVerdict({ ...verdictEvidence, fidelityReview: fidelity.review });await followUpAgentGoalFidelity({ agentId, task, fidelity, fidelityDowngrade });- if (!terminatedByUser && !isPrivateSecurityTask(task)) {- await persistCompletionSummary(agentId, { workspacePath, finalSummary });- }// Programmatic-I/O task types (e.g. layered-intelligence) run a deterministic// post-agent step on the agent's STRUCTURED output — the parsed `.agent-done`@@ -1852,7 +1887,6 @@ export async function finalizeAgent({});const taskType = task?.taskType || 'user';- const taskUpdate = await resolveFinalTaskUpdate({ task, preHookTask, hookMetadata, verdict, terminatedByUser, agentId });// Success-criteria validation (issue #2344): stamp an explicit pass/fail (or// null-when-undeclared) verdict onto the completion result, distinct from the@@ -1874,14 +1908,29 @@ export async function finalizeAgent({return null;});+ const taskOutcome = resolveTaskOutcome({ reported: reportedTaskOutcome, success: verdict.success,+ validationPassed, branchProvenEmpty, noChangeAllowed: permitsNoChangeCompletion(task) });+ const outcomeHeld = ['blocked', 'incomplete'].includes(taskOutcome?.status);+ const deliverySuccess = verdict.success && !outcomeHeld;+ const deliveryVerdict = !deliverySuccess && verdict.success ? { ...verdict, success: false,+ error: taskOutcome.reason,+ errorAnalysis: { category: hookResult?.outcome?.reason || `task-${taskOutcome.status}`,+ message: taskOutcome.reason, permanent: true, actionable: false, requiresFallback: false },+ } : verdict;+ const taskUpdate = (deliveryHeld || (verdict.success && outcomeHeld)) && !terminatedByUser+ ? { status: 'blocked', metadata: { ...preHookTask.metadata, blockedReason: taskOutcome.reason,+ blockedCategory: `task-${taskOutcome.status}`, blockedAt: new Date().toISOString() } }+ : await resolveFinalTaskUpdate({ task, preHookTask, hookMetadata, verdict, terminatedByUser, agentId });+ taskUpdate.metadata = { ...(taskUpdate.metadata || task.metadata), taskOutcome };+if (isLegacyDeepAudit(task.metadata) && hookResult?.deepAudit) {hookResult.deepAudit = await (await import('./deepAudit.js')).settleDeepAuditDelivery({task, agentId, success: verdict.success && !terminatedByUser, validationPassed,}).catch(err => ({ ...hookResult.deepAudit, complete: false, deliveryComplete: false, reason: `Delivery persistence failed: ${err.message}` }));await updateAgent(agentId, { metadata: { deepAudit: hookResult.deepAudit } });- if (hookResult.deepAudit.complete && verdict.success && !terminatedByUser) {+ if (hookResult.deepAudit.complete && verdict.success && !terminatedByUser && !outcomeHeld) {taskUpdate.status = 'completed';- taskUpdate.metadata = { ...task.metadata };+ taskUpdate.metadata = { ...task.metadata, taskOutcome };}}@@ -1891,9 +1940,9 @@ export async function finalizeAgent({// completeAgentRun writes its own runs/<id>/metadata.json (separate lock),// so its place in the chain is purely about progress reporting on partial// failure.- await completeAgent(agentId, completionRecord({- task, verdict, hookResult, fidelity, executionInterruption, exitCode, duration, outputBuffer, validationPassed,- }));+ await completeAgent(agentId, { ...completionRecord({+ task, verdict: deliveryVerdict, hookResult, fidelity, executionInterruption, exitCode, duration, outputBuffer, validationPassed,+ }), executionSuccess, taskOutcome });if (runId) {// Every failed verdict overrides exit-code/commit rescue in run tracking,@@ -1903,7 +1952,7 @@ export async function finalizeAgent({? 'Private security assessment: see the local Review Hub report.': 'Private security assessment report was not verified; inspect the local assessment archive.': outputBuffer;- await completeAgentRun(runId, runOutput, exitCode, duration, verdict.errorAnalysis, verdict.success ? null : false);+ await completeAgentRun(runId, runOutput, exitCode, duration, deliveryVerdict.errorAnalysis, deliverySuccess ? null : false, { executionSuccess, taskOutcome });}// LI hand-off execution verdict (#2779): stamp the per-proposal execution outcome into@@ -1911,7 +1960,7 @@ export async function finalizeAgent({// (which filed the proposal and runs LI for that app) can derive `recordProposalExecution`// from the terminal synced task — cross-peer parity for the #2765 LOCAL write, which only// lands on the peer that ran the agent.- await stampLiExecutionVerdict(taskUpdate, task, { success: verdict.success, validationPassed, errorAnalysis: verdict.errorAnalysis });+ await stampLiExecutionVerdict(taskUpdate, task, { success: deliverySuccess, validationPassed, errorAnalysis: deliveryVerdict.errorAnalysis });// The bounded source inventory belongs only to this run and its private// report. Task metadata is replicated to peers and reused in later prompts.@@ -1927,9 +1976,9 @@ export async function finalizeAgent({await sidelineFailedAgentProvider({ providerId, verdict, terminatedByUser });- await recordScheduledAgentOutcome({ agentId, task, verdict, terminatedByUser, hookResult });+ await recordScheduledAgentOutcome({ agentId, task, verdict: deliveryVerdict, terminatedByUser, hookResult });- await processAgentCompletion(agentId, task, verdict.success, outputBuffer);+ await processAgentCompletion(agentId, task, deliverySuccess, outputBuffer);if (usesCreativeDirectorScratchCwd(task)) {await removeCreativeDirectorScratchCwd(agentId).catch((err) => {@@ -1943,7 +1992,8 @@ export async function finalizeAgent({// removed, local branch deleted, and no resume pointer recorded — destroying// the state the retry needs to open the PR that is missing.return {- success: verdict.success,+ success: deliverySuccess,+ taskOutcome,prClaimVerified: prClaimWasVerified(prEvidence.cleanupEvidence),branchProvenEmpty: prEvidence.branchProvenEmpty,cleanupEvidence: prEvidence.cleanupEvidence,@@ -2217,12 +2267,14 @@ async function dispatchTaskOutputHook({ agentId, task, success, workspacePath, a* The transcript remains available separately; it is never a substitute for a* missing final response, including on a partial Deep checkpoint.*/-async function persistCompletionSummary(agentId, { workspacePath, finalSummary = null }) {+async function persistCompletionSummary(agentId, { workspacePath, finalSummary = null, existingRecord = null }) {const { doneSentinelPath, parseSentinelPayload } = await import('../lib/agentSentinel.js');const sentinelPath = doneSentinelPath(workspacePath, agentId);const contents = sentinelPath ? await tryReadFile(sentinelPath) : null;let summary = null;let source = null;+ let taskOutcome = null;+ let taskOutcomeSource = null;if (typeof contents === 'string' && contents.trim()) {const trimmed = contents.trim();const envelope = trimmed.match(/^```json\s*\n([\s\S]*?)\n```$/)?.[1]?.trim() ?? trimmed;@@ -2230,28 +2282,46 @@ async function persistCompletionSummary(agentId, { workspacePath, finalSummary =// Legacy markdown sentinels remain supported.const structured = trimmed.startsWith('{') || trimmed.startsWith('[') || trimmed.startsWith('```json');const parsed = structured ? safeJSONParse(envelope, null) : null;+ taskOutcome = normalizeTaskOutcome(parsed?.taskOutcome);+ if (taskOutcome) taskOutcomeSource = 'sentinel';if (!structured || (parsed && !Array.isArray(parsed) && typeof parsed.summary === 'string')) {- summary = parseSentinelPayload(envelope).summary.trim() || null;+ const parsedSentinel = parseSentinelPayload(envelope);+ summary = parsedSentinel.summary.trim() || null;+ taskOutcome = parsedSentinel.taskOutcome || null;if (summary) source = 'sentinel';}}if (!summary && typeof finalSummary === 'string') {- summary = finalSummary.trim() || null;+ const terminal = parseSentinelPayload(finalSummary);+ summary = terminal.summary.trim() || null;+ if (!taskOutcome && terminal.taskOutcome) {+ taskOutcome = terminal.taskOutcome;+ taskOutcomeSource = 'terminal-result';+ }if (summary) source = 'terminal-result';}- if (!summary) {+ if (!summary && !taskOutcome) {// Cleanup may already have removed the sentinel on a finalization replay.// Only retain a completion whose source was recorded for this same agent;// older heuristic transcript summaries are not evidence of a final reply.- const existing = await getAgentRecord(agentId);+ const existing = existingRecord || await getAgentRecord(agentId);+ if (existing?.id === agentId) {+ taskOutcome = normalizeTaskOutcome(existing.result?.taskOutcome)+ || (['sentinel', 'terminal-result'].includes(existing.metadata?.taskOutcomeSource)+ ? normalizeTaskOutcome(existing.metadata?.taskOutcome) : null);+ if (taskOutcome) taskOutcomeSource = existing.metadata?.taskOutcomeSource || 'saved-result';+ }if (existing?.id === agentId&& ['sentinel', 'terminal-result'].includes(existing.metadata?.taskSummarySource)&& typeof existing.metadata?.taskSummary === 'string'- && existing.metadata.taskSummary.trim()) return;+ && existing.metadata.taskSummary.trim()) return taskOutcome;}await updateAgent(agentId, { metadata: {taskSummary: summary,taskSummarySource: source,+ taskOutcome,+ taskOutcomeSource,simplifySummary: null,} });+ return taskOutcome;}diff --git a/server/services/agentFinalization.outputHooks.test.js b/server/services/agentFinalization.outputHooks.test.jsindex cde2556e38..6dde44c14d 100644--- a/server/services/agentFinalization.outputHooks.test.js+++ b/server/services/agentFinalization.outputHooks.test.js@@ -49,6 +49,7 @@ import { getAgent, getAgentRecord, updateAgent, completeAgent } from './cosAgentimport { canRunTaskOutputHookWithoutPayload, getTaskOutputHook, isProgrammaticIoTaskType } from './taskTypeHooks.js';import {finalizeAgent,+ retireDeadAgent,dispatchRecoveredTaskOutputHook,dispatchTaskOutputHookOnce,} from './agentFinalization.js';@@ -130,7 +131,7 @@ describe('recovery output-hook dispatch (#3182)', () => {});await vi.waitFor(() => expect(recordTaskTypeSuccess).toHaveBeenCalledWith('example-output-hook', 'app-example'));- expect(updateTask).toHaveBeenCalledWith(TASK.id, { status: 'completed' }, 'internal');+ expect(updateTask).toHaveBeenCalledWith(TASK.id, expect.objectContaining({ status: 'completed', metadata: expect.objectContaining({ taskOutcome: { status: 'completed', reason: 'The task delivery criteria passed.' } }) }), 'internal');expect(processAgentCompletion).not.toHaveBeenCalled();rejectLedger(new Error('ledger write failed'));@@ -315,7 +316,7 @@ describe('recovery output-hook dispatch (#3182)', () => {await finalizeAgent({ agentId: 'audit-final', task, success: true, exitCode: 0, duration: 1000,workspacePath: '/missing-audit-worktree', startedAt: Date.now() - 1000, outputBuffer: 'Audit complete' });expect(completeAgent).toHaveBeenCalledWith('audit-final', expect.objectContaining({- success: true, validationPassed: false, auditAssessment: { status: 'not-recorded' },+ success: false, executionSuccess: true, validationPassed: false, taskOutcome: { status: 'incomplete', reason: 'Delivery checks did not pass.' }, auditAssessment: { status: 'not-recorded' },}));isProgrammaticIoTaskType.mockReturnValue(true);});@@ -347,6 +348,80 @@ describe('recovery output-hook dispatch (#3182)', () => {}});+ it.each(['blocked', 'incomplete', 'completed', 'no-action-needed'])('persists explicit %s delivery independently of a zero exit', async (status) => {+ const { mkdtemp, writeFile, rm } = await import('node:fs/promises');+ const { tmpdir } = await import('node:os');+ const workspacePath = await mkdtemp(join(tmpdir(), 'task-outcome-'));+ const taskOutcome = { status, reason: 'Invented prerequisite or delivery evidence.' };+ const held = ['blocked', 'incomplete'].includes(status);+ const task = { ...TASK, metadata: { ...TASK.metadata } };+ try {+ await writeFile(join(workspacePath, '.agent-done-agent-example'), JSON.stringify({ summary: 'Invented final report.', taskOutcome, payload: { result: 'example' } }));+ const result = await finalizeAgent({ agentId: 'agent-example', runId: 'run-example', task, success: true,+ exitCode: 0, duration: 1000, workspacePath, outputBuffer: '' });+ expect(result).toMatchObject({ success: !held, taskOutcome });+ expect(completeAgent).toHaveBeenCalledWith('agent-example', expect.objectContaining({ executionSuccess: true, success: !held, taskOutcome }));+ expect(completeAgentRun).toHaveBeenCalledWith('run-example', '', 0, 1000, held ? expect.objectContaining({ category: `task-${status}` }) : undefined, held ? false : null, { executionSuccess: true, taskOutcome });+ expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: held ? 'blocked' : 'completed', metadata: expect.objectContaining({ taskOutcome }) }), task.taskType);+ expect(persistedAgent.metadata.taskOutcome).toEqual(taskOutcome);+ expect(processAgentCompletion).toHaveBeenCalledWith('agent-example', task, !held, '');+ } finally {+ await rm(workspacePath, { recursive: true, force: true });+ }+ });++ it('holds an unverified no-op but leaves legacy prose as unknown delivery', async () => {+ isProgrammaticIoTaskType.mockReturnValue(false);+ try {+ const task = { id: 'user-example', taskType: 'user', metadata: {} };+ await finalizeAgent({ agentId: 'agent-example', task, success: true, exitCode: 0, outputBuffer: '',+ finalSummary: JSON.stringify({ summary: 'Invented no-op.', taskOutcome: { status: 'no-action-needed', reason: 'No changes made.' } }) });+ expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ executionSuccess: true, success: false,+ taskOutcome: { status: 'incomplete', reason: 'The reported no-action-needed result was not verified.' } }));+ await finalizeAgent({ agentId: 'agent-example', task, success: true, exitCode: 0, outputBuffer: '',+ finalSummary: 'Status: BLOCKED - invented contradictory instructions' });+ expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ executionSuccess: true, taskOutcome: null }));+ } finally {+ isProgrammaticIoTaskType.mockReturnValue(true);+ }+ });++ it('replays verified no-op recovery after terminal persistence fails without repeating its hook', async () => {+ const { mkdtemp, writeFile, rm } = await import('node:fs/promises');+ const { tmpdir } = await import('node:os');+ const workspacePath = await mkdtemp(join(tmpdir(), 'verified-noop-replay-'));+ const taskOutcome = { status: 'no-action-needed', reason: 'Invented verified no-op.' };+ persistedAgent.metadata.workspacePath = workspacePath;+ hook.mockResolvedValue({ accepted: true });+ completeAgent.mockRejectedValueOnce(new Error('invented persistence failure'));+ const finish = () => retireDeadAgent({ agent: persistedAgent, task: TASK, success: true, exitCode: 0, duration: 1000 });+ try {+ await writeFile(join(workspacePath, '.agent-done-agent-example'), JSON.stringify({ taskOutcome }));+ await expect(finish()).rejects.toThrow('invented persistence failure');+ await expect(finish()).resolves.toEqual({ success: true, taskOutcome, deliveryHeld: false });+ expect(hook).toHaveBeenCalledOnce();+ expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ success: true, validationPassed: true, taskOutcome }));+ } finally { await rm(workspacePath, { recursive: true, force: true }); }+ });++ it('retains an outcome-only sentinel on repeat finalization after cleanup', async () => {+ const { mkdtemp, writeFile, rm } = await import('node:fs/promises');+ const { tmpdir } = await import('node:os');+ const workspacePath = await mkdtemp(join(tmpdir(), 'outcome-replay-'));+ const sentinelPath = join(workspacePath, '.agent-done-agent-example');+ const taskOutcome = { status: 'blocked', reason: 'Invented prerequisite remains unmet.' };+ const finish = () => finalizeAgent({ agentId: 'agent-example', task: TASK, success: true,+ exitCode: 0, duration: 1000, workspacePath, outputBuffer: '' });+ try {+ await writeFile(sentinelPath, JSON.stringify({ taskOutcome }));+ await finish();+ await rm(sentinelPath);+ await finish();+ expect(completeAgent).toHaveBeenLastCalledWith('agent-example', expect.objectContaining({ success: false, executionSuccess: true, taskOutcome }));+ expect(updateTask).toHaveBeenLastCalledWith(TASK.id, expect.objectContaining({ status: 'blocked', metadata: expect.objectContaining({ taskOutcome }) }), TASK.taskType);+ } finally { await rm(workspacePath, { recursive: true, force: true }); }+ });+it.each(['sentinel', 'terminal-result', 'legacy'])('retains only authoritative %s summaries on repeat finalization after cleanup', async (source) => {const { mkdtemp, writeFile, rm } = await import('node:fs/promises');const { tmpdir } = await import('node:os');@@ -381,7 +456,7 @@ it('finishes extended Deep with an honest partial summary through ordinary complworkspacePath: '/example/repo', finalSummary: 'Investigated high-risk paths and fixed two coherent defects. Coverage remains partial.', outputBuffer: 'tool transcript' });expect(deep.checkpointDeepAudit).not.toHaveBeenCalled();expect(deep.settleDeepAuditDelivery).not.toHaveBeenCalled();- expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'completed' }), expect.anything());+ expect(updateTask).toHaveBeenCalledWith(task.id, expect.objectContaining({ status: 'completed', metadata: expect.objectContaining({ taskOutcome: null }) }), expect.anything());expect(persistedAgent.metadata.taskSummary).toContain('Coverage remains partial');expect(persistedAgent.metadata.taskSummarySource).toBe('terminal-result');});@@ -428,7 +503,7 @@ it('finishes extended Deep with an honest partial summary through ordinary compl}));expect(updateAgent).toHaveBeenCalledWith(persistedAgent.id,- { metadata: { outputHookDispatchedAt: expect.any(String) } },+ { metadata: { outputHookDispatchedAt: expect.any(String), outputHookValidationPassed: expect.any(Boolean) } },);});@@ -457,7 +532,7 @@ it('finishes extended Deep with an honest partial summary through ordinary complagentId: persistedAgent.id,task: TASK,success: false,- })).resolves.toEqual({ ran: false, alreadyDispatched: true });+ })).resolves.toMatchObject({ ran: false, alreadyDispatched: true });expect(hook).toHaveBeenCalledOnce();});@@ -484,7 +559,7 @@ it('finishes extended Deep with an honest partial summary through ordinary complfinishHook({ recorded: true });await vi.waitFor(() => expect(updateAgent).toHaveBeenCalledWith(persistedAgent.id,- { metadata: { outputHookDispatchedAt: expect.any(String) } },+ { metadata: { outputHookDispatchedAt: expect.any(String), outputHookValidationPassed: expect.any(Boolean) } },));vi.useRealTimers();@@ -492,7 +567,7 @@ it('finishes extended Deep with an honest partial summary through ordinary complagentId: persistedAgent.id,task: TASK,success: false,- })).resolves.toEqual({ ran: false, alreadyDispatched: true });+ })).resolves.toMatchObject({ ran: false, alreadyDispatched: true });expect(hook).toHaveBeenCalledOnce();});@@ -503,7 +578,7 @@ it('finishes extended Deep with an honest partial summary through ordinary complagentId: persistedAgent.id,task: TASK,success: false,- })).resolves.toEqual({ ran: false, alreadyDispatched: true });+ })).resolves.toMatchObject({ ran: false, alreadyDispatched: true });expect(hook).not.toHaveBeenCalled();});@@ -600,7 +675,7 @@ describe('permanent output-hook rejection (#6124)', () => {errorAnalysis: expect.objectContaining({ permanent: true, origin: 'task-output-hook' }),}));expect(completeAgentRun).toHaveBeenCalledWith('run-rejected', '', 1, 1000,- expect.objectContaining({ category: 'output-missing', permanent: true }), false);+ expect.objectContaining({ category: 'output-missing', permanent: true }), false, expect.objectContaining({ executionSuccess: false, taskOutcome: { status: 'incomplete', reason: 'Delivery checks did not pass.' } }));expect(addTask).not.toHaveBeenCalled();// The task's retry decision is resolved once, against the final verdict —// not once for the run's own failure and again for the escalation (#9645).diff --git a/server/services/agentFinalization.retireDeadAgent.test.js b/server/services/agentFinalization.retireDeadAgent.test.jsindex 8a17e0840f..ec8ee4af5c 100644--- a/server/services/agentFinalization.retireDeadAgent.test.js+++ b/server/services/agentFinalization.retireDeadAgent.test.js@@ -56,8 +56,12 @@ vi.mock('./codeReview.js', async (importOriginal) => ({}));import { completeAgent } from './cosAgentLifecycle.js';+import { updateTask } from './cosTaskStore.js';+import { mkdtemp, writeFile, rm } from 'node:fs/promises';+import { join } from 'node:path';+import { tmpdir } from 'node:os';import { removeCompletionSentinel } from './agentCompletionCleanup.js';-import { getTaskOutputHook } from './taskTypeHooks.js';+import { getTaskOutputHook, isProgrammaticIoTaskType } from './taskTypeHooks.js';import { completeAgentRun } from './agentRunTracking.js';import { retireDeadAgent } from './agentFinalization.js';import { PRIVATE_SECURITY_TASK_TYPE } from '../lib/privateSecurityPolicy.js';@@ -92,9 +96,12 @@ describe('retireDeadAgent (#8440)', () => {expect(completeAgentRun).toHaveBeenCalledWith('run-1', '', 1, 500, {message: 'Agent process terminated unexpectedly',category: 'orphaned',- });+ }, false, { executionSuccess: false, taskOutcome: null });expect(completeAgent).toHaveBeenCalledWith('agent-dead', {success: false,+ executionSuccess: false,+ taskOutcome: null,+ validationPassed: null,exitCode: 1,duration: 500,orphaned: true,@@ -102,6 +109,45 @@ describe('retireDeadAgent (#8440)', () => {});});+ it.each(['blocked', 'incomplete'])('preserves a recovered %s sentinel and parks its task before removing evidence', async status => {+ const workspacePath = await mkdtemp(join(tmpdir(), 'recovered-outcome-'));+ const taskOutcome = { status, reason: 'Invented prerequisite remains unmet.' };+ const order = [];+ updateTask.mockImplementationOnce(async () => { order.push('task'); return {}; });+ removeCompletionSentinel.mockImplementationOnce(async () => { order.push('remove'); });+ try {+ await writeFile(join(workspacePath, '.agent-done-agent-dead'), JSON.stringify({ taskOutcome }));+ const result = await retireDeadAgent({ agent: { ...AGENT, metadata: { workspacePath, runId: 'run-1' } },+ task: TASK, success: true, exitCode: 0, duration: 100 });+ expect(result).toEqual({ success: false, taskOutcome, deliveryHeld: true });+ expect(completeAgent).toHaveBeenCalledWith(AGENT.id, expect.objectContaining({ success: false, executionSuccess: true, taskOutcome }));+ expect(updateTask).toHaveBeenCalledWith(TASK.id, expect.objectContaining({ status: 'blocked', metadata: expect.objectContaining({ taskOutcome }) }), 'user');+ expect(order).toEqual(['task', 'remove']);+ } finally { await rm(workspacePath, { recursive: true, force: true }); }+ });++ it('accepts a recovered no-op only after its output hook verifies delivery', async () => {+ const taskOutcome = { status: 'no-action-needed', reason: 'Invented verification found no remaining work.' };+ const hook = vi.fn(async () => ({ accepted: true }));+ getTaskOutputHook.mockResolvedValueOnce(hook);+ isProgrammaticIoTaskType.mockReturnValueOnce(true);+ const result = await retireDeadAgent({ agent: { ...AGENT, result: { taskOutcome } }, task: TASK,+ success: true, exitCode: 0, duration: 100 });+ expect(result).toEqual({ success: true, taskOutcome, deliveryHeld: false });+ expect(completeAgent).toHaveBeenCalledWith(AGENT.id, expect.objectContaining({ success: true,+ validationPassed: true, taskOutcome }));+ expect(updateTask).not.toHaveBeenCalled();+ });++ it('leaves recovery retryable when parking the held task cannot be persisted', async () => {+ const taskOutcome = { status: 'blocked', reason: 'Invented prerequisite.' };+ updateTask.mockResolvedValueOnce({ error: 'storage-unavailable' });+ await expect(retireDeadAgent({ agent: { ...AGENT, result: { taskOutcome } }, task: TASK,+ success: true, exitCode: 0, duration: 100 })).rejects.toThrow('storage-unavailable');+ expect(completeAgent).not.toHaveBeenCalled();+ expect(removeCompletionSentinel).not.toHaveBeenCalled();+ });+it('skips closing the run record for an agent with no runId', async () => {await retireDeadAgent({ agent: AGENT, task: TASK, success: true, exitCode: 0, duration: 100 });@@ -115,14 +161,14 @@ describe('retireDeadAgent (#8440)', () => {agent: { ...AGENT, metadata: { runId: 'run-refused', executionInterruption } }, task: TASK,success, exitCode: success ? 0 : 143, duration: 100, category: 'interrupted',});- expect(result).toEqual({ success: false });+ expect(result).toEqual({ success: false, taskOutcome: null, deliveryHeld: false });expect(completeAgentRun).toHaveBeenCalledWith('run-refused', '', success ? 0 : 143, 100,- expect.objectContaining({ category: 'content-refusal', origin: 'provider', permanent: true, requiresFallback: false }));+ expect.objectContaining({ category: 'content-refusal', origin: 'provider', permanent: true, requiresFallback: false }), false, { executionSuccess: success, taskOutcome: null });expect(completeAgent).toHaveBeenCalledWith('agent-dead', expect.objectContaining({ success: false,executionInterruption, errorAnalysis: expect.objectContaining({ category: 'content-refusal' }) }));});- it('dispatches the output hook before removing the sentinel, and the run and agent records close after both', async () => {+ it('dispatches the output hook before removing the sentinel, and removes the sentinel only after persisting the run and agent records', async () => {const order = [];getTaskOutputHook.mockResolvedValueOnce(async () => { order.push('hook'); return { accepted: true }; });removeCompletionSentinel.mockImplementation(async () => { order.push('sentinel-removed'); });@@ -138,7 +184,7 @@ describe('retireDeadAgent (#8440)', () => {});expect(removeCompletionSentinel).toHaveBeenCalledWith({ agentId: 'agent-dead', agentState: expect.objectContaining({ id: 'agent-dead' }) });- expect(order).toEqual(['hook', 'sentinel-removed', 'run', 'agent']);+ expect(order).toEqual(['hook', 'run', 'agent', 'sentinel-removed']);});// No immutable source inventory survives to validate a recovered private-security@@ -155,13 +201,15 @@ describe('retireDeadAgent (#8440)', () => {duration: 10,});- expect(result).toEqual({ success: false });+ expect(result).toEqual({ success: false, taskOutcome: null, deliveryHeld: false });expect(completeAgentRun).toHaveBeenCalledWith('run-private','Private security assessment interrupted; inspect its local assessment archive.',0,10,expect.anything(),+ false,+ { executionSuccess: true, taskOutcome: null },);expect(completeAgent).toHaveBeenCalledWith('agent-dead', expect.objectContaining({ success: false }));});diff --git a/server/services/agentLifecycle.js b/server/services/agentLifecycle.jsindex 86698d1f7d..22cd378153 100644--- a/server/services/agentLifecycle.js+++ b/server/services/agentLifecycle.js@@ -458,7 +458,7 @@ async function completeUntrackedAgentFromCosState(agentId, exitCode, success, du// message agrees with the record it lands on instead of leaving a failed// record with no error string.const willSucceed = success && !isPrivateSecurityTask(task) && !isPrivateSecurityTask(cosAgent);- const { success: retiredSuccess } = await retireDeadAgent({+ const { success: retiredSuccess, taskOutcome, deliveryHeld } = await retireDeadAgent({agent: cosAgent,task,success,@@ -467,13 +467,13 @@ async function completeUntrackedAgentFromCosState(agentId, exitCode, success, duerrorMessage: interruptedStartup?.message ?? (willSucceed ? undefined : 'Agent completed after server restart'),...(interruptedStartup ? { category: 'interrupted', agentResultExtra: { interruptedByRestart: true } } : {}),});- if (cosAgent.taskId && task && task.status !== 'completed') {+ if (cosAgent.taskId && task && task.status !== 'completed' && !deliveryHeld) {if (retiredSuccess) {// Stamp the LI hand-off verdict here too (#2779, codex P2) — this post-restart// recovery bypasses finalizeAgent, so without it a hand-off that finished while// the server was down would never federate its outcome. Only `success` is known// on this path (no validationPassed/errorAnalysis), so it records a clean success.- const taskUpdate = await stampLiExecutionVerdict({ status: 'completed' }, task, { success: retiredSuccess });+ const taskUpdate = await stampLiExecutionVerdict({ status: 'completed', metadata: { ...task.metadata, taskOutcome: taskOutcome || null } }, task, { success: retiredSuccess });await updateTask(cosAgent.taskId, taskUpdate, task.taskType || 'user');} else {// Hand the dead run's metadata to the retry handler so it can resume whatdiff --git a/server/services/agentLifecycle.spawnViaRunner.test.js b/server/services/agentLifecycle.spawnViaRunner.test.jsindex c00833a3b1..a6e03b3f26 100644--- a/server/services/agentLifecycle.spawnViaRunner.test.js+++ b/server/services/agentLifecycle.spawnViaRunner.test.js@@ -135,7 +135,7 @@ import { completeAgent, updateAgent } from './cosAgentLifecycle.js';import { completeAgentRun } from './agentRunTracking.js';import { finalizeAgent, releaseAgentLane, retireDeadAgent } from './agentFinalization.js';import { getAgent, getAgentRecord } from './cosAgentLifecycle.js';-import { getTaskById } from './cosTaskStore.js';+import { getTaskById, updateTask } from './cosTaskStore.js';import { release } from './executionLanes.js';import { releaseRetryHold } from './agentWorktreeCleanup.js';import { analyzeAgentFailure } from './agentErrorAnalysis.js';@@ -176,6 +176,20 @@ it('settles an interrupted TUI startup as a restart interruption, charging the texpect(runnerAgents.has('agent-interrupted')).toBe(false);});+it('does not complete or retry a task whose recovered outcome was held', async () => {+ vi.clearAllMocks();+ const task = { id: 'task-blocked', taskType: 'user', status: 'in_progress', metadata: {} };+ const record = { id: 'agent-blocked', status: 'running', taskId: task.id, metadata: {} };+ getAgent.mockResolvedValueOnce(record);+ getTaskById.mockResolvedValueOnce(task);+ retireDeadAgent.mockResolvedValueOnce({ success: false, deliveryHeld: true,+ taskOutcome: { status: 'blocked', reason: 'Invented prerequisite.' } });+ await handleAgentCompletion(record.id, 0, true, 1000);+ expect(retireDeadAgent).toHaveBeenCalled();+ expect(handleOrphanedTask).not.toHaveBeenCalled();+ expect(updateTask).not.toHaveBeenCalled();+});+describe('interrupted TUI startup — cases that must keep finalizing normally', () => {const startupErrorAnalysis = {category: 'startup-failure', origin: 'runner', actionable: false,diff --git a/server/services/agentLifecycle.test.js b/server/services/agentLifecycle.test.jsindex 81e671af4c..7ea6493aff 100644--- a/server/services/agentLifecycle.test.js+++ b/server/services/agentLifecycle.test.js@@ -489,7 +489,7 @@ describe('self-update spawn gate — funnel coverage (#4124)', () => {const body = AGENT_FINALIZATION_SRC.slice(idx, updateIdx);// The verdict is stamped into taskUpdate via the shared helper BEFORE the updateTask// call, so it federates in the same write that marks the task terminal.- expect(body).toMatch(/await stampLiExecutionVerdict\(taskUpdate, task, \{ success: verdict\.success, validationPassed, errorAnalysis: verdict\.errorAnalysis \}\)/);+ expect(body).toMatch(/await stampLiExecutionVerdict\(taskUpdate, task, \{ success: deliverySuccess, validationPassed, errorAnalysis: deliveryVerdict\.errorAnalysis \}\)/);});it('stampLiExecutionVerdict builds the verdict from the task liProposal marker via the shared builder (#2779)', () => {@@ -512,7 +512,7 @@ describe('self-update spawn gate — funnel coverage (#4124)', () => {const body = recoveryBranchSource();// The direct-success completion doesn't route through handleOrphanedTask, so it// stamps its own clean-completion verdict here.- expect(body).toMatch(/await stampLiExecutionVerdict\(\{ status: 'completed' \}, task, \{ success: retiredSuccess \}\)/);+ expect(body).toMatch(/await stampLiExecutionVerdict\(\{ status: 'completed', metadata: \{ \.\.\.task\.metadata, taskOutcome: taskOutcome \|\| null \} \}, task, \{ success: retiredSuccess \}\)/);});// The failure-path re-stamp used to live here too (re-reading the task afterdiff --git a/server/services/agentManagement.js b/server/services/agentManagement.jsindex 0da3834d09..a620fb3d9c 100644--- a/server/services/agentManagement.js+++ b/server/services/agentManagement.js@@ -1337,7 +1337,7 @@ async function runCleanupOrphanedAgents() {// completion, in that order. A hard kill (`pm2 restart`, reboot) lands here,// so this is the path that leaves dirt in a managed app repo if any of it// is skipped.- await retireDeadAgent({+ const retirement = await retireDeadAgent({agent,task,success: false,@@ -1356,7 +1356,7 @@ async function runCleanupOrphanedAgents() {cleanedCount++;retiredAgentIds.push(agent.id);- if (agent.taskId) {+ if (agent.taskId && !retirement.deliveryHeld) {// Carry the agent's metadata forward rather than re-reading the record// later: `getAgent` on a completed agent still hits the disk to hydrate// its output.txt tail (capped since #3498, but not free), and thediff --git a/server/services/agentManagement.test.js b/server/services/agentManagement.test.jsindex 2366696fbf..483ebc5447 100644--- a/server/services/agentManagement.test.js+++ b/server/services/agentManagement.test.js@@ -420,6 +420,19 @@ describe('cleanupOrphanedAgents — startup recovery coordination', () => {expect(runnerAgents.has('agent-stale')).toBe(false);});+ it('preserves the blocked task and worktree after retiring a run with a held outcome', async () => {+ getAgents.mockResolvedValueOnce([{ id: 'agent-held', status: 'running', pid: 2147483646,+ taskId: 'task-held', metadata: { useRunner: true, executionMode: 'runner' } }]);+ getActiveAgentsFromRunner.mockResolvedValueOnce([{ id: 'agent-held', pid: 2147483646,+ kind: 'cli', processActive: false, liveness: 'pid' }]);+ getTaskById.mockResolvedValue({ id: 'task-held', taskType: 'user', status: 'in_progress', metadata: {} });+ retireDeadAgent.mockResolvedValueOnce({ success: false, deliveryHeld: true,+ taskOutcome: { status: 'blocked', reason: 'Invented prerequisite.' } });+ await cleanupOrphanedAgents();+ expect(retireDeadAgent).toHaveBeenCalled();+ expect(updateTask).not.toHaveBeenCalled();+ });+it('does not reap a pre-fix Windows TUI whose processActive is a pid-0 artifact', async () => {getAgents.mockResolvedValueOnce([{id: 'agent-tui-old',diff --git a/server/services/agentRunTracking.js b/server/services/agentRunTracking.jsindex da79d682ea..02a59d0845 100644--- a/server/services/agentRunTracking.js+++ b/server/services/agentRunTracking.js@@ -105,7 +105,7 @@ export async function createAgentRun({ agentId, task, model, provider, workspace* history would keep saying "success" for exactly the run the agent record and* the task status now agree did NOT land its deliverable.*/-export async function completeAgentRun(runId, output, exitCode, duration, errorAnalysis = null, successOverride = null) {+export async function completeAgentRun(runId, output, exitCode, duration, errorAnalysis = null, successOverride = null, delivery = null) {if (!runId) return; // Skip if no runId (e.g., agent recovered after restart)const runDir = join(RUNS_DIR, runId);@@ -141,6 +141,10 @@ export async function completeAgentRun(runId, output, exitCode, duration, errorAif (successOverride === false || refused) success = false;metadata.success = success;+ if (delivery) {+ metadata.executionSuccess = delivery.executionSuccess;+ metadata.taskOutcome = delivery.taskOutcome;+ }metadata.outputSize = Buffer.byteLength(output || '');// Store error details - extract from output if no analysis provided. A cleandiff --git a/server/services/agentRunTracking.test.js b/server/services/agentRunTracking.test.jsindex 129f265a97..4a21013d9c 100644--- a/server/services/agentRunTracking.test.js+++ b/server/services/agentRunTracking.test.js@@ -199,7 +199,10 @@ describe('completeAgentRun lifecycle ledger', () => {// Exit 0, but the caller's successOverride says the deliverable never landed// (#3358) — the ledger must agree with the run record, not with the process.- await completeAgentRun('run-overridden', 'output', 0, 4200, null, false);+ const taskOutcome = { status: 'blocked', reason: 'Invented missing prerequisite.' };+ await completeAgentRun('run-overridden', 'output', 0, 4200, null, false, { executionSuccess: true, taskOutcome });+ const { atomicWrite } = await import('../lib/fileUtils.js');+ expect(atomicWrite).toHaveBeenCalledWith(expect.stringContaining('metadata.json'), expect.objectContaining({ executionSuccess: true, success: false, taskOutcome }));expect(appendRunEvent).toHaveBeenCalledWith(expect.objectContaining({kind: 'run.finalized',diff --git a/server/services/cosAgentLifecycle.test.js b/server/services/cosAgentLifecycle.test.jsindex 0943d03b57..3af715402b 100644--- a/server/services/cosAgentLifecycle.test.js+++ b/server/services/cosAgentLifecycle.test.js@@ -450,6 +450,17 @@ describe('completeAgent budget-ledger ordering (#1683)', () => {expect(order).toEqual(['usage', 'completed']);});+ it('retains delivery outcome through archive storage and list projection without changing feedback', async () => {+ const { toAgentListItem } = await import('../lib/cosAgentListProjection.js');+ const agentId = 'agent-task-outcome';+ const taskOutcome = { status: 'blocked', reason: 'Invented prerequisite missing.' };+ const feedback = { rating: 'positive', comment: 'Original feedback.' };+ mockCosState.state.agents[agentId] = { id: agentId, status: 'running', metadata: {}, feedback };+ const completed = await completeAgent(agentId, { success: false, executionSuccess: true, taskOutcome });+ const archived = JSON.parse(await readFile(join(mockCosState.agentsDir, completed.completedAt.slice(0, 10), agentId, 'metadata.json'), 'utf8'));+ expect(toAgentListItem(archived)).toMatchObject({ result: { success: false, executionSuccess: true, taskOutcome }, feedback });+ });+it('still emits agent:completed when the usage-ledger write rejects', async () => {// recordDomainUsage is .catch-guarded, so a ledger-write failure must not// swallow the completion event — the scheduler still needs to advance.diff --git a/server/services/githubNotificationResolveTask.js b/server/services/githubNotificationResolveTask.jsindex 2f7229a16b..9428415f55 100644--- a/server/services/githubNotificationResolveTask.js+++ b/server/services/githubNotificationResolveTask.js@@ -17,7 +17,7 @@* the thread goes back to its old decision with a failed marker for the pill.*/import { query } from '../lib/db.js';-import { isQueuedContinuation } from '../lib/agentOutcome.js';+import { isQueuedContinuation, isTaskDeliveryComplete } from '../lib/agentOutcome.js';import { GENERIC_AGENT_LANE } from '../lib/githubNotificationTriage.js';import { notificationHtmlUrl, repoApiPath } from '../lib/githubNotificationParse.js';import { toPgJson } from '../lib/pgJson.js';@@ -197,9 +197,9 @@ function onResolveAgentCompleted(agent) {const taskId = agent?.taskId;// A relaunch requeues the same task; its continuation reports the outcome.if (!taskId || isQueuedContinuation(agent)) return null;- const run = agent.result?.success === true+ const run = isTaskDeliveryComplete(agent)? markResolved(taskId, agent.id)- : markFailed(taskId, agent.id, agent.result?.error);+ : markFailed(taskId, agent.id, agent.result?.taskOutcome?.reason || agent.result?.error || 'Task delivery was not verified.');return run.catch((error) => console.error(`❌ GitHub notification follow-up for agent task ${taskId} failed: ${error.message}`));}diff --git a/server/services/githubNotifications.db.test.js b/server/services/githubNotifications.db.test.jsindex 56e637357a..cc009438d9 100644--- a/server/services/githubNotifications.db.test.js+++ b/server/services/githubNotifications.db.test.js@@ -818,7 +818,7 @@ describe.skipIf(!runDb)('GitHub notifications inbox against Postgres', () => {// listeners run as CoS delivers its events; awaiting them keeps the order.startNotificationResolveListener();const deliver = (event, payload) => Promise.all(cosEvents.listeners(event).map((listener) => listener(payload)));- await deliver('agent:completed', { id: 'agent-1', taskId: 'task-1', result: { success: true } });+ await deliver('agent:completed', { id: 'agent-1', taskId: 'task-1', result: { success: true, taskOutcome: { status: 'completed', reason: 'Verified invented CI repair.' } } });expect(actions).toContainEqual(['DELETE', 'notifications/threads/1501']);const resolved = await getNotification(account.id, '1501');expect(resolved.state).toBe('done');@@ -827,6 +827,7 @@ describe.skipIf(!runDb)('GitHub notifications inbox against Postgres', () => {// back with its pill, once even when the spawn error and the completion both report it.await deliver('agent:completed', { id: 'agent-2', taskId: 'task-2', result: { success: false, resumed: true, resumedTaskId: 'task-2' } });expect(await getNotification(account.id, '1505')).toMatchObject({ decision: 'handed-off', agentFailed: null });+ await deliver('agent:completed', { id: 'agent-2', taskId: 'task-2', result: { success: true, taskOutcome: { status: 'blocked', reason: 'Invented missing prerequisite.' } } });await deliver('agent:error', { taskId: 'task-2', error: 'spawn failed' });await deliver('agent:completed', { id: 'agent-2', taskId: 'task-2', result: { success: false } });const failed = await getNotification(account.id, '1505');diff --git a/server/services/promptSections/completion.js b/server/services/promptSections/completion.jsindex 3d6f79b8a4..c005ae3ecb 100644--- a/server/services/promptSections/completion.js+++ b/server/services/promptSections/completion.js@@ -74,8 +74,10 @@ const SENTINEL_WATCH_TAIL = 'PortOS watches this sentinel and finalizes the run* per-section splice the next mode had to remember. Composing it here keeps* "prints a sentinel path" and "says the write is permitted" one fact.*/+const TASK_OUTCOME_GUIDANCE = 'Write a JSON envelope with `summary` (your markdown report), `taskOutcome: { "status": "completed" | "no-action-needed" | "blocked" | "incomplete", "reason": "specific evidence or blocker" }`, and the existing `payload` when your task requires one. Use completed only when the requested deliverable is finished; no-action-needed only when checks verified no work remains; blocked for an unmet prerequisite; incomplete for unfinished work. Process exit and writing this file do not prove task achievement. Preserve unfinished work and name what remains in the reason.';+const sentinelCompletionSection = (notice, writeInstruction) =>- [notice, '', `${writeInstruction} ${SENTINEL_WATCH_TAIL}`, '', SENTINEL_WRITE_PERMISSION_NOTE].join('\n');+ [notice, '', `${writeInstruction} ${SENTINEL_WATCH_TAIL}`, '', TASK_OUTCOME_GUIDANCE, '', SENTINEL_WRITE_PERMISSION_NOTE].join('\n');const REASONING_ONLY_BULLET = '**This is a reasoning-only task.** The worktree is discarded on exit — do NOT commit, push, merge, or open a PR. Write your result to the completion sentinel (see the Completion section) and stop.';const DISCARD_WORKTREE_HYGIENE = '- **Do NOT commit, push, or open a PR.** This worktree is discarded on exit — your only output is the completion sentinel (see the Completion section above).';@@ -427,7 +429,7 @@ export function buildReadOnlyCompletionSection({ isTui = false, sentinelPath = nif (!isTui || !sentinelPath) return notice;return sentinelCompletionSection(notice,- `When you have finished, write a short markdown summary of what you found (and where you recorded it) to \`${sentinelPath}\`, then stop.`+ `When you have finished, write a JSON envelope summarizing what you found (and where you recorded it) to \`${sentinelPath}\`, then stop.`);}@@ -499,7 +501,7 @@ export function buildAuditOutputCompletionSection(task, sentinelPath) {if (!isAuditTaskType(category)) return '';return `## Required audit assessment handoffBefore writing the completion sentinel, prepare the validated QUALITY_AUDIT_JSON report described in the audit instructions for category "${category}".-Write your human summary AND exactly one single-line QUALITY_AUDIT_JSON: {...} report together to \`${sentinelPath}\`, then stop. This applies to every provider, including agents that normally finish by exiting.+Write your human summary AND exactly one single-line QUALITY_AUDIT_JSON: {...} report together inside the \`summary\` string of the JSON completion envelope at \`${sentinelPath}\`, then stop. This applies to every provider, including agents that normally finish by exiting.The report is required even when no issues are filed or no code changes are needed. A successful issue or PR does not supply a quality assessment. A final response alone is not enough: PortOS reads the sentinel file to save the dashboard score.Preserve the report when following the summary template above; the template's length guidance does not replace this required output. If assessment is unavailable, use sliceScore:null and explain the missing evidence rather than inventing a score.`;}@@ -857,24 +859,19 @@ function resolveReviewInvocation({ willOpenPR, runsReviewLoop, reviewPolicy }) {* The `.agent-done` sentinel-write instruction block shared by* buildTuiCompletionSection and buildManualTuiCompletionSection: the "write a* short summary, then stop" instruction plus the fenced heredoc template.- * Returns the lines to splice into the caller's own line array — output must- * stay byte-identical since this is agent-facing prompt text.+ * Returns the lines to splice into the caller's completion workflow.*/export function buildSentinelWriteSteps(stepNumber, sentinelPath, sentinelTail) {return [- `${stepNumber}. Write a short markdown summary (~5–15 lines) to the completion sentinel, then stop — this sentinel is the done signal. PortOS watches it and finalizes the run shortly after it appears. Do NOT run \`/quit\` (it's a UI command, not something you can invoke) and do NOT wait for anything after writing the sentinel.`,+ `${stepNumber}. Write the structured completion JSON envelope to the completion sentinel, then stop — this sentinel is the done signal. PortOS watches it and finalizes the run shortly after it appears. Do NOT run \`/quit\` (it's a UI command, not something you can invoke) and do NOT wait for anything after writing the sentinel.`,'',+ ` ${TASK_OUTCOME_GUIDANCE}`,+ ` Include in the summary: ${sentinelTail.trim()}`,` ${SENTINEL_WRITE_PERMISSION_NOTE}`,'',' ```bash',` cat > "${sentinelPath}" <<'EOF'`,- ' ## Summary',- ' <one-sentence statement of what was accomplished>',- '',- ' ## Changes',- ' - <key file or area>: <what changed and why>',- '',- sentinelTail,+ ' {"summary":"## Summary\\n<what was accomplished or remains unfinished>\\n## Changes\\n<changes and verification>","taskOutcome":{"status":"<completed|no-action-needed|blocked|incomplete>","reason":"<evidence or blocker>"}}',' EOF',' ```'];diff --git a/server/services/promptSections/completion.test.js b/server/services/promptSections/completion.test.jsindex c2408285bb..6476094689 100644--- a/server/services/promptSections/completion.test.js+++ b/server/services/promptSections/completion.test.js@@ -31,7 +31,7 @@ describe('review-enabled completion merge gate', () => {expect(section).toContain('mergeHandoffMinQueuedRuns');expect(section).toContain('Unknown backlog, refused handoff');expect(section).not.toContain('--auto --merge');- expect(section).toContain('8. Write a short markdown summary');+ expect(section).toContain('8. Write the structured completion JSON envelope');});it('retains immediate merging for a registered claim requiring local admission', () => {