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

23.4 KB
Raw Blame
/**
 * Series Autopilot — editorial pipeline steps (#2842 split of seriesAutopilot.js):
 * script verification, the LLM review loop, the reverse-outline refresh, the
 * declarative editorial-check pass and the readiness/health gate.
 */

import { recordDomainUsage } from '../../domainUsage.js';
import { getSettings } from '../../settings.js';
import { getIssue } from '../issues.js';
import { analyzeManuscriptCompleteness } from '../arcPlanner.js';
import { verifyComicScript } from '../scriptVerify.js';
import { seedReviewFromFindings, getReview } from '../manuscriptReview.js';
import { generateManuscriptFix, acceptManuscriptFix } from '../manuscriptFix.js';
import { runEditorialChecks, buildEditorialCheckPlan, enabledChecksConsumeReverseOutline, buildReverseOutlineGateContext, summarizeCheckErrors } from '../editorial/checkRunner.js';
import { generateReverseOutline, getReverseOutline } from '../reverseOutline.js';
import { computeHealth, openBlockers, summarizeEditorialBlockers, formatBlockerSummary } from '../editorialScore.js';
import { MAX_EDITORIAL_ROUNDS } from './config.js';
import { DIVERGENCE_PATIENCE, trackConvergence, convergencePauseReason, divergencePauseReason } from './convergence.js';
import { broadcast, budgetPause, fileGap, providerOverrideOpts, providerIdOpts } from './session.js';
import { scriptStructurallyReady } from './stepResolver.js';

export async function runScriptVerify(sId, issueId, record) {
  record.runState.scriptChecked.add(issueId);
  const issue = await getIssue(issueId);

  // Gate 1 — STRUCTURAL (pure, cheap): does the script parse into pages/panels?
  // This is the only structural validation before completion in text-only /
  // visual-disabled comic runs, so a failure must BLOCK (pause), not just mark
  // the issue checked — otherwise the run could report done with a script that
  // can't become pages.
  if (!scriptStructurallyReady(issue)) {
    await fileGap(record, sId, {
      gapKind: 'script-unparseable',
      issueId,
      summary: 'The comic script for this issue does not parse into pages/panels, so comic pages can\'t be extracted. It likely needs a manual fix or regeneration of the comicScript stage.',
      context: `issueId=${issueId}`,
    });
    return {
      pause: true,
      gapFiled: true,
      reason: `comic script for issue ${issue.number ?? issueId} does not parse into pages/panels`,
      residual: [{ severity: 'high', location: `issue ${issue.number ?? '?'} / comicScript`, problem: 'script did not parse into pages/panels — cannot extract comic pages' }],
    };
  }

  // Gate 2 — CRAFT (LLM): does the script function as a comic script? This is
  // ADVISORY — unlike arc continuity, script craft is subjective and the
  // gating quality pass is the series-level editorial review, so blocking
  // findings are surfaced + filed (not auto-rewritten, not a hard pause) and
  // the autopilot keeps moving toward a draft. Wrapped so an LLM failure
  // downgrades to a skip instead of aborting the whole run.
  let issues = [];
  try {
    const result = await verifyComicScript(issueId, providerIdOpts(record, 'judge'));
    issues = result.issues || [];
    await recordDomainUsage('cos', { actions: 1 });
  } catch (err) {
    broadcast(sId, { type: 'step:skip', kind: 'scriptVerify', issueId, reason: `craft verify unavailable: ${(err?.message || err).toString().slice(0, 200)}` });
    return {};
  }
  const blocking = issues.filter((i) => i.severity === 'high');
  broadcast(sId, { type: 'verify:round', scope: 'script', issueId, round: 1, findings: issues.length, blocking: blocking.length });
  if (blocking.length) {
    await fileGap(record, sId, {
      gapKind: 'script-craft',
      issueId,
      summary: `Comic script craft review found ${blocking.length} blocking issue(s): ${blocking.map((b) => b.problem).join(' | ').slice(0, 600)}`,
      context: JSON.stringify(blocking).slice(0, 1000),
    });
    // #1572 — fileGap is advisory and only persists a gap task when fileGaps is
    // on (mirror its predicate). Tally what was actually FILED so the terminal
    // "complete" frame can qualify itself instead of silently reporting clean.
    if (record.options.fileGaps && record.mode === 'execute') {
      record.runState.scriptCraftGapIssues.add(issueId);
      record.runState.scriptCraftBlocking += blocking.length;
    }
  }
  return {};
}

