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

143 KB
Raw Blame
import { newAuditMetadata } from '../lib/auditWorkflow.js';
import { auditQualityInstructions } from '../lib/auditQuality.js';
import { isPrivateSecurityTask, PRIVATE_SECURITY_DELIVERY } from '../lib/privateSecurityPolicy.js';
/**
 * CoS Task Generator Module
 *
 * The task-generation + evaluation engine extracted from cos.js. Owns:
 *  - `evaluateTasks` — the periodic/startup evaluation loop that decides what
 *    to spawn (priority 0 on-demand → 1 user → 2 auto-system → 3.6 feature agent
 *    → 4 idle review) and emits `task:ready` for each pick.
 *  - the self-improvement / managed-app / idle-review generators that build the
 *    actual task objects (prompt template + metadata + confidence approval).
 *  - the PLAN.md in-flight pick helper (`applyPlanIdMetadata`) and the
 *    pipeline-precondition helpers (`checkStagePrecondition`,
 *    `shouldSkipForPrecondition`, `initializePipelineMetadata`,
 *    `applyAppWorktreeDefault`).
 *
 * The per-task-type prompt PRE-STEP layer (the deterministic scans, their
 * `{ skip, block }` resolvers, the drain brakes, and the token renderer) lives
 * in `cosTaskPreStepBlocks.js`; this module composes it.
 *
 * Self-contained — it imports only sibling services (no import back to cos.js).
 * `evaluateTasks` emits `task:ready` rather than spawning directly, so the
 * spawn-side scheduler (`dequeueNextTask`/`tryImmediateSpawn`) stays in cos.js.
 * The startup-skip flag is passed in as the `initialStartup` option rather than
 * read from cos.js module state, and the paused check reads state directly.
 */

import { readFile } from 'fs/promises';
import { existsSync } from 'fs';
import { join } from 'path';
import { sanitizeTaskMetadata, PIPELINE_STAGE_BEHAVIOR_FLAGS, MAX_TOTAL_SPAWNS, resolveClaimReviewerConfig, reviewerConfigMetadata } from '../lib/validation.js';
import { PATHS } from '../lib/fileUtils.js';
import { renderOrPrependSection } from '../lib/promptSectionRenderer.js';
import { currentTaskTypeName } from '../lib/scheduledTaskTypes.js';
import { TASK_READINESS_REASON } from '../lib/taskReadinessReasons.js';
import { isPlainObject } from '../lib/objects.js';
import { hasQuotaBurnProvenance, isManualOnDemandRequest, onDemandRequestMetadata } from '../lib/quotaBurnOrigin.js';
import { isAutoApprovableInvestigation } from '../lib/investigationTasks.js';
import { parsePlanItems, extractAllIds, findInProgressIds, pickFirstAvailable, diagnoseUnpickablePlan } from '../lib/planIds.js';
import { formatSkipCauses } from '../lib/perpetualSkipCauses.js';
import { loadState, saveState, withStateLock, isImprovementEnabled, isDaemonRunning } from './cosState.js';
import { getDomainMode } from '../lib/domainAutonomy.js';
import { remainingActionBudget } from '../lib/domainBudgets.js';
import { getDomainBudgetStatus } from './domainUsage.js';
import { pendingCosActionReservations } from './cosAdmissionReservations.js';
import { cosEvents, emitLog } from './cosEvents.js';
import { addTask, updateTask, getAllTasks, getCosTasks, reconcileLegacyForgeMaintenanceTasks } from './cosTaskStore.js';
import { PRIORITY_VALUES } from '../lib/taskParser.js';
import { recordDecision, DECISION_TYPES } from './decisionLog.js';
import { isAppOnCooldown, markAppReviewCooldown, bindAppReviewAgent, markIdleReviewStarted, getNextAppForReview, loadAppActivity, isAppActivityOnCooldown } from './appActivity.js';
import { getActiveApps, getAppTaskTypeOverrides } from './apps.js';
// The single Priority-0 on-demand loop body, shared with the dequeueNextTask
// engine in cos.js so the two can no longer drift (#6618).
import { drainOnDemandRequests } from './onDemandDrain.js';
import { admitFeatureAgentTasks, admitIdleReviewTask, countUnregisteredInFlight, isUserTaskRunnableUnattended } from './cosDequeue.js';
import { spawningTasks } from './agentState.js';
import { resolveAgentProviderPin } from './appTaskProviderPin.js';
import { getTaskTypeConfidence } from './taskLearning.js';
import { classifySafetyKind, requiresSafetyApproval } from './taskLearning/safetyKind.js';
import { isRecoveryTask } from './recoveryTasks.js';
import { getCodeReviewDefaults } from './codeReview.js';
import { getSkipReason } from './cosTaskClaim.js';
import { ensureInstanceId } from './instanceIdentity.js';
import { PR_COMPLETIONS, resolveAppPrCompletion } from '../lib/prDisposition.js';
import { resolveTrackerFilingBlock } from '../lib/workTracker.js';
import {
  isAuditTaskType,
  isFileIssuesMode,
  auditDoWorkRequiresWorktree,
  modeContractFor,
  applyAuditModeWrapper,
  applyDepfreeMode,
  FILE_ISSUES_DELIVERY_SETTINGS,
} from '../lib/auditCatalog.js';
import { TIMED_COOLDOWN_BLOCKED_CATEGORIES } from '../lib/taskBlockCategories.js';
// The claim marker this stamps is separate from `openPR: false`, which is the
// CoS provisioning posture that prevents a nested worktree. agentPromptBuilder.js
// reads the same set back via isClaimFlowTask().
import { CLAIM_FLOW_TASK_TYPES } from '../lib/claimFlowTaskTypes.js';
import { isReconcileDrainTaskType } from './taskScheduleConstants.js';
import { isProgrammaticScheduledTaskType, requiresInstallWideTarget } from './taskScheduleRegistry.js';
import {
  appendReviewerEffortBlock,
  buildLocalReviewerInstructions,
} from './cosTaskPrompts.js';
import { appendTaskDataInputs, resolveTaskDataInputs } from './taskDataInputs.js';
import { ensurePrReviewerPipeline, runPrReviewerSecurityPreflight, scopeDescriptionToPullRequest } from './prReviewerPipeline.js';
import {
  applyPerpetualDrainCap,
  applyReleaseOptions,
  buildImprovementTaskDescription,
  buildPlanConstraintBlock,
  resolveBranchReconcileBlock,
  resolveIssueReconcileBlock,
  resolvePrWatcherBlock,
  resolveReferenceWatchBlock,
  resolveRepoSyncBlock,
} from './cosTaskPreStepBlocks.js';
import { detectIdleLeftoverBranches, formatUserActionDetectorBlock } from './userActionDetectors.js';

import { isTruthyMeta } from '../lib/metadataFlags.js';
// Back-compat shim — these five were public here before the pre-step layer moved
// to its own module, so a deep import of this file keeps resolving them.
export {
  applyPerpetualDrainCap,
  resolveIssueAuthorFilterBlock,
  resolveIssueExcludeLabelsBlock,
  resolveReconcileDrainGate,
  resolveSwarmBlock,
} from './cosTaskPreStepBlocks.js';

export {
  buildClaimOverrideContextBlock,
  buildLocalReviewerInstructions,
  buildPrefetchedIssueContextBlock,
  buildTargetWorkItemBlock,
  normalizeWorkItemRef,
} from './cosTaskPrompts.js';

// `buildSecurityScanPipelineOutput` was public here before the pr-reviewer
// security preflight moved beside the rest of that pipeline's contract.
export { buildSecurityScanPipelineOutput } from './prReviewerPipeline.js';

/**
 * Persist a `blocked` status on a task that has hit the max-total-spawns
 * ceiling. Unconditional: the caller has already established `exceedsMaxSpawns`.
 * The name carries the side effect — dry-run planning must only ever call the
 * pure `exceedsMaxSpawns` predicate.
 */
async function blockMaxSpawnsExceeded(task, taskType) {
  const totalSpawns = Number(task.metadata?.totalSpawnCount) || 0;
  emitLog('info', `🚫 Blocking task ${task.id} — exceeded max spawns (${totalSpawns}/${MAX_TOTAL_SPAWNS})`, { taskId: task.id });
  await updateTask(task.id, {
    status: 'blocked',
    metadata: { ...task.metadata, blockedReason: `Max total spawns exceeded (${totalSpawns}/${MAX_TOTAL_SPAWNS})`, blockedCategory: 'max-spawns', blockedAt: new Date().toISOString() }
  }, taskType).catch(err => {
    emitLog('warn', `Failed to block task ${task.id}: ${err.message}`, { taskId: task.id });
  });
}

/**
 * Pure predicate — true when a task has hit the max-total-spawns ceiling.
 * Never blocks or persists; the execute passes pair it with
 * `blockMaxSpawnsExceeded`, and the dry-run pass uses it alone.
 */
export function exceedsMaxSpawns(task) {
  return (Number(task.metadata?.totalSpawnCount) || 0) >= MAX_TOTAL_SPAWNS;
}

/**
 * A task that must BYPASS the per-app review cooldown at spawn time. Three
 * classes qualify, for the same reason — the cooldown is not their throttle:
 *   - **Pipeline continuations** (`metadata.pipeline.currentStage > 0`) — a
 *     multi-stage pipeline's own stage gating sequences the work.
 *   - **Perpetual drains** (`metadata.perpetual`) — the work-detector park is the
 *     throttle (see `queueEligibleImprovementTasks` / agentCompletion.js). Without
 *     this, a perpetual task the refill just *queued* (after correctly bypassing
 *     the queue-path cooldown) would still be skipped here at the spawn gate,
 *     because the on-demand "Run" path stamped `lastReviewedAt` and these gates
 *     read it — so a manually-triggered perpetual drain stalls one item in.
 *   - **Quota burns** (`metadata.quotaBurnFamily`) — the throttle is the burn
 *     plan's own gate ladder: the reset-window horizon, the family's reserve, and
 *     `maxDispatchesPerWindow`, all checked before the task is ever queued. The
 *     app cooldown is re-stamped by EVERY completed task on that app, so on an app
 *     carrying any other recurring CoS work (a perpetual drain, which is itself
 *     exempt and therefore keeps completing) it never lapses — and the burn task
 *     sits in Pending until its window resets unspent, which is the exact outcome
 *     quota burn exists to prevent. (Tasks queued before this stamp existed are
 *     back-filled by migration 225, so the predicate reads metadata only.) Read
 *     through `hasQuotaBurnProvenance` rather than the raw key so this gate stays
 *     tied to the one block definition in `lib/quotaBurnOrigin.js` — a task
 *     written by any release, in either the flat or the block shape, is exempt.
 *
 * `metadata.perpetual` is a bare boolean set upstream, but it round-trips through
 * COS-TASKS.md as the STRING `"true"` (taskParser serializes non-string/-object
 * metadata via `String(value)`; only arrays/objects like `pipeline` get the JSON
 * sentinel that preserves their type). So accept BOTH the in-memory boolean and
 * the re-parsed string — a `=== true` check alone would silently miss the
 * persisted-then-reloaded task, which is exactly the one the spawn gate sees.
 *
 * Shared by both spawn engines (`dequeueNextTask` in cos.js and `evaluateTasks`
 * here) and their dry-run planners so the cooldown-exempt set can't drift.
 */
export function isCooldownExemptTask(task) {
  const meta = task?.metadata;
  if (!meta) return false;
  return meta.pipeline?.currentStage > 0
    || isTruthyMeta(meta.perpetual)
    || hasQuotaBurnProvenance(meta);
}

/**
 * A claim/plan perpetual drain must stop when a completed agent leaves the
 * complete actionable set unchanged. A null signature means the detector has
 * no progress identity and keeps the legacy behavior; an empty signature is a
 * valid idle result but never reaches this predicate because `actionable` is
 * false.
 */
export function shouldParkUnchangedPerpetualWork(detection, lastSignature, dispatchCount = 0) {
  return detection?.actionable === true
    && detection.signature != null
    && lastSignature != null
    && detection.signature === lastSignature
    // A same-issue continuation is allowed one unchanged recheck: the prior
    // claim may have shipped a partial slice while leaving the issue actionable.
    // A second unchanged observation is a genuine no-progress loop.
    && dispatchCount > 1;
}

// The generator can be called before either spawn engine admits its result, so
// the drain signature travels as a plain data record returned alongside the
// task (`pendingPerpetualDispatch`, see `prepareManagedAppImprovementTask`)
// instead of being parked in a WeakMap keyed on the task object. The object-
// identity version required every admission site to keep re-finding the EXACT
// object the generator returned; `cosTaskStore.addTask` hands back a DIFFERENT
// object whenever the description is multi-line, which is the normal case, so
// a caller that naturally kept using the store's returned object instead of
// the generator's recorded nothing, silently (#6871).
export async function recordDeferredPerpetualDispatch(pendingPerpetualDispatch, taskSchedule) {
  // Sentinel on the field the record can't exist without, not mere truthiness
  // of the object — a malformed record must never reach recordPerpetualDispatch
  // as `undefined`, which would write a bogus schedule entry instead of no-oping.
  if (!pendingPerpetualDispatch?.taskType) return false;
  const { taskType, appId, signature } = pendingPerpetualDispatch;
  await taskSchedule.recordPerpetualDispatch(taskType, appId, signature);
  return true;
}

/**
 * The ordered per-task admission gates for auto-approved system tasks — the ONE
 * place their order lives. `selectDryRunAutoApproved` walks it for the plan
 * (never calling `onReject`); `admitAutoApprovedSystemTasks` walks it for the
 * real pass and runs the first rejecting gate's `onReject` effect. Adding or
 * reordering a gate here changes both passes at once, so the dry-run plan cannot
 * drift from what execute does.
 *
 * `rejects(task, hooks)` is pure (it may await a read-only probe); every side
 * effect (logging, persisting a block, deferral records) belongs to `onReject`.
 * `hooks` carries the engine-specific predicates: `notRunnableHere` (pinned to
 * another instance #4520, or a peer's live lease #1650 — returns a truthy
 * reason), `extraSkip` (disabled analysis type), `cooldownExempt`, `isOnCooldown`.
 */
const AUTO_APPROVED_GATES = Object.freeze([
  {
    name: 'not-runnable-here',
    rejects: (task, hooks) => hooks.notRunnableHere(task),
    onReject: async (task, { detail }) => {
      emitLog('debug', `Skipping system task ${task.id} — ${detail}`, { taskId: task.id });
    },
  },
  {
    name: 'max-spawns',
    rejects: (task) => exceedsMaxSpawns(task),
    onReject: (task) => blockMaxSpawnsExceeded(task, 'internal'),
  },
  {
    name: 'disabled-analysis-type',
    rejects: (task, hooks) => hooks.extraSkip(task),
    onReject: async (task) => {
      emitLog('info', `System task skipped — task type '${analysisTypeForTask(task)}' is disabled`, { taskId: task.id });
    },
  },
  {
    name: 'cooldown',
    rejects: async (task, hooks) => {
      const appId = task.metadata?.app;
      return Boolean(appId) && !hooks.cooldownExempt(task) && (await hooks.isOnCooldown(appId));
    },
    onReject: (task, { onDefer }) => onDefer({ type: 'cooldown', task, appId: task.metadata?.app }),
  },
]);

/**
 * First gate in `AUTO_APPROVED_GATES` that rejects `task`, as `{ gate, detail }`
 * (`detail` is the gate's truthy verdict, e.g. the not-runnable-here reason), or
 * null when the task clears them all. Pure — runs no `onReject` effect.
 */
async function firstRejectingGate(task, hooks) {
  for (const gate of AUTO_APPROVED_GATES) {
    const detail = await gate.rejects(task, hooks);
    if (detail) return { gate, detail };
  }
  return null;
}

/**
 * Dry-run eligibility pass over auto-approved system tasks. Walks the tasks in
 * file order applying the SAME gates execute mode uses — global slot cap, then
 * the shared `AUTO_APPROVED_GATES` table (one declarative list that
 * `admitAutoApprovedSystemTasks` also iterates), then per-project cap — while tracking virtual
 * capacity, and returns the ordered subset execute mode WOULD spawn. It never
 * blocks, persists, or emits anything, so a dry-run can log exactly the set
 * execute would spawn instead of over-reporting (logging tasks execute would
 * skip) or under-reporting (stopping early before applying the gates).
 *
 * The two spawn engines (`dequeueNextTask` in cos.js and `evaluateTasks` here)
 * have small execute-path differences, expressed via the optional per-task
 * hooks so each engine's dry-run plan matches its own execute path:
 * `extraSkip` adds an engine-specific gate (dequeue's disabled-analysis-type
 * check); `cooldownExempt` exempts a task from the cooldown gate (this engine's
 * pipeline-continuation bypass).
 *
 * @param {object[]} autoApproved - auto-approved system tasks, file order
 * @param {object} ctx
 * @param {number} ctx.availableSlots - global free slots at the start of this cycle
 * @param {number} ctx.alreadySpawned - slots already consumed by higher-priority picks (on-demand/user)
 * @param {number} ctx.perProjectLimit - per-project concurrent cap
 * @param {Record<string, number>} ctx.spawnProjectCounts - running+spawned counts per project (cloned, not mutated)
 * @param {(appId: string) => Promise<boolean>} ctx.isOnCooldown - async cooldown probe
 * @param {(task: object) => boolean} [ctx.cooldownExempt] - true ⇒ skip the cooldown gate for this task
 * @param {(task: object) => boolean} [ctx.extraSkip] - true ⇒ task ineligible (engine-specific gate)
 * @param {(task: object) => boolean} [ctx.notRunnableHere] - true ⇒ this instance would pass over the task anyway: it is pinned to another instance (#4520) or a federated peer holds a live lease on it (#1650). The execute path skips it before spawning, so the dry-run plan must too
 * @returns {Promise<object[]>} the tasks execute mode would spawn, in order
 */
