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 { auditWorkflow, newAuditMetadata, isLegacyDeepAudit } from '../lib/auditWorkflow.js';
import { isForgeMaintenanceTask, hasCurrentForgeMaintenanceEvidence, LEGACY_FORGE_MAINTENANCE_REASON } from '../lib/forgeMaintenanceTasks.js';
import { getSkipReason } from './cosTaskClaim.js';
import { isDeepStrictEqual } from 'node:util';
/**
* CoS Task Store Module
*
* Task CRUD + queue persistence extracted from cos.js. Owns the read/write
* round-trip to the user and internal task queues (`cos_tasks`, through
* `cosTaskRepository.js`): the cached working set, row-diff saves, grouping,
* dedup, and the `tasks:changed` event emissions that drive the scheduler. The request → record mapping (ID generation, metadata
* normalization) is `cosTaskIntake.js`, kept in parity with the request schema.
*
* Self-contained — it emits `tasks:changed` rather than calling the scheduler
* directly. cos.js's `init()` listens on that event to fire `tryImmediateSpawn`
* (user-added tasks) and `dequeueNextTask` (approved tasks), so the spawn-side
* logic stays in cos.js while persistence lives here.
*/
import { DEVELOPMENT_ACTIVE_STATUSES, developmentWorkIdentity, sameDevelopmentWork } from '../lib/developmentWorkIdentity.js';
import { reviewerModelsFromDefaults } from '../lib/reviewerConfig.js';
import { createSingleFlight } from '../lib/singleFlight.js';
import { groupTasksByStatus, getAutoApprovedTasks, getAwaitingApprovalTasks, hasKnownPrefix, toRepresentableTask, PRIORITY_VALUES } from '../lib/taskParser.js';
import { MAX_TOTAL_SPAWNS, cosTaskTypeSchema, validateRequest } from '../lib/validation.js';
import { RETRY_HOLD_KEY, RETRY_HOLD_SINCE_KEY, isRetryHeld } from '../lib/taskRetryHold.js';
import { resolveTaskTargetBranch, shouldStripTaskTargetBranch } from '../lib/taskTargetBranch.js';
import { AGENT_PAUSED_CATEGORY, PAUSE_METADATA_KEYS, isAgentPausedTask, resolvePausedTaskResume, retirePausedAgent } from '../lib/taskPauseHold.js';
import { REQUEUED_AT_KEY } from '../lib/taskRequeue.js';
import { resolveTaskStatusTransition, isTerminalTaskStatus } from '../lib/taskStatusTransition.js';
import { isInvestigationTask } from '../lib/investigationTasks.js';
import { PAUSED_BLOCKED_CATEGORIES, USER_DECISION_BLOCKED_CATEGORIES } from '../lib/taskBlockCategories.js';
import { splitTaskPromptFields, TASK_PROMPT_KEY, TASK_CONTEXT_KEY } from '../lib/cosTaskPrompt.js';
import { normalizeOrchestrationMode, normalizeOrchestrationProfile } from '../lib/orchestrationProfile.js';
import { loadState, withStateLock } from './cosState.js';
import { activeAgents, runnerAgents, hasActiveTaskOwner } from './agentState.js';
import { cosEvents } from './cosEvents.js';
import { CLAIM_METADATA_KEYS } from './cosTaskClaim.js';
import { mergeTaskLists } from './cosTaskMerge.js';
import { applyTaskListSave, countCompletedTasks, deleteStoredTask, getCompletedTaskIds, getStoredTask, loadTaskWorkingSet, pageCompletedTasks, readTaskListVersion } from './cosTaskRepository.js';
import { planListSave, selectWorkingSet } from '../lib/cosTaskRows.js';
import { buildQueuedTask } from './cosTaskIntake.js';
import { canChallenge, getChallengeCount, buildChallengePatch, buildChallengeResolutionPatch, classifyRecheckOutcome, MAX_CHALLENGES_PER_TASK } from './cosChallenge.js';
import { runLocalCodeReview, getCodeReviewDefaults } from './codeReview.js';
// First non-empty line of a string — used by addTask's dedup, since stored
// descriptions are flattened to a single line by generateTasksMarkdown. Declared
// in the dependency-free text leaf and re-exported here at the address this
// module's callers already import it from.
import { firstLine } from '../lib/textUtils.js';
export { firstLine };
const CLAIM_KEY_SET = new Set(CLAIM_METADATA_KEYS);
// Heading the update path stamps on text it lifts out of a multi-line description
// edit and into the newline-safe note, so the provenance survives a later read.
const DESCRIPTION_OVERFLOW_HEADING = '(from description)';
/**
* Normalize a multi-line `description` on the UPDATE path, preserving the body.
*
* Markdown task rows are ONE-LINE records: `generateTasksMarkdown` emits the
* description into `- [ ] #id | PRIORITY | <description>` and
* `parseTasksMarkdown` reads only that first line. `addTask` has collapsed a
* multi-line description for exactly that reason since #4153 — `writeTaskUpdate`
* did not, so saving a multi-line edit from the task editor's textarea wrote the
* extra lines into the file as free text. Reparsing then silently truncated the
* description, scraped any ` - key: value` line into the task's OWN metadata
* (re-targeting its app/provider/prompt), and minted a phantom auto-approved
* task out of any pasted `- [ ] #id | …` row that the spawner would then run
* (#7240).
*
* Unlike `addTask` this never DROPS the remainder. The full submitted text goes
* to `metadata.prompt` when the task has none; when it already has one, the text
* is appended to `metadata.context` instead, because `updateTask` must not
* overwrite a real prompt (the contract in `server/lib/cosTaskPrompt.js`). Both
* fields round-trip newlines through the JSON sentinel, and `taskContextBlock`
* already renders prompt + note together — nothing is lost and nothing is
* silently replaced. An explicitly-cleared prompt (`''`) counts as present, the
* same absent-vs-cleared rule the rest of the store follows.
*
* Returns `null` when there is nothing to normalize; never mutates its input.
*/
function normalizeUpdatedDescription(description, metadata) {
if (typeof description !== 'string' || !description.includes('\n')) return null;
const nextMetadata = { ...metadata };
if (typeof nextMetadata[TASK_PROMPT_KEY] === 'string') {
const block = `${DESCRIPTION_OVERFLOW_HEADING}\n${description}`;
const existing = typeof nextMetadata[TASK_CONTEXT_KEY] === 'string' ? nextMetadata[TASK_CONTEXT_KEY] : '';
// Re-saving the same edit must not grow the note without bound.
if (!existing.includes(block)) {
nextMetadata[TASK_CONTEXT_KEY] = existing ? `${existing}\n\n${block}` : block;
}
} else {
nextMetadata[TASK_PROMPT_KEY] = description;
}
return { description: firstLine(description), metadata: nextMetadata };
}
// The `blockedCategory` vocabulary lives in `lib/taskBlockCategories.js` — the
// pause logic, the failure reaper below, and the investigation auto-retry all
// have to answer "may I move this task?" from that one value, and each keeping
// its own literal set is how they drifted. Re-exported at the address callers
// already use.
export { PAUSED_BLOCKED_CATEGORIES };
// Fields an `updateTask` patch may carry directly (vs nested under `metadata`);
// they're normalized into `metadata` on write. Listed once so the content-edit
// detector and the normalizer below can't drift apart. `prompt` joined the list
// with the #4153 split so the task editor can edit the agent-facing payload the
// same way it edits the human note — deliberately WITHOUT re-classification, so
// a multi-line note edit can't overwrite the payload (see `splitTaskPromptFields`).
const LEGACY_DIRECT_FIELDS = ['context', 'prompt', 'model', 'provider', 'effort', 'temperature', 'thinking', 'app', 'orchestrationMode', 'orchestrationProfile'];
// Equality for metadata values across a fresh markdown re-parse: primitives by
// ===, arrays/objects (reviewers[], screenshots[], …) by JSON since the two
// sides are independent parses with different references but equal content.
const metaValueEqual = (a, b) => {
if (a === b) return true;
if (a && b && typeof a === 'object' && typeof b === 'object') {
return JSON.stringify(a) === JSON.stringify(b);
}
return false;
};
/**
* Does an `updateTask` patch change a task's EDITABLE CONTENT (vs only its
* claim/lease metadata)? Used to decide whether to bump the `updatedAt` LWW stamp
* (#1714). A claim-only write — most importantly the periodic lease-renewal
* heartbeat — must NOT bump the stamp: a heartbeat is not a content edit, and
* letting it advance `updatedAt` would make a lease-renewing peer spuriously win
* same-status content ties over the other peer's genuine edit.
*
* Crucially, the heartbeat does NOT pass a claim-only patch — `cos.js`
* `processOrphanedTasks` spreads the WHOLE existing metadata plus the fresh lease
* (`{ ...task.metadata, ...renewal }`). So presence of a non-claim key is not
* enough to call it an edit; we must compare VALUES against the task's current
* metadata and treat a key as content only when it actually changed. The edit
* stamp itself is never content. Status/priority/description/approval changes and
* legacy direct fields are always edits when present (callers only pass those
* with intent).
*
* @param {object} updates the updateTask patch
* @param {object} existingMetadata the task's current persisted metadata
*/
function isContentEdit(updates, existingMetadata = {}) {
if (!updates || typeof updates !== 'object') return false;
if (updates.status !== undefined) return true;
if (updates.description !== undefined) return true;
if (updates.priority !== undefined) return true;
if (updates.approvalRequired !== undefined || updates.autoApproved !== undefined) return true;
if (LEGACY_DIRECT_FIELDS.some(f => updates[f] !== undefined)) return true;
if (updates.metadata && typeof updates.metadata === 'object') {
const existing = (existingMetadata && typeof existingMetadata === 'object') ? existingMetadata : {};
for (const [key, value] of Object.entries(updates.metadata)) {
if (CLAIM_KEY_SET.has(key) || key === 'updatedAt') continue; // claim keys + the stamp never count
if (!metaValueEqual(value, existing[key])) return true; // a non-claim key counts only if it CHANGED
}
}
return false;
}
// ── Working-set cache ───────────────────────────────────────────────────────
//
// `getUserTasks`/`getCosTasks`/`getTaskById` run on every daemon evaluation
// tick, scheduler sweep, and agent state update. A queue's WORKING SET (every
// open task plus recently completed ones, see lib/cosTaskRows.js) is loaded once
// per queue version and shared: an unchanged queue costs one single-row version
// read plus a structured clone instead of a query over the rows.
//
// Concurrent readers share the load for a version (#12225), so a cold cache does
// not multiply the working set by the number of readers. Correctness rests on:
//
// 1. The queue version, bumped by every write in the same transaction, so a
// write this process did NOT make is noticed on the next read.
// 2. Our own writes replace the cached entry only when the version moved by
// exactly one (nobody else wrote in between); otherwise they drop it.
const snapshotCache = new Map(); // source -> { version, snapshot }
const snapshotLoads = createSingleFlight();
// A list may be mutated or transformed before saving. Keep its ORIGINAL read
// snapshot, never a fresh read whose omissions could turn into accidental deletes.
const listSnapshots = new WeakMap();
// Private snapshots never leave this module: list readers clone the array,
// while ID lookups clone only the matching task. Both share invalidation.
// `rows` keeps each task's stored position for the next save's diff.
async function readTaskSnapshot(source) {
const version = await readTaskListVersion(source);
const cached = snapshotCache.get(source);
if (cached?.version === version) return cached.snapshot;
return snapshotLoads.run(`${source}:${version}`, async () => {
const loaded = await loadTaskWorkingSet(source);
const snapshot = { version: loaded.version, rows: loaded.rows, tasks: loaded.rows.map((row) => row.task) };
if (!snapshotCache.get(source) || snapshotCache.get(source).version <= loaded.version) {
snapshotCache.set(source, { version: loaded.version, snapshot });
}
return snapshot;
});
}
async function readTaskFile(source) {
const snapshot = await readTaskSnapshot(source);
const tasks = structuredClone(snapshot.tasks);
listSnapshots.set(tasks, snapshot);
return tasks;
}
async function findTaskInFile(source, taskId) {
const snapshot = await readTaskSnapshot(source);
if (!snapshot.byId) {
snapshot.byId = new Map();
for (const task of snapshot.tasks) {
// Preserve Array.find's first-match behavior for duplicate IDs.
if (!snapshot.byId.has(task.id)) snapshot.byId.set(task.id, task);
}
}
const task = snapshot.byId.get(taskId);
return task ? structuredClone(task) : null;
}
/**
* Persist the queue as `tasks`: diff against the stored working set and write
* only the rows that changed, in one transaction. Every write path in this
* module goes through here. Resolves to whether anything was written.
*/
async function writeTaskList(source, tasks, original = tasks, dependencies = {}) {
const snapshot = listSnapshots.get(original);
if (!snapshot) throw new Error('Task saves require their original read snapshot');
const cached = snapshotCache.get(source);
const plan = planListSave({ previous: snapshot.rows, next: tasks, source });
if (plan.upserts.length === 0 && plan.deletes.length === 0) return false;
const version = await applyTaskListSave(source, {
...plan, expectedVersions: { ...dependencies, [source]: snapshot.version },
});
const positions = new Map(snapshot.rows.map((row) => [row.task.id, row.position]));
for (const { task, position } of plan.upserts) positions.set(task.id, position);
if (cached?.snapshot === snapshot && version === cached.version + 1) {
// Same bound as a reload, so completions never accumulate in the cache.
const rows = selectWorkingSet(plan.saved.map((task) => ({ task, position: positions.get(task.id) })));
snapshotCache.set(source, { version, snapshot: { version, rows, tasks: rows.map((row) => row.task) } });
} else {
snapshotCache.delete(source);
}
return true;
}
/** Test hook: forget every cached working set. */
export function __resetTaskCache() {
snapshotCache.clear();
}
/**
* Get user tasks
*/
export async function getUserTasks() {
const tasks = await readTaskFile('user');
return { tasks, grouped: groupTasksByStatus(tasks), type: 'user' };
}
/**
* Get CoS internal tasks
*/
export async function getCosTasks() {
const tasks = await readTaskFile('internal');
const grouped = groupTasksByStatus(tasks);
const autoApproved = getAutoApprovedTasks(tasks);
const awaitingApproval = getAwaitingApprovalTasks(tasks);
return { tasks, grouped, type: 'internal', autoApproved, awaitingApproval };
}
/**
* Get all tasks (user + internal)
*/
export async function getAllTasks() {
const [userTasks, cosTasks] = await Promise.all([getUserTasks(), getCosTasks()]);
return { user: userTasks, cos: cosTasks };
}
// ── Bounded task views (#9677) ──────────────────────────────────────────────
//
// `GET /api/cos/tasks` returns the open queue plus at most one page of completed
// history, yet `getAllTasks()` structured-clones the whole working set (recent
// completed prompt bodies included) from BOTH queues first. These readers select
// from the private snapshot, or page completed history straight from the table,
// and clone only what the response carries. Nothing returned here aliases the cache.
const COMPLETED_FIRST_PAGE = 25;
const SOURCES = ['user', 'internal'];
const isCompleted = (task) => task.status === 'completed';
// Per-snapshot derivations, dropped with the snapshot on any version change.
function snapshotPartitions(snapshot) {
if (!snapshot.partitions) {
const open = [];
const completed = [];
for (const task of snapshot.tasks) (isCompleted(task) ? completed : open).push(task);
snapshot.partitions = { open, completed };
}
return snapshot.partitions;
}
// Shape of getUserTasks()/getCosTasks() over an already-selected task subset.
// Callers pass CLONED tasks; grouped/derived lists share those clones.
function sourceShape(type, tasks) {
const shape = { tasks, grouped: groupTasksByStatus(tasks), type };
if (type === 'internal') {
shape.autoApproved = getAutoApprovedTasks(tasks);
shape.awaitingApproval = getAwaitingApprovalTasks(tasks);
}
return shape;
}
/**
* One page of completed history from ONE queue, newest id first, straight from
* the table. `nextCursor` is the last id of a full page when more remain.
*/
async function pageCompleted(type, { cursor = null, limit }) {
const rows = await pageCompletedTasks(type, { before: cursor, limit: limit + 1 });
const items = rows.slice(0, limit);
return { items, total: await countCompletedTasks(type), nextCursor: rows.length > limit ? items[limit - 1].id : null };
}
/**
* Open queue (every non-completed task, plus the `selected` historical task)
* for both queues. `completedCount` carries the completed total.
*/
async function readQueueView(selected) {
const read = async (type) => {
const snapshot = await readTaskSnapshot(type);
const { open } = snapshotPartitions(snapshot);
const refs = selected === undefined ? open : snapshot.tasks.filter((task) => !isCompleted(task) || task.id === selected);
const tasks = structuredClone(refs);
// A selected historical task older than the working set is fetched by id.
if (selected !== undefined && !refs.some((task) => task.id === selected)) {
const stored = await getStoredTask(selected, type);
if (stored) tasks.push(stored.task);
}
return { ...sourceShape(type, tasks), completedCount: await countCompletedTasks(type) };
};
const [user, cos] = await Promise.all([read('user'), read('internal')]);
return { user, cos };
}
/** Open queue plus the first completed page; the rest of the history stays in the table. */
async function readBareView() {
const read = async (type) => {
const { open } = snapshotPartitions(await readTaskSnapshot(type));
const page = await pageCompleted(type, { limit: COMPLETED_FIRST_PAGE });
const shape = sourceShape(type, [...structuredClone(open), ...page.items]);
// Completed rows leave `grouped`; only the page inside `tasks` carries them.
return { ...shape, grouped: { ...shape.grouped, completed: [] }, completedCount: page.total, completedNextCursor: page.nextCursor };
};
const [user, cos] = await Promise.all([read('user'), read('internal')]);
return { user, cos };
}
/** One page of completed history from ONE source, newest id first. */
async function readCompletedView({ source, cursor, limit }) {
return pageCompleted(source === 'internal' ? 'internal' : 'user', { cursor, limit });
}
/**
* Legacy limit/offset window over each queue's working set, in queue order. The
* slice and scalar metadata only; completed history older than the working set
* pages through the `completed` view.
*/
async function readWindowView({ offset, limit }) {
const read = async (type) => {
const { tasks } = await readTaskSnapshot(type);
return { meta: { type }, tasks: structuredClone(tasks.slice(offset, offset + limit)), total: tasks.length };
};
const [user, cos] = await Promise.all([read('user'), read('internal')]);
return {
user: { ...user.meta, tasks: user.tasks },
cos: { ...cos.meta, tasks: cos.tasks },
totals: { user: user.total, cos: cos.total },
};
}
/**
* Read-only, bounded task view for the HTTP layer. `kind`:
* - 'queue' { selected? } open tasks (+ the selected historical one) + completedCount
* - 'bare' open tasks + first completed page (+ completedCount/completedNextCursor)
* - 'completed' { source, cursor?, limit } one source's page → { items, total, nextCursor }
* - 'window' { offset, limit } legacy slice of the working set → { user, cos, totals }
* Sources come back unsettled for the spawn window; `getAllTasks()` stays the raw
* truth (the working set) for scheduler readers and `view=full`.
*/
export async function getTaskView({ kind, ...options }) {
if (kind === 'queue') return readQueueView(options.selected);
if (kind === 'bare') return readBareView();
if (kind === 'completed') return readCompletedView(options);
if (kind === 'window') return readWindowView(options);
throw new Error(`Unknown task view: ${kind}`);
}
/**
* Lightweight live-activity input. Derive once per queue version, so a
* three-second poll never clones prompts or groups completed history.
* Keep duplicates and source order, matching getAllTasks() counting semantics.
*/
export async function getPendingTaskIds() {
const sources = await Promise.all(SOURCES.map(async (source) => {
const snapshot = await readTaskSnapshot(source);
snapshot.pendingIds ??= snapshot.tasks.filter(task => task.status === 'pending').map(task => task.id);
return snapshot.pendingIds;
}));
// Never expose the cached arrays to callers.
return sources.flat();
}
/**
* Telemetry reads only diagnostics-bearing records, never full prompts or
* grouped history. Derive per snapshot and reuse the cache's write invalidation;
* clone the projection to keep it private.
*/
export async function getTaskDiagnostics() {
const sources = await Promise.all(SOURCES.map(async (source) => {
const snapshot = await readTaskSnapshot(source);
snapshot.diagnosticTasks ??= snapshot.tasks.filter(task => {
const diagnostics = task.metadata?.diagnostics;
return diagnostics && typeof diagnostics === 'object' && !Array.isArray(diagnostics);
}).map(task => ({
status: task.status,
metadata: { diagnostics: task.metadata.diagnostics, updatedAt: task.metadata.updatedAt }
}));
return snapshot.diagnosticTasks;
}));
return structuredClone(sources.flat());
}
/**
* Approval-state view of the internal queue for pollers that need the awaiting
* list or the auto-approved count, not the whole queue. `getCosTasks()` clones
* every working-set prompt body to answer the same question. Derived once per
* snapshot; only the first `limit` awaiting tasks are cloned.
*/
export async function getCosApprovalView({ limit = Infinity } = {}) {
const snapshot = await readTaskSnapshot('internal');
snapshot.approval ??= {
awaiting: getAwaitingApprovalTasks(snapshot.tasks),
autoApprovedCount: getAutoApprovedTasks(snapshot.tasks).length,
};
const { awaiting, autoApprovedCount } = snapshot.approval;
return { awaitingApproval: structuredClone(awaiting.slice(0, limit)), autoApprovedCount };
}
/**
* Alias for backward compatibility
*/
export const getTasks = getUserTasks;
/**
* Get a specific task by ID from any task source
*/
/**
* One task and the queue it lives in: `{ task, source: 'user' | 'internal' }`,
* or null. The record is returned as stored (its own `taskType` intact), which
* is what a client merging it into a list it already holds needs.
*/
export async function findTaskWithSource(taskId) {
// Keep user-first precedence, including legacy/custom IDs. Do not infer the
// source from a prefix or prepare grouped copies of both queues for one ID.
const userTask = await findTaskInFile('user', taskId);
if (userTask) return { task: userTask, source: 'user' };
const cosTask = await findTaskInFile('internal', taskId);
if (cosTask) return { task: cosTask, source: 'internal' };
// Completed history older than the working set is fetched by id.
const stored = await getStoredTask(taskId);
return stored ? { task: stored.task, source: stored.source } : null;
}
// Legacy shape: the source overwrites the record's `taskType`. Callers that
// need the record as stored use findTaskWithSource.
export async function getTaskById(taskId) {
const found = await findTaskWithSource(taskId);
return found ? { ...found.task, taskType: found.source } : null;
}
async function uniqueTaskId(source, id, tasks) {
const taken = async (candidate) => tasks.some((task) => task.id === candidate) || Boolean(await getStoredTask(candidate, source));
if (!await taken(id)) return id;
for (let suffix = 2; ; suffix++) {
const candidate = `${id}-dup${suffix}`;
if (!await taken(candidate)) return candidate;
}
}
/**
* Add a new task to the user or internal queue.
*
* Emits `tasks:changed` with `action: 'added'` on success; cos.js's init
* listener turns that into a `tryImmediateSpawn` for user tasks so a newly
* submitted task starts instantly instead of waiting for the next evaluation
* interval. `suppressDequeue` is reserved for an explicit dispatcher that will
* force-spawn the returned task itself; the change event still reaches socket
* consumers, but the normal scheduler must not race that dispatch.
*/
export async function addTask(taskData, taskType = 'user', options = {}) {
// Only addition is replayed: it has no effects before persistence. Re-read
// both queues and recompute dedup/IDs on conflict; never retry a stale plan.
// Other mutations surface 409 so decisions or side effects are not replayed.
for (let attempt = 0; ; attempt++) {
const result = await addTaskAttempt(taskData, taskType, options).catch(error => {
if (error.code !== 'COS_TASK_LIST_CONFLICT' || attempt >= 3) throw error;
return null;
});
if (result !== null) return result;
}
}
async function addTaskAttempt(taskData, taskType, { raw = false, ignoreTaskId = null, now = Date.now(), suppressDequeue = false }) {
validateRequest(cosTaskTypeSchema, taskType);
if (!raw && taskData.metadata) taskData = { ...taskData, metadata: newAuditMetadata(taskData.metadata) };
return withStateLock(async () => {
const tasks = await readTaskFile(taskType);
// One state lock covers BOTH queues: manual and autonomous producers
// must acquire the same durable work identity even with different titles.
const newWorkIdentity = developmentWorkIdentity(taskData);
const dependencies = {};
if (newWorkIdentity) {
const other = await readTaskFile(taskType === 'user' ? 'internal' : 'user');
dependencies[taskType === 'user' ? 'internal' : 'user'] = listSnapshots.get(other).version;
const owner = [...tasks, ...other].find(task => task.id !== ignoreTaskId
&& DEVELOPMENT_ACTIVE_STATUSES.has(task.status) && sameDevelopmentWork(task, taskData)
// Targeted claims and the backlog drain coexist in either admission order.
// Otherwise a completed drain cannot refill while a targeted claim runs:
// the on-demand request is consumed as a duplicate with nothing queued.
// Two claims of the same issue, or two unpinned drains, still deduplicate.
&& !(newWorkIdentity.kind === 'issue'
&& (newWorkIdentity.key === '*') !== (developmentWorkIdentity(task)?.key === '*')));
if (owner) return { ...owner, duplicate: true };
}
// Reject duplicate: same first-line description AND same target app already
// pending, in_progress, or blocked. The `metadata.app` scope matters — the same
// description against two different apps is two different pieces of work
// (e.g. "fix the failing test" in PortOS vs in BookLoom), and collapsing
// them silently drops the second dispatch.
//
// `ignoreTaskId` excludes one specific task from the dedup scan. The perpetual
// drain-on-completion refill needs this: `agent:completed` fires from
// completeAgent BEFORE the completion flow's updateTask marks the just-finished
// task done, so that task is still `in_progress` on disk here. A perpetual
// schedule (claim-issue/claim-work) regenerates an identical first-line for the
// same app, so without excluding the completing task the refill is rejected as a
// duplicate of it and the back-to-back drain stalls until the next scheduler
// tick. The completing task is about to become `completed`, so ignoring it is
// correct, not a dedup hole.
const normalizedDesc = firstLine(taskData.description).toLowerCase();
// The candidate's app can arrive two ways: non-raw tasks pass it top-level as
// `taskData.app` (used below to build `metadata.app`); raw tasks — the queue-path
// improvement tasks and on-demand generated tasks — arrive pre-built with the app
// already in `metadata.app` and NO top-level `app`. Read both, or the app-scoped
// dedup silently no-ops for raw managed-app tasks: `targetApp` would be `null` and
// never equal the existing task's `metadata.app`, so two concurrent
// `queueEligibleImprovementTasks` snapshots (the periodic evaluation + the
// improvement-check timer firing close together) each add an identical
// `[Improvement: PortOS] …` task, producing the overlapping duplicate runs.
const targetApp = taskData.app ?? taskData.metadata?.app ?? null;
// Blocked tasks count as duplicates too (#2614): a task blocked by repeated
// failures (max-retries, max-spawns, provider-config, …) still occupies its
// slot — the retry path is unblocking the existing task, not minting a new
// identical one. Before this, a persistently-failing scheduled type piled up
// one blocked duplicate per cadence tick, forever (nothing reaps blocked
// tasks automatically).
const duplicate = tasks.find(t =>
t.id !== ignoreTaskId &&
(t.status === 'pending' || t.status === 'in_progress' || t.status === 'blocked') &&
firstLine(t.description).toLowerCase() === normalizedDesc &&
(t.metadata?.app || null) === targetApp &&
auditWorkflow(t.metadata) === auditWorkflow(taskData.metadata)
);
if (duplicate) {
console.log(`⚠️ Duplicate task rejected: "${normalizedDesc.substring(0, 60)}" matches ${duplicate.id}${duplicate.status === 'blocked' ? ` (blocked: ${duplicate.metadata?.blockedCategory || 'unknown'})` : ''}`);
return { ...duplicate, duplicate: true };
}
// When raw=true, use the pre-built task object directly (for on-demand/generated tasks)
let newTask = raw ? taskData : buildQueuedTask(taskData, taskType, { now });
// A raw producer mints its own id and this path writes it verbatim, but the
// next READ rewrites an unregistered prefix to `task-<id>` — so a producer
// that re-derives its id instead of keeping the one returned here misses on
// every later read and write, silently (those call sites are best-effort).
// The preflight card lost a whole pr-reviewer run that way. The fix is to
// register the prefix in lib/taskParser.js, not to rename the producer.
if (raw && newTask?.id && !hasKnownPrefix(newTask.id)) {
console.error(`❌ Task id ${newTask.id} uses an unregistered prefix — it will be read back as task-${newTask.id}. Register the prefix in lib/taskParser.js`);
}
// Ids are the row key and are minted from the clock, so two tasks created in the
// same millisecond collide. Suffix `-dup2`, `-dup3`, ... as the Markdown reader
// always did, but checked against every stored task, not just the working set.
if (newTask?.id) {
const id = await uniqueTaskId(taskType, newTask.id, tasks);
if (id !== newTask.id) newTask = { ...newTask, id };
}
// Route a multi-line context payload to `metadata.prompt` (#4153). Applied to
// BOTH branches — the raw path is how the generator, the reference-watch
// analysis, and the repo-study filer queue their pre-built tasks, and they
// carry the same kind of multi-thousand-character body the direct-write path
// does. One classification, at CREATE only: `updateTask` deliberately leaves
// both fields alone, because the task editor's textarea is seeded from the
// NOTE and re-classifying a multi-line edit of it would overwrite the task's
// real prompt. A producer that already wrote `metadata.prompt` wins over the
// inference. See `server/lib/cosTaskPrompt.js` for the full contract.
// Markdown task rows are one-line records. Preserve every generated prompt
// in the newline-safe metadata field before persistence, including raw
// on-demand tasks that bypass the queue generator's normalization pass.
//
// This runs BEFORE the context reclassification below on purpose: a producer
// that hands over a multi-line description AND a multi-line context note (the
// pr-reviewer generator's security-scan summary) means the description is the
// prompt and the note is the note. Reclassifying first promoted the note to
// `prompt`, which then counted as an explicit producer prompt and silently
// discarded the stage instructions — Stage 2 ran with no gate rules and no
// output contract.
if (typeof newTask.description === 'string' && newTask.description.includes('\n')) {
newTask = {
...newTask,
description: firstLine(newTask.description),
metadata: {
...(newTask.metadata || {}),
prompt: typeof newTask.metadata?.prompt === 'string'
? newTask.metadata.prompt
: newTask.description,
},
};
}
const splitMetadata = splitTaskPromptFields(newTask.metadata);
if (splitMetadata !== newTask.metadata) newTask = { ...newTask, metadata: splitMetadata };
// Add task to top or bottom based on position parameter
if (taskData.position === 'top') {
tasks.unshift(newTask);
} else {
tasks.push(newTask);
}
await writeTaskList(taskType, tasks, tasks, dependencies);
// cos.js init listens for this event. For user tasks it fires
// tryImmediateSpawn so the task starts instantly if slots are available,
// bypassing the evaluation interval (which is meant for system task generation).
const change = { type: taskType, action: 'added', task: newTask };
if (suppressDequeue) change.suppressDequeue = true;
cosEvents.emit('tasks:changed', change);
return newTask;
});
}
/**
* Update an existing task.
*
* Wraps the persisted write with the rest of the pause release (#3730). Dropping
* `PAUSE_METADATA_KEYS` on the blocked transition (below) stops a revived task from
* advertising a pause it no longer has, but a pause is not only bookkeeping: the run
* that paused left a branch — usually a whole worktree — behind, and the resumed run
* has to be POINTED at it or it starts clean and redoes that work. Resolving that
* pointer lived in `resumeAgent`, so the Resume dialog resumed properly while every
* other door into `blocked(agent-paused) → pending` (the Tasks-tab status toggle's
* bare `{ status: 'pending' }`, and `reviveBlockedTask` on behalf of on-demand Run /
* pipeline advance / Creative Director / manual job trigger / voice dispatch) still
* spawned a second agent on a clean workspace. Owning it at the transition fixes
* them all, and future callers by construction.
*
* The resolve runs BEFORE the lock and the retire AFTER it. Both reach the agent
* layer through the registered adapter, and `retirePausedAgent` writes agent state
* via `completeAgent` — which takes the same non-reentrant `withStateLock`, so
* running either inside would deadlock. Resolving first is also what keeps the task
* from ever being `pending` (spawnable) without its pointer.
*
* `expectedStatus`, when supplied, is checked under the task-file lock. A mismatch
* returns `{ statusChanged: true }` without writing or retiring pause state.
*/
export async function updateTask(taskId, updates, taskType = 'user', { now = Date.now(), suppressDequeue = false, expectedStatus = null, expectedMetadata = null, expectedTask = null, recoveryOwner = null, preserveRetryBudget = false } = {}) {
validateRequest(cosTaskTypeSchema, taskType);
const release = await preparePauseRelease(taskId, updates);
const result = await writeTaskUpdate(taskId, release ? { ...updates, metadata: release.metadata } : updates, taskType, { now, suppressDequeue, expectedStatus, expectedMetadata, expectedTask, recoveryOwner, preserveRetryBudget });
if (release && !result?.error && !result?.statusChanged) {
await retirePausedAgent(release.agentId, taskId, resolveTaskTargetBranch(result?.metadata));
}
return result;
}
/**
* Is this update releasing a user pause, and if so what does the resumed run need?
*
* `null` for every other update — including a paused task moving to any status but
* `pending` (terminating a paused task is not a resume; nothing to point at, and the
* record's retirement belongs to whatever terminated it), and a pending flip on a
* task nobody paused. `pausedAgentId` is required: without it there is no record to
* resolve a pointer from or retire, so the flip is an ordinary unblock.
*/
async function preparePauseRelease(taskId, updates) {
if (updates?.status !== 'pending') return null;
const task = await getTaskById(taskId).catch(() => null);
if (!isAgentPausedTask(task)) return null;
const agentId = task.metadata?.pausedAgentId;
if (!agentId) return null;
// Fails open to "start clean" the way every other resume-pointer caller does:
// un-blocking the task matters more than resuming it in place, and the worktree
// stays on disk for a human either way.
const pointer = await resolvePausedTaskResume(task).catch(err => {
console.error(`❌ Resume pointer for task ${taskId} could not be resolved: ${err.message}`);
return {};
});
// The caller's own metadata still wins — the Resume dialog's provider/model/context
// overrides, and a caller that resolved a pointer itself.
return { agentId, metadata: { ...pointer, ...(updates.metadata || {}) } };
}
/**
* Metadata a status transition RETIRES, as `[transition field, keys]` rows applied
* in order by `writeTaskUpdate`. One row per subsystem the transition releases —
* adding a lifecycle clear is a row here, not another hand-written predicate in the
* middle of the write.
*
* ORDER IS BEHAVIOR: the `leavesBlocked` row clears `blockedCategory`, and the
* resume-pointer drop below the loop reads that same key to decide whether the
* block was a PAUSE. A paused task flipped straight to `completed` is therefore no
* longer pause-categorized by the time the pointer is evaluated, and its spent
* pointer drops — pinned by cosTaskStore.test.js.
*
* The retry hold and the federation claim are two rows even though both key on
* `leavesInProgress`: they release different subsystems (#3373's cleanup handshake
* and #1563's cross-peer lease) and are separately documented at their sites. What
* they must never do again is drift, so they read the ONE descriptor field rather
* than each re-testing `updates.status !== 'in_progress'`.
*/
const TRANSITION_METADATA_CLEARS = Object.freeze([
// An explicit retry or new cycle cancels the old cleanup coordinator.
['isRequeue', ['deliveryRecovery', 'deliveryRecoveryAgentId']],
['isRevive', ['deliveryRecovery', 'deliveryRecoveryAgentId']],
// Leaving `blocked` by any door — a dedupe revive, an autopilot re-dispatch, an
// orphan-cooldown expiry, or a human unblocking it from the task list. Clearing
// only in `resumeAgent` left every one of those paths running a task that still
// advertised a live pause: the UI kept showing it parked, and `resumeAgent` on the
// still-paused agent record then read its own pause as spent and spawned a SECOND
// agent on a fresh task. The failure counters go too, or the revived task
// re-blocks on the budget it blocked with.
['leavesBlocked', ['blocker', 'blockedReason', 'blockedCategory', 'blockedAt', 'deliveryDecisionAgentId', 'failureCount', 'lastErrorCategory', 'lastFailureAt', ...PAUSE_METADATA_KEYS]],
// A retry hold (#3373) only means anything while the task is `in_progress` waiting
// on a cleanup to resolve its resume pointer. Any other status the task reaches —
// terminal, or a requeue some other path performed — retires it, so drop the marker
// rather than leave a stale one for a late cleanup (or the orphan sweep) to act on.
['leavesInProgress', [RETRY_HOLD_KEY, RETRY_HOLD_SINCE_KEY]],
// Release the federation claim/lease (#1563). A claim only protects in-flight work;
// once the task completes, fails back to pending, or is blocked, it must become
// freely claimable by either peer — a stale lease blocks a legitimate retry (by this
// instance or its peer) for a full lease window.
['leavesInProgress', CLAIM_METADATA_KEYS]
]);
/**
* Merge an `updateTask` patch's metadata onto the task's existing metadata, in the
* shape the store persists. Purely about the PATCH's shape — it answers nothing
* about the status transition, which `resolveTaskStatusTransition` owns.
*
* Legacy direct fields use ?? not ||, so an intentional clear to "" is preserved
* as "" rather than dropped: || maps every falsy value (incl. "") to undefined,
* which `writeTaskUpdate`'s cleanup pass then deletes, conflating "cleared" with
* "absent" (absent-vs-cleared, AGENTS.md). Only null becomes undefined (→ deleted);
* absent fields never enter the loop.
*
* The orchestration pins are re-normalized after that verbatim copy (#5992) so an
* update lands the same persisted shape `addTask` writes: a profile of empty role
* objects, or the default `direct` mode, is stored as absent rather than as an
* inert override. A null from the route still arrives here as `undefined` and is
* deleted by the cleanup pass — an explicit clear.
*/
function mergeUpdateMetadata(existingMetadata, updates) {
const merged = { ...existingMetadata, ...(updates.metadata || {}) };
for (const f of LEGACY_DIRECT_FIELDS) {
if (updates[f] !== undefined) merged[f] = updates[f] ?? undefined;
}
if (merged.orchestrationProfile !== undefined) {
merged.orchestrationProfile = normalizeOrchestrationProfile(merged.orchestrationProfile) ?? undefined;
}
if (merged.orchestrationMode !== undefined) {
merged.orchestrationMode = normalizeOrchestrationMode(merged.orchestrationMode) === 'orchestrated' ? 'orchestrated' : undefined;
}
return merged;
}
async function writeTaskUpdate(taskId, updates, taskType, options) {
return withStateLock(() => writeTaskUpdateLocked(taskId, updates, taskType, options));
}
// Caller holds withStateLock, including its status and ownership decision.
async function writeTaskUpdateLocked(taskId, updates, taskType, { now, suppressDequeue = false, expectedStatus = null, expectedMetadata = null, expectedTask = null, recoveryOwner = null, preserveRetryBudget = false }) {
const tasks = await readTaskFile(taskType);
let taskIndex = tasks.findIndex(t => t.id === taskId);
// A history item older than the working set can still be edited or reopened:
// fetch it by id into the list being saved; the save upserts its row in place.
if (taskIndex === -1) {
const stored = await getStoredTask(taskId, taskType);
if (stored) {
tasks.push(stored.task);
taskIndex = tasks.length - 1;
}
}
if (taskIndex === -1) {
console.log(`⚠️ updateTask: task ${taskId} not found in the ${taskType} queue (working set of ${tasks.length} tasks, status update: ${updates.status || 'none'})`);
return { error: 'Task not found' };
}
// Deterministic sweepers can retire a queued task only while it is still
// pending. Check under the same lock as the write so a concurrent dequeue or
// user action cannot be overwritten by a stale queue snapshot.
if (expectedStatus && tasks[taskIndex].status !== expectedStatus) {
return { statusChanged: true, task: tasks[taskIndex] };
}
const current = tasks[taskIndex];
if (expectedTask && Object.entries(expectedTask).some(([key, value]) => !isDeepStrictEqual(current[key], value))) {
return { statusChanged: true, task: current };
}
if (recoveryOwner) {
const state = await loadState();
const registered = state.agents?.[recoveryOwner.id];
const competing = Object.values(state.agents || {}).some(agent => agent.id !== recoveryOwner.id
&& agent.taskId === taskId && ['running', 'paused'].includes(agent.status))
|| [activeAgents, runnerAgents].some(entries => [...entries].some(([id, agent]) => id !== recoveryOwner.id
&& (agent.taskId || agent.task?.id) === taskId));
if (competing || (registered && registered.startedAt !== recoveryOwner.startedAt)) return { statusChanged: true, task: current };
}
if (expectedMetadata && Object.entries(expectedMetadata).some(([key, value]) => current.metadata?.[key] !== value)) {
return { statusChanged: true, task: current };
}
if (updates.status === 'pending' && isLegacyDeepAudit(current.metadata)) return { error: 'Historical Deep certification tasks are read-only; start a new Deep audit' };
if (updates.status === 'pending' && current.metadata?.auditDepth === 'deep' && isRetryHeld(current.metadata)) {
// Extended audits retry normally after cleanup. Only the guarded release of
// this exact persisted hold may make one spawnable; a bare Resume/Run must
// still wait, and legacy certification records remain read-only above.
const releasesCurrentHold = expectedStatus === 'in_progress'
&& expectedMetadata?.[RETRY_HOLD_KEY] === current.metadata[RETRY_HOLD_KEY]
&& Object.hasOwn(updates.metadata || {}, RETRY_HOLD_KEY)
&& updates.metadata[RETRY_HOLD_KEY] === undefined;
if (!releasesCurrentHold) return { error: 'Deep checkpoint cleanup is still pending; resume after cleanup finishes' };
}
const runtimeHeld = current.status === 'blocked' && current.metadata?.blockedCategory === 'runtime-verification';
const runtimeRelease = runtimeHeld && updates.status === 'pending'
&& expectedStatus === 'blocked' && expectedMetadata?.runtimeVerificationId === current.metadata.runtimeVerificationId
&& updates.metadata?.runtimeVerification?.status === 'resumed';
if (runtimeHeld && updates.status && updates.status !== 'blocked' && !runtimeRelease) {
return { error: 'Runtime verification prerequisite must be released by its server coordinator' };
}
const updatedMetadata = mergeUpdateMetadata(tasks[taskIndex].metadata, updates);
// Ask "what status transition is this?" ONCE. Every lifecycle rule below reads a
// field off this descriptor instead of re-deriving an answer from
// `(previousStatus, updates.status)` at its own site — which is how the retry-hold
// clear and the claim release ended up as the same predicate written twice, and
// how the requeue stamp and the emitted action came to key on the same edge from
// 52 lines apart while having to agree (#6620).
const previousStatus = tasks[taskIndex].status;
const transition = resolveTaskStatusTransition(previousStatus, updates.status);
// Retire the metadata this transition releases. Ordered — see the table's note on
// the `blockedCategory` clear feeding the resume-pointer check below.
for (const [field, keys] of TRANSITION_METADATA_CLEARS) {
if (!transition[field]) continue;
for (const key of keys) {
if (runtimeRelease && ['failureCount', 'lastErrorCategory', 'lastFailureAt'].includes(key)) continue;
delete updatedMetadata[key];
}
}
// Automatic delivery recovery continues the charged attempt, unlike an
// explicit human revive. Persist its budget in the same write as its hold.
if (preserveRetryBudget && expectedStatus === 'blocked' && expectedTask && transition.leavesBlocked
&& updates.status === 'in_progress' && typeof updates.metadata?.retryPendingCleanup === 'string') {
for (const key of ['failureCount', 'lastErrorCategory', 'lastFailureAt']) {
if (Object.hasOwn(updates.metadata, key)) updatedMetadata[key] = updates.metadata[key];
}
}
// Drop the resume pointer once the task reaches a terminal state. `existingBranch`
// + `resumeWorktreePath` + `resumedFromAgentId` are stamped by
// `resolveTaskResumePatch` so a FAILED or ORPHANED task's retry picks up the
// branch (and worktree) its dead agent left behind and resumes instead of
// restarting. Once the task is done (or blocked for a human), that pointer is
// spent: a PERPETUAL task type re-queues the same task id for unrelated future
// work, and a stale `existingBranch` would silently attach that fresh run to a
// long-merged branch. Only cleared on terminal statuses — a `pending` retry is
// exactly who needs the pointer intact.
//
// PAUSE-shaped blocks are the exception (`PAUSED_BLOCKED_CATEGORIES`): the task
// is waiting on something outside itself and is expected to run again, so its
// pointer is not spent. `orphan-cooldown` is a TIMED pause —
// `unblockExpiredCooldowns` (cosTaskGenerator.js) flips it back to
// `pending` once `cooldownUntil` passes. The workspace blocks are a CONFIG pause:
// the app's Repository Path is missing/unreachable, and the user fixes it and
// revives the task. Stripping the pointer in either case means the revived task
// starts clean and abandons the worktree its dead agent left behind — which is
// exactly the recovery this mechanism exists for.
if (transition.isTerminal && !PAUSED_BLOCKED_CATEGORIES.has(updatedMetadata.blockedCategory)) {
// The shared predicate identifies only retry-owned `existingBranch` pointers.
// Review-loop follow-ups own `reviewLoopPRBranch`, so their canonical target
// remains intact even when a legacy duplicate is removed here.
if (shouldStripTaskTargetBranch(updatedMetadata)) delete updatedMetadata.existingBranch;
delete updatedMetadata.resumedFromAgentId;
delete updatedMetadata.resumeWorktreePath;
delete updatedMetadata.claimResumeInPlace;
}
// Stamp the moment a RUNNING task is requeued (#3376). `in_progress → pending`
// is the one backward transition in the lifecycle (the orphan sweep and the
// retry-hold release both perform it), and the federated merge has to be able to
// tell that requeue apart from an ordinary content edit that merely happens to
// land on a peer's stale `pending` copy — the first must beat a stale
// `in_progress` snapshot, the second must NOT revert a genuinely running task.
// `updatedAt` alone can't distinguish them; this stamp, compared against the
// other side's `lastSpawnedAt`, says the requeue came AFTER that spawn. Only the
// real transition sets it, so a later edit carries it forward untouched, and the
// next spawn clears it below.
if (transition.isRequeue) {
updatedMetadata[REQUEUED_AT_KEY] = new Date(now).toISOString();
}
// A fresh spawn retires the marker — from here on THIS run's `lastSpawnedAt` is
// what a future requeue must beat, and a leftover stamp from the previous cycle
// would let a peer's pre-spawn `pending` copy win on a stale requeue.
if (transition.entersInProgress) delete updatedMetadata[REQUEUED_AT_KEY];
// Bump the content-edit stamp (#1714) on a genuine content change so the peer's
// claim-aware merge can resolve a same-status edit by newest-edit-wins. Compared
// against the task's CURRENT metadata so a lease-renewal heartbeat that re-includes
// unchanged metadata doesn't read as an edit (see isContentEdit). `now` is
// injectable for deterministic test output.
if (isContentEdit(updates, tasks[taskIndex].metadata)) {
updatedMetadata.updatedAt = new Date(now).toISOString();
}
// Clean undefined values from metadata
Object.keys(updatedMetadata).forEach(key => {
if (updatedMetadata[key] === undefined) delete updatedMetadata[key];
});
// Collapse a multi-line description to the one-line record the markdown row can
// hold, re-homing the body into prompt/context rather than dropping it (#7240).
const normalizedDescription = normalizeUpdatedDescription(updates.description, updatedMetadata);
const nextMetadata = normalizedDescription ? normalizedDescription.metadata : updatedMetadata;
const nextDescription = normalizedDescription ? normalizedDescription.description : updates.description;
// Update the task. Through `toRepresentableTask` so the object we return and
// emit on `tasks:changed` is the one the file will hold — repairing only inside
// generateTasksMarkdown would leave every consumer reading the pre-repair status
// until something re-read the file (#7239).
const updatedTask = toRepresentableTask({
...tasks[taskIndex],
...(updates.description && { description: nextDescription }),
...(updates.priority && {
priority: updates.priority.toUpperCase(),
priorityValue: PRIORITY_VALUES[updates.priority.toUpperCase()] || 2
}),
...(updates.status && { status: updates.status }),
metadata: nextMetadata
});
tasks[taskIndex] = updatedTask;
await writeTaskList(taskType, tasks);
// `transition.action` distinguishes the two flips that must WAKE the scheduler
// from an ordinary edit. A blocked → pending flip is a revive: the task is newly
// spawnable, exactly like an approval, and cos.init's listener re-runs the dequeue
// on it (#2614) — the generic 'updated' action doesn't, which left revived tasks
// stranded until an unrelated event or timer fired. An in_progress → pending flip
// is a requeue and needs the same wake (#3373): a failed run's retry is released
// from its hold by exactly this transition, and by then the `agent:completed`
// dequeue has long since run — without a signal the retry would idle until the
// next timer. Same for the orphan sweep's requeue, which previously depended on
// its caller remembering to evaluate.
// `previousStatus` rides along so consumers can key on the TRANSITION rather
// than re-deriving one from the level. `updateTask` on an already-terminal task
// re-emits `updated` with the same status — an edit to a completed task's
// description is enough — so a consumer that reacts to "reached completed"
// (the investigation auto-retry; the voice completion line) needs the edge, not
// `status === 'completed'`, which is true on every later write too.
const change = { type: taskType, action: transition.action, task: updatedTask, previousStatus };
if (suppressDequeue) change.suppressDequeue = true;
cosEvents.emit('tasks:changed', change);
return updatedTask;
}
/**
* Explicitly revive a blocked task back to pending (#2614).
*
* The retry path for a failure-blocked duplicate is unblocking the existing
* task, not minting a new one — every explicit dispatch path (on-demand Run,
* pipeline advance, Creative Director re-trigger, manual job trigger, voice
* dispatch) that collides with a blocked twin routes through here. On top of
* updateTask's blocked-transition clear (blocker/blockedReason/blockedCategory/
* blockedAt/failureCount/lastErrorCategory/lastFailureAt), this also resets the
* spawn/orphan retry budgets — a revived task must behave like a fresh one, not
* immediately re-block on the exhausted budget it blocked with. The reset keys
* are spread AFTER the caller's fresh metadata so a carried-forward budget
* (e.g. a pipeline hand-off spreading the prior stage's metadata) can't win.
* updateTask emits `tasks:changed` action 'unblocked', which re-runs the
* dequeue, so callers don't need a separate wake signal.
*/
export async function reviveBlockedTask(taskId, { priority, metadata } = {}, taskType = 'internal', { suppressDequeue = false } = {}) {
return updateTask(taskId, {
status: 'pending',
...(priority ? { priority } : {}),
metadata: {
...(metadata || {}),
totalSpawnCount: undefined,
orphanRetryCount: undefined,
lastOrphanedAt: undefined,
// Same reasoning: the branch-busy patience budget is spent by the time a
// follow-up hard-blocks, so a revived one would hard-block again on the
// first busy race instead of waiting the other worktree out. NOT cleared on
// the cooldown revive (updateTask's blocked→pending path) — that runs on
// every wait and would defeat the cap.
worktreeBusyAttempts: undefined
}
}, taskType, { suppressDequeue });
}
/**
* Merge a full-sync peer's task list into one local task file (#1712).
*
* The receiver side of CoS task federation: `syncCosTasksFromPeer` fetches the
* peer's live backlog and hands the tasks for ONE file (user vs internal) here.
* The read-merge-write runs under `withStateLock` so it serializes against the
* spawn path's claim writes (agentLifecycle → updateTask, also lock-held) — the
* merge always sees, and merges against, the freshest persisted claim metadata.
*
* Idempotent + write-skipping: the claim-aware merge (cosTaskMerge) is pure and
* deterministic, so we compare the GENERATED markdown before/after (not the raw
* file bytes — pre-existing formatting drift shouldn't force a write) and only
* persist + emit `tasks:changed` when the merge actually changed something.
*
* @param {'user'|'internal'} taskType which file to merge into
* @param {Array} remoteTasks peer tasks for this file (wire-validated)
* @param {{ now?: number }} [opts] injectable clock for deterministic tests
* @returns {Promise<{ changed: boolean, count?: number }>}
*/
export async function mergePeerTasks(taskType, remoteTasks, { now = Date.now() } = {}) {
validateRequest(cosTaskTypeSchema, taskType);
const { changed, count, merged } = await withStateLock(async () => {
const localTasks = await readTaskFile(taskType);
// A peer still advertises completed tasks this machine already holds in
// history; merging them in would pull them back into the working set.
const remoteCompletedIds = remoteTasks.filter((task) => task?.status === 'completed').map((task) => task.id);
const knownCompleted = await getCompletedTaskIds(taskType, remoteCompletedIds);
const incoming = knownCompleted.size === 0
? remoteTasks
: remoteTasks.filter((task) => !(task?.status === 'completed' && knownCompleted.has(task.id)));
const merged = mergeTaskLists(localTasks, incoming, { now });
// Nothing the peer sent changed our state — skip the write (and the event that would
// wake the scheduler). `merged` is still returned so the post-lock LI-verdict consume
// (#2779) can run even on a no-op sweep — durability requires it (an old peer that
// stored a terminal verdict before upgrading, or a crash before a prior consume, leaves
// the task terminal with the merge producing no change, so a changed-only consume would
// never catch up). Re-offering is cheap: the consumer is a durable no-op after the first.
if (!await writeTaskList(taskType, merged, localTasks)) return { changed: false, merged };
cosEvents.emit('tasks:changed', { type: taskType, action: 'peer-merged' });
return { changed: true, count: merged.length, merged };
});
// Post-lock, best-effort: derive recordProposalExecution from every terminal hand-off task
// carrying an LI execution verdict (#2779) — a task filed here but executed on a peer, whose
// terminal state (with the stamped LI_EXECUTION_VERDICT_KEY) has synced back. Runs on EVERY
// sweep (changed or not); idempotency + retry-correctness are durable and record-level in the
// consumer (skips a verdict no newer than the stored execution), so re-offering the same
// verdict is a no-op while a genuinely re-executed hand-off overwrites. `requireExisting`
// there scopes the write to a proposal THIS peer filed, so a non-originating peer is a no-op.
// Kept out of the lock — recordProposalExecution touches a different store (li-outcomes) — and
// the LI import graph stays off cosTaskStore's static chain (lazy import).
const { LI_EXECUTION_VERDICT_KEY, recordProposalExecutionFromVerdict } = await import('./layeredIntelligenceOutcomes.js');
for (const task of merged || []) {
if (!isTerminalTaskStatus(task?.status)) continue;
const verdict = task?.metadata?.[LI_EXECUTION_VERDICT_KEY];
if (!verdict) continue;
await recordProposalExecutionFromVerdict(verdict)
.catch(err => console.error(`❌ 📚 cosTaskStore: failed to consume LI execution verdict: ${err.message}`));
}
return changed ? { changed, count } : { changed: false };
}
/**
* Delete a task
*/
export async function deleteTask(taskId, taskType = 'user') {
validateRequest(cosTaskTypeSchema, taskType);
return withStateLock(async () => {
// One row delete, whether the task is in the working set or old history. It
// bumps the queue version, which is what makes the next read reload.
if (await deleteStoredTask(taskId, taskType) === 0) return { error: 'Task not found' };
cosEvents.emit('tasks:changed', { type: taskType, action: 'deleted', taskId });
return { success: true, taskId };
});
}
/**
* Recover the scalar-version mismatch and retire genuinely unscreened system
* tasks before they can occupy the scheduler's dedup slots. History remains;
* a retired prompt is never upgraded by stamping it with a screening marker.
* Ownership and fresh queue state are checked under the same lock as writes.
*/
export async function reconcileLegacyForgeMaintenanceTasks({ instanceId, now = Date.now() } = {}) {
return withStateLock(async () => {
const state = await loadState();
const tasks = await readTaskFile('internal');
let recovered = 0;
let retired = 0;
const resetApps = new Set();
for (const task of tasks) {
if (!isForgeMaintenanceTask(task) || getSkipReason(task.metadata, instanceId, now)
|| hasActiveTaskOwner(task.id, state.agents)) continue;
const erroneousBlock = task.status === 'blocked'
&& task.metadata?.blockedCategory === 'provider-config'
&& task.metadata?.blockedReason === LEGACY_FORGE_MAINTENANCE_REASON;
if (task.status !== 'pending' && !erroneousBlock) continue;
const screened = hasCurrentForgeMaintenanceEvidence(task);
if (screened && !erroneousBlock) continue;
// Unknown future versions belong to their own compatibility contract.
if (!screened && task.metadata?.forgeMaintenanceVersion != null) continue;
if (!screened && task.metadata.analysisType === 'pr-watcher' && task.metadata.app
&& !resetApps.has(task.metadata.app)) {
const { persistPrWatcherState } = await import('./prWatcher.js');
// Old discovery may have acknowledged the PRs before screening existed.
// Keep the baseline; empty activity makes current open PRs retryable.
await persistPrWatcherState(task.metadata.app, { activityByPr: {} });
resetApps.add(task.metadata.app);
}
await writeTaskUpdateLocked(task.id, {
status: screened ? 'pending' : 'completed',
metadata: screened
? { maintenanceRecoveredAt: new Date(now).toISOString() }
: { resolution: 'superseded', supersededReason: 'unscreened-forge-maintenance', supersededAt: new Date(now).toISOString() }
}, 'internal', { now, suppressDequeue: true });
if (screened) recovered++; else retired++;
}
return { recovered, retired };
});
}
// ── Stale failure-artifact reaper (issue #2619) ──────────────────────────────
//
// After a failure storm is fixed, nothing retired what it left behind: tasks
// parked in `blocked` by a failure category, and the `[Auto] Investigate agent
// failure` tasks filed against them. They persisted indefinitely and stayed
// input to every generator/learning read. The sweep below runs on the CoS
// health tick and resolves them via STATUS FLIP (→ completed + a `resolution:
// 'auto-expired'` marker), NEVER deletion: LWW federation sync does not
// propagate deletions, so a delete just resurrects from any peer still holding
// the row.
// Default age a failure-blocked task must exceed before it is auto-expired.
export const DEFAULT_FAILURE_TASK_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000; // 14 days
// Max tasks the reaper flips in a single sweep — bounded so one tick can't fan
// out an unbounded burst of writes/`tasks:changed` events after a large storm.
export const DEFAULT_REAP_LIMIT = 50;
// Blocks that encode USER INTENT or an OPEN user decision are the reaper's
// exemption (`USER_DECISION_BLOCKED_CATEGORIES`, lib/taskBlockCategories.js).
// Everything else with a `blockedCategory` is a failure-path block and therefore
// reapable — including `orphan-cooldown`, which revives itself in ~30 minutes, so
// one still sitting there after 14 days IS stale.
/**
* Age (ms) of a failure-blocked task, read from the most specific timestamp it
* carries. Returns null when the task is not a reapable failure block, or when
* it has no parseable timestamp — an undated block is never reaped (we can't
* prove it is old, so leaving it is the safe default). Pure.
*/
export function blockedFailureAgeMs(task, now = Date.now()) {
if (task?.status !== 'blocked') return null;
const category = task.metadata?.blockedCategory;
if (!category || USER_DECISION_BLOCKED_CATEGORIES.has(category)) return null;
const stampedAt = task.metadata?.blockedAt
|| task.metadata?.lastFailureAt
|| task.metadata?.updatedAt;
const t = Date.parse(stampedAt);
if (!Number.isFinite(t)) return null;
return Math.max(0, now - t);
}
/** True when a failure-blocked task is old enough to auto-expire. Pure. */
export function isReapableBlockedFailure(task, { now = Date.now(), maxAgeMs = DEFAULT_FAILURE_TASK_MAX_AGE_MS } = {}) {
const age = blockedFailureAgeMs(task, now);
return age !== null && age >= maxAgeMs;
}
/**
* True when an investigation task's originating task(s) are all resolved —
* absent (already reaped/deleted) or in a terminal `completed` status — so the
* investigation no longer tracks any live failure. Requires a known originating
* link (`metadata.affectedTasks`); a legacy investigation with no link is left
* alone (we can't prove its cause is resolved). Pure.
*
* @param {object} task the candidate investigation task
* @param {Map} tasksById id → task across BOTH queues
*/
export function isReapableInvestigation(task, tasksById) {
if (!isInvestigationTask(task)) return false;
if (task.status === 'completed') return false; // already terminal
// An in-progress investigation has a live agent diagnosing it; reaping it
// would let a later finalize regress the status or spawn a second run (#12059).
if (task.status === 'in_progress') return false;
const affected = Array.isArray(task.metadata?.affectedTasks) ? task.metadata.affectedTasks : [];
if (affected.length === 0) return false;
return affected.every((id) => {
const origin = tasksById?.get(id);
return !origin || origin.status === 'completed';
});
}
/**
* Sweep resolved failure artifacts and auto-expire them via status flip (#2619).
*
* Two categories, both resolved to `completed` with a `resolution: 'auto-expired'`
* marker (never deleted — federation-safe): (1) tasks parked in `blocked` by a
* failure `blockedCategory` older than `maxAgeMs`, and (2) `[Auto] Investigate
* agent failure` tasks whose originating task(s) are gone/completed. Bounded to
* `limit` flips per call and single-line-logged. Runs off the health tick.
*
* @param {{ now?:number, maxAgeMs?:number, limit?:number }} [opts]
* @returns {Promise<{ reaped:number, staleBlocks:number, investigations:number }>}
*/
export async function sweepResolvedFailureTasks({
now = Date.now(),
maxAgeMs = DEFAULT_FAILURE_TASK_MAX_AGE_MS,
limit = DEFAULT_REAP_LIMIT
} = {}) {
const { user, cos } = await getAllTasks();
const userTasks = user?.tasks || [];
const cosTasks = cos?.tasks || [];
const tasksById = new Map([...userTasks, ...cosTasks].map((t) => [t.id, t]));
// Collect targets across both queues, tagging each with its file type so the
// flip writes back to the right markdown store. Bounded by `limit`.
const targets = [];
for (const [type, list] of [['user', userTasks], ['internal', cosTasks]]) {
for (const task of list) {
const reason = isReapableBlockedFailure(task, { now, maxAgeMs })
? 'stale-failure-block'
: (isReapableInvestigation(task, tasksById) ? 'investigation-resolved' : null);
if (reason) targets.push({ task, type, reason });
if (targets.length >= limit) break;
}
if (targets.length >= limit) break;
}
if (targets.length === 0) return { reaped: 0, staleBlocks: 0, investigations: 0 };
let staleBlocks = 0;
let investigations = 0;
for (const { task, type, reason } of targets) {
// Re-read BOTH queues and re-evaluate the reason under the same lock as the
// write. Status/metadata pins protect a target from its own stale snapshot,
// but an investigation also depends on its origins: one can be resumed after
// this sweep's snapshot while the investigation itself stays pending (#12059).
const updated = await withStateLock(async () => {
const current = await getAllTasks();
const currentTask = (type === 'user' ? current.user.tasks : current.cos.tasks)
.find((candidate) => candidate.id === task.id);
if (!currentTask) return { statusChanged: true };
const currentById = new Map([...current.user.tasks, ...current.cos.tasks].map((candidate) => [candidate.id, candidate]));
const currentReason = isReapableBlockedFailure(currentTask, { now, maxAgeMs })
? 'stale-failure-block'
: (isReapableInvestigation(currentTask, currentById) ? 'investigation-resolved' : null);
if (currentReason !== reason) return { statusChanged: true, task: currentTask };
return writeTaskUpdateLocked(task.id, {
status: 'completed',
metadata: { resolution: 'auto-expired', autoExpiredReason: reason, autoExpiredAt: new Date(now).toISOString() }
}, type, {
now,
expectedStatus: task.status,
// A revived task can fail again before this write and return to blocked.
// Preserve the category and every age fallback that justified this sweep.
expectedMetadata: reason === 'stale-failure-block' ? {
blockedCategory: task.metadata?.blockedCategory,
blockedAt: task.metadata?.blockedAt,
lastFailureAt: task.metadata?.lastFailureAt,
updatedAt: task.metadata?.updatedAt,
} : null,
});
});
if (updated?.error || updated?.statusChanged) continue;
if (reason === 'stale-failure-block') staleBlocks++; else investigations++;
}
const reaped = staleBlocks + investigations;
if (reaped > 0) {
console.log(`🧹 Reaped ${reaped} resolved failure task(s): ${staleBlocks} stale block(s), ${investigations} investigation(s)`);
}
return { reaped, staleBlocks, investigations };
}
/**
* Reorder user tasks based on an array of task IDs
*/
export async function reorderTasks(taskIds) {
return withStateLock(async () => {
const tasks = await readTaskFile('user');
// Create a map of tasks by ID for quick lookup. Ids are the row key, so this
// Map can't silently collapse colliding tasks and drop them on write-back.
const taskMap = new Map(tasks.map(t => [t.id, t]));
// Reorder based on the provided order
const reorderedTasks = [];
for (const id of taskIds) {
const task = taskMap.get(id);
if (task) {
reorderedTasks.push(task);
taskMap.delete(id);
}
}
// Append any tasks not in the provided order (shouldn't happen, but safe)
for (const task of taskMap.values()) {
reorderedTasks.push(task);
}
await writeTaskList('user', reorderedTasks, tasks);
cosEvents.emit('tasks:changed', { type: 'user', action: 'reordered' });
return { success: true, order: reorderedTasks.map(t => t.id) };
});
}
/**
* Approve a task that requires approval (marks it as auto-approved).
*
* Emits `tasks:changed` with `action: 'approved'`; cos.js's init listener
* fires `dequeueNextTask` off that so the newly approved task can spawn
* immediately.
*/
export async function approveTask(taskId, { now = Date.now() } = {}) {
return withStateLock(async () => {
// Both queues, internal first. A USER row can hold too: a row the parser had
// to RECOVER is withheld from the unattended spawn and now persists that hold
// as `| APPROVAL |` (#7300, #7367). Without a release path here that row is a
// zombie — pending forever, with nothing in the product able to clear it —
// which is a worse outcome than the evaporating hold it replaced.
let found = null;
for (const taskType of ['internal', 'user']) {
const tasks = await readTaskFile(taskType);
const taskIndex = tasks.findIndex(t => t.id === taskId);
if (taskIndex !== -1) {
found = { taskType, tasks, taskIndex };
break;
}
}
if (!found) {
return { error: 'Task not found' };
}
const { taskType, tasks, taskIndex } = found;
if (!tasks[taskIndex].approvalRequired) {
return { error: 'Task does not require approval' };
}
// Update approval flags. Approval is editable content (the merge's
// contentSignature counts the approval flags), so bump the `updatedAt` LWW
// stamp (#1714) too — otherwise an approval on one peer would lose a same-status
// tie to a stale edit on the other instead of winning as the newest edit.
tasks[taskIndex] = {
...tasks[taskIndex],
approvalRequired: false,
autoApproved: true,
metadata: { ...tasks[taskIndex].metadata, updatedAt: new Date(now).toISOString() }
};
await writeTaskList(taskType, tasks);
cosEvents.emit('tasks:changed', { type: taskType, action: 'approved', task: tasks[taskIndex] });
const { removeByMetadata } = await import('./notifications.js');
await removeByMetadata('taskId', taskId).catch(() => {});
return tasks[taskIndex];
});
}
/**
* Record a sub-agent's challenge of a reviewer rejection (#2441).
*
* Parks the task in the `challenged` status with the worker's case attached and
* consumes one of its bounded challenge slots (MAX_CHALLENGES_PER_TASK). A second
* dispute on the same task is refused — the acceptance contract is "exactly one
* per task." Read, budget check, and write share the completion/state lock.
*
* @returns the updated task, or `{ error, code }` on not-found / budget-exhausted.
*/
export async function challengeTask(taskId, { reason, evidence, reviewer } = {}, taskType = 'user', { now = Date.now() } = {}) {
return withStateLock(async () => {
const task = await getTaskById(taskId);
if (!task) return { error: 'Task not found', code: 'NOT_FOUND' };
const resolvedType = task.taskType || taskType;
// A challenge disputes a REJECTION of in-flight work — never a finished task.
// Parking a `completed` task in `challenged` would also regress it out of a
// terminal state (a completed task never re-completes), so refuse it outright.
if (task.status === 'completed') {
return { error: 'Cannot challenge a completed task', code: 'CANNOT_CHALLENGE_COMPLETED' };
}
// Bounded by BOTH the one-shot dispute cap AND the shared retry budget (#2471) —
// a challenge that overturns re-queues the task, so refuse one that's already out
// of total spawns (it would only get re-blocked by agentLifecycle's spawn gate).
if (!canChallenge(task.metadata, { maxTotalSpawns: MAX_TOTAL_SPAWNS })) {
const spawns = Number(task.metadata?.totalSpawnCount) || 0;
const budgetExhausted = spawns >= MAX_TOTAL_SPAWNS;
return {
error: budgetExhausted
? `Retry budget exhausted (${spawns}/${MAX_TOTAL_SPAWNS} spawns) — cannot challenge a task out of retries`
: `Challenge budget exhausted (${getChallengeCount(task.metadata)}/${MAX_CHALLENGES_PER_TASK} used)`,
code: budgetExhausted ? 'CHALLENGE_BUDGET_EXHAUSTED' : 'CHALLENGE_EXHAUSTED',
};
}
const patch = buildChallengePatch(task.metadata, { reason, evidence, reviewer, now });
const updated = await writeTaskUpdateLocked(taskId, { status: 'challenged', metadata: patch }, resolvedType, { now });
if (updated?.error) return updated;
console.log(`⚖️ Task ${taskId} challenged (${patch.challengeCount}/${MAX_CHALLENGES_PER_TASK})${patch.challenge.reviewer ? ` — disputing ${patch.challenge.reviewer}` : ''}`);
cosEvents.emit('task:challenged', { taskId, taskType: resolvedType, reviewer: patch.challenge.reviewer || null });
return updated;
});
}
/**
* Resolve a parked challenge (#2441). `upheld` overturns the rejection and
* preserves its active owner (→ in_progress), or requeues an unowned task
* (→ pending); `escalated` hands the unresolved dispute to
* the user — the task is blocked with a challenge-escalation reason AND an
* approval-required arbitration task is filed into COS-TASKS.md (reusing the same
* investigation/escalation surface `createInvestigationTask` writes to), so a
* sustained disagreement surfaces to the user rather than silently fixing or
* quietly blocking.
*
* @returns the updated task, or `{ error, code }` on not-found / not-challenged /
* invalid-outcome.
*/
export async function resolveTaskChallenge(taskId, { outcome, note, resolvedBy } = {}, taskType = 'user', { now = Date.now() } = {}) {
const resolution = await withStateLock(async () => {
const task = await getTaskById(taskId);
if (!task) return { error: 'Task not found', code: 'NOT_FOUND' };
if (task.status !== 'challenged') {
return { error: 'Task is not under challenge', code: 'NOT_CHALLENGED' };
}
const resolvedType = task.taskType || taskType;
const resolutionPatch = buildChallengeResolutionPatch({ outcome, note, resolvedBy, now });
if (!resolutionPatch) return { error: `Invalid challenge outcome: ${outcome}`, code: 'INVALID_OUTCOME' };
const state = await loadState();
const nextStatus = outcome === 'upheld'
? (hasActiveTaskOwner(taskId, state.agents) ? 'in_progress' : 'pending')
: 'blocked';
const metadataPatch = { ...resolutionPatch };
if (outcome === 'escalated') {
metadataPatch.blockedReason = 'Challenge unresolved — escalated to user for arbitration';
metadataPatch.blockedCategory = 'challenge-escalation';
}
const updated = await writeTaskUpdateLocked(taskId, { status: nextStatus, metadata: metadataPatch }, resolvedType, { now });
if (updated?.error) return updated;
return { task, updated, nextStatus, resolvedType };
});
if (resolution.error) return resolution;
const { task, updated, nextStatus, resolvedType } = resolution;
if (outcome === 'escalated') {
// Surface the dispute to the single PortOS user as an approval-required
// arbitration task (mirrors createInvestigationTask's escalation surface).
// Best-effort: a failed escalation-task write must not fail the resolution
// itself (the original task is already blocked with the reason attached).
const caseReason = task.metadata?.challenge?.reason || '(no reason recorded)';
const disputedReviewer = task.metadata?.challenge?.reviewer;
const escalationDescription = `[Challenge] Arbitrate disputed rejection on ${taskId}`;
const escalationContext = [
`A sub-agent challenged a reviewer rejection on task ${taskId} and the dispute is unresolved.`,
disputedReviewer ? `Disputed reviewer: ${disputedReviewer}` : null,
`Worker's case: ${caseReason}`,
note ? `Resolver note: ${note}` : null,
'Decide: approve to overturn the rejection, or delete to let the rejection stand.',
].filter(Boolean).join('\n');
await addTask({
description: escalationDescription,
priority: 'HIGH',
context: escalationContext,
approvalRequired: true,
}, 'internal', { now }).catch((err) => {
console.error(`❌ Failed to file challenge-escalation task for ${taskId}: ${err.message}`);
});
}
console.log(`⚖️ Task ${taskId} challenge resolved: ${outcome} → ${nextStatus}`);
cosEvents.emit('task:challenge-resolved', { taskId, taskType: resolvedType, outcome });
return updated;
}
/**
* Resolve a parked challenge by AUTOMATIC reviewer re-check (#2471). Instead of a
* human verdict, re-run the disputed (or a second) local-LLM reviewer against the
* current diff and derive the outcome from its fresh findings — a blocking finding
* that survives sustains the rejection (→ escalated); nothing blocking overturns it
* (→ upheld). This is the cheap confirm/overturn pass that runs BEFORE falling back
* to user escalation, closing the gap #2470 left ("this slice resolves manually").
*
* Only the in-process local reviewers (`LOCAL_LLM_REVIEWERS`) are re-run here; CLI
* reviewers are re-run by the follow-up agent itself, which then calls the manual
* `resolveTaskChallenge` path with an explicit outcome.
*
* @returns the updated task, or `{ error, code }` on not-found / not-challenged /
* RECHECK_FAILED (reviewer unreachable or no usable findings).
*/
export async function resolveTaskChallengeWithRecheck(taskId, { recheck, resolvedBy } = {}, taskType = 'user', { now = Date.now() } = {}) {
const task = await getTaskById(taskId);
if (!task) return { error: 'Task not found', code: 'NOT_FOUND' };
if (task.status !== 'challenged') {
return { error: 'Task is not under challenge', code: 'NOT_CHALLENGED' };
}
const backend = recheck?.backend;
// Model: explicit override wins, else the Code Review Defaults for this backend.
// Effort has no per-request override (a re-check re-runs the SAME reviewer
// configuration, it doesn't reconfigure it), so it always comes from the
// defaults — but it must come from somewhere: this verdict decides whether a
// disputed rejection is upheld or escalated to the user, and deriving it from a
// pass run at a weaker effort than the user configured is the same silent
// downgrade the pin exists to prevent.
// Read straight off the picked defaults: `pickCodeReviewDefaults` already ran
// every `<reviewer>Effort` scalar through `reviewerEffortsFromDefaults`, so a
// stale level is null by the time it reaches here — same as the model read below.
const recheckDefaults = await getCodeReviewDefaults().catch(() => null);
const effort = recheckDefaults?.[`${backend}Effort`] || null;
// Keyed off the roster's `<reviewer>Model` scalar rather than a per-backend
// branch (matching `POST /api/code-review/local`): the old ollama-or-lmstudio
// ternary read LM STUDIO's model for any third local backend, so an `mtplx`
// re-check ran against a model id from the wrong daemon.
//
// An unset scalar is no longer fatal here: `runLocalCodeReview` falls back to the
// model the backend is actually serving when that answer is unambiguous, so a
// single-model daemon re-checks without one. It reports `code: 'NO_MODEL'` when it
// could not resolve one either, which stays a config problem (4xx) rather than the
// 502 bucket reserved for a reviewer that's actually unreachable.
const model = recheck?.model || reviewerModelsFromDefaults(recheckDefaults)[backend] || null;
console.log(`⚖️ Re-checking challenge on ${taskId} via ${backend} (${model || 'model from the backend'}${effort ? `, ${effort} effort` : ''})`);
const review = await runLocalCodeReview({ backend, model, effort, diff: recheck?.diff });
if (!review?.ok) {
if (review?.code === 'NO_MODEL') return { error: review.error, code: 'RECHECK_NO_MODEL' };
return { error: `Re-check failed: ${review?.error || 'unknown reviewer error'}`, code: 'RECHECK_FAILED' };
}
const outcome = classifyRecheckOutcome(review.findings);
if (!outcome) {
return { error: 'Re-check returned no usable findings', code: 'RECHECK_FAILED' };
}
const verdict = outcome === 'upheld'
? `no blocking findings survived (${backend})`
: `a blocking finding still stands (${backend})`;
// The resolution note is auto-generated from the re-check verdict (any caller
// `note` is intentionally not threaded here — the machine verdict is the record).
// `review.model` rather than `model`: the reviewer resolves an unpinned id from
// what the backend is serving, and the record has to name the model that actually
// produced this verdict, not `null`.
const note = `Auto re-check by ${backend} (${review.model || model}): ${verdict}.`;
return resolveTaskChallenge(taskId, { outcome, note, resolvedBy: resolvedBy || `recheck:${backend}` }, taskType, { now });
}