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

8.0 KB
Raw Blame
/**
 * CoS Task Challenge — bounded worker↔reviewer dispute protocol (#2441)
 *
 * When a review-loop reviewer REJECTS a sub-agent's work, the agent's only prior
 * outcomes were "silently fix whatever was flagged" or "get blocked" — a wrong
 * rejection (common with noisy local/CLI reviewers) burned budget on an unneeded
 * fix or false-blocked good work. This module is the safety primitive for the
 * alternative: a worker may DISPUTE a rejection exactly once per task, parking it
 * in the `challenged` status with its full case attached, and the dispute either
 * resolves back to work (`upheld`) or escalates to the single PortOS user
 * (`escalated`) — never an unbounded fix/challenge loop.
 *
 * Bounded by design (Conductor's challenge protocol shares the retry budget so an
 * agent can't loop forever disputing): `MAX_CHALLENGES_PER_TASK` caps disputes at
 * one; `canChallenge` refuses a second. Single-user trust model — "escalate to the
 * user" = surface a decision to the one operator, not multi-actor arbitration.
 *
 * Pure + side-effect-free (mirrors cosTaskClaim.js): every function operates on a
 * plain task-metadata object and returns a partial-metadata patch to merge via
 * `cosTaskStore.updateTask`, a boolean, or a number. Persistence, the status
 * transition, and the escalation task live in the caller (cosTaskStore.js).
 *
 * The challenge record round-trips the TASKS.md markdown store like any other
 * metadata (objects/numbers via the JSON sentinel — see taskParser.js), and is
 * part of the merge's content signature, so a challenge federates + converges
 * across peers with no bespoke wire field (#1712 cosTasks federation).
 */

// One dispute per task. Sized as a hard cap (not a knob) so the acceptance
// contract — "a worker can dispute exactly one rejection per task; further
// disputes are refused" — is enforced in one place.
export const MAX_CHALLENGES_PER_TASK = 1;

// Resolution outcomes. `upheld` overturns the rejection (work re-queues);
// `escalated` hands an unresolved/failed dispute to the user rather than
// silently fixing or blocking. Mirrored by the route enum in cosValidation.js
// (`resolveChallengeSchema`) — a parity test keeps the two in lockstep.
export const CHALLENGE_OUTCOMES = Object.freeze(['upheld', 'escalated']);

// The metadata keys this module owns on a task. Exported so callers/tests can
// reason about (or strip) the challenge trio in one place.
export const CHALLENGE_METADATA_KEYS = Object.freeze(['challengeCount', 'challenge', 'challengeResolution']);

/**
 * How many challenges a task has already consumed. Coerces the value defensively:
 * after a TASKS.md round-trip the number arrives as the string `"1"`, so parse it
 * and treat anything non-positive/unparseable as 0 ("never challenged").
 */
export function getChallengeCount(metadata) {
  const raw = metadata?.challengeCount;
  const n = typeof raw === 'number' ? raw : Number.parseInt(raw, 10);
  return Number.isInteger(n) && n > 0 ? n : 0;
}

/**
 * May this task still be challenged? Bounded by BOTH the one-shot per-task cap
 * AND — when `maxTotalSpawns` is supplied — the task's shared retry budget (#2471).
 *
 * The one-shot cap (`max`) is the acceptance contract: exactly one dispute per task.
 * The retry-budget bound makes the module's "shares the retry budget so an agent
 * can't loop forever disputing" promise real: a challenge that succeeds re-queues
 * the task, so once it has burned its total-spawn budget (`totalSpawnCount` ≥
 * `maxTotalSpawns`) a further dispute is pointless — the re-queued task would only
 * be re-blocked by agentLifecycle's spawn-cap gate. Callers pass `maxTotalSpawns`
 * (the shared `MAX_TOTAL_SPAWNS` from validation.js) to opt into that bound; when
 * omitted only the one-shot cap applies, so this stays a pure, import-free module.
 */
export function canChallenge(metadata, { max = MAX_CHALLENGES_PER_TASK, maxTotalSpawns } = {}) {
  if (getChallengeCount(metadata) >= max) return false;
  if (maxTotalSpawns != null) {
    const spawns = Number(metadata?.totalSpawnCount) || 0;
    if (spawns >= maxTotalSpawns) return false;
  }
  return true;
}