export async function runEditorial(sId, record) {
  const maxRounds = Number.isInteger(record.options.maxEditorialRounds)
    ? record.options.maxEditorialRounds
    : MAX_EDITORIAL_ROUNDS;
  // maxRounds === 0 means "skip the editorial gate entirely" — which includes
  // the registry-driven editorial checks (the default info-dumping check is
  // LLM-backed, so a skip run must not spend budget on it). Mark both reviewed
  // so the resolver advances past editorialChecks too; the user can still run
  // checks on demand via the route.
  if (maxRounds === 0) {
    record.runState.editorialReviewed = true;
    // The reverse-outline refresh (#1349) only feeds the registry checks, so a run
    // that skips the whole editorial gate must skip it too — mark it refreshed so
    // the resolver advances past STEP 5.1 without spending budget.
    record.runState.reverseOutlineRefreshed = true;
    record.runState.editorialChecksReviewed = true;
    // Skipping the editorial gate also skips its health convergence check (#1316)
    // — the resolver must advance past editorialHealthGate too.
    record.runState.editorialHealthReady = true;
    return {};
  }
  let convergence = { best: null, sinceBest: 0 };
  for (let round = 1; round <= maxRounds; round += 1) {
    if (record.cancelRequested) return { canceled: true };
    const beforeAnalyze = await budgetPause();
    if (beforeAnalyze) return beforeAnalyze;
    const { issues, runId } = await analyzeManuscriptCompleteness(sId, {
      withEdits: true,
      ...providerOverrideOpts(record, 'judge'),
    });
    await recordDomainUsage('cos', { actions: 1 });
    const blocking = (issues || []).filter((i) => record.options.blockingSets.editorial.has(i.severity));
    broadcast(sId, {
      type: 'verify:round', scope: 'editorial', round, findings: (issues || []).length, blocking: blocking.length,
    });
    // Seed the manuscript-review comment set so the findings are visible in the
    // manuscript editor regardless of auto-fix outcome.
    await seedReviewFromFindings(sId, issues || [], { runId, mode: 'fresh' }).catch((err) => {
      console.log(`⚠️ autopilot: seed editorial review failed for ${sId.slice(0, 12)}: ${err.message}`);
    });
    if (blocking.length === 0) {
      record.runState.editorialReviewed = true;
      return {};
    }
    if (round === maxRounds) {
      return { pause: true, pauseKind: 'maxRounds', reason: convergencePauseReason('editorial', maxRounds, blocking.length), residual: blocking };
    }
    // Divergence guard (#1571): bail when the auto-fix passes stop reducing blocking findings.
    convergence = trackConvergence(convergence, blocking.length);
    if (convergence.sinceBest >= DIVERGENCE_PATIENCE) {
      return { pause: true, pauseKind: 'divergence', reason: divergencePauseReason('editorial', blocking.length, DIVERGENCE_PATIENCE), residual: blocking };
    }
    // Bounded auto-fix: apply a fix for each open high-severity comment, then
    // the loop re-analyzes. Each fix is wrapped so one bad anchor doesn't abort
    // the pass (boundary use of try/catch — these call into LLM/file paths).
    const review = await getReview(sId).catch(() => ({ comments: [] }));
    const open = (review.comments || []).filter((c) => c.status === 'open' && record.options.blockingSets.editorial.has(c.severity));
    for (const comment of open) {
      if (record.cancelRequested) return { canceled: true };
      // Each generated fix is its own LLM call — gate AND bill per comment so a
      // multi-comment pass can't overspend or under-count the daily budget.
      const beforeFix = await budgetPause();
      if (beforeFix) return beforeFix;
      try {
        // Thread the run's provider/model override into fix GENERATION (an LLM
        // call) so it honors the same provider as the review — without this the
        // fix silently runs on the active/default provider (and its runtime
        // fallback), which diverges from the run's chosen model and, when the
        // default is rate-limited, degrades fixes onto a weak fallback. Accept
        // is a deterministic edit application (no LLM), so it needs no override.
        if (!comment.fix) await generateManuscriptFix(sId, { commentId: comment.id, ...providerOverrideOpts(record) });
        await acceptManuscriptFix(sId, { commentId: comment.id });
        await recordDomainUsage('cos', { actions: 1 });
      } catch (err) {
        console.log(`⚠️ autopilot: editorial fix ${comment.id} failed: ${(err?.message || err)}`);
      }
    }
  }
  return {};
}