export async function selectDryRunAutoApproved(autoApproved, ctx) {
  const {
    availableSlots,
    alreadySpawned = 0,
    perProjectLimit,
    spawnProjectCounts = {},
    isOnCooldown,
    cooldownExempt = () => false,
    extraSkip = () => false,
    notRunnableHere = () => false
  } = ctx;
  const hooks = { isOnCooldown, cooldownExempt, extraSkip, notRunnableHere };

  const counts = { ...spawnProjectCounts };
  let spawned = alreadySpawned;
  const spawnable = [];

  for (const task of autoApproved) {
    if (spawned >= availableSlots) break;
    if (await firstRejectingGate(task, hooks)) continue;
    const project = task.metadata?.app || '_self';
    if ((counts[project] || 0) >= perProjectLimit) continue;
    counts[project] = (counts[project] || 0) + 1;
    spawned++;
    spawnable.push(task);
  }

  return spawnable;
}

// Task types where the scheduler reads PLAN.md to find an in-flight-aware pick.
// `do-replan` is excluded — it assigns IDs rather than picking one off the list.
const PLAN_PICK_TASK_TYPES = new Set(['feature-ideas', 'plan-task']);

// Subset of PLAN_PICK_TASK_TYPES where the AGENT picks (and claims) its own slug
// at execution time — mirroring the `/claim` slash command. For these, the
// scheduler must NOT stamp `metadata.planId`: a dispatch-time pre-pick happens
// before the agent creates its `claim/<slug>` branch (the real lock), so two
// near-simultaneous dispatches would both target the same first-available item.
// We still run the in-flight scan below purely as a DISPATCH GATE (skip the run
// when nothing is pickable), but leave the actual pick to the agent's Phase 1
// scan, which immediately precedes branch creation. The 2026-05-21 duplicate-PR
// incident (see cos.test.js) is guarded by the full Phase 1–7 self-pick prompt,
// not by the pre-pick. `feature-ideas` is intentionally NOT in this set — it
// uses a scheduler-managed worktree whose branch name encodes `planId`.
const PLAN_SELF_CLAIM_TASK_TYPES = new Set(['plan-task']);

// Subset of PLAN_PICK_TASK_TYPES where the dispatch should be skipped entirely
// when no PLAN.md item is dispatchable. `feature-ideas` is intentionally
// excluded: it brainstorms new items when PLAN.md is empty/blocked, so it
// must run regardless. `plan-task` is a strict executor and would just exit
// cleanly — burning an LLM round for nothing.
const PLAN_GATE_TASK_TYPES = new Set(['plan-task']);

/**
 * For feature-ideas / plan-task, read the target repo's PLAN.md, find which
 * item IDs are already in flight via branch/PR scan, and pick the first
 * available item. Mutates `metadata` in place by setting `planId` when a
 * pick succeeds — EXCEPT for self-claiming task types (PLAN_SELF_CLAIM_TASK_TYPES),
 * where the agent picks its own slug at execution time and the scan is used
 * only as the dispatch gate (no `planId` stamp).
 *
 * Returns `{ skipReason }` so the caller can short-circuit the LLM dispatch
 * for `plan-task` when there's literally nothing to do (empty plan, all
 * items blocked on human input via NEEDS_INPUT/DRIFT, or all claimed
 * elsewhere). `feature-ideas` is never gated — its job is to brainstorm
 * from scratch when the plan is empty, so it always runs.
 *
 * @returns {Promise<{ skipReason: string | null }>}
 */
async function applyPlanIdMetadata(taskType, repoPath, metadata) {
  if (!PLAN_PICK_TASK_TYPES.has(taskType)) return { skipReason: null };
  if (!repoPath) return { skipReason: null };
  const planMd = await readFile(join(repoPath, 'PLAN.md'), 'utf-8').catch(() => '');
  const gateDispatch = PLAN_GATE_TASK_TYPES.has(taskType);
  if (!planMd) {
    return { skipReason: gateDispatch ? 'PLAN.md missing or empty' : null };
  }
  const items = parsePlanItems(planMd);

  // Short-circuit on local evidence before the network round-trip to
  // `git fetch --prune` + `gh pr list`. When every unchecked item is
  // already blocked on human input, no in-flight scan can change that.
  if (gateDispatch) {
    const localOnly = diagnoseUnpickablePlan(null, new Set(), items);
    if (localOnly) return { skipReason: localOnly };
  }

  const knownIds = new Set(extractAllIds(planMd));
  const inFlight = await findInProgressIds(repoPath, knownIds).catch(() => new Set());
  const pick = pickFirstAvailable(items, inFlight);
  if (pick?.id) {
    // Self-claiming task types pick their own slug at execution time (like
    // `/claim`); stamping it here would pin concurrent dispatches to the same
    // item. For them this scan only serves as the gate above.
    if (!PLAN_SELF_CLAIM_TASK_TYPES.has(taskType)) {
      metadata.planId = pick.id;
    }
    return { skipReason: null };
  }
  if (!gateDispatch) return { skipReason: null };
  return { skipReason: diagnoseUnpickablePlan(null, inFlight, items) };
}

/**
 * Count running agents grouped by project (app ID).
 * Agents without an app (self-improvement, PortOS tasks) are grouped under '_self'.
 */
export function countRunningAgentsByProject(agents) {
  const counts = {};
  for (const agent of Object.values(agents)) {
    if (agent.status !== 'running') continue;
    const project = agent.metadata?.taskApp || agent.metadata?.app || '_self';
    counts[project] = (counts[project] || 0) + 1;
  }
  return counts;
}

/**
 * Check if a task would exceed the per-project concurrency limit.
 * Returns true if the task can be spawned (within limit), false otherwise.
 */
export function isWithinProjectLimit(task, agentsByProject, perProjectLimit) {
  const project = task.metadata?.app || '_self';
  const current = agentsByProject[project] || 0;
  return current < perProjectLimit;
}

/**
 * Unblock every expired timed-cooldown task in ONE queue's blocked group.
 * `defaultTaskType` names the store the array came from, so a task that carries
 * no explicit `taskType` is routed back to the queue it was read from — no
 * membership scan needed.
 *
 * Gated on the shared `TIMED_COOLDOWN_BLOCKED_CATEGORIES` vocabulary rather than
 * a literal `orphan-cooldown`: any block whose only precondition is "wait a
 * while" (the newer `worktree-busy` is the second) revives through this same
 * pass, and a category added to that set without a sweeper of its own would
 * otherwise sit blocked forever.
 */
async function unblockExpiredCooldownsInQueue(blocked, defaultTaskType) {
  let revived = 0;
  for (const task of blocked || []) {
    if (!TIMED_COOLDOWN_BLOCKED_CATEGORIES.has(task.metadata?.blockedCategory) || !task.metadata?.cooldownUntil) continue;
    // An unparseable `cooldownUntil` yields NaN, and NaN loses BOTH comparisons —
    // so the expiry test has to be written as "is expired", not as the negation of
    // "is still cooling". Guard it explicitly: a garbage timestamp leaves the task
    // blocked (the pre-#3500 behavior) rather than reviving it on the next tick.
    const cooldownUntil = new Date(task.metadata.cooldownUntil).getTime();
    if (!(cooldownUntil <= Date.now())) continue;
    emitLog('info', `⏰ Cooldown expired for task ${task.id} (${task.metadata.blockedCategory}), unblocking`, { taskId: task.id });
    await updateTask(task.id, {
      status: 'pending',
      metadata: {
        ...task.metadata,
        blockedReason: undefined,
        blockedCategory: undefined,
        blockedAt: undefined,
        cooldownUntil: undefined
      }
    }, task.taskType || defaultTaskType);
    revived++;
  }
  return revived;
}

/**
 * Unblock tasks whose timed cooldown has expired. Walks the blocked groups of
 * both task stores and flips any task in `TIMED_COOLDOWN_BLOCKED_CATEGORIES`
 * back to pending once its `cooldownUntil` has passed. Extracted from
 * `evaluateTasks` so the cooldown-unblock pass is independently testable.
 *
 * Each store is walked separately rather than concatenated: the old single-pass
 * version re-derived the queue of origin with `userBlocked.includes(task)` per
 * task, an O(N) scan inside an O(N) loop (#3500). Passing the origin down makes
 * classification O(1) and the whole pass linear.
 *
 * @returns {Promise<number>} how many tasks were revived
 */
export async function unblockExpiredCooldowns(userTaskData, cosTaskData) {
  const user = await unblockExpiredCooldownsInQueue(userTaskData.grouped?.blocked, 'user');
  const internal = await unblockExpiredCooldownsInQueue(cosTaskData.grouped?.blocked, 'internal');
  return user + internal;
}

/**
 * Resolve the per-domain CoS auto-run mode and the remaining autonomous-action
 * budget for this cycle (#711). The mode starts from `getDomainMode` and is
 * forced to `off` when the daily minutes cap is hit; the action budget caps how
 * many autonomous admissions the autonomous tiers may add this cycle.
 *
 * Off/dry-run withhold all AUTOMATIC internal spawns (auto-approved system
 * tasks, feature-agent, idle-review). User and on-demand tasks bypass this mode
 * gate; on-demand tasks also bypass the global pause. All non-user runs,
 * including on-demand work, count toward the daily actions/minutes ledger in
 * completeAgent and the in-flight action allowance here. A pure dry-run never
 * accrues usage.
 *
 * @returns {Promise<{ cosAutonomyMode: string, autonomousActionsRemaining: number }>}
 */
export async function resolveAutonomyBudget(state, runningAgentEntries) {
  let cosAutonomyMode = getDomainMode(state.config, 'cos');

  // Daily CoS budget (#711). Two dimensions, handled differently so a single
  // evaluation can't overshoot a small cap by spawning a whole concurrent batch:
  //  - minutes: binary — a run's wall-clock isn't known at spawn time, so once
  //    today's autonomous minutes reach the cap we withhold all automatic spawns
  //    (treat as `off`); a single in-flight run's overshoot is unavoidable.
  //  - actions: precise — cap THIS cycle's autonomous admissions to the remaining
  //    daily allowance, counting both completed (ledger) and in-flight autonomous
  //    runs. `autonomousActionsRemaining` flows into `autonomousSlotCeiling`.
  const cosBudget = await getDomainBudgetStatus('cos');
  let autonomousActionsRemaining = Infinity;
  if (cosAutonomyMode !== 'off') {
    if (cosBudget.exceeded === 'minutes') {
      emitLog('info', `CoS auto-run paused — daily minutes budget reached`, { domainBudget: 'cos', exceeded: 'minutes' });
      cosAutonomyMode = 'off';
    } else if (cosBudget.budget?.maxActionsPerDay != null) {
      const runningAutonomous = runningAgentEntries.filter(
        (a) => a.metadata?.taskType && a.metadata.taskType !== 'user'
      ).length;
      autonomousActionsRemaining = remainingActionBudget(
        cosBudget.budget,
        cosBudget.usage,
        runningAutonomous + pendingCosActionReservations()
      );
      if (autonomousActionsRemaining === 0) {
        emitLog('info', `CoS auto-run paused — daily actions budget reached`, { domainBudget: 'cos', exceeded: 'actions' });
        cosAutonomyMode = 'off';
      }
    }
  }

  return { cosAutonomyMode, autonomousActionsRemaining };
}

// Tasks queued before a task-type rename (TASK_TYPE_RENAMES) resolve to the
// current schedule key, or they would read as disabled and never drain.
const analysisTypeForTask = (task) => currentTaskTypeName(task.metadata?.analysisType || task.metadata?.selfImprovementType);

function isDisabledAnalysisType(task, taskSchedule) {
  const analysisType = analysisTypeForTask(task);
  // The shared drain contract always supplies a schedule. If that contract is
  // ever violated, fail closed for scheduled analysis work without aborting the
  // rest of the evaluation cycle.
  return Boolean(analysisType) && taskSchedule?.tasks?.[analysisType]?.enabled !== true;
}

/**
 * Run the one Priority-2 admission pass shared by the periodic evaluator and
 * event-driven dequeue engine. The pass owns candidate expansion and every
 * dry-run/execute gate; adapters only decide how an admitted task is emitted
 * and how their per-cycle capacity bookkeeping is updated.
 */
export async function admitAutoApprovedSystemTasks(ctx, adapter) {
  const {
    state,
    cosTaskData,
    taskSchedule,
    cosAutonomyMode,
    autonomousSlotCeiling,
    alreadySpawned,
    perProjectLimit,
    spawnProjectCounts,
    instanceId,
  } = ctx;
  const { canSpawn, trackSpawn, emitSpawn, isOwned = () => false, onDefer = async () => {} } = adapter;

  // A task already spawning or admitted this cycle is not a candidate: letting
  // it reach the gates would record a capacity/cooldown deferral for work that
  // is already running.
  const autoApproved = [
    ...(cosTaskData.autoApproved || []),
    ...(state.config.autoApproveInvestigations
      ? (cosTaskData.grouped?.pending || []).filter((task) => isAutoApprovableInvestigation(task, state.config))
      : [])
  ].filter((task) => !isOwned(task));
  // One hook set feeds both walks, so the dry-run plan and the execute pass
  // cannot disagree about what each gate means.
  const gateHooks = {
    isOnCooldown: (appId) => isAppOnCooldown(appId, state.config.appReviewCooldownMs),
    cooldownExempt: isCooldownExemptTask,
    extraSkip: (task) => isDisabledAnalysisType(task, taskSchedule),
    notRunnableHere: (task) => getSkipReason(task.metadata, instanceId)
  };

  if (cosAutonomyMode !== 'execute') {
    if (cosAutonomyMode !== 'dry-run') return [];
    const wouldSpawn = await selectDryRunAutoApproved(autoApproved, {
      availableSlots: autonomousSlotCeiling,
      alreadySpawned,
      perProjectLimit,
      spawnProjectCounts,
      ...gateHooks
    });
    for (const task of wouldSpawn) {
      emitLog('info', `[dry-run] CoS auto-run would spawn system task: ${task.id}`, { taskId: task.id, domainAutonomy: 'cos' });
    }
    return wouldSpawn;
  }

  const admitted = [];
  let spawned = alreadySpawned;
  for (const task of autoApproved) {
    if (spawned >= autonomousSlotCeiling) break;
    const rejection = await firstRejectingGate(task, gateHooks);
    if (rejection) {
      await rejection.gate.onReject(task, { detail: rejection.detail, onDefer });
      continue;
    }
    const appId = task.metadata?.app;
    const sysTask = { ...task, taskType: 'internal' };
    if (!canSpawn(sysTask, autonomousSlotCeiling)) {
      await onDefer({ type: 'capacity', task, project: appId || '_self' });
      continue;
    }
    emitSpawn(sysTask);
    trackSpawn(sysTask);
    admitted.push(sysTask);
    spawned++;
  }
  return admitted;
}

async function recordAutoApprovedDeferral({ type, task, appId, project }, state, perProjectLimit) {
  if (type === 'cooldown') {
    emitLog('debug', `Skipping system task ${task.id} - app ${appId} on cooldown`);
    await recordDecision(
      DECISION_TYPES.COOLDOWN_ACTIVE,
      `System task ${task.id} skipped — app ${appId} on cooldown (${Math.round(state.config.appReviewCooldownMs / 60000)}min window)`,
      { taskId: task.id, appId, cooldownMs: state.config.appReviewCooldownMs }
    );
    return;
  }
  emitLog('debug', `⏳ Queued system task ${task.id} - per-project limit reached for ${project}`);
  await recordDecision(
    DECISION_TYPES.CAPACITY_FULL,
    `System task ${task.id} deferred — per-project limit (${perProjectLimit}) reached for ${project}`,
    { taskId: task.id, project, limit: perProjectLimit }
  );
}

/**
 * Run the one Priority-1 admission pass shared by the periodic evaluator and
 * event-driven dequeue engine (#7523 — the two used to hand-mirror this
 * ordered ladder, and #4520/#7300 each landed as two synchronized edits).
 * Owns the ordered not-runnable-here, approval, and max-spawn gates for
 * pending user tasks; adapters only decide how an admitted task is emitted,
 * how per-cycle capacity is tracked, and (optionally) what happens when
 * capacity denies a candidate.
 */
export async function admitPendingUserTasks({ pendingUserTasks, instanceId }, adapter) {
  const { capacityExhausted, canSpawn, emitSpawn, trackSpawn, isOwned = () => false, onDefer = async () => {} } = adapter;

  const admitted = [];
  for (const task of pendingUserTasks) {
    if (capacityExhausted()) break;
    // Already spawning or admitted this cycle — not deferred, just not a candidate.
    if (isOwned(task)) continue;
    // Not runnable here: the task is pinned to another instance (#4520), or a
    // federated peer holds a live lease on it (#1650) and is working it on the
    // other machine. Skip it during candidate selection so it doesn't consume
    // this cycle's spawn slot (the spawn guard would return null anyway) and
    // starve later runnable tasks.
    const skipReason = getSkipReason(task.metadata, instanceId);
    if (skipReason) {
      emitLog('debug', `Skipping user task ${task.id} — ${skipReason}`, { taskId: task.id });
      continue;
    }
    // A user row that says it is NOT auto-approved is withheld from the unattended
    // spawn (#7300) — see isUserTaskRunnableUnattended for why, and for why the
    // rule lives in cosDequeue.js rather than once per engine.
    if (!isUserTaskRunnableUnattended(task)) {
      emitLog('debug', `Skipping user task ${task.id} — recovered row is not auto-approved`, { taskId: task.id });
      continue;
    }
    if (exceedsMaxSpawns(task)) {
      await blockMaxSpawnsExceeded(task, 'user');
      continue;
    }
    const userTask = { ...task, taskType: 'user' };
    if (!canSpawn(userTask)) {
      await onDefer(userTask);
      continue;
    }
    emitSpawn(userTask);
    trackSpawn(userTask);
    admitted.push(userTask);
  }
  return admitted;
}

