Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
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 };
}