// STEP 5.1 — refresh the reverse-outline scene segmentation (#1349) before the
// registry-driven editorial checks (5.2), so the scene-consuming checks read the
// current draft's scenes rather than a segmentation staled by this run's editorial
// edits. Two cheap pre-gates keep this from spending budget needlessly:
//   1. skip entirely when no enabled editorial check declares a reverse-outline
//      source (mirrors the runner's own needsReverseOutline gate), and
//   2. skip when the stored outline is already fresh — using getReverseOutline's
//      canonical `stale` flag, NOT a stale-check reimplemented here.
// Only when a regenerate will actually occur do we gate the daily budget and bill a
// cos action — the same shape as runEditorialChecksPass, which gates+bills only when
// an enabled LLM check will actually run. `force:false`
// is a belt-and-suspenders second guard against the stored outline going fresh
// between the pre-check and the call. Failures are advisory (logged), never block.

// #1575 — the per-run editorial-check subset (null = all enabled). Absent/empty
// is normalized to null so EVERY consumer (this reverse-outline gate, the budget
// plan, the checks run) resolves the identical set — otherwise a subset of checks
// that skip the outline could still trigger/bill the refresh keyed off the global
// enabled set, or the gate could bill against checks the run skips.
export const editorialSubsetIds = (options) =>
  Array.isArray(options?.editorialCheckIds) && options.editorialCheckIds.length
    ? options.editorialCheckIds
    : null;

export async function runReverseOutlineRefresh(sId, record) {
  if (record.cancelRequested) return { canceled: true };
  const settings = await getSettings();
  const checkIds = editorialSubsetIds(record.options);
  // Gate 1 — sources-only pre-filter: does any enabled check (narrowed to this
  // run's subset) even DECLARE the outline as a source? If not, nothing to do —
  // and a subset that skips outline-consuming checks must not pay for a refresh
  // those checks would have triggered.
  if (!enabledChecksConsumeReverseOutline(settings, checkIds)) {
    record.runState.reverseOutlineRefreshed = true;
    return {};
  }
  // Gate 2 — is the stored outline stale (or never generated against a draftable
  // manuscript)? `no-content` (nothing drafted) needs no outline; `none` (draftable
  // but never segmented) and a `complete`-but-`stale` outline both need a regen.
  const current = await getReverseOutline(sId).catch(() => null);
  const needsRegen = !!current
    && current.status !== 'no-content'
    && (current.status === 'none' || current.stale === true);
  if (!needsRegen) {
    record.runState.reverseOutlineRefreshed = true;
    return {};
  }
  // Gate 3 (#1614) — gate-aware consumption. A check that DECLARES the outline as
  // a source still won't run if its runtime gate declines for this series (e.g. a
  // canon-less roster). Evaluate each consumer's gate against the current outline
  // and skip the refresh when none would run. Gate on SCENE PRESENCE, not
  // `status`: the precondition is "there's scene content to evaluate gates
  // against" — a never-generated (`status:'none'`) or empty outline has none, so
  // we bootstrap the first generation unconditionally rather than chicken-and-egg
  // ourselves out of it. enabledChecksConsumeReverseOutline only trusts a
  // DECLINING gate that didn't read the outline (the refresh regenerates it, so
  // an outline-content gate's stale verdict can't be trusted and keeps the check
  // a consumer) — so a scoped run of only outline-gated checks still refreshes.
  if (Array.isArray(current.scenes) && current.scenes.length > 0) {
    const gateCtx = await buildReverseOutlineGateContext(sId, { outline: current }).catch(() => null);
    if (gateCtx && !enabledChecksConsumeReverseOutline(settings, checkIds, gateCtx)) {
      record.runState.reverseOutlineRefreshed = true;
      return {};
    }
  }
  // A regenerate WILL spend one LLM call — gate the budget and bill, like the
  // other LLM passes. Bridge autopilot cancellation into the stage's AbortSignal.
  const beforeRefresh = await budgetPause();
  if (beforeRefresh) return beforeRefresh;
  const signal = { get aborted() { return record.cancelRequested; } };
  const regen = (force) => generateReverseOutline(sId, { ...providerIdOpts(record, 'judge'), force, signal })
    .catch((err) => {
      console.log(`⚠️ autopilot: reverse-outline refresh failed for ${sId.slice(0, 12)}: ${err.message}`);
      return null;
    });
  let result = await regen(false);
  // Canceled mid-pass — don't bill, don't mark refreshed; let the loop unwind.
  if (result?.status === 'canceled' || record.cancelRequested) return { canceled: true };
  // (#1614) A `cached:true` result means the manuscript hash still matched the
  // stored outline at generate time. Re-confirm staleness against the LIVE
  // manuscript within this run: if a concurrent edit moved the manuscript again
  // after that cache check, the cached outline is now stale and the downstream
  // checks would read it — force exactly one regen so they don't.
  if (result?.cached === true) {
    const after = await getReverseOutline(sId).catch(() => null);
    if (after?.stale === true) {
      result = await regen(true);
      if (result?.status === 'canceled' || record.cancelRequested) return { canceled: true };
    }
  }
  // Bill ONLY when the call actually regenerated (an LLM run). A `cached` result
  // (outline still fresh in the race window) or a `no-content` series spent nothing.
  // No verify:round broadcast here — a refresh isn't a review round (it produces
  // scenes, not findings); the conductor's generic step:start/step:complete already
  // surface "Refreshing scene segmentation…" / "done" to the UI.
  if (result && result.cached !== true && result.status !== 'no-content') {
    await recordDomainUsage('cos', { actions: 1 });
  }
  record.runState.reverseOutlineRefreshed = true;
  return {};
}

