Skip to content

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

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.jsx
index 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.jsx
index 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.md
index 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.js
index 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.md
index 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.
+
## Features
1. **Dual Task Lists**: User tasks and system tasks, both stored in `cos_tasks`
diff --git a/server/lib/README.md b/server/lib/README.md
index 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.js
index 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.js
index 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.js
index 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, duration
const 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, duration
exitCode,
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.js
index 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 './cosAgent
import { 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 compl
workspacePath: '/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 compl
agentId: 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 compl
finishHook({ 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 compl
agentId: 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 compl
agentId: 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.js
index 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.js
index 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, du
errorMessage: 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 what
diff --git a/server/services/agentLifecycle.spawnViaRunner.test.js b/server/services/agentLifecycle.spawnViaRunner.test.js
index 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 t
expect(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.js
index 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 after
diff --git a/server/services/agentManagement.js b/server/services/agentManagement.js
index 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 the
diff --git a/server/services/agentManagement.test.js b/server/services/agentManagement.test.js
index 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.js
index 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, errorA
if (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 clean
diff --git a/server/services/agentRunTracking.test.js b/server/services/agentRunTracking.test.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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 = n
if (!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 handoff
Before 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.js
index 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', () => {