/**
 * Build the metadata patch that RECORDS a worker's dispute and consumes a
 * challenge slot. Increments `challengeCount`, stores the worker's case under
 * `challenge` ({ reason, evidence?, reviewer?, challengedAt }), and clears any
 * prior `challengeResolution` (undefined → updateTask strips it) so a re-dispute
 * doesn't carry a stale verdict. Merge over the task's existing metadata.
 *
 * The caller is responsible for the `canChallenge` guard + the `challenged`
 * status transition; this only shapes the metadata.
 */
export function buildChallengePatch(metadata, { reason, evidence, reviewer, now = Date.now() } = {}) {
  const challenge = {
    reason: String(reason ?? '').trim(),
    challengedAt: new Date(now).toISOString(),
  };
  if (typeof evidence === 'string' && evidence.trim()) challenge.evidence = evidence.trim();
  if (typeof reviewer === 'string' && reviewer.trim()) challenge.reviewer = reviewer.trim();
  return {
    challengeCount: getChallengeCount(metadata) + 1,
    challenge,
    // A fresh dispute is unresolved — drop any prior verdict.
    challengeResolution: undefined,
  };
}

/**
 * Build the metadata patch that RESOLVES a dispute. Returns null for an unknown
 * outcome so the caller can reject it. `challengeResolution` records the verdict
 * ({ outcome, resolvedAt, note?, resolvedBy? }); the caller maps the outcome to
 * the next task status (`upheld` → pending, `escalated` → blocked + user surface).
 */
export function buildChallengeResolutionPatch({ outcome, note, resolvedBy, now = Date.now() } = {}) {
  if (!CHALLENGE_OUTCOMES.includes(outcome)) return null;
  const resolution = {
    outcome,
    resolvedAt: new Date(now).toISOString(),
  };
  if (typeof note === 'string' && note.trim()) resolution.note = note.trim();
  if (typeof resolvedBy === 'string' && resolvedBy.trim()) resolution.resolvedBy = resolvedBy.trim();
  return { challengeResolution: resolution };
}

/**
 * Classify a re-check reviewer's fresh findings into a resolution outcome (#2471).
 *
 * When a challenge is resolved by re-running a reviewer against the current diff
 * (rather than a human verdict), the merge-gating signal is the reviewer's
 * `## Blocking` section — a `## Recommended` finding never blocks a merge, so only a
 * surviving blocking finding sustains the original rejection. The local-LLM
 * reviewer emits the exact `No findings.` sentinel for a fully clean diff
 * (see codeReview.js CODE_REVIEW_SYSTEM_PROMPT) and a `## Blocking` header only
 * when it still has a blocking objection.
 *
 * - `upheld`   → the rejection is overturned (no blocking finding survives) → work re-queues.
 * - `escalated` → a blocking finding still stands → surface the dispute to the user.
 *
 * Returns `null` for unusable input (non-string / empty) so the caller can treat
 * a failed re-check as an error rather than silently escalating (or overturning)
 * on no signal — the sentinel-vs-empty rule, not `.length` truthiness.
 */
export function classifyRecheckOutcome(findings) {
  if (typeof findings !== 'string') return null;
  const trimmed = findings.trim();
  if (!trimmed) return null;
  // Exact clean sentinel — the diff is clean across all severities.
  if (/^no findings\.?$/i.test(trimmed)) return 'upheld';
  // A `## Blocking` section only sustains the rejection when it actually carries a
  // finding. A noisy reviewer (the very case this protocol guards against) that
  // emits a bare/empty Blocking header must NOT trigger the expensive user
  // escalation on the header alone — require non-empty body text under it.
  const blockingMatch = trimmed.match(/^\s*#{1,6}\s*blocking\b[^\n]*\n?([\s\S]*)$/im);
  if (blockingMatch) {
    // Body = text after the Blocking header up to the next heading (or EOF).
    const body = blockingMatch[1].split(/^\s*#{1,6}\s/m)[0];
    if (body.trim()) return 'escalated';
  }
  // Findings present, but nothing blocking — nothing gates the merge.
  return 'upheld';
}