/**
 * Priority 0: On-demand task requests, including user, refill and quota-burn
 * origins. Reads the live schedule's `onDemandRequests`, clears each
 * as it is processed, and admits any produced task (deduped) through the
 * cycle's shared `spawnAdapter`. On-demand work bypasses the auto-run mode gate
 * and global pause, but uses global slots and counts toward the daily budget
 * like other non-user runs.
 *
 * Returns the schedule the drain loaded so `evaluateTasks` can hand it to
 * Priority 2 explicitly (its disabled-analysis-type gate) instead of a second
 * load.
 */
async function spawnPriority0OnDemand(ctx) {
  const { state, availableSlots, perProjectLimit, spawnProjectCounts, tasksToSpawn, spawnAdapter } = ctx;

  const { schedule } = await drainOnDemandRequests({ state }, {
    capacityExhausted: () => tasksToSpawn.length >= availableSlots,
    projectCapacityExhausted: (appId) =>
      (spawnProjectCounts[appId || '_self'] || 0) >= perProjectLimit,
    canSpawn: spawnAdapter.canSpawn,
    emitSpawn: spawnAdapter.emitSpawn,
  });
  return { schedule };
}

/**
 * Priority 1: User tasks (always run — cooldown only applies to system tasks).
 * Runs against the global slot cap; user work never counts against the
 * autonomous action budget.
 */
async function spawnPriority1UserTasks(ctx) {
  const { pendingUserTasks, availableSlots, perProjectLimit, tasksToSpawn, spawnAdapter, instanceId } = ctx;
  await admitPendingUserTasks({ pendingUserTasks, instanceId }, {
    ...spawnAdapter,
    capacityExhausted: () => tasksToSpawn.length >= availableSlots,
    onDefer: (task) => recordPendingUserDeferral(task, perProjectLimit),
  });
}

async function recordPendingUserDeferral(task, perProjectLimit) {
  const project = task.metadata?.app || '_self';
  emitLog('debug', `⏳ Queued user task ${task.id} - per-project limit reached for ${project}`);
  await recordDecision(
    DECISION_TYPES.CAPACITY_FULL,
    `User task ${task.id} deferred — per-project limit (${perProjectLimit}) reached for ${project}`,
    { taskId: task.id, project, limit: perProjectLimit }
  );
}

/**
 * Priority 2: Auto-approved system tasks (if slots available) — gated by the
 * CoS auto-run domain. off/dry-run withhold the unattended spawn; dry-run logs
 * what would have run so the user can see the plan without it executing. Capped
 * by `autonomousSlotCeiling` (the CoS action budget, #711).
 */
async function spawnPriority2AutoApproved(ctx, { taskSchedule, autonomousSlotCeiling }) {
  const { state, cosTaskData, cosAutonomyMode, perProjectLimit, spawnProjectCounts, tasksToSpawn, spawnAdapter, instanceId } = ctx;
  return admitAutoApprovedSystemTasks({
    state,
    cosTaskData,
    taskSchedule,
    cosAutonomyMode,
    autonomousSlotCeiling,
    alreadySpawned: tasksToSpawn.length,
    perProjectLimit,
    spawnProjectCounts,
    instanceId,
  }, {
    ...spawnAdapter,
    onDefer: (decision) => recordAutoApprovedDeferral(decision, state, perProjectLimit),
  });
}

/**
 * Background: Queue eligible self-improvement tasks as system tasks. Only queue
 * if there are NO pending user tasks (user tasks always take priority). Skip on
 * initial startup to avoid auto-spawning agents on fresh installs. Also skip
 * when CoS auto-run isn't `execute` — queueing creates autonomous work.
 */
async function maybeQueueImprovementTasks(ctx) {
  const { state, cosTaskData, hasPendingUserTasks, initialStartup, cosAutonomyMode } = ctx;
  if (state.config.idleReviewEnabled && !hasPendingUserTasks && !initialStartup && cosAutonomyMode === 'execute') {
    await queueEligibleImprovementTasks(state, cosTaskData);
  }
}

/**
 * Priority 3.6: Feature Agents (after autonomous jobs, yield to user tasks).
 * Autonomous — gated by the CoS auto-run domain and capped by
 * `autonomousSlotCeiling`. The admission pass is shared with dequeueNextTask.
 */
async function spawnPriority36FeatureAgents(ctx, { autonomousSlotCeiling }) {
  return admitFeatureAgentTasks({
    spawnedCount: () => ctx.tasksToSpawn.length,
    hasPendingUserTasks: ctx.hasPendingUserTasks,
    cosAutonomyMode: ctx.cosAutonomyMode,
    autonomousSlotCeiling,
  }, ctx.spawnAdapter);
}

/**
 * Priority 4: Generate a direct idle-review task ONLY when:
 * 1. Nothing else is queued to spawn
 * 2. No pending user tasks (even on cooldown)
 * 3. No system tasks queued
 * Autonomous — gated by the CoS auto-run domain.
 */
async function spawnPriority4IdleReview(ctx, { autonomousSlotCeiling }) {
  return admitIdleReviewTask({
    state: ctx.state,
    alreadySpawned: ctx.tasksToSpawn.length,
    hasPendingUserTasks: ctx.hasPendingUserTasks,
    cosAutonomyMode: ctx.cosAutonomyMode,
    autonomousSlotCeiling,
  }, ctx.spawnAdapter);
}

/**
 * Evaluate tasks and decide what to spawn.
 *
 * Orchestrates the spawn-priority tiers in sequence, each extracted into a named
 * private function that reads a frozen spawn context (`ctx`), admits through its
 * shared `spawnAdapter`, and receives anything an earlier tier produced (the
 * Priority-0 schedule, the autonomous ceiling) as an explicit argument:
 *   - Priority 0 — on-demand requests       (`spawnPriority0OnDemand`)
 *   - Priority 1 — pending user tasks        (`spawnPriority1UserTasks`)
 *   - Priority 2 — auto-approved system tasks (`spawnPriority2AutoApproved`)
 *   - Priority 3.6 — due feature agents      (`spawnPriority36FeatureAgents`)
 *   - Priority 4 — idle review               (`spawnPriority4IdleReview`)
 *
 * Cross-cutting gates live here so they cover every tier uniformly: the
 * paused/daemon guard, the global slot cap, orphan-cooldown unblocking, and the
 * CoS auto-run + daily-budget gate (`resolveAutonomyBudget`). Priorities 0–1
 * spend against the global `availableSlots`; the autonomous tiers (2, 3.6, 4)
 * spend against the lower `autonomousSlotCeiling` so the CoS action budget caps
 * them. `evaluateTasks` emits `task:ready` per pick; the spawn-side scheduler
 * (`dequeueNextTask`/`tryImmediateSpawn`) stays in cos.js.
 */
export async function evaluateTasks(options) {
  // `initialStartup` is passed by cos.js's start() (true on the boot-time eval)
  // so the self-improvement queue is skipped on fresh installs; all other
  // callers omit it. Destructured from a plain options arg (not a destructuring
  // param) so the signature carries no leading brace.
  const { initialStartup = false } = options || {};
  if (!isDaemonRunning()) return;

  // A global pause stops scheduled/autonomous/user spawning, but NOT explicit
  // user triggers: on-demand requests (Priority 0) are still drained while
  // paused so a manual "Run" (or a force-evaluate) fires. The user/autonomous
  // tiers below are gated on `!paused` — parity with dequeueNextTask in cos.js.
  const paused = (await loadState()).paused || false;

  // Update evaluation timestamp with lock to prevent race conditions
  const state = await withStateLock(async () => {
    const s = await loadState();
    s.stats.lastEvaluation = new Date().toISOString();
    await saveState(s);
    return s;
  });

  // Drain merge-only PRs here rather than on the `pr-watcher` task's schedule,
  // which most installs leave disabled — that coupling stranded every green
  // PortOS-opened PR at `ticks: 0` forever. This is the OPPORTUNISTIC drain:
  // evaluation is event-driven, so the cadence-bearing one is the
  // `cos-pending-merge-sweep` timer in cos.js (#3630). Keeping it here costs
  // nothing and makes `POST /api/cos/evaluate` do the obvious thing.
  // Runs BEFORE the agent-slot
  // gate below because a deterministic merge claims no lane, so a full agent
  // roster must not also wedge the merge queue.
  //
  // Gated on `!paused` AND on CoS auto-run being in `execute`, like every other
  // autonomous tier: merging writes to a default branch, so it is the LAST thing
  // that may run while the user has auto-run set to `off` or `dry-run`. The mode
  // is read directly rather than via `resolveAutonomyBudget` (which runs further
  // down, after the agent-slot gate) because the daily minutes/actions budget
  // meters agent RUNS — a deterministic merge spawns nothing and consumes none
  // of it — while the mode is the user's "may PortOS act on its own" switch.
  if (!paused && getDomainMode(state.config, 'cos') === 'execute') {
    const { sweepInitializedCheckoutRecoveries } = await import('./initializedCheckoutRecoverySweep.js');
    // This drain has its own cadence/single-flight guard and rechecks autonomy
    // between stages, including after native archive verification.
    void sweepInitializedCheckoutRecoveries(async () => {
      if (!isDaemonRunning()) return 'daemon-stopped';
      const current = await loadState();
      return current.paused ? 'daemon-paused' : getDomainMode(current.config, 'cos') !== 'execute' ? 'autonomy-not-execute' : null;
    }).catch(error => console.warn(`⚠️ Initialized retirement recovery deferred: ${error.message}`));
    const prWatcher = await import('./prWatcher.js');
    const sweep = await prWatcher.sweepPendingMergePrs();
    if (sweep.merged || sweep.escalated || sweep.timedOut) {
      emitLog('info', `🤖 Pending merges: ${sweep.merged} merged, ${sweep.escalated} escalated, ${sweep.timedOut} timed out`);
    }
  }

  if (state.config.persistentMindMaintainer?.enabled) {
    const { runDevelopmentWatchdog } = await import('./developmentWatchdog.js');
    await runDevelopmentWatchdog().catch(err => console.error(`❌ Development watchdog failed: ${err.message}`));
  }

  // Resolve this instance's federation id once per cycle so the priority tiers
  // can skip tasks a peer holds a live lease on (#1650). Warm path is the cheap
  // cached read; only the cold boot creates the identity.
  const instanceId = await ensureInstanceId();

  if (!paused && getDomainMode(state.config, 'cos') === 'execute') {
    await reconcileLegacyForgeMaintenanceTasks({ instanceId });
  }

  // Get both user and CoS tasks
  const { user: userTaskData, cos: cosTaskData } = await getAllTasks();

  // Unblock tasks whose orphan-retry cooldown has expired
  await unblockExpiredCooldowns(userTaskData, cosTaskData);

  // Count running agents and available slots (global + per-project)
  const runningAgentEntries = Object.values(state.agents).filter(a => a.status === 'running');
  const runningAgents = runningAgentEntries.length;
  // In-flight spawns hold a slot before their agent registers as running.
  const availableSlots = state.config.maxConcurrentAgents - runningAgents - countUnregisteredInFlight(spawningTasks, state.agents);

  const perProjectLimit = state.config.maxConcurrentAgentsPerProject || state.config.maxConcurrentAgents;
  const agentsByProject = countRunningAgentsByProject(state.agents);

  if (availableSlots <= 0) {
    emitLog('warn', `Max concurrent agents reached (${runningAgents}/${state.config.maxConcurrentAgents})`);
    await recordDecision(
      DECISION_TYPES.CAPACITY_FULL,
      `All ${state.config.maxConcurrentAgents} agent slots occupied`,
      { running: runningAgents, max: state.config.maxConcurrentAgents }
    );
    cosEvents.emit('evaluation', { message: 'Max concurrent agents reached', running: runningAgents });
    return;
  }

  const tasksToSpawn = [];
  // Track per-project counts including tasks we're about to spawn in this batch
  const spawnProjectCounts = { ...agentsByProject };

  // Resolve the CoS auto-run mode + daily-budget ceiling for this cycle (#711).
  const { cosAutonomyMode, autonomousActionsRemaining } = await resolveAutonomyBudget(state, runningAgentEntries);

  // Helper: check if a task can spawn (within both global and per-project limits).
  // `ceiling` defaults to the global slot count; autonomous sections pass the
  // lower `autonomousSlotCeiling` so the CoS action budget (#711) caps them.
  const admittedTaskIds = new Set();
  const isTaskOwned = (task) => Boolean(task?.id) && (admittedTaskIds.has(task.id) || spawningTasks.has(task.id));
  const canSpawnTask = (task, ceiling = availableSlots) => {
    if (isTaskOwned(task)) return false;
    if (tasksToSpawn.length >= ceiling) return false;
    const project = task.metadata?.app || '_self';
    return (spawnProjectCounts[project] || 0) < perProjectLimit;
  };
  // The ONE admission sink every tier uses: queue the pick for the spawn loop
  // below AND count it against its project's cap, together, so no tier can do
  // one without the other (#9609).
  const admitSpawn = (task) => {
    tasksToSpawn.push(task);
    if (task.id) admittedTaskIds.add(task.id);
    const project = task.metadata?.app || '_self';
    spawnProjectCounts[project] = (spawnProjectCounts[project] || 0) + 1;
  };
  // The adapter every tier hands to its shared admission pass, unchanged. Those
  // passes also serve dequeueNextTask (cos.js), which dispatches and counts
  // through different objects, so they take emit and track as separate hooks;
  // here `admitSpawn` already does both, so the track hook is inert.
  const spawnAdapter = Object.freeze({ canSpawn: canSpawnTask, emitSpawn: admitSpawn, trackSpawn: () => {}, isOwned: isTaskOwned });

  // Check if there are pending user tasks (even if on cooldown). If user tasks
  // exist, don't run self-improvement — wait for user tasks to be ready.
  const pendingUserTasks = userTaskData.grouped?.pending || [];
  const hasPendingUserTasks = pendingUserTasks.length > 0;

  // Read-only spawn context shared by every priority tier (#9609). Frozen so a
  // tier cannot pass a value to a later tier by writing into it — a tier that
  // produces something a later tier needs RETURNS it, and the sequence below
  // threads it as a named argument. Spawning goes through `spawnAdapter`, whose
  // closures own the running `tasksToSpawn` / `spawnProjectCounts` totals.
  const ctx = Object.freeze({
    state,
    cosTaskData,
    instanceId,
    availableSlots,
    perProjectLimit,
    tasksToSpawn,
    spawnProjectCounts,
    cosAutonomyMode,
    initialStartup,
    pendingUserTasks,
    hasPendingUserTasks,
    spawnAdapter,
  });

  // Priority 0 (on-demand) spends against the global slot cap and runs even when
  // paused — an explicit user "Run" bypasses the global pause.
  const { schedule: taskSchedule } = await spawnPriority0OnDemand(ctx);

  // Every tier below is scheduled/autonomous/user work that the global pause
  // stops. When paused we skip them and let the shared spawn loop below emit just
  // the on-demand tasks Priority 0 collected.
  if (!paused) {
    // Priority 1 spends against the global slot cap.
    await spawnPriority1UserTasks(ctx);

    // Ceiling for AUTOMATIC admissions this cycle (#711). User and on-demand
    // tasks already bypassed the mode gate; on-demand also bypasses pause. The
    // automatic tiers may add at most `autonomousActionsRemaining` more tasks.
    // On-demand runs still count as non-user work in the completion ledger and
    // subsequent in-flight allowance; only user tasks are exempt. With no action
    // cap this equals `availableSlots`.
    const autonomousSlotCeiling = Math.min(availableSlots, tasksToSpawn.length + autonomousActionsRemaining);

    // Priorities 2, 3.6, 4 spend against the lower autonomous ceiling.
    await spawnPriority2AutoApproved(ctx, { taskSchedule, autonomousSlotCeiling });
    await maybeQueueImprovementTasks(ctx);
    await spawnPriority36FeatureAgents(ctx, { autonomousSlotCeiling });
    await spawnPriority4IdleReview(ctx, { autonomousSlotCeiling });
  }

  // Emit evaluation status
  const pendingUserCount = userTaskData.grouped?.pending?.length || 0;
  const inProgressCount = userTaskData.grouped?.in_progress?.length || 0;
  const pendingSystemCount = cosTaskData.grouped?.pending?.length || 0;

  const evalLevel = tasksToSpawn.length > 0 ? 'info' : 'debug';
  emitLog(evalLevel, `Evaluation: ${pendingUserCount} user pending, ${inProgressCount} in_progress, ${pendingSystemCount} system, spawning ${tasksToSpawn.length}`, {
    pendingUser: pendingUserCount,
    inProgress: inProgressCount,
    pendingSystem: pendingSystemCount,
    toSpawn: tasksToSpawn.length,
    availableSlots
  });

  // Note: Performance summaries, learning insights, and rehabilitation checks
  // are now handled by dedicated maintenance intervals (cos-performance-summary,
  // cos-learning-insights, cos-rehabilitation-check) instead of evalCount gating.

  // Spawn all ready tasks (up to available slots)
  for (const task of tasksToSpawn) {
    emitLog('success', `Spawning task: ${task.id} (${task.priority || 'MEDIUM'})`, {
      taskId: task.id,
      taskType: task.taskType,
      app: task.metadata?.app
    });
    cosEvents.emit('task:ready', task);
  }

  // Emit awaiting approval count if any
  if (cosTaskData.awaitingApproval?.length > 0) {
    emitLog('info', `${cosTaskData.awaitingApproval.length} tasks awaiting approval`);
    cosEvents.emit('evaluation', {
      message: 'Tasks awaiting approval',
      awaitingApproval: cosTaskData.awaitingApproval.length
    });
  }

  if (tasksToSpawn.length === 0) {
    const awaitingCount = cosTaskData.awaitingApproval?.length || 0;
    const idleReason = awaitingCount > 0
      ? `${awaitingCount} task(s) awaiting approval, none auto-approved`
      : hasPendingUserTasks
        ? 'User tasks exist but all on cooldown or at capacity'
        : 'No user tasks, system tasks, or idle work available';
    emitLog('debug', `No tasks to process - idle: ${idleReason}`);
    await recordDecision(
      DECISION_TYPES.IDLE,
      idleReason,
      { pendingUser: pendingUserCount, pendingSystem: pendingSystemCount, awaitingApproval: awaitingCount, runningAgents }
    );
    cosEvents.emit('evaluation', { message: 'No pending tasks to process' });
  }
}