// STEP 5.2 — run the registry-driven editorial checks once per run, seeding
// their findings into the same manuscript-review comment set. Only LLM-kind
// checks cost tokens, so gate the daily budget AND bill a cos action only when
// an enabled LLM check will actually run — a deterministic-only (or all-checks-
// disabled) run does cheap local work and must neither pause on an exhausted
// budget nor consume quota. Failures are surfaced (logged) but never block the
// run — editorial checks are advisory.
export async function runEditorialChecksPass(sId, record) {
  if (record.cancelRequested) return { canceled: true };
  const settings = await getSettings();
  // #1575 — narrow the pass + its budget gate to this run's subset (null = all
  // enabled). The gate (buildEditorialCheckPlan) and the run (runEditorialChecks)
  // must resolve the SAME set so billing and execution agree.
  const checkIds = editorialSubsetIds(record.options);
  const plan = await buildEditorialCheckPlan(sId, { checkIds, settings });
  const hasLlmCheck = plan.checks.some((c) => c.kind === 'llm');
  if (hasLlmCheck) {
    const beforeChecks = await budgetPause();
    if (beforeChecks) return beforeChecks;
  }
  // Bridge autopilot cancellation into the runner's cooperative AbortSignal so a
  // mid-pass /autopilot/cancel stops before the next check and skips seeding
  // (the runner re-checks `signal.aborted` after each check). A live getter
  // reflects `record.cancelRequested` without a separate controller to manage.
  const signal = { get aborted() { return record.cancelRequested; } };
  // #1578 — forward the runner's per-check check:start/check:complete frames up
  // the autopilot SSE stream (tagged scope:'editorialChecks' so the UI groups
  // them with the editorialChecks verify:round). Without this the only signal
  // during a long (issues × checks) pass is the single terminal verify:round
  // total — no per-check progress or severity breakdown.
  const onProgress = (event) => broadcast(sId, { ...event, scope: 'editorialChecks' });
  const result = await runEditorialChecks(sId, { ...providerOverrideOpts(record, 'judge'), checkIds, settings, signal, onProgress }).catch((err) => {
    console.log(`⚠️ autopilot: editorial checks failed for ${sId.slice(0, 12)}: ${err.message}`);
    return null;
  });
  // Canceled mid-pass — don't bill, don't mark the step reviewed; let the loop
  // unwind via its canceled branch.
  if (result?.canceled || record.cancelRequested) return { canceled: true };
  if (result) {
    if (hasLlmCheck) await recordDomainUsage('cos', { actions: 1 });
    // #1573 — a check whose run() threw is recorded in perCheck.error but the
    // pass otherwise looks clean. Surface the errored count + failing checkIds on
    // the round frame and accumulate them onto the run so the terminal summary
    // can flag a partial failure (no silent "complete").
    const { errored, erroredCheckIds } = summarizeCheckErrors(result.perCheck);
    erroredCheckIds.forEach((id) => record.runState.editorialCheckErroredIds.add(id));
    // #1613 — count the high-severity findings this pass surfaced. The round frame
    // previously hardcoded `blocking: 0`, which made a 50-high-finding pass look
    // "complete" — the misleading per-step signal the issue calls out. Report the
    // real high count so the step's `blocking` matches what it found, whether or
    // not the optional pause gate is armed.
    const highFindings = result.findings.filter((f) => f.severity === 'high');
    broadcast(sId, { type: 'verify:round', scope: 'editorialChecks', round: 1, findings: result.findings.length, blocking: highFindings.length, errored, erroredCheckIds });
    if (errored) {
      console.error(`❌ autopilot: ${errored} editorial check(s) errored — series=${sId.slice(0, 12)} ${erroredCheckIds.join(', ')}`);
    }
    // #1613 — optional gate: when armed (threshold > 0) and the pass surfaced at
    // least that many high findings, PAUSE for human review instead of silently
    // proceeding to the health gate. Off by default (threshold 0), so existing
    // runs are unchanged. Do NOT mark the step reviewed — a resume re-runs the
    // checks and reconciles (like the health gate), so once the human reduces the
    // high findings below the threshold (or lowers it) the run continues.
    const threshold = record.options.checkFindingsPauseThreshold || 0;
    if (threshold > 0 && highFindings.length >= threshold) {
      // Editorial findings already carry severity/location/problem (manuscriptReview
      // sanitizes them), so the residual uses the same shape as the other pauses;
      // keep checkId so the UI can link a residual back to the check that raised it.
      const residual = highFindings.map((f) => ({
        severity: f.severity, // already filtered to 'high' — carry it rather than re-asserting
        location: f.location || (f.checkId ? `check ${f.checkId}` : 'manuscript'),
        problem: f.problem || 'high-severity editorial finding',
        checkId: f.checkId,
      }));
      console.log(`🚦 editorial checks gate — series=${sId.slice(0, 12)} ${highFindings.length} high finding(s) ≥ threshold ${threshold}, pausing for review`);
      return {
        pause: true,
        pauseKind: 'checkFindings',
        reason: `Editorial checks surfaced ${highFindings.length} high-severity finding(s) (≥ threshold ${threshold}) — paused for review. Address them in the manuscript editor, or raise the editorial-check pause threshold above ${highFindings.length} (set it to 0 to disable) in Options and resume.`,
        residual,
      };
    }
  }
  record.runState.editorialChecksReviewed = true;
  return {};
}

