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
/**
* Agent final verdict (#9645)
*
* The completion outcome `finalizeAgent` (services/agentFinalization.js)
* persists, as one pure function of the evidence it gathered: the agent's
* reported result, primary-checkout drift, the PR claim check, the goal-fidelity
* review, and the programmatic-I/O output hook. Kept out of the finalization
* module so the precedence ladder can be read — and tested — without the
* agent-state graph that module drags in.
*/
import { PR_MISSING_CATEGORY } from './prDisposition.js';
import { PRIMARY_CHECKOUT_MUTATED_ESCALATION, PRIMARY_CHECKOUT_MUTATED_REASON } from './primaryCheckoutGuard.js';
import { GOAL_FIDELITY_CATEGORY, formatGoalFidelitySummary, goalFidelityHoldsRun } from './goalFidelity.js';
/**
* The `errorAnalysis` shape for a detected branch-jack. `actionable` because a
* human has to decide whether to discard the primary's commits — a retry cannot
* repair this, and silently retrying would leave the mutated checkout in place.
*/
function primaryCheckoutDriftAnalysis(drift) {
return {
category: drift.category,
// Observed by the spawner from the checkout's own git state, not scraped out
// of the transcript — the same provenance rule the structural analyses use.
origin: 'runner',
completionReason: PRIMARY_CHECKOUT_MUTATED_REASON,
actionable: true,
escalation: PRIMARY_CHECKOUT_MUTATED_ESCALATION,
message: drift.message,
suggestedFix: drift.suggestedFix
};
}
/**
* The `errorAnalysis` shape for a failed PR verification. Non-actionable so the
* task RETRIES (a re-run can open the missing PR, or find the forge back) rather
* than blocking on a first miss — `resolveFailedTaskDecision` still blocks it
* once it has burned its retry budget.
*/
function prVerificationAnalysis(verdict) {
return {
category: verdict.category,
message: verdict.message,
actionable: false,
suggestedFix: verdict.category === PR_MISSING_CATEGORY
? `The branch ${verdict.branch} holds ${verdict.commitsAhead ?? 'unreviewed'} commit(s) but has no open change request. Re-run the task, or open it by hand (\`gh pr create --head ${verdict.branch}\` / \`glab mr create --source-branch ${verdict.branch}\`).`
: 'Check the forge probe on the System Health page — the forge CLI could not reach the forge, so the run\'s change request could not be confirmed.'
};
}
/** `errorAnalysis` for a run held by the goal-fidelity gate. */
function goalFidelityAnalysis(review) {
const named = [...(review.missing || []), ...(review.unrequested || [])];
return {
category: GOAL_FIDELITY_CATEGORY,
message: `${formatGoalFidelitySummary(review)} — the diff does not deliver the task's stated objective`,
actionable: false,
origin: 'goal-fidelity-review',
suggestedFix: named.length
? `Re-read the task against the change and reconcile: ${named.slice(0, 3).join('; ')}.`
: 'Re-read the task against the change: the review found the work does something other than what was asked.',
};
}
/**
* The run's outcome as one pure function of the evidence finalize gathered.
* Diagnoses apply in a fixed priority — drift > PR > fidelity > hook > the
* originally reported error — and each later layer can only replace a verdict
* it is eligible to replace:
*
* - DRIFT overrides only a run that would otherwise have been a success. On a
* run that already failed, the original analysis is the better diagnosis;
* the branch-jack is on the record via finalize's warn log either way.
* - PR replaces any non-drift verdict when the forge could not confirm the
* promised change request — a concrete delivery failure.
* - FIDELITY can only hold a run that is still a success; re-judging a failed
* run against its objective would trade a real cause for a symptom.
* - HOOK rejection fails a successful run outright. On an already-failed run
* it takes over only when the rejection is PERMANENT (#6124), the run named
* no other cause (an `unknown` category), and the prior failure would not
* already block the task — a terminal decision keeps its own diagnosis
* rather than being re-resolved into a second investigation task. A
* non-escalating rejection of an otherwise-undowngraded failure surfaces the
* original analysis on the card.
*
* Callers gate evidence gathering on an earlier layer's answer (fidelity runs
* only on a delivered success; the hook is told the judged outcome), so they
* call this with the evidence collected so far and omit the rest — an omitted
* layer simply does not apply. Returns a frozen verdict; nothing downstream may
* amend it.
*
* @param {object} p
* @param {(errorAnalysis: object) => boolean} [p.failureIsTerminal] whether a
* failure with this analysis would block the task. Consulted only when a
* permanent hook rejection lands on an already-failed run; must be pure.
* @returns {Readonly<{source: 'reported'|'drift'|'pr'|'fidelity'|'hook', success: boolean, errorAnalysis: object|null|undefined, error: string|undefined, completionReason: string|undefined}>}
*/
export function resolveAgentFinalVerdict({
reportedSuccess,
errorAnalysis,
error,
completionReason,
terminatedByUser = false,
drift = null,
prEvidence,
fidelityReview = null,
hookResult = null,
failureIsTerminal = () => false,
}) {
// Delivery checks cannot turn a provider refusal into an ordinary retryable
// PR/validation failure. The refusal remains the terminal execution cause.
if (['content-refusal', 'content-filtered'].includes(errorAnalysis?.category)) {
return Object.freeze({ source: 'reported', success: false, errorAnalysis,
error: errorAnalysis.message || error, completionReason: errorAnalysis.category });
}
const driftDowngrade = Boolean(drift?.drifted) && reportedSuccess && !terminatedByUser;
const prVerdict = prEvidence.completionVerdict;
const delivered = driftDowngrade
? {
source: 'drift',
success: false,
errorAnalysis: primaryCheckoutDriftAnalysis(drift),
error: drift.message,
completionReason: PRIMARY_CHECKOUT_MUTATED_REASON,
}
: !prEvidence.completionOk
? {
source: 'pr',
success: false,
errorAnalysis: prVerificationAnalysis(prVerdict),
error: prVerdict.message,
completionReason: prVerdict.category,
}
: { source: 'reported', success: Boolean(reportedSuccess), errorAnalysis, error, completionReason };
const fidelityAnalysis = delivered.success && goalFidelityHoldsRun(fidelityReview)
? goalFidelityAnalysis(fidelityReview)
: null;
const judged = fidelityAnalysis
? {
source: 'fidelity',
success: false,
errorAnalysis: fidelityAnalysis,
error: fidelityAnalysis.message,
completionReason: GOAL_FIDELITY_CATEGORY,
}
: delivered;
const hookOutcome = hookResult?.outcome;
const hookRejected = !terminatedByUser && Boolean(hookResult?.ran) && hookOutcome?.accepted === false;
if (!hookRejected) return Object.freeze(judged);
// A PERMANENT rejection — the stage produced no parseable output at all —
// re-fails identically on every retry, so it blocks instead of burning
// MAX_TASK_RETRIES spawns. Honoured only when the run named no other cause:
// a run that failed for a NAMED reason (rate-limit, auth-error, a killed
// provider) is missing its output because the environment misbehaved, and
// keeps its ordinary retries.
const causeNamed = !judged.success && Boolean(judged.errorAnalysis?.category) && judged.errorAnalysis.category !== 'unknown';
const hookPermanent = hookOutcome.permanent === true && !causeNamed;
if (judged.success || (hookPermanent && !failureIsTerminal(judged.errorAnalysis))) {
const analysis = {
category: hookOutcome.reason || 'output-hook-rejected',
message: hookOutcome.message || 'The scheduled task output was rejected by its validation hook',
actionable: false,
...(hookPermanent && { permanent: true }),
origin: 'task-output-hook',
};
return Object.freeze({
source: 'hook',
success: false,
errorAnalysis: analysis,
error: analysis.message,
completionReason: analysis.category,
});
}
// A rejection on an already-failed run keeps its original diagnosis. Surface
// that analysis on the card too, without replacing a prior downgrade.
if (judged.source === 'reported') {
return Object.freeze({
...judged,
error: judged.errorAnalysis?.message || error,
completionReason: judged.errorAnalysis?.category || completionReason,
});
}
return Object.freeze(judged);
}