/**
 * Generate an idle task when no user/system tasks are pending
 * Alternates between:
 * 1. Self-improvement tasks (UI analysis, security, code quality)
 * 2. App reviews for managed apps
 *
 * @param {Object} state - Current CoS state
 * @param {Object} options - Completion exclusion and optional app eligibility
 * @returns {Object} Task plus deferred dispatch/card handoff, or a null task
 */
export async function generateIdleReviewTask(state, { ignoreTaskId = null, isAppEligible = () => true } = {}) {
  if (!isImprovementEnabled(state)) {
    emitLog('debug', 'Improvement tasks are disabled');
    return { task: null, pendingPerpetualDispatch: null, preflightCardId: null };
  }

  // Exclude full projects before selection commits cooldown/request state.
  const apps = (await getActiveApps().catch(() => [])).filter(isAppEligible);

  if (apps.length > 0) {
    // Find next app eligible for review (not on cooldown, oldest review first)
    const nextApp = await getNextAppForReview(apps, state.config.appReviewCooldownMs);

    if (nextApp) {
      // Mark that we're starting an idle review. Advance the per-app cooldown
      // eagerly (so this app isn't re-picked on the next idle tick) but do NOT
      // bind an active agent yet — the task generator below may return null
      // (no claimable PLAN item, watcher no-op, precondition skip), in which
      // case binding here would strand `activeAgentId` and leave the app stuck
      // reading "in review" until stale-agent cleanup (issue #978).
      await markIdleReviewStarted();
      await markAppReviewCooldown(nextApp.id);

      // Update lastIdleReview timestamp
      await withStateLock(async () => {
        const s = await loadState();
        s.stats.lastIdleReview = new Date().toISOString();
        await saveState(s);
      });

      const { task: idleTask, pendingPerpetualDispatch, preflightCardId } = await generateManagedAppImprovementTask(nextApp, state, { ignoreTaskId });
      // Only bind the active marker once a real task exists.
      if (idleTask) {
        await bindAppReviewAgent(nextApp.id, `idle-review-${Date.now()}`);
      }
      return { task: idleTask, pendingPerpetualDispatch, preflightCardId };
    }
  }

  emitLog('debug', 'No idle tasks available');
  return { task: null, pendingPerpetualDispatch: null, preflightCardId: null };
}

/**
 * Build the dedup sets `queueEligibleImprovementTasks` uses to decide whether
 * an improvement slot is already occupied.
 *
 * Active (pending/in_progress) tasks occupy both their per-type slot and the
 * per-app "one improvement at a time" cap. Blocked tasks ALSO occupy their
 * per-type slot regardless of blockedCategory (#2614): before this, only
 * `user-terminated` blocked tasks counted, so a task blocked by repeated
 * failures (max-retries, max-spawns, provider-config, unknown, …) was
 * invisible to dedup and the generator minted an identical duplicate every
 * cadence tick — nothing reaps blocked tasks, so the pile grew unbounded.
 * Failure-blocked *improvement* tasks (blocked with any category except
 * `user-terminated`, AND an analysis type is derivable) also count toward the
 * per-app cap — the retry path is unblocking the existing task, not creating
 * a new one. A blocked NON-improvement task (an investigation, a review
 * follow-up) never holds the app cap: blocked tasks are not reaped, so it
 * would freeze the app's improvement rotation forever. `user-terminated`
 * keeps its original scope (per-type slot only) so an intentional kill of
 * one type doesn't freeze the whole app's rotation either.
 *
 * `blockedTaskTypes` / `appsWithBlockedImprovement` are Maps (key → blocking
 * task id) mirroring which entries came from blocked tasks so the caller can
 * log a visible, actionable skip reason instead of silently suppressing
 * generation.
 *
 * `ignoreTaskId` excludes one task from every set — used by the perpetual
 * drain-on-completion refill, where the just-completed task is still
 * `in_progress` on disk (agent:completed fires before updateTask finalizes
 * it). Without it the completing task would make its own app look busy and
 * block the next perpetual run.
 */
export function buildImprovementDedupSets(existingTasks, { ignoreTaskId = null } = {}) {
  const existingTaskTypes = new Set();
  // Apps that already have *any* pending/in_progress/failure-blocked improvement
  // task. We cap each app at one queued improvement at a time to avoid a fan-out
  // where multiple improvement types pile up faster than the per-app cooldown
  // can drain them.
  const appsWithPendingImprovement = new Set();
  const blockedTaskTypes = new Map();
  const appsWithBlockedImprovement = new Map();

  for (const task of existingTasks) {
    if (task.id === ignoreTaskId) continue;
    const isActive = task.status === 'pending' || task.status === 'in_progress';
    const isBlocked = task.status === 'blocked';
    const isFailureBlocked = isBlocked && task.metadata?.blockedCategory !== 'user-terminated';
    const analysisType = currentTaskTypeName(task.metadata?.analysisType ||
      task.metadata?.selfImprovementType ||
      task.description?.match(/\[(?:self-improvement|improvement)\]\s*(\w[\w-]*)/i)?.[1]);
    const appId = task.metadata?.app;
    if ((isActive || isBlocked) && analysisType) {
      const taskKey = appId ? `app:${appId}:${analysisType}` : analysisType;
      existingTaskTypes.add(taskKey);
      if (isBlocked && !blockedTaskTypes.has(taskKey)) blockedTaskTypes.set(taskKey, task.id);
    }
    // Active tasks of ANY kind with an app hold the per-app cap (pre-existing
    // behavior — active tasks drain, so the hold is temporary). Blocked tasks
    // hold it only when failure-blocked AND actually an improvement task —
    // see the docstring above.
    if ((isActive || (isFailureBlocked && analysisType)) && appId && !isRecoveryTask(task)) {
      appsWithPendingImprovement.add(appId);
      if (isFailureBlocked && !appsWithBlockedImprovement.has(appId)) appsWithBlockedImprovement.set(appId, task.id);
    }
  }

  return { existingTaskTypes, appsWithPendingImprovement, blockedTaskTypes, appsWithBlockedImprovement };
}


export async function queueDueInstallWideImprovementTasks({
  dueTasks,
  state,
  taskSchedule,
  existingTaskTypes,
  blockedTaskTypes,
  ignoreTaskId = null,
  wakeAfterRecord = true,
  generateTask = generateSelfImprovementTaskForType,
  persistTask = addTask,
  wake = () => cosEvents.emit('cos:dequeue-requested')
}) {
  let queued = 0;
  const dueInstallWideTasks = dueTasks
    .filter(({ taskType }) => taskSchedule.INSTALL_WIDE_TASK_TYPES.has(taskType));

  for (const { taskType } of dueInstallWideTasks) {
    const taskKey = taskType;
    if (existingTaskTypes.has(taskKey)) {
      if (blockedTaskTypes.has(taskKey)) {
        emitLog('info', `⏸️ Skipping install-wide ${taskType}: blocked task ${blockedTaskTypes.get(taskKey)} already exists — resolve or delete it to resume`, { analysisType: taskType });
      } else {
        emitLog('debug', `Install-wide improvement task ${taskType} already queued`);
      }
      continue;
    }

    const task = await generateTask(taskType, state);
    // Hooks such as user-action-review's empty-ledger check deliberately
    // advance their cadence while returning no task, so do not record a second
    // execution here when the generator declines to dispatch.
    if (!task) continue;

    task.priority = 'LOW';
    task.priorityValue = PRIORITY_VALUES.LOW;
    task.id = `sys-install-${taskType}-${Date.now().toString(36)}`;

    const newTask = await persistTask(task, 'internal', { raw: true, ignoreTaskId, suppressDequeue: true });
    if (newTask?.duplicate) continue;
    if (wakeAfterRecord) wake();

    await taskSchedule.recordExecution(`task:${taskType}`);
    emitLog('info', `Queued install-wide improvement task: ${taskType}`, { taskId: newTask.id, analysisType: taskType });
    existingTaskTypes.add(taskKey);
    queued++;
  }

  return queued;
}

/**
 * Queue eligible self-improvement and app improvement tasks as system tasks.
 * Called by evaluation (`maybeQueueImprovementTasks`) only when no user tasks
 * are pending and COS auto-run is `execute`, by `runImprovementCheckOnce`, by
 * the post-startup queue in `cos.js`, and by `refillPerpetualForCompletedAgent`.
 * The latter three gate on `canQueueImprovementTasks` before allowing this
 * COS-TASKS.md write.
 * Tasks are picked up in Priority 2.
 */
export async function queueEligibleImprovementTasks(state, cosTaskData, {
  ignoreTaskId = null, wakeAfterRecord = true, perpetualContinuation = null,
  prepareTask = prepareManagedAppImprovementTask, persistTask = addTask
} = {}) {
  const taskSchedule = await import('./taskSchedule.js');
  const { getDueTasks, getNextTaskType, recordExecution } = taskSchedule;

  if (!isImprovementEnabled(state)) return;

  // Existing active AND blocked system tasks feed the dedup sets — see
  // buildImprovementDedupSets for the occupancy semantics (#2614). The same
  // `ignoreTaskId` is forwarded to addTask below so its disk-level duplicate
  // scan ignores it too.
  const existingTasks = cosTaskData.tasks || [];
  const { existingTaskTypes, appsWithPendingImprovement, blockedTaskTypes, appsWithBlockedImprovement } =
    buildImprovementDedupSets(existingTasks, { ignoreTaskId });

  // One clock for the whole tick: cron eligibility lasts a single minute, and
  // preparing earlier apps can take longer than that (#11755).
  const tickNow = Date.now();
  let queued = 0;

  // Install-wide task types have no managed-app target: their cadence is
  // tracked by the global execution record, and one task is the complete run
  // for this PortOS install. Run this before the per-app pass: an install-wide
  // hook may deliberately reject app targets while recording that app-scoped
  // check, which must not consume the global due window first.
  //
  // Do not select a single generic next task here — every install-wide type
  // that is independently due must get its own lane. The dedup key is the bare
  // analysis type, matching buildImprovementDedupSets for globally-scoped tasks
  // and ensuring one pending/blocked task suppresses only its own duplicate.
  queued += await queueDueInstallWideImprovementTasks({
    dueTasks: await getDueTasks(null, { now: tickNow }), state, taskSchedule, existingTaskTypes,
    blockedTaskTypes, ignoreTaskId, wakeAfterRecord
  });

  // Load the activity snapshot ONCE before the per-app loop. The cooldown gate
  // is derived from `data/app-activity.json`; before this hoist, each app paid a
  // separate disk read (via `isAppOnCooldown`), so a 10-app deployment re-read
  // the same file once per app per scheduler tick. With the snapshot pinned, the
  // cost is O(1) read per `queueEligibleImprovementTasks` invocation. Falls back
  // to an empty `apps` map on disk error so the loop's per-app lookups uniformly
  // return `undefined` (read as "no activity yet — not on cooldown").
  const activitySnapshot = await loadAppActivity().catch(() => ({ apps: {} }));

  // Queue eligible improvement tasks for all managed apps (including PortOS)
  const apps = await getActiveApps().catch(() => []);
  // Snapshot every app's due set against `tickNow` BEFORE any prepareTask runs:
  // prepare does network and git work, so evaluating lazily would judge later
  // apps against a clock that already left the cron minute.
  const appDueSnapshots = [];
  for (const app of apps) {
    const continuingTaskType = perpetualContinuation?.appId === app.id ? perpetualContinuation.taskType : null;
    appDueSnapshots.push({
      app, continuingTaskType,
      dueTasks: await getDueTasks(app.id, { continuingTaskType, now: tickNow })
    });
  }

  for (const { app, continuingTaskType, dueTasks } of appDueSnapshots) {
    // Capture every due clock slot before applying the background-drain cap.
    // Cron eligibility lasts one minute: a busy app or a sibling cron must not
    // discard that occurrence. Persist it now; spawn admission still enforces
    // concurrency, budgets and cooldowns when the task actually executes.
    // Use the readiness reason rather than the global interval: an app may
    // supply its own cron while the global task remains on-demand.
    const cronTasks = dueTasks.filter(task => task.reason === TASK_READINESS_REASON.CRON_DUE);
    const appBusy = appsWithPendingImprovement.has(app.id);
    if (appBusy && cronTasks.length === 0) {
      if (appsWithBlockedImprovement.has(app.id)) {
        emitLog('info', `⏸️ Skipping improvement queue for ${app.name}: failure-blocked improvement task ${appsWithBlockedImprovement.get(app.id)} occupies the app slot — resolve or delete it to resume`, { appId: app.id });
      } else {
        emitLog('debug', `App ${app.name} already has a pending improvement task — skipping queue`);
      }
      continue;
    }

    // Derive both gates from the single shared snapshot. The async
    // `isAppOnCooldown` would also work, but it loads the activity file
    // again per app — see comment on `activitySnapshot` above.
    // Optional chain on `.apps` — `loadAppActivity()` spreads
    // `DEFAULT_ACTIVITY` over the file contents, but a hand-edited
    // activity.json that explicitly sets `apps: null` (or any non-object)
    // would still surface here; both gates treat `undefined` as
    // "no activity yet."
    const appActivity = activitySnapshot.apps?.[app.id];

    // Perpetual (drain-until-done) tasks BYPASS the per-app review cooldown:
    // their work-detector park IS the throttle (taskSchedule.parkPerpetual), and
    // agentCompletion.js already skips the post-completion cooldown bump for
    // them. But the spawn-time `markAppReviewCooldown` stamp (written by BOTH the
    // on-demand manual-trigger path and the idle-review loop) sets
    // `lastReviewedAt`, which `isAppActivityOnCooldown` reads — so without a
    // bypass the back-to-back refill fired right after a perpetual run reads its
    // OWN app as "on cooldown" and skips the re-queue, and the drain stalls.
    //
    // Once clock slots have been captured, cooldown only narrows the
    // background pick to a perpetual drain, whose park is its own throttle.
    const onCooldown = isAppActivityOnCooldown(appActivity, state.config.appReviewCooldownMs);

    const nextTypeResult = cronTasks.length === 0
      ? await getNextTaskType(app.id, {
        perpetualOnly: onCooldown, continuingTaskType, dueTasks
      }).catch(err => {
        emitLog('error', `Failed to select next improvement task type for ${app.name}: ${err.message}`, { appId: app.id });
        return null;
      })
      : null;
    const nextTypes = cronTasks.length > 0
      ? cronTasks.map(task => task.taskType)
      : nextTypeResult ? [nextTypeResult.taskType] : [];

    for (const nextType of nextTypes) {
      const taskKey = `app:${app.id}:${nextType}`;
      if (existingTaskTypes.has(taskKey)) {
        if (blockedTaskTypes.has(taskKey)) {
          emitLog('info', `⏸️ Skipping ${nextType} for ${app.name}: blocked task ${blockedTaskTypes.get(taskKey)} of this type already exists — resolve or delete it to resume`, { appId: app.id });
        } else {
          emitLog('debug', `Improvement task ${nextType} for ${app.name} already queued`);
        }
        continue;
      }

      // Route through the rich generator so `applyPlanIdMetadata` runs — it
      // scans open `claim/<slug>` branches + PRs and excludes in-flight slugs
      // from the pick. The old stub path skipped this and let two plan-task
      // agents claim the same slug (2026-05-21 incident). The generator
      // returns null on plan-gate / precondition skip; we silently continue.
      // Regression-pinned in cos.test.js.
      const prepared = await prepareTask(nextType, app, state, { ignoreTaskId });
      if (!prepared.task) continue;
      const { task, pendingPerpetualDispatch } = prepared;

      // Queue-path invariants override the generator's direct-spawn defaults
      // (which use MEDIUM priority + `app-improve-*` id).
      task.priority = 'LOW';
      task.priorityValue = PRIORITY_VALUES.LOW;
      task.id = `sys-${app.id.slice(0, 8)}-${nextType}-${Date.now().toString(36)}`;

      // Queue path: addTask's raw branch persists the task through COS-TASKS.md,
      // which folds multi-line descriptions to first line + full body in
      // metadata.prompt (#4153). On-demand path: emits unpersisted task on
      // task:ready, renders full description via getTaskPrompt.
      const newTask = await persistTask(task, 'internal', { raw: true, ignoreTaskId, suppressDequeue: true });
      if (newTask?.duplicate) continue;
      // Recorded from `pendingPerpetualDispatch` — the RECORD prepare returned —
      // never from `task` or `newTask`: addTask hands back a different object
      // whenever the description is multi-line, so recording must not depend on
      // which one the caller is holding (#6871).
      await recordDeferredPerpetualDispatch(pendingPerpetualDispatch, taskSchedule);
      if (wakeAfterRecord) cosEvents.emit('cos:dequeue-requested');

      await recordExecution(`task:${nextType}`, app.id);

      emitLog('info', `Queued improvement task: ${nextType} for ${app.name}`, { taskId: newTask.id, appId: app.id });
      existingTaskTypes.add(taskKey);
      appsWithPendingImprovement.add(app.id);
      queued++;
    }
    // Background drains still enqueue at most one task per app per evaluation.
  }

  if (queued > 0) {
    emitLog('info', `Queued ${queued} improvement task(s) to system tasks`);
  }
}

/**
 * Resolve auto-approval for a task based on confidence scoring, with a
 * safety-kind override (#2440) that is orthogonal to confidence.
 *
 * Outward-facing / irreversible work (publishing content, federating records to
 * sync peers, external/upstream PRs, releases) always requires the user's
 * sign-off no matter how high the task type's success rate is — a high score
 * can't undo work that has already left the install. Reversible internal work
 * (analysis, refactor, same-repo improvement PRs) keeps the pure success-rate
 * gate, so existing behavior is unchanged unless the task carries an outward
 * signal.
 *
 * Returns { autoApproved, approvalRequired, safetyKind, approvalReason? } ready
 * to spread into task objects — `safetyKind` + `approvalReason` surface WHY a
 * high-confidence task still needs approval on the task record and in the UI.
 */