// STEP 5.3 — editorial health convergence gate (#1316). A cheap, no-LLM gate:
// read the persisted review, compute the aggregate health under the configured
// readiness gate, and either mark the run clean (proceed to visuals) or PAUSE
// with the open blockers for human triage. This is the consolidated "ready"
// signal — distinct from the completeness loop's own per-round high-only gate —
// so a blocker the registry checks (5.2) surfaced after completeness converged
// still stops the run. No auto-fix here: the completeness loop already attempted
// fixes; remaining blockers need a human (or a re-run after edits).
export async function runEditorialHealthGate(sId, record) {
  if (record.cancelRequested) return { canceled: true };
  // The effective gate (per-run override → persisted setting → null) was resolved
  // and stamped onto record.options at start (#1580), mirroring the round bounds —
  // so the loop and the dry-run plan can't disagree on which gate applied. null
  // falls through to DEFAULT_READINESS_GATE inside computeHealth/openBlockers.
  const gate = record.options.readinessGate || undefined;
  // Do NOT swallow a getReview error into an empty review — that would fail OPEN
  // (the gate would pass on a corrupt/unreadable store and let the run proceed to
  // visuals without verifying health). Let it bubble to the coordinator's
  // top-level catch, which records a clean `error` terminal state.
  const review = await getReview(sId);
  const comments = review.comments || [];
  // Per-series severity-weight override (#1616) resolved + stamped at start, so
  // the health score the gate reads matches the live + persisted scores.
  const health = computeHealth(comments, gate, { weights: record.options.severityWeights });
  broadcast(sId, {
    type: 'verify:round', scope: 'editorialHealth', round: 1,
    findings: health.open, blocking: health.ready ? 0 : health.open, score: health.score,
  });
  if (health.ready) {
    record.runState.editorialHealthReady = true;
    return {};
  }
  // Not clean — surface the open blockers (via the shared helper, so the residual
  // can't disagree with computeHealth's `ready` verdict) for the human triage.
  // No pauseKind (#1571): this is a single-pass gate, not a bounded verify→resolve
  // loop, so it has no maxRounds/divergence distinction — leave it null. If this
  // ever gains a retry loop, thread pauseKind through trackConvergence then.
  const blockers = openBlockers(comments, gate);
  // Surface the per-check / per-issue breakdown that drove the pause (#1579) —
  // a single emoji-prefixed line so "why did health reject my 50-issue series?"
  // is answerable from the logs, and the same breakdown on the marker so the UI
  // / resume banner can render it without re-hitting the health API.
  const healthBreakdown = summarizeEditorialBlockers(health);
  console.log(`🩺 editorial health gate not clean — series=${sId.slice(0, 12)} score=${health.score}, ${health.open} open: ${formatBlockerSummary(healthBreakdown)}`);
  return { pause: true, reason: `editorial health not clean (score ${health.score}, ${health.open} open finding(s))`, residual: blockers, healthBreakdown };
}