export function isConfiguredApprovalRequired(metadata) {
  return metadata?.requireApproval === true;
}

async function resolveConfidenceApproval(state, taskTypeKey, logLabel, metadata = {}) {
  const safety = classifySafetyKind({ taskTypeKey, metadata });
  const safetyConfig = state?.config?.safetyKindApproval ?? {};

  // Explicit per-type/per-app toggle wins over every automatic gate. The user
  // turned "Require approval" on for this scheduled type; do not second-guess
  // that with confidence or a Run Now consent flip.
  if (isConfiguredApprovalRequired(metadata)) {
    emitLog('info', `🔒 ${logLabel} requires approval (task metadata requireApproval)`, {}, '[Approval]');
    return {
      autoApproved: false,
      approvalRequired: true,
      safetyKind: safety.kind,
      approvalReason: 'config:requireApproval'
    };
  }

  // Safety-kind override runs BEFORE (and independent of) the confidence gate.
  if (safety.outwardFacing && requiresSafetyApproval(safety.kind, safetyConfig)) {
    emitLog('info', `🔒 ${logLabel} requires approval (safety-kind: ${safety.kind} — ${safety.reason})`, {}, '[Safety]');
    return {
      autoApproved: false,
      approvalRequired: true,
      safetyKind: safety.kind,
      approvalReason: `safety-kind:${safety.kind}`
    };
  }

  const config = state?.config?.confidenceAutoApproval ?? {};
  if (config.enabled === false) {
    return { autoApproved: true, approvalRequired: false, safetyKind: safety.kind };
  }

  const confidence = await getTaskTypeConfidence(taskTypeKey, config);
  if (!confidence.autoApprove) {
    emitLog('info', `🔒 ${logLabel} requires approval (${confidence.reason})`, {}, '[Confidence]');
  }
  return {
    autoApproved: confidence.autoApprove,
    approvalRequired: !confidence.autoApprove,
    safetyKind: safety.kind,
    ...(confidence.autoApprove ? {} : { approvalReason: `confidence:${confidence.tier}` })
  };
}

/**
 * Clicking Run (or a refill of that run) is the user's consent. Safety-kind
 * and confidence gates exist so UNATTENDED queue-path work can't ship
 * irreversible actions on its own — they must not re-hold a task the user
 * just asked to run, or "Run Now" lands in awaiting-approve and never
 * auto-spawns (Priority 2 only picks AUTO tasks; force-spawn refuses
 * APPROVAL tasks).
 *
 * `metadata.requireApproval` is the escape hatch: a type the user marked
 * "always ask" (e.g. do-release when they want to review the merge)
 * keeps the hold even on Run Now.
 */
export function applyOnDemandConsent(task) {
  if (!task) return task;
  if (isConfiguredApprovalRequired(task.metadata)) return task;
  task.approvalRequired = false;
  task.autoApproved = true;
  if ('approvalReason' in task) delete task.approvalReason;
  // The hint TaskItem reads lives on metadata — COS-TASKS.md only persists
  // that bag. Clear both so a consented Run Now does not keep a stale reason.
  if (task.metadata && 'approvalReason' in task.metadata) delete task.metadata.approvalReason;
  return task;
}

function stampApprovalReason(metadata, approval) {
  if (approval?.approvalReason) metadata.approvalReason = approval.approvalReason;
  else delete metadata.approvalReason;
}

/**
 * Helper function to generate a self-improvement task for a specific type
 * Used by both normal rotation and on-demand task requests
 */
export async function generateSelfImprovementTaskForType(taskType, state) {
  if (taskType === 'development-watchdog') return null;
  const taskSchedule = await import('./taskSchedule.js');
  const { getTaskPrompt } = await import('./taskPromptService.js');
  const interval = await taskSchedule.getTaskInterval(taskType);
  // App-scoped task types must never fall through this global lane. The
  // on-demand request gate normally rejects a missing appId, but scheduled
  // rotation and older callers can still reach the generator directly.
  if (taskSchedule.requiresManagedAppTarget(taskType)) {
    emitLog('warn', `Skipping ${taskType} without a managed app target`);
    return null;
  }
  let description = await getTaskPrompt(taskType);

  const metadata = {
    analysisType: taskType,
    autoGenerated: true,
    selfImprovement: true
  };

  // Apply sanitized task-type-specific metadata from schedule config (e.g., useWorktree, simplify)
  const sanitizedMeta = sanitizeTaskMetadata(interval.taskMetadata);
  if (sanitizedMeta) {
    Object.assign(metadata, sanitizedMeta);
    Object.assign(metadata, newAuditMetadata(metadata));
  }

  // Use configured model/provider if specified, otherwise use default
  if (interval.providerId) {
    metadata.provider = interval.providerId;
    metadata.providerId = interval.providerId;
  }
  // Only pin a model when the schedule config explicitly sets one. With no
  // pin, leave metadata.model unset so selectModelForTask resolves the ACTIVE
  // provider's tier/default model at spawn time — never a hardcoded literal.
  // (A stale literal here once pinned an opus release that had since dropped
  // out of the provider config, spawning claude with a --model the provider
  // no longer lists.)
  if (interval.model) {
    metadata.model = interval.model;
  }
  if (interval.effort) {
    metadata.effort = interval.effort;
  }

  // repo-sync's install-wide sweep. This lane is what a global "Run Now" (no
  // app) hits, and sweeping EVERY managed app in one run is the shape the task
  // exists for — so the pre-step runs here, not only in the per-app lane. It
  // returns `skip` when the sweep left nothing for an agent to do, which is the
  // common case on an already-clean machine and costs no provider call.
  // Programmatic pre-agent input hook (taskTypeHooks.js) — the install-wide
  // lane mirrors the per-app one so a hook-gated type (user-action-review's
  // empty-ledger check) can skip here too, without burning an agent. Gated to
  // INSTALL-WIDE types: the per-app hooks (issue-watcher, layered-intelligence)
  // guard on `!app`, and the synthetic `{ id: null }` row below is truthy — an
  // ungated call would march issue-watcher into resolving the PortOS repo as
  // its app via getOriginInfo's cwd default. The synthetic row only labels the
  // skip log / execution record; provider pins from a hook are a per-app
  // concept and are not applied in this lane.
  if (taskSchedule.INSTALL_WIDE_TASK_TYPES.has(taskType)) {
    const inputHook = await resolveTaskInputHook({ id: null, name: 'PortOS' }, taskType, taskSchedule);
    if (inputHook.skip) return null;
    if (inputHook.hookPrompt) description = inputHook.hookPrompt;
  }

  // Operator review and model research deliver actions/data, never a commit.
  // Stamp the action-output posture the way the audit file-issues path does —
  // `noCodeOutput` is dispatch-stamped, not user-settable, so it cannot arrive
  // from DEFAULT_TASK_INTERVALS through sanitizeTaskMetadata. Without it the
  // completion contract tells a live-checkout agent to commit and `/do:push`.
  if (taskType === 'user-action-review' || taskType === 'model-comparison-refresh') {
    metadata.noCodeOutput = true;
    metadata.worktreeChangesExpected = false;
  }

  // user-action-review: render the delivery posture the operator chose
  // (fileIssues on = tracker issues, off = queued CoS tasks).
  description = applyUserActionDeliveryMode(description, taskType, metadata);
  description = applyReleaseOptions(description, taskType, metadata);
  description = await applyUserActionDetectorSection(description, taskType);

  const repoSync = await resolveRepoSyncBlock(null, taskType, metadata);
  if (repoSync.skip) return null;
  if (repoSync.block) {
    // Function form — the report embeds branch names, git error text, and stash
    // subjects, any of which may contain a dollar-sign backreference token that a
    // replacement STRING would expand instead of inserting literally (same reason
    // as {referenceData}/{prData}).
    description = description.replace(/\{repoSyncReport\}/g, () => repoSync.block);
  }

  const approval = await resolveConfidenceApproval(state, `self-improve:${taskType}`, `Task self-improve:${taskType}`, metadata);
  stampApprovalReason(metadata, approval);

  // Self-improvement tasks do not pass through the managed-app prompt renderer,
  // but do-release still names the install's configured reviewers explicitly.
  // Resolve that token here so the global/on-demand path gets the same reviewer
  // contract and local-review procedure as an app-scoped release task.
  if (description.includes('{reviewers}')) {
    const codeReviewDefaults = await getCodeReviewDefaults().catch(() => null);
    const reviewers = resolveClaimReviewerConfig(metadata, codeReviewDefaults, codeReviewDefaults?.reviewers);
    Object.assign(metadata, reviewerConfigMetadata(reviewers));
    description = description
      .replace(/\{reviewers\}/g, () => reviewers.csv)
      + appendReviewerEffortBlock(reviewers.reviewers, reviewers.reviewerEfforts, reviewers.reviewerModels)
      + buildLocalReviewerInstructions(reviewers.reviewers, reviewers.reviewerModels, reviewers.reviewerEfforts);
  }

  const taskDataInputs = await resolveTaskDataInputs(interval.dataInputs, {
    app: { id: null, name: 'PortOS', repoPath: PATHS.root },
    taskMetadata: metadata,
    taskType
  });
  description = appendTaskDataInputs(description, taskDataInputs);

  const task = {
    id: `self-improve-${taskType}-${Date.now().toString(36)}`,
    status: 'pending',
    priority: 'MEDIUM',
    priorityValue: PRIORITY_VALUES['MEDIUM'],
    description,
    metadata,
    taskType: 'internal',
    ...approval
  };

  return task;
}

/**
 * Check if a pipeline stage's precondition is met.
 * Supports { fileExists: 'path' } and { fileNotExists: 'path' }.
 * Paths are relative to repoPath.
 */
export function checkStagePrecondition(stage, repoPath) {
  const pre = stage?.precondition;
  if (!pre || !repoPath) return { passed: true };
  if (pre.fileExists) {
    const fullPath = join(repoPath, pre.fileExists);
    if (!existsSync(fullPath)) return { passed: false, reason: `${pre.fileExists} does not exist` };
  }
  if (pre.fileNotExists) {
    const fullPath = join(repoPath, pre.fileNotExists);
    if (existsSync(fullPath)) return { passed: false, reason: `${pre.fileNotExists} already exists` };
  }
  return { passed: true };
}

/**
 * Check stage 0 precondition after pipeline initialization.
 * Returns true if the task should be skipped (precondition failed).
 */
function shouldSkipForPrecondition(metadata, app, analysisType) {
  const stage0 = metadata.pipeline?.stages?.[0];
  if (!stage0?.precondition) return false;
  const check = checkStagePrecondition(stage0, app.repoPath);
  if (!check.passed) {
    emitLog('info', `⏭️ Skipping ${analysisType} for ${app.name}: ${check.reason}`, { appId: app.id, analysisType });
    return true;
  }
  return false;
}

/**
 * Initialize pipeline runtime state on metadata if pipeline stages are configured.
 * Mutates the metadata object in place.
 */
function initializePipelineMetadata(metadata) {
  if (!metadata.pipeline?.stages?.length) return;
  metadata.pipeline = {
    ...metadata.pipeline,
    id: `pipeline-${Date.now().toString(36)}`,
    currentStage: 0,
    stageResults: [],
    previousStageAgentId: null,
    status: 'running'
  };
  const stage0 = metadata.pipeline.stages[0];
  if (stage0.readOnly !== undefined) {
    metadata.readOnly = stage0.readOnly;
  }
  // Propagate stage 0's provider/model/effort so the first agent uses per-stage config
  if (stage0.model) metadata.model = stage0.model;
  if (stage0.providerId) {
    metadata.provider = stage0.providerId;
    metadata.providerId = stage0.providerId;
  }
  if (stage0.effort) metadata.effort = stage0.effort;
  // Save task-level defaults and apply stage 0 overrides in one pass
  // Read-only stages default flags to false to prevent worktree/PR/simplify on review-only stages
  metadata.pipeline.taskDefaults = {};
  const stageReadOnly = stage0.readOnly ?? false;
  for (const flag of PIPELINE_STAGE_BEHAVIOR_FLAGS) {
    if (metadata[flag] !== undefined) metadata.pipeline.taskDefaults[flag] = metadata[flag];
    // Draft delivery constrains the whole run, including read-only stages whose
    // audit output could otherwise publish an automatically merged snapshot.
    if (flag === 'prCompletion' && metadata.pipeline.taskDefaults.prCompletion === PR_COMPLETIONS.DRAFT) continue;
    if (flag in stage0) {
      metadata[flag] = stage0[flag];
    } else if (stageReadOnly) {
      metadata[flag] = false;
    }
  }
}

// Apply app-level worktree/PR defaults only when not already set by task-type metadata.
// openPR is applied first since it implies useWorktree — this prevents defaultUseWorktree: false
// from blocking defaultOpenPR: true when both are app-level defaults.
export function applyAppWorktreeDefault(metadata, app) {
  const taskTypeDisabledWorktree = metadata.useWorktree === false || metadata.useWorktree === 'false';

  // Apply defaultOpenPR first (since openPR implies useWorktree)
  if (metadata.openPR === undefined) {
    if (app.defaultOpenPR === true && !taskTypeDisabledWorktree) {
      metadata.openPR = true;
      metadata.useWorktree = true; // openPR implies useWorktree
    } else if (app.defaultOpenPR === false || taskTypeDisabledWorktree) {
      metadata.openPR = false;
    } else if ((app.defaultUseWorktree === true || isTruthyMeta(metadata.useWorktree)) && app.defaultOpenPR !== false) {
      metadata.openPR = true;
      metadata.useWorktree = true;
    }
  }

  // Apply defaultUseWorktree (only if not already set by task-type or openPR above)
  if (metadata.useWorktree === undefined) {
    // openPR implies useWorktree — don't let app default override explicit openPR: true
    const explicitOpenPR = isTruthyMeta(metadata.openPR);
    if (explicitOpenPR) {
      metadata.useWorktree = true;
    } else if (app.defaultUseWorktree === true) {
      metadata.useWorktree = true;
    } else if (app.defaultUseWorktree === false) {
      metadata.useWorktree = false;
    }
  }

  // Final invariant: openPR implies useWorktree (normalize in both directions)
  const finalOpenPR = isTruthyMeta(metadata.openPR);
  const finalWorktreeOff = metadata.useWorktree === false || metadata.useWorktree === 'false';
  if (finalOpenPR && finalWorktreeOff) {
    // openPR wins — force useWorktree on
    metadata.useWorktree = true;
  } else if (finalWorktreeOff) {
    metadata.openPR = false;
  }

  // Pin the policy on new PR tasks so later app-default changes cannot change
  // a running task's authority. Stored legacy tasks are resolved separately.
  if ((finalOpenPR || isTruthyMeta(metadata.claimFlow)) && metadata.prCompletion === undefined) {
    metadata.prCompletion = resolveAppPrCompletion(app, metadata);
  }
}

async function generateManagedAppImprovementTask(app, state, { ignoreTaskId = null } = {}) {
  const taskSchedule = await import('./taskSchedule.js');

  // First, check for any on-demand task requests for this app
  const onDemandRequests = await taskSchedule.getOnDemandRequests();
  const appRequests = onDemandRequests.filter(r => r.appId === app.id);

  let nextType;
  let selectionReason;
  // A stolen on-demand request may be SCOPED to one PR (the PRs/MRs tab's
  // per-row pr-reviewer trigger). Carrying it is not optional: the generator
  // reads no target as "sweep every external PR", so dropping it here would
  // silently promote the user's one-row click into a full-repo review — the
  // same widening the perpetual-refill skip guards against on the other side.
  let targetPullRequest = null;
  // The card a human's "Run" already opened, when this steal is serving one —
  // stealing the request means inheriting its card, because the on-demand drain
  // will never see that request again. See `finishPreflightDispatch`.
  let stolenCardId = null;
  // A stolen request's run parameters (a quota-burn or maintenance step's
  // `params`), forwarded exactly as the on-demand drain forwards them.
  let stolenRunOverrides = null;
  let stolenRequest = null;

  if (appRequests.length > 0) {
    const request = await taskSchedule.clearOnDemandRequest(appRequests[0].id);
    if (!request) {
      // Another drain (or cancellation) owns this receipt. Returning its card
      // would let the idle tier close the winner's still-running preflight.
      return { task: null, pendingPerpetualDispatch: null, preflightCardId: null };
    }
    stolenRequest = request;
    targetPullRequest = request.targetPullRequest ?? null;
    stolenRunOverrides = request.burn?.overrides?.params ?? null;
    const { cardIdForRequest } = await import('./preflightTaskCard.js');
    stolenCardId = cardIdForRequest(request);
    // Only a human "Run" may clear the drain's brakes (park state, dispatch
    // count); the policy lives in applyOnDemandRunResets so this idle-review
    // path can't drift from the shared on-demand drain — without it,
    // a currently drain-capped or parked perpetual type dequeued here stays
    // capped/parked and the explicit "Run" silently produces no task.
    await taskSchedule.applyOnDemandRunResets(request, app.id);
    nextType = request.taskType;
    selectionReason = 'on-demand';
    emitLog('info', `Processing on-demand app task request: ${nextType} for ${app.name}`, { requestId: request.id });
  } else {
    // Use the schedule service to determine the next task type
    const nextTypeResult = await taskSchedule.getNextTaskType(app.id);

    if (!nextTypeResult) {
      emitLog('info', `No app improvement tasks are eligible for ${app.name} based on schedule`);
      // `stolenCardId`, never a literal null: this branch happens to be the one
      // where no steal occurred, but a later early return added above it would
      // strand the card all over again.
      return { task: null, pendingPerpetualDispatch: null, preflightCardId: stolenCardId };
    }

    nextType = nextTypeResult.taskType;
    selectionReason = nextTypeResult.reason;
  }

  // Delegate the actual task build to the per-type generator so the dynamic
  // blocks run on the idle-review path too: pr-watcher's PR poll +
  // {prData}/{repoFullName}/{defaultBranch} injection, and reference-watch's
  // {referenceData} injection. Without delegation this path replaced only the
  // generic placeholders, so a watcher type selected here would spawn a prompt
  // with the literal {prData}/{referenceData} markers and never poll. The
  // preparer owns skip cadence and success activity/logging; this caller
  // records execution only when preparation produces a task.
  const prepared = await prepareManagedAppImprovementTask(nextType, app, state, {
    ignoreTaskId,
    targetPullRequest,
    onDemand: selectionReason === 'on-demand',
    runOverrides: stolenRunOverrides,
    providerOverride: stolenRequest?.providerOverride ?? null,
    // The deterministic pre-agent work (pr-reviewer's security preflight)
    // reports into the stolen Run's card as it runs, exactly as it does on the
    // on-demand drain — this is the whole reason the card is opened early.
    preflightCardId: stolenCardId
  });
  const { task, pendingPerpetualDispatch } = prepared;
  if (task) await taskSchedule.recordExecution(`task:${nextType}`, app.id);
  // Idle-review can steal a queued on-demand request for this app. That
  // request is still a user Run — apply the same consent as Priority 0.
  if (stolenRequest) {
    applyOnDemandConsent(task);
    if (task) task.metadata = { ...(task.metadata || {}), ...onDemandRequestMetadata(stolenRequest) };
  }
  // The card is closed by whoever rules on the task (the spawn tier), not here:
  // a task this returns can still be refused a slot, and a card closed
  // `handed-off` would then name an agent that never started.
  return { task, pendingPerpetualDispatch, preflightCardId: stolenCardId };
}

// How many CONSECUTIVE transient skips (across evaluations) applyPerpetualWorkGate
// tolerates at `debug` before escalating to `warn` — see noteTransientProbe's
// return value.
export const PERPETUAL_TRANSIENT_ESCALATION_THRESHOLD = 3;

// Consecutive-transient-skip counters, keyed `taskType:appId`. This is the ONLY
// state that has to outlive a single evaluation (it counts how many evaluations
// IN A ROW came back transient); the skip's REASON travels back explicitly on
// prepareManagedAppImprovementTask's `skip` result instead of through a side
// channel.
const transientStreaks = new Map();
const transientStreakKey = (taskType, appId) => `${taskType}:${appId || 'global'}`;

/**
 * Count one more consecutive transient (non-parking) probe failure for
 * `taskType` + `appId`.
 *
 * @returns {number} the new consecutive-transient count.
 */
function noteTransientProbe(taskType, appId) {
  const key = transientStreakKey(taskType, appId);
  const count = (transientStreaks.get(key) || 0) + 1;
  transientStreaks.set(key, count);
  return count;
}

/** Reset the consecutive-transient streak — the probe stopped being transient. */
function clearTransientProbeStreak(taskType, appId) {
  transientStreaks.delete(transientStreakKey(taskType, appId));
}

/**
 * Drain the on-demand requests for PROGRAMMATIC scheduled task types
 * (`services/scheduledHandlers/`) — the ones PortOS performs ITSELF.
 *
 * They never become a CoS task and never spawn an agent, so they are drained
 * ahead of (and outside) the slot-bounded loops in the two on-demand engines:
 * queueing a describe/render batch behind agent capacity it does not use would
 * leave a user's explicit "Run Now" sitting until an unrelated agent finished.
 *
 * Both engines call this once per cycle and then skip the ids it returns in
 * their own loop, so a request drained here is handled exactly once whichever
 * engine gets there first (the request is cleared before the handler runs).
 * Returning the ids rather than re-testing the task type keeps the engines from
 * importing the handler registry statically — see server/AGENTS.md's import
 * scoping rule — and covers requests the drain cleared WITHOUT running (the
 * type was disabled, or Improve is off), which must not fall through either.
 *
 * `force: true` — a manual Run is explicit consent for THIS work, so the run
 * ignores the shared in-flight cooldown that stops the burn rotation re-picking
 * rows whose render hasn't landed yet. `context` is deliberately omitted: with
 * no probe to reuse, `run` does its own scan, which is the contract's
 * `context: undefined` path.
 *
 * Returns the ids of the requests it took responsibility for. Never throws —
 * `runScheduledHandler` converts a handler throw into a non-dispatch, and this
 * runs outside the request lifecycle.
 */
export async function drainProgrammaticOnDemandRequests({ taskScheduleMod, requests, schedule, state }) {
  const handled = new Set();
  const pending = (requests || []).filter((request) => isProgrammaticScheduledTaskType(request.taskType));
  if (pending.length === 0) return handled;

  const { runScheduledHandler } = await import('./scheduledHandlers/index.js');
  for (const request of pending) {
    const taskConfig = schedule?.tasks?.[request.taskType];
    handled.add(request.id);
    if (request.taskType !== 'development-watchdog' && !isImprovementEnabled(state)) {
      emitLog('warn', `On-demand request dropped — improvement is disabled (Config → Improve)`, { requestId: request.id, taskType: request.taskType });
      await taskScheduleMod.clearOnDemandRequest(request.id);
      continue;
    }
    // Match the agent drain: manual runs bypass cadence, never task removal.
    if (!taskConfig || (!isManualOnDemandRequest(request) && !taskConfig.enabled)) {
      emitLog('info', `On-demand request skipped — task type '${request.taskType}' is disabled`, { requestId: request.id });
      await taskScheduleMod.clearOnDemandRequest(request.id);
      continue;
    }

    // CLAIM the request, and only run if this drain is the one that took it.
    // The two engines are independent and each drains its own snapshot, so both
    // can hold the same request; `clearOnDemandRequest` is a serialized
    // read-modify-write that returns the record only to the caller that removed
    // it, and returns null to the loser. Without this check one "Run Now" would
    // spend two describe/render batches and toast twice. Agent preparation
    // takes the same claim before any preflight work; task-store deduplication
    // alone happens too late to protect either lane's preparation.
    const claimed = await taskScheduleMod.clearOnDemandRequest(request.id);
    if (!claimed) continue;

    await taskScheduleMod.recordExecution(`task:${request.taskType}`);
    const outcome = await runScheduledHandler({
      taskType: request.taskType,
      params: taskConfig.taskMetadata || {},
      job: { model: taskConfig.model || null, effort: taskConfig.effort || null, providerId: taskConfig.providerId || null },
      force: true,
    });

    emitLog(outcome?.dispatched ? 'info' : 'debug',
      `${request.taskType}: ${outcome?.summary || outcome?.reason || 'nothing to do'}`,
      { requestId: request.id });
    // The client toasts this so an explicit Run isn't a silent no-op. Separate
    // from `schedule:on-demand-empty`: that channel means "no agent task was
    // produced", while this one reports work PortOS already finished.
    cosEvents.emit('schedule:on-demand-handled', {
      requestId: request.id,
      taskType: request.taskType,
      dispatched: outcome?.dispatched === true,
      summary: outcome?.summary || null,
      reason: outcome?.reason || null,
    });
  }
  return handled;
}

/**
 * Surface WHY a user-initiated on-demand "Run" produced no task, so the trigger
 * isn't a silent no-op the user only discovers in the pm2 logs. Emits
 * `schedule:on-demand-empty` (which the client toasts) with an `outcome`:
 *   - 'parked'    → a detector-driven task re-checked and found no actionable work;
 *                   carries the reason + open/in-flight/filtered breakdown.
 *   - 'transient' → a detector-driven task that did NOT park — a gh/glab probe
 *                   failure — so the check didn't actually complete. Carries a
 *                   `forge` block naming the real fault when the CLI is broken
 *                   in a way that will NOT clear on its own.
 *   - 'idle'      → a non-perpetual task produced no task: a genuine "nothing to
 *                   do", NOT a failure (e.g. pr-watcher with no new PRs).
 *
 * Called from the shared on-demand drain (onDemandDrain.js), which both
 * Priority-0 engines delegate to, so a user Run gets the same feedback no matter
 * which one drains the request. `taskConfig` is the already-loaded interval for the task,
 * passed in to avoid re-reading the schedule. The event fires ONLY on the
 * user-initiated on-demand path, so the client can toast it without
 * background-park noise.
 *
 * `skip` is the `skip` field of the prepareManagedAppImprovementTask result
 * that produced no task (null when the caller had none, e.g. a global task): it
 * carries pr-reviewer's preflight reason and the transient detector verdict
 * (`cli` / `remedy`) that the outcome classification below explains.
 */
export async function emitOnDemandEmpty({ taskScheduleMod, request, targetApp, taskConfig, preflightCardId = null, skip = null }) {
  const appId = targetApp?.id || null;
  const parkInfo = await taskScheduleMod.getPerpetualParkInfo(request.taskType, appId).catch(() => null);
  const isDetectorDriven = taskConfig?.perpetual === true || request.taskType === 'branch-reconcile';
  const outcome = skip?.gate === 'reviewer-identity'
    ? 'transient'
    : parkInfo ? 'parked' : (isDetectorDriven ? 'transient' : 'idle');

  // Layered Intelligence skips (e.g. a provider that can't drive an agent) record
  // an actionable last-run reason. Surface it so a manual "Run" toasts WHY it
  // produced nothing (e.g. "pick a CLI/TUI provider") instead of a misleading
  // generic "nothing to do". Read the freshest record — the skip's recordRun
  // landed after `targetApp` was loaded. Best-effort; a read failure just omits it.
  let reason = null;
  if (skip?.gate === 'reviewer-identity') reason = skip.reason;
  if (outcome === 'idle' && appId && request.taskType === 'layered-intelligence') {
    const { getAppById } = await import('./apps.js');
    const app = await getAppById(appId).catch(() => null);
    reason = app?.layeredIntelligence?.lastRunReason || null;
  }
  if (outcome === 'idle' && request.taskType === 'pr-reviewer') {
    reason = skip?.gate === 'security-preflight' ? skip.reason : null;
  }
  // error-log-triage never produces an agent task of its own — its pass IS the
  // run — so toast what that pass did instead of "nothing to do".
  if (outcome === 'idle' && request.taskType === 'error-log-triage') {
    const { readLastTriageSummary } = await import('./errorLogTriage.js');
    reason = await readLastTriageSummary().catch(() => null);
  }

  // 'transient' says "the forge probe failed, try again shortly" — only true when
  // the forge is momentarily flaky. A gh that is missing, unauthenticated, or
  // blocked by an outbound firewall fails EVERY tick forever, so that advice sends
  // the user in circles. Ask the CLI the detector actually ran (recorded by the
  // work gate on `skip` — the task-type NAME can't answer this: `claim-work`
  // resolves its forge internally, and branch-reconcile goes transient over
  // git/provider faults with no forge involved) whether it is broken in a
  // way that won't self-clear, and pass the remedy through. No verdict, an
  // unprobeable CLI, or a healthy one all leave `forge` null and keep the
  // generic copy — the failure really was a blip, or at least not one we can name.
  let forge = skip?.gate === 'reviewer-identity'
    ? { cli: 'reviewer identity', remedy: skip.reason }
    : null;
  const verdict = outcome === 'transient' && skip?.gate === 'perpetual-work' ? skip : null;
  if (verdict?.remedy) {
    // The detector already knew the fault AND the way out — a per-repo permission
    // the token lacks (e.g. the collaborators/members list behind the "Me +
    // collaborators" author gate). checkGhHealth can't see that: it probes global
    // auth, which such a token passes, so asking it here would drop the remedy and
    // fall back to "try again shortly" — the exact dead end this channel exists to
    // avoid.
    forge = { cli: verdict.cli, remedy: verdict.remedy };
  } else if (verdict?.cli === 'gh') {
    const { checkGhHealth } = await import('./github.js');
    const health = await checkGhHealth().catch(() => null);
    if (health && !health.ok && health.remedy) forge = { cli: 'gh', remedy: health.remedy };
  }

  // Close the run's card — or, for an automated run that never opened one, mint
  // it in its terminal state. A preflight has no agent lifecycle, but an
  // explicit failure still needs a durable record: terminal status prevents
  // either spawn engine from running this diagnostic as a task, and a retry has
  // to enter through the security scan again. The PR row paints from the
  // `preflightFailure` + `note` this stamps.
  const securityFailure = request.taskType === 'pr-reviewer' && appId
    && reason?.startsWith('security-') && reason !== 'security-scan-report-pending';
  const { finishPreflightCard, recordPreflightOutcome } = await import('./preflightTaskCard.js');
  if (securityFailure) {
    // Minted when absent: an automated cadence run reaches the same failure with
    // no card to close, and it needs the record just as much.
    await recordPreflightOutcome({
      requestId: request.id,
      taskType: request.taskType,
      appId,
      appName: targetApp?.name || null,
      targetPullRequest: request.targetPullRequest ?? null,
      outcome: 'failed',
      reason,
      note: `PR review stopped before an agent started (${reason}). No PR actions were taken. `
        + (reason.startsWith('security-guard-')
          ? 'Open Models → LLMs → Abuse Guard, check its setup and repair it if needed, then retry PR review. The classifier did not return a usable safety verdict; this is not a finding against the PR.'
          : 'Check the repository connection and security scan configuration, then retry PR review.'),
    });
  } else {
    // An ordinary empty outcome — parked, transient, plain nothing to do. Only
    // ever closes a card that already exists: minting one for an automated run
    // nobody is watching would fill the Tasks page with cadence noise.
    await finishPreflightCard(preflightCardId, {
      outcome: 'nothing-to-do',
      reason: reason || parkInfo?.parkReason || outcome,
    });
  }

  // A park is a drain brake, not a promise of another automatic run. Read the
  // actual eligibility, including per-app cadence/enablement and manual-only
  // drains, rather than interpreting the stored park deadline as a schedule.
  const readiness = parkInfo
    ? await taskScheduleMod.shouldRunTask(request.taskType, appId).catch(() => null)
    : null;
  const nextAutoRecheckAt = readiness?.nextRunAt || (readiness?.shouldRun ? new Date().toISOString() : null);

  cosEvents.emit('schedule:on-demand-empty', {
    requestId: request.id,
    taskType: request.taskType,
    appId,
    appName: targetApp?.name || null,
    outcome,
    reason,
    forge,
    parkReason: parkInfo?.parkReason || null,
    parkedUntil: parkInfo?.parkedUntil || null,
    nextAutoRecheckAt,
    actionableCount: parkInfo?.parkActionableCount ?? null,
    counts: parkInfo?.parkCounts || null,
    skipCauses: parkInfo?.parkSkipCauses || null
  });
}

/**
 * Assemble the base improvement-task metadata and layer the sanitized global
 * (schedule interval) + per-app taskMetadata overrides on top. `appOverride` is
 * this app's stored entry for `taskType` (loaded once by the caller, which also
 * reads its provider/model pin). Per-app strips
 * managed-agent fields first (see the sibling generateManagedAppTask path for
 * the rationale). Pure assembly — no gating, no early return.
 */
function buildImprovementTaskMetadata(taskType, app, interval, taskSchedule, appOverride) {
  const metadata = {
    app: app.id,
    appName: app.name,
    repoPath: app.repoPath,
    analysisType: taskType,
    autoGenerated: true,
    comprehensiveImprovement: true
  };

  // Apply sanitized task-type-specific metadata from schedule config (e.g., useWorktree, simplify, pipeline)
  const sanitizedGlobalMeta = sanitizeTaskMetadata(interval.taskMetadata);
  if (sanitizedGlobalMeta) {
    Object.assign(metadata, sanitizedGlobalMeta);
  }

  // Apply sanitized per-app taskMetadata overrides (merge on top of global).
  const strippedAppOverride = taskSchedule.stripManagedAgentOptionsFromOverride(
    taskType, appOverride?.taskMetadata
  );
  const sanitizedAppMeta = sanitizeTaskMetadata(strippedAppOverride);
  if (sanitizedAppMeta) {
    Object.assign(metadata, sanitizedAppMeta);
  }

  // Derive the marker from the task type as well as the shipped schedule
  // metadata. This keeps pre-migration/custom schedule records from losing the
  // claim-owned lifecycle when they still carry the legacy false/false flags.
  // Do this after schedule and app overrides so the claim contract cannot be
  // disabled by stale or malformed metadata.
  if (CLAIM_FLOW_TASK_TYPES.has(taskType)) metadata.claimFlow = true;

  return metadata;
}

/**
 * The dispatch-side half of audit applicability (see `resolveAuditApplicability`).
 * A detection failure never blocks work — the gate only removes what it has
 * evidence against.
 *
 * @returns {Promise<boolean>} true when the dispatch must be skipped
 */
async function skipInapplicableAudit(app, taskType, taskSchedule) {
  const { resolveAuditApplicability } = await import('./appQualitySchedule.js');
  const verdict = await resolveAuditApplicability(app, taskType).catch((err) => {
    emitLog('warn', `Audit applicability check failed for ${taskType}/${app.name}: ${err.message}`, { appId: app.id, analysisType: taskType });
    return { applicable: true, reason: null };
  });
  if (verdict.applicable) return false;
  emitLog('info', `⏭️ Skipping ${taskType} for ${app.name}: not applicable — ${verdict.reason}`, { appId: app.id, analysisType: taskType });
  await taskSchedule.recordExecution(taskType, app.id);
  return true;
}

/**
 * Run a task type's registered buildTaskInput hook (taskTypeHooks.js) for
 * deterministic pre-agent data collection. Returns `{ skip: true }` when the
 * hook opts out (execution recorded so cadence advances), otherwise
 * `{ skip: false, hookPrompt, hookOverride, hookMetadata }` — the hook may fully
 * own the rendered prompt, pin the app's per-app provider/model, and hand back a
 * metadata bag to stamp onto the created task.
 *
 * `hookMetadata` is normalized to null unless the hook returned a real object,
 * so the caller's "stamp it" check can't be tripped by a stray primitive.
 */
export async function resolveTaskInputHook(app, taskType, taskSchedule, { ignoreTaskId = null } = {}) {
  const { getTaskInputHook } = await import('./taskTypeHooks.js');
  const inputHook = await getTaskInputHook(taskType);
  if (!inputHook) return { skip: false, hookPrompt: null, hookOverride: {}, hookMetadata: null };
  const interval = taskType === 'issue-watcher' ? await taskSchedule.getTaskInterval(taskType) : undefined;
  const input = await inputHook({ app, taskType, ignoreTaskId, ...(interval ? { interval } : {}) }).catch((err) => {
    emitLog('warn', `buildTaskInput hook failed for ${taskType}/${app.name}: ${err.message}`, { appId: app.id, analysisType: taskType });
    return { skip: { reason: 'input-hook-error' } };
  });
  if (input?.skip) {
    emitLog('info', `Skipping ${taskType} for ${app.name}: ${input.skip.reason}`, { appId: app.id, analysisType: taskType });
    await taskSchedule.recordExecution(taskType, app.id);
    return { skip: true };
  }
  return {
    skip: false,
    hookPrompt: input?.prompt || null,
    hookOverride: { providerId: input?.providerId || null, model: input?.model || null },
    hookMetadata: isPlainObject(input?.hookMetadata) ? input.hookMetadata : null
  };
}

/**
 * claim-work single-source router: resolve the app's workTracker (default
 * 'auto' → git origin host) and delegate to the concrete claim flow. Mutates
 * `metadata` with the delegated flow's isolation posture (useWorktree/openPR)
 * and returns the resolved promptTaskType (=== taskType for every
 * non-claim-work type). The hook stays even though all four concrete claim
 * prompts self-manage worktree+PR, so a future delegated type carrying a
 * CoS-managed DEFAULT_TASK_INTERVALS entry would have its posture applied.
 */
async function resolveClaimWorkRouting(app, taskType, metadata, taskSchedule) {
  if (taskType !== 'claim-work') return taskType;
  metadata.claimFlow = true;
  const { resolveAppWorkTracker, trackerToClaimTaskType } = await import('../lib/workTracker.js');
  const wt = await resolveAppWorkTracker(app);
  const promptTaskType = trackerToClaimTaskType(wt.resolved) || 'plan-task';
  emitLog('info', `claim-work for ${app.name}: tracker=${wt.resolved} (${wt.source}) → ${promptTaskType}`, { appId: app.id, analysisType: taskType });
  const delegatedMeta = taskSchedule.DEFAULT_TASK_INTERVALS[promptTaskType]?.taskMetadata;
  if (delegatedMeta) {
    if ('useWorktree' in delegatedMeta) metadata.useWorktree = delegatedMeta.useWorktree;
    if ('openPR' in delegatedMeta) metadata.openPR = delegatedMeta.openPR;
  }
  return promptTaskType;
}

/**
 * Perpetual (drain-until-done) work-detector gate. For a task type running on
 * the 'perpetual' interval — excluding branch-/issue-reconcile, whose own scan
 * IS the detector — a programmatic detector decides whether there's anything to
 * claim BEFORE building the (expensive) prompt or burning an agent:
 *   - actionable → stamp metadata.perpetual (skip cooldown), proceed;
 *   - unchanged actionable set → PARK after a successful no-progress run;
 *   - idle (definitive) → PARK on the recheck cadence, skip;
 *   - transient probe failure → skip WITHOUT parking so the next tick retries.
 * The detector keys on the RESOLVED promptTaskType. Returns `{ skip, verdict,
 * spendDispatch, signature }` — `verdict` (`{ cli, reason, remedy, detail }`) is
 * set only on the transient skip, so the caller can hand the reason to the
 * user-facing "Run" toast — and mutates `metadata.perpetual` on the actionable path.
 *
 * `spendDispatch` is the caller's cue to call `recordPerpetualDispatch` (which
 * clears the park and spends one unit of the type's `drainDispatchCap` budget in a
 * single write) — deliberately NOT done here. Gates that run AFTER this one can
 * still return null with no agent ever spawned (`applyPlanIdMetadata` skips
 * plan-task when every unchecked item is in-flight or blocked), and charging the
 * budget for a task that was never created would exhaust a capped drain on
 * evaluations alone, parking it for `drain-cap` without a single dispatch.
 */
async function applyPerpetualWorkGate(app, taskType, promptTaskType, metadata, interval, taskSchedule, { ignoreTaskId = null } = {}) {
  // The reconcile drains run their own scan-driven gate (the blocks in
  // cosTaskPreStepBlocks), so they opt out of the generic work detector.
  if (interval.perpetual !== true || isReconcileDrainTaskType(taskType)) {
    return { skip: false };
  }
  const { detectActionableWork } = await import('./perpetualWork.js');
  const detection = await detectActionableWork(promptTaskType, app, {
    issueAuthorFilter: metadata.issueAuthorFilter || 'self',
    issueExcludeLabels: metadata.issueExcludeLabels || [],
    // A detector that counts in-flight work must skip the task whose completion
    // triggered this refill — it is already recorded, just not yet marked done.
    ignoreTaskId
  });
  if (detection.actionable) {
    // A probe that reports actionable work is, by definition, not stuck — clear
    // both the transient streak and any persisted stall diagnostic before
    // deciding whether THIS evaluation dispatches or parks on no-progress.
    clearTransientProbeStreak(taskType, app.id);
    await taskSchedule.recordPerpetualStall(taskType, app.id, null);
    // A successful claim/plan agent can still return without changing forge or
    // PLAN state (for example, it decides not to pick the advertised item). The
    // completion refill would otherwise dispatch the same candidate forever.
    // The detector's signature covers the complete set; `items` is capped for
    // the picker and is not sufficient for convergence.
    const drainSignature = detection.signature == null
      ? null
      : JSON.stringify({ taskType: promptTaskType, candidates: detection.signature });
    if (drainSignature != null) {
      const { signature: lastSignature, dispatchCount } = await taskSchedule.getPerpetualDrainState(taskType, app.id);
      if (shouldParkUnchangedPerpetualWork({ ...detection, signature: drainSignature }, lastSignature, dispatchCount)) {
        const counts = detection.total != null
          ? { open: detection.total, inFlight: detection.inFlightCount ?? 0, filtered: detection.filteredCount ?? 0 }
          : null;
        await taskSchedule.parkPerpetual(taskType, app.id, {
          reason: 'no-progress',
          actionableCount: detection.count,
          counts,
          signature: null
        });
        emitLog('info', `Perpetual ${taskType} parked for ${app.name}: actionable work unchanged after the last run`, { appId: app.id });
        return { skip: true };
      }
    }
    metadata.perpetual = true;
    // The dispatch is SPENT BY THE CALLER, once a task is certain — see the note
    // on `spendDispatch` in the JSDoc above.
    return { skip: false, spendDispatch: true, signature: drainSignature };
  }
  if (detection.transient) {
    // Record BEFORE logging, so the log line (and the escalation decision) can
    // report which consecutive occurrence this is. A single blip stays at
    // `debug` (suppressed on a default install); once the SAME probe has failed
    // PERPETUAL_TRANSIENT_ESCALATION_THRESHOLD evaluations in a row, escalate to
    // `warn` (reaches the console and the cos:log stream) and persist the
    // stalled verdict — otherwise a perpetual drain whose forge CLI is broken
    // produces zero console output, zero persisted state, and zero UI signal,
    // indefinitely (#7551).
    const verdict = {
      cli: detection.cli || null, reason: detection.reason, remedy: detection.remedy || null, detail: detection.detail || null
    };
    const consecutive = noteTransientProbe(taskType, app.id);
    const detailSuffix = detection.detail ? ` — ${detection.detail}` : '';
    const escalated = consecutive >= PERPETUAL_TRANSIENT_ESCALATION_THRESHOLD;
    emitLog(escalated ? 'warn' : 'debug',
      `Perpetual ${taskType} skip for ${app.name} (transient: ${detection.reason}${detailSuffix}, ${consecutive} consecutive)`,
      { appId: app.id, consecutive });
    // The skip is silent by design at low counts (the next tick retries), but an
    // explicit user "Run" ends here too — return which CLI failed (`verdict`) so
    // emitOnDemandEmpty can tell the difference between a blip and a forge that
    // is broken for good, plus any remedy the detector already named (a
    // permission the token lacks, which no amount of retrying fixes).
    if (escalated) {
      await taskSchedule.recordPerpetualStall(taskType, app.id, {
        cli: detection.cli || null, reason: detection.reason, detail: detection.detail || null, consecutive
      });
    }
    return { skip: true, verdict };
  }
  clearTransientProbeStreak(taskType, app.id);
  await taskSchedule.recordPerpetualStall(taskType, app.id, null);
  // Carry the detector's open/in-flight/filtered breakdown into the park so an
  // explicit "Run" can explain WHY a non-empty queue yielded no work.
  const counts = detection.total != null
    ? { open: detection.total, inFlight: detection.inFlightCount ?? 0, filtered: detection.filteredCount ?? 0 }
    : null;
  // Per-cause skip attribution for the same question at one level deeper: not
  // just "78 filtered" but "49 needs-input, 17 blocked, …". Only the claim
  // detectors report it; every other park shape keeps the field absent.
  // parkPerpetual's own log line renders the summary (it is the single choke
  // point every park flows through), so this one stays bare.
  const skipCauses = detection.skipCauses ?? null;
  // Terminal park — parkPerpetual zeroes the dispatch budget in the same write, so
  // the next drain window starts fresh instead of capping early on this one's spend.
  await taskSchedule.parkPerpetual(taskType, app.id, { reason: detection.reason, actionableCount: detection.count, counts, skipCauses, signature: null });
  emitLog('info', `Perpetual ${taskType} parked for ${app.name}: ${detection.reason}`, { appId: app.id });
  return { skip: true };
}

/**
 * user-action-review's `{userActionDelivery}` block: the operator's
 * `fileIssues` choice decides HOW proposals leave the run — filed tracker
 * issues (default) or queued CoS tasks. Resolved at dispatch, like the audit
 * mode contract, so a customized stored prompt still honors the toggle. The
 * type is not in the audit catalog (its "do work" alternative is queueing
 * tasks, not editing code), so the audit mode wrapper does not apply to it.
 */
export function resolveUserActionDeliveryBlock(taskType, metadata) {
  if (taskType !== 'user-action-review') return '';
  return metadata?.fileIssues === false || metadata?.fileIssues === 'false'
    ? 'Deliver each accepted proposal as a QUEUED CoS TASK (`POST /api/cos/tasks`, one bounded task per proposal, priority LOW unless the evidence is severe) — the operator turned off file-issues mode for this schedule. Do not file tracker issues.'
    : 'Deliver each accepted proposal as a FILED TRACKER ISSUE in the PortOS repository (`gh issue create` with the `plan` label; create the label first if missing). This is file-issues mode, the default. Do not queue CoS tasks.';
}

/**
 * Render the delivery posture into a user-action-review prompt. Mirrors
 * `applyAuditModeWrapper`: a customized stored prompt that dropped the
 * `{userActionDelivery}` token still gets the operator's choice PREPENDED —
 * otherwise flipping fileIssues would be a silent no-op on that install.
 */
export function applyUserActionDeliveryMode(promptTemplate, taskType, metadata) {
  const prompt = typeof promptTemplate === 'string' ? promptTemplate : '';
  const block = resolveUserActionDeliveryBlock(taskType, metadata);
  if (!block) return prompt;
  return renderOrPrependSection(prompt, '{userActionDelivery}', 'Delivery mode', block);
}

/**
 * Render leftover-branch detector findings into a user-action-review prompt.
 * A customized stored prompt that dropped `{userActionDetectors}` still gets
 * the section PREPENDED — otherwise the detector would be a silent no-op.
 */
export async function applyUserActionDetectorSection(promptTemplate, taskType) {
  if (taskType !== 'user-action-review') return typeof promptTemplate === 'string' ? promptTemplate : '';
  const prompt = typeof promptTemplate === 'string' ? promptTemplate : '';
  const findings = await detectIdleLeftoverBranches().catch((error) => {
    console.error(`❌ user-action-review detector interpolation failed: ${error.message}`);
    return [];
  });
  const block = formatUserActionDetectorBlock(findings) || 'No leftover-branch findings.';
  return renderOrPrependSection(prompt, '{userActionDetectors}', 'Detectors', block);
}


const EMPTY_PROVIDER_PIN = Object.freeze({ providerId: null, model: null });

/**
 * The app's per-app provider/model pin for this task type, as an overlay to apply
 * over the global Schedule pin. Runs the shared harness guard
 * (`resolveAgentProviderPin`) so an api-typed per-app pin — which has no
 * file-writing harness and could only ever fail at spawn — falls back to the
 * Schedule pin rather than reaching the agent.
 *
 * Returns an EMPTY overlay when nothing resolvable is harness-capable: the
 * Schedule pin then stands untouched and agentProviderResolution reports its
 * actionable permanent error, which beats silently rerouting the run onto a
 * provider the user never chose.
 */
async function resolveAppProviderPin({ app, taskType, appOverride, interval }) {
  if (!appOverride?.providerId && !appOverride?.model) return EMPTY_PROVIDER_PIN;
  const { providerId, model, skipReason } = await resolveAgentProviderPin({
    appPin: { providerId: appOverride.providerId || null, model: appOverride.model ?? null },
    readSchedulePin: () => interval,
    taskType,
    appName: app.name
  });
  return skipReason ? EMPTY_PROVIDER_PIN : { providerId, model };
}

/**
 * Layer the provider/model/effort pins onto `metadata`, least specific first:
 * the global schedule interval, then the app's own per-app pin, then a
 * buildTaskInput hook's fully-resolved choice, then an explicit per-request
 * override (the Pull Requests tab's "Run with" picker on one on-demand run). A
 * model is only ever pinned when explicitly configured — otherwise it stays
 * unset so selectModelForTask resolves the active provider's tier/default
 * model at spawn time (see the note in generateSelfImprovementTaskForType).
 */
function applyOneProviderPin(metadata, pin) {
  // A model pinned with no provider REFINES the layer below (the user picked a
  // model for the provider that layer resolved), so it applies on its own.
  if (!pin?.providerId) {
    if (pin?.model) metadata.model = pin.model;
    return;
  }
  metadata.provider = pin.providerId;
  metadata.providerId = pin.providerId;
  // A model is PROVIDER-SCOPED: one chosen for the layer below is not something
  // the provider that just replaced it can necessarily run, and
  // agentProviderResolution honors an explicit `metadata.model` as a CLI
  // pass-through rather than dropping it — so a leaked model ships to the wrong
  // CLI (`claude --model gemini-…`) and fails on every retry until the task
  // blocks. Take this layer's model, or none and let selectModelForTask resolve
  // the new provider's own default.
  if (pin.model) metadata.model = pin.model;
  else delete metadata.model;
}

function applyProviderModelPins(metadata, interval, appPin, hookOverride, requestOverride) {
  // Least specific first: the task's global Schedule pin. Then the app's own
  // per-app pin, which is the more specific choice — honored for EVERY task type
  // (#4783), not just the one whose buildTaskInput hook read it. Then a
  // buildTaskInput hook's fully-resolved choice, which wins outright.
  applyOneProviderPin(metadata, { providerId: interval.providerId || null, model: interval.model || null });
  if (interval.effort) {
    metadata.effort = interval.effort;
  }
  applyOneProviderPin(metadata, appPin);
  applyOneProviderPin(metadata, hookOverride);
  // A pipeline's current stage is more specific than the whole-task defaults.
  // Stage 0 may already have advanced through a server-owned preflight.
  const stage = metadata.pipeline?.stages?.[metadata.pipeline.currentStage ?? 0];
  if (stage) {
    applyOneProviderPin(metadata, stage);
    if (stage.providerId) delete metadata.effort;
    if (stage.effort) metadata.effort = stage.effort;
  }
  // Most specific: an explicit per-request pin (e.g. one "PR review" click from
  // the Pull Requests tab), applied last so it wins over every configured pin
  // above. A public-review posture still gates the final provider to its own
  // eligible set at spawn time (resolveAgentProviderAndModel). An unsupported
  // pin blocks instead of granting permission to spend on another provider.
  applyOneProviderPin(metadata, { providerId: requestOverride?.provider || null, model: requestOverride?.model || null });
  if (requestOverride?.effort) {
    metadata.effort = requestOverride.effort;
  }
}

// The one "nothing to build" result of prepareManagedAppImprovementTask — every
// skip exit returns this, so the one-shape rule is enforced in one place and the
// reason for the skip travels with the answer instead of through a side channel.
const skipped = (gate, { reason = null, cli = null, remedy = null, detail = null } = {}) =>
  ({ task: null, pendingPerpetualDispatch: null, skip: { gate, reason, cli, remedy, detail } });

/**
 * Decide whether a managed-app improvement task should be generated for
 * `taskType`, and build it if so. Never records a perpetual-drain dispatch —
 * that is returned as `pendingPerpetualDispatch` (`null`, or
 * `{ taskType, appId, signature }`) alongside the task, so the caller can
 * record it (via `recordDeferredPerpetualDispatch`) at whatever point the
 * task's admission is certain. The queue, on-demand, and idle-review paths call
 * this function directly and defer the record until their own spawn-engine
 * admission succeeds (#6871).
 *
 * Always resolves to ONE shape, `{ task, pendingPerpetualDispatch, skip }`:
 * `skip` is `null` when a task was built, otherwise
 * `{ gate, reason, cli, remedy, detail }` (built by `skipped`) naming the exit
 * that declined — `reason`/`cli`/`remedy`/`detail` are the operator-facing
 * detail where the gate has one (pr-reviewer's security preflight, the transient
 * work-detector verdict, the plan gate), null otherwise.
 *
 * @returns {Promise<{ task: Object|null, pendingPerpetualDispatch: Object|null, skip: { gate: string, reason: string|null, cli: string|null, remedy: string|null, detail: string|null }|null }>}
 */
export async function prepareManagedAppImprovementTask(taskType, app, state, {
  skipPreconditions = false,
  ignoreTaskId = null,
  // An on-demand request this call is serving (a user Run, a quota-burn or
  // maintenance step), whichever lane picked it up. Exempts it from the
  // scheduled lane's audit-applicability gate.
  onDemand = false,
  targetPullRequest = null,
  // Per-request provider/model/effort pin — see applyProviderModelPins.
  providerOverride = null,
  runOverrides = null,
  // The user's programmatic-phase card, when a human triggered this run. The
  // deterministic pre-agent work reports its progress into it.
  preflightCardId = null
} = {}) {
  const { updateAppActivity } = await import('./appActivity.js');
  const taskSchedule = await import('./taskSchedule.js');
  const { getTaskPrompt, getStagePrompt } = await import('./taskPromptService.js');

  // Also protect requests queued before the target-scope gate was installed.
  if (requiresInstallWideTarget(taskType)) return skipped('install-wide-target');

  // NOTE: `updateAppActivity` + the "Generating improvement task" log are
  // intentionally deferred until AFTER every gate returns non-null (see end
  // of function). The original code stamped both eagerly, which was tolerable
  // when only the on-demand path called this — the user explicitly asked for
  // a task, so logging + rotation-pointer advance was correct even when the
  // generator decided not to produce one. Now `queueEligibleImprovementTasks`
  // routes through this every scheduler tick, so an eager update would (a)
  // advance the per-app rotation pointer on every skip (biasing
  // `getNextTaskType` away from a type with nothing actionable to do, but
  // also away from types that *could* run on a future tick) and (b) emit a
  // misleading "Generating improvement task" line for skipped types. The
  // single-call ordering at the bottom keeps both paths in sync — a returned
  // task means rotation advanced; a `skipped(...)` short-circuit means it
  // didn't.

  // Get interval settings to determine provider/model and pipeline config.
  // The per-app override entry is loaded ONCE here: it carries both the
  // taskMetadata merged below and the provider/model pin applied further down.
  const [interval, appOverrides] = await Promise.all([
    taskSchedule.getTaskInterval(taskType),
    getAppTaskTypeOverrides(app.id)
  ]);
  const appOverride = appOverrides[taskType] || null;
  const metadata = buildImprovementTaskMetadata(taskType, app, interval, taskSchedule, appOverride);

  // Per-INVOCATION run parameters, layered on top of the schedule + per-app
  // metadata the task saved. A quota-burn step is the caller that needs them: a
  // step migrated from an issues-only burn preset pins `fileIssues: true`
  // explicitly, so it keeps filing even against an audit type whose shipped
  // scheduled default is `false` — migration must never silently turn an
  // issues-only burn into code-writing work.
  //
  // It has to land HERE, before the mode decision and the prompt render below.
  // The post-generation stamp both on-demand engines apply
  // (`onDemandRequestMetadata`) is far too late: by then the banner is chosen
  // and the description is built, so a `fileIssues` arriving there would flip
  // the flag while the agent still read a "fix and commit" prompt.
  //
  // Sanitized through the SAME allowlist the schedule and per-app overrides
  // pass, so an invocation can carry nothing a stored override could not.
  const sanitizedRunMeta = sanitizeTaskMetadata(runOverrides);
  if (sanitizedRunMeta) Object.assign(metadata, sanitizedRunMeta);
  Object.assign(metadata, newAuditMetadata(metadata));

  // Audit applicability bail-out — before preflights or a spawn slot. On the
  // SCHEDULED lane, a quality audit this repository cannot have findings for (a
  // mobile audit of a pure API, an infrastructure audit of a repo with no
  // deployment config) is skipped with a logged reason instead of paying a
  // provider call to be told "not applicable"; execution is recorded so the
  // cadence advances. An on-demand request is not gated here — whether the
  // drain or idle review serves it: a manual Run is an explicit choice, and the
  // automated on-demand callers (maintenance runs, quota-burn steps) gate in
  // `resolveQuotaBurnStep` before they queue. `runInapplicableAudit` is the
  // user's recorded override from the schedule form.
  if (!skipPreconditions && !onDemand && isAuditTaskType(taskType) && metadata.runInapplicableAudit !== true
    && await skipInapplicableAudit(app, taskType, taskSchedule)) return skipped('audit-inapplicable');

  if (taskType === 'pr-reviewer') ensurePrReviewerPipeline(metadata);
  initializePipelineMetadata(metadata);
  const { preflightReporter } = await import('./preflightTaskCard.js');
  const securityPreflight = await runPrReviewerSecurityPreflight(taskType, app, metadata, targetPullRequest, taskSchedule, {
    progress: preflightReporter(preflightCardId),
  });
  // The preflight's reason rides the skip result to emitOnDemandEmpty, so a user
  // "Run" of pr-reviewer that hits the security guard toasts WHY.
  if (securityPreflight.skipped) return skipped('security-preflight', { reason: securityPreflight.reason || null });
  if (!skipPreconditions && shouldSkipForPrecondition(metadata, app, taskType)) return skipped('precondition');

  // Programmatic-I/O input hook. A task type may register a buildTaskInput hook
  // (taskTypeHooks.js) that does deterministic pre-agent data collection and
  // fully OWNS its prompt. `hookOverride` may pin the app's per-app
  // provider/model — captured here but APPLIED AFTER the global-interval
  // provider/model block below, so the per-app choice wins.
  // `ignoreTaskId` reaches the hook because a drain-on-completion refill runs
  // while the completing task is still `in_progress` on disk — a hook that
  // counts in-flight tasks against a budget must not count the run that just
  // finished and already recorded itself (#3179).
      const inputHook = await resolveTaskInputHook(app, taskType, taskSchedule, { ignoreTaskId });
  if (inputHook.skip) return skipped('input-hook');
  const { hookPrompt, hookOverride, hookMetadata } = inputHook;

  // claim-work single-source router: `taskType` stays 'claim-work' for
  // interval/cadence/recording; `promptTaskType` drives prompt selection, PLAN
  // gating, and the forge-specific author-filter directive below.
  const promptTaskType = await resolveClaimWorkRouting(app, taskType, metadata, taskSchedule);

  // Consecutive-dispatch cap for EVERY perpetual drain (#3848). First, because a
  // capped drain must not pay for a work-detector probe or a reconcile git/gh scan
  // it is only going to discard.
  const drainCap = await applyPerpetualDrainCap(app, taskType, interval, taskSchedule, { onDemand });
  if (drainCap.skip) return skipped('drain-cap');

  // Perpetual (drain-until-done) gate — probes for actionable work before
  // building the prompt or burning an agent (branch-/issue-reconcile self-gate
  // in their own blocks, so this excludes them).
  const perpetualGate = await applyPerpetualWorkGate(app, taskType, promptTaskType, metadata, interval, taskSchedule, { ignoreTaskId });
  if (perpetualGate.skip) return skipped('perpetual-work', perpetualGate.verdict);

  // branch-reconcile: deterministic git/gh pre-step that carries the actionable
  // in-flight set into the prompt via {inFlightBranches}.
  const branchReconcile = await resolveBranchReconcileBlock(app, taskType, metadata, taskSchedule);
  if (branchReconcile.skip) return skipped('branch-reconcile');
  const inFlightBranchesBlock = branchReconcile.block;

  // repo-sync: deterministic git pre-step that syncs this app's checkout with
  // origin and carries whatever it refused to do into the prompt via
  // {repoSyncReport}. (The install-wide sweep runs from the global lane —
  // generateSelfImprovementTaskForType — which is what "Run Now" with no app
  // triggers; this branch covers a run scoped to one app.)
  const repoSync = await resolveRepoSyncBlock(app, taskType, metadata);
  if (repoSync.skip) return skipped('repo-sync');
  const repoSyncReportBlock = repoSync.block;

  // issue-reconcile: deterministic forge pre-step that carries the zombie-issue
  // set into the prompt via {zombieIssues}.
  const issueReconcile = await resolveIssueReconcileBlock(app, taskType, metadata, taskSchedule);
  if (issueReconcile.skip) return skipped('issue-reconcile');
  const zombieIssuesBlock = issueReconcile.block;

  // Honor a direct claim-work prompt customization if the user set one;
  // otherwise delegate to the resolved tracker's prompt body via
  // getTaskPrompt(promptTaskType), which reads THAT type's interval.prompt
  // override — so a user's claim-issue / plan-task customization flows
  // through. (The prompt-only bodies claim-issue-gitlab and claim-issue-jira
  // have no schedule/UI customization slot, so they always render the shipped
  // default.)
  const promptKeyForBody = (taskType === 'claim-work' && !interval.prompt) ? promptTaskType : taskType;

  // A buildTaskInput hook that returned a fully-rendered prompt wins over the
  // template path — the hook owns its prompt (LI has no DEFAULT_TASK_PROMPTS
  // entry). The token-replacement chain below is a no-op on it (no {tokens}).
  const currentStageIndex = metadata.pipeline?.currentStage ?? 0;
  const promptTemplate = hookPrompt
    ? hookPrompt
    : (metadata.pipeline?.stages
      ? await getStagePrompt(taskType, currentStageIndex)
      : await getTaskPrompt(promptKeyForBody));

  // reference-watch: dynamically inject {referenceData} — a Markdown chunk
  // describing each ref configured on the app + commits since lastReviewedSha.
  const referenceWatch = await resolveReferenceWatchBlock(app, taskType);
  if (referenceWatch.skip) return skipped('reference-watch');
  const referenceDataBlock = referenceWatch.block;

  // Tracker-filing types (reference-watch, or an audit type with fileIssues):
  // the {trackerInstructions} block for the app's resolved work tracker.
  const fileIssues = isFileIssuesMode(taskType, metadata);
  if (isAuditTaskType(taskType)) {
    metadata.noChangeSuccess = !fileIssues;
  }
  const trackerFiling = await resolveTrackerFilingBlock(app, taskType, { fileIssues: fileIssues || isAuditTaskType(taskType) });
  // Git-backed issue trackers have a readback verifier; preserve Jira/PLAN.md
  // delivery without promising an unsupported machine-checkable gate.
  if (isAuditTaskType(taskType) && !fileIssues && ['github', 'gitlab'].includes(trackerFiling.workTracker)) metadata.auditDispositionVersion = 1;
  if (trackerFiling.workTracker && (fileIssues || !isAuditTaskType(taskType))) {
    // Traceability + deliverable posture, derived from the SAME resolved tracker
    // that selected the {trackerInstructions} block above so the flag can't drift
    // from the instructions the agent actually got: the PLAN.md path commits
    // checklist items (dirty tree), while github/gitlab/jira file issues/tickets
    // and leave the tree CLEAN. Without this downstream bookkeeping mistakes a
    // scheduled forge-tracker run for missing code work (#3102).
    metadata.workTracker = trackerFiling.workTracker;
    // Stamped unconditionally — a schedule/per-app `worktreeChangesExpected`
    // override would let the flag disagree with the instructions the agent
    // actually got, which is the exact drift this derivation exists to prevent.
    metadata.worktreeChangesExpected = trackerFiling.worktreeChangesExpected;
  }

  // pr-watcher: poll the app's GitHub repo for PRs newly opened against the
  // default branch; injects {prData}/{repoFullName}/{defaultBranch}.
  const prWatch = await resolvePrWatcherBlock(app, taskType, metadata, taskSchedule);
  if (prWatch.skip) return skipped('pr-watcher');
  const prDataBlock = prWatch.block;
  const prRepoFullName = prWatch.repoFullName;
  const prDefaultBranch = prWatch.defaultBranch;

  // Gate on PLAN.md using the RESOLVED type so a claim-work run routed to the
  // PLAN.md flow still skips cleanly on an empty/all-in-flight queue. For
  // standalone tasks promptTaskType === taskType, so behavior is unchanged.
  const planMeta = await applyPlanIdMetadata(promptTaskType, app.repoPath, metadata);
  if (planMeta.skipReason) {
    emitLog('info', `Skipping ${taskType} for ${app.name}: ${planMeta.skipReason}`, { appId: app.id });
    return skipped('plan-gate', { reason: planMeta.skipReason });
  }
  const planConstraintBlock = buildPlanConstraintBlock(metadata.planId);

  const modeInstructions = isAuditTaskType(taskType)
    ? `${modeContractFor(fileIssues)}\n\n${auditQualityInstructions(taskType)}`
    : '';
  // Resolve completion before rendering reviewers, including claim flows that
  // own their PR while intentionally disabling CoS worktree provisioning.
  applyAppWorktreeDefault(metadata, app);
  let baseDescription;
  try {
    baseDescription = await buildImprovementTaskDescription({
      promptTemplate: applyAuditModeWrapper(applyDepfreeMode(applyReleaseOptions(promptTemplate, promptTaskType, metadata), promptTaskType, metadata), modeInstructions),
      app, promptTaskType, metadata,
      reviewerTaskType: taskType, reviewerOverrideMetadata: appOverride?.taskMetadata,
      blocks: {
        referenceData: referenceDataBlock,
        trackerInstructions: trackerFiling.trackerInstructions,
        modeInstructions,
        prData: prDataBlock,
        inFlightBranches: inFlightBranchesBlock,
        zombieIssues: zombieIssuesBlock,
        repoSyncReport: repoSyncReportBlock,
        repoFullName: prRepoFullName,
        defaultBranch: prDefaultBranch,
        planConstraint: planConstraintBlock
      }
    });
  } catch (err) {
    if (err.code !== 'REVIEWER_IDENTITY_NOT_FOUND') throw err;
    emitLog('info', err.message, { appId: app.id, analysisType: taskType });
    const { recordPreflightOutcome } = await import('./preflightTaskCard.js');
    await recordPreflightOutcome({
      requestId: preflightCardId?.replace(/^preflight-/, '') || `reviewer-identity-${app.id}-${taskType}-${Date.now().toString(36)}`,
      taskType, appId: app.id, appName: app.name,
      outcome: 'failed', reason: err.code, note: err.message,
    });
    return skipped('reviewer-identity', { reason: err.message, detail: err.context });
  }
  const taskDataInputs = await resolveTaskDataInputs(interval.dataInputs, {
    app, taskMetadata: metadata, taskType: promptTaskType,
    trustedPullRequestData: prDataBlock,
  });
  const description = scopeDescriptionToPullRequest(
    appendTaskDataInputs(baseDescription, taskDataInputs),
    metadata
  );

  // File-issues posture wins over app worktree/PR defaults — the deliverable
  // is tracker items, so a managed worktree or an implied PR is the wrong shape.
  if (fileIssues) {
    // The catalog's one delivery posture, stamped rather than restated — the
    // custom-job lane (autonomousJobs/skillTemplates.js) applies this same
    // object, so the two cannot drift into different definitions of the mode.
    Object.assign(metadata, FILE_ISSUES_DELIVERY_SETTINGS);
  } else if (auditDoWorkRequiresWorktree(taskType)) {
    // Some structural audits are safe to remediate only in isolation. Enforce
    // this after schedule/app defaults so a stale file-issues toggle transition
    // cannot dispatch edits into the app's live checkout. PR creation remains
    // independently configurable through metadata.openPR.
    metadata.useWorktree = true;
  }
  // The app's per-app provider/model pin (#4783). Resolved through the shared
  // harness guard, so an api-typed pin falls back to the Schedule pin instead of
  // reaching the spawn as a permanent provider failure. Skipped when a
  // buildTaskInput hook already resolved the provider — its return wins anyway, so
  // re-deriving here would only duplicate the fallback log line.
  const appPin = hookOverride.providerId
    ? EMPTY_PROVIDER_PIN
    : await resolveAppProviderPin({ app, taskType, appOverride, interval });
  applyProviderModelPins(metadata, interval, appPin, hookOverride, providerOverride);

  const approval = await resolveConfidenceApproval(state, `app-improve:${taskType}`, `Task app-improve:${taskType} for ${app.name}`, metadata);
  stampApprovalReason(metadata, approval);

  // All gates passed — stamp the buildTaskInput hook's metadata bag, record the
  // rotation-pointer advance, and emit the generation log. Deferred from the top
  // of the function (see note there); every `skipped(...)` exit above this point
  // intentionally leaves all three untouched.
  //
  // The hook bag lands HERE, below the last gate, precisely so a hook can defer a
  // side effect keyed on it until the task is certain to exist. Several gates
  // below `resolveTaskInputHook` can still `return skipped(...)` with no agent ever
  // spawned, so a hook that charged a spend ledger from `buildTaskInput` would
  // burn budget on a dispatch that never happened (#3179).
  //
  // Generator-computed keys always win. Stamping last would otherwise let a hook
  // silently clobber a decision made a few lines earlier — `analysisType` is the
  // dangerous one, since resolveTaskHookType reads it to dispatch the output hook,
  // so a collision would stop the very hook that asked for the bag from ever
  // running. Hooks pin provider/model and own the prompt through their own return
  // fields; the bag is for values that must SURVIVE to processTaskOutput, not an
  // override channel. Dropped collisions are logged rather than merged silently.
  for (const [key, value] of Object.entries(hookMetadata || {})) {
    if (key in metadata) {
      emitLog('warn', `Ignoring ${taskType} hookMetadata key '${key}' for ${app.name}: it would overwrite generator-owned task metadata`, { appId: app.id, analysisType: taskType });
      continue;
    }
    metadata[key] = value;
  }
  if (isPrivateSecurityTask({ metadata })) Object.assign(metadata, PRIVATE_SECURITY_DELIVERY);
  await updateAppActivity(app.id, { lastImprovementType: taskType });
  emitLog('info', `Generating improvement task for ${app.name}: ${taskType}`, { appId: app.id, analysisType: taskType });

  const task = {
    id: `app-improve-${app.id}-${taskType}-${Date.now().toString(36)}`,
    status: 'pending',
    priority: state.config.idleReviewPriority || 'MEDIUM',
    priorityValue: PRIORITY_VALUES[state.config.idleReviewPriority] || 2,
    description,
    metadata,
    taskType: 'internal',
    ...approval
  };

  // The drain signature returns alongside the task instead of being recorded
  // here — every caller sits between task construction and spawn-engine
  // admission, and recordDeferredPerpetualDispatch is the one choke point
  // that may spend the budget, once admission is certain (#6871).
  const pendingPerpetualDispatch = perpetualGate.spendDispatch
    ? { taskType, appId: app.id, signature: perpetualGate.signature ?? null }
    : null;

  return { task, pendingPerpetualDispatch, skip: null };
}