Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

36.2 KB
Raw Blame
/**
 * CoS Task CRUD, Enhancement, and Evaluation Routes
 */

import { Router } from 'express';
import { z } from 'zod';
import { existsSync } from 'fs';
import { isRepo, notGitRepoMessage } from '../services/git.js';
import { addTask, approveTask, challengeTask, deleteTask, findTaskWithSource, getAllTasks, getTaskById, getTaskView, reorderTasks, resolveTaskChallenge, resolveTaskChallengeWithRecheck, updateTask } from '../services/cosTaskStore.js';
import { evaluateTasks } from '../services/cosTaskGenerator.js';
import { forceSpawnTask } from '../services/cos.js';
import { getAgents } from '../services/cosAgentLifecycle.js';
import { enhanceTaskPrompt } from '../services/taskEnhancer.js';
import { buildClaimWorkTask, buildIssueReplanTask, buildJiraTicketTask } from '../services/cosTaskClaimWork.js';
import { getAppById, getAppWorkTracker, PORTOS_APP_ID } from '../services/apps.js';
import { prepareAppIssueClaim } from '../services/appIssues.js';
import { getAssignableInstances } from '../services/instances.js';
import { resolveManagedAppIssueTarget } from '../services/managedAppRepositories.js';
import { resolveAppPrCompletion } from '../lib/prDisposition.js';
import { workTrackerLabel } from '../lib/workTracker.js';
import { runningAgentsByTaskId, settleTaskSourceSpawnWindow } from '../lib/cosSpawnWindow.js';
import { getSlashdoWorkflow, slashdoWorkflowAppliesTo, SLASHDO_COMMAND_NAMES } from '../lib/slashdoCatalog.js';
import { NON_PM2_TYPES } from '../services/appProcessTypes.js';
import { asyncHandler, ServerError, failValidation } from '../lib/errorHandler.js';
import { recordUserAction } from '../services/userActions.js';
import { fileInvestigationTask } from '../services/investigationTaskProducer.js';
import { reportGoalFidelityFalsePositive } from '../services/goalFidelityCalibration.js';
import { CLIENT_INVESTIGATION_DELIVERY, clientInvestigationFingerprint } from '../lib/investigationTasks.js';
import {
  createCosTaskSchema,
  slashdoTaskSchema,
  updateCosTaskSchema,
  challengeTaskSchema,
  resolveChallengeSchema,
  goalFidelityFalsePositiveSchema,
  validateRequest,
  cosTaskReorderBodySchema,
  cosTaskDeleteQuerySchema,
  isPaginationRequested,
  parsePagination,
} from '../lib/validation.js';

const enhanceTaskSchema = z.object({
  description: z.string().min(1),
  context: z.string().optional(),
});

// ── Operator-action ledger (#5594) ──────────────────────────────────────────
//
// Hooked at the THREE HTTP create routes below rather than at
// `cosTaskStore.addTask`, which is ALSO the generator / autopilot / mind dispatch
// path. Only a request arriving here is a human pressing a button, and the whole
// point of the ledger is to separate those from everything PortOS queues itself.
//
// Every write is awaited before the response (same posture as `history.logAction`),
// and every hook fires only AFTER the mutation succeeded — a 409/404 is not an
// operator action that happened.
const TASK_CREATE_PAYLOAD_FIELDS = [
  'prompt', 'description', 'context', 'provider', 'model', 'effort', 'app',
  'orchestrationMode', 'orchestrationProfile',
  'useWorktree', 'openPR', 'prCompletion', 'planOnly', 'reviewLoop', 'reviewers',
  'approvalRequired', 'isInvestigation', 'noChangeSuccess',
  // The one create field with an open shape (`cosTaskDiagnosticsSchema` is a
  // passthrough), so it is both the most informative thing to keep and the reason
  // `recordUserAction` redacts credential-shaped keys at all.
  'diagnostics',
];

const routeSource = (req) => ({ route: `${req.baseUrl}${req.route?.path ?? ''}`, method: req.method });

const pickDefined = (source, fields) => Object.fromEntries(
  fields.filter((field) => source?.[field] !== undefined).map((field) => [field, source[field]]),
);

// The task change has committed before these diagnostic ledger writes. A ledger
// outage must not turn it into a failed request that encourages another mutation.
const recordCommittedTaskAction = (action) => recordUserAction(action).catch((err) => {
  console.error(`❌ Failed to record ${action.type} after task mutation: ${err.message}`);
});

async function logTaskCreated(req, task, taskData) {
  await recordCommittedTaskAction({
    type: 'cos.task.create',
    target: task.id,
    targetName: task.description,
    summary: `Queued CoS task: ${task.description}`,
    payload: { taskId: task.id, ...pickDefined(taskData, TASK_CREATE_PAYLOAD_FIELDS) },
    source: routeSource(req),
    dedupeKey: `cos.task.create:${task.id}`,
  });
}

// One-off "implement THIS JIRA ticket" task (the per-card play button on the
// app overview's sprint board). `ticketKey` is a JIRA key like `PROJ-1234`.
const jiraTicketTaskSchema = z.object({
  app: z.string().min(1),
  ticketKey: z.string().trim().regex(/^[A-Za-z][A-Za-z0-9]*-\d+$/, 'Invalid JIRA ticket key'),
});

// Reject a task pinned to an instance this install does not know (#4520). The
// picker only offers registry members, so this catches the two ways a bad pin
// still arrives: a hand-crafted request, and a peer removed between the form
// render and the submit. A pin no instance matches is worse than none — every
// peer would pass over the task and it would sit pending forever.
async function assertAssignableInstance(instanceId) {
  const assignable = await getAssignableInstances();
  if (assignable.some(i => i.instanceId === instanceId)) return;
  throw new ServerError('Unknown instance — pick one of this install\'s federated instances', { status: 400, code: 'UNKNOWN_INSTANCE' });
}

// Worktree/PR delivery needs a git checkout; refuse at creation rather than
// letting the task block at spawn. A missing directory is left to the spawn-time
// workspace validation, which has its own message.
async function assertWorktreeCapableApp(taskData) {
  if (!taskData.app || !(taskData.useWorktree || taskData.openPR)) return;
  const app = await getAppById(taskData.app);
  if (!app?.repoPath || !existsSync(app.repoPath)) return app;
  if (!(await isRepo(app.repoPath))) {
    throw new ServerError(notGitRepoMessage(app.name || taskData.app), { status: 400, code: 'NOT_A_GIT_REPO' });
  }
  return app;
}

const ISSUE_TRACKERS = new Set(['github', 'gitlab']);

function issueTargetInstructions(target, tracker) {
  if (!target?.fullName) {
    return '## Issue repository\n\nBefore filing, inspect whether the checkout origin is a fork. If it is, file on the canonical upstream repository rather than the origin fork. Do not rely on the working directory\'s implicit forge target.';
  }
  const role = target.role === 'upstream' ? 'canonical upstream' : 'configured origin';
  const repoFlag = tracker === 'github' ? (target.repoSpec || target.fullName) : target.fullName;
  const cli = tracker === 'github' ? 'gh' : 'glab';
  return `## Issue repository\n\nFile this issue on the ${role} repository \`${target.fullName}\`. Pass \`--repo ${repoFlag}\` to every \`${cli} issue\`, label, and related repository command; do not let \`${cli}\` infer the origin fork from the working directory.`;
}

// The bundled plan-task workflow files an issue; resolve the app's canonical
// destination before queueing so a checkout whose origin is a fork does not
// silently file project work on that fork. The form may deliberately choose the
// origin; upstream is the unattended/default posture.
async function preparePlanOnlyTask(taskData, knownApp = null) {
  if (taskData.planOnly !== true && taskData.slashdoCommand !== 'plan-task') return taskData;
  const appId = taskData.app || PORTOS_APP_ID;
  const [trackerInfo, app] = await Promise.all([
    getAppWorkTracker(appId),
    knownApp ? Promise.resolve(knownApp) : getAppById(appId),
  ]);
  if (trackerInfo && !ISSUE_TRACKERS.has(trackerInfo.resolved)) {
    throw new ServerError(
      `Plan-and-file tasks require a GitHub or GitLab issue tracker (resolved to ${trackerInfo.resolved})`,
      { status: 400, code: 'UNSUPPORTED_PLAN_ONLY_TRACKER' }
    );
  }
  if (!app || !trackerInfo) return taskData;
  const target = await resolveManagedAppIssueTarget(app, taskData.issueTarget || 'upstream').catch(() => null);
  const targetPrompt = issueTargetInstructions(target, target?.forge || trackerInfo.resolved);
  return { ...taskData, prompt: [taskData.prompt, targetPrompt].filter(Boolean).join('\n\n') };
}

const router = Router();

// GET /api/cos/tasks - Get all tasks (user + internal), grouped by source.
//
// Settled for the spawn window (lib/cosSpawnWindow.js): an agent registers as
// `running` a beat before its task leaves `pending`, so a caller that counted
// `grouped.pending` raw reported the one task it was already working as queued
// too. Settling HERE rather than in `getAllTasks()` keeps the dispatch readers
// (task generation, retry revival, dedup) on the raw truth they need, while
// every API consumer gets an honest queue depth without knowing the window
// exists. The bounded views (`getTaskView`) select from the parsed snapshot
// before cloning; only `view=full` pays for the whole store.
//
// With no params it returns a bounded `{ user, cos }` projection: all non-completed
// tasks plus grouped/derived lists, and only the first page of completed history
// (+ `completedCount`/`completedNextCursor`; page on with `view=completed`).
// `view=full` returns everything the task files hold (open queue + the recent completed
// window); older completed tasks live in the archive and page through `view=completed`.
// When a client passes
// `limit`/`offset`, each source is reduced to a *genuinely bounded* shape: the
// windowed `tasks` slice plus scalar metadata only. The full-set derived
// collections (`grouped`, `autoApproved`, `awaitingApproval`) are dropped from
// the paginated branch — keeping them would re-include the entire queue the
// caller asked to page through, defeating the bound. A `pagination` block with
// the true per-source totals is added so the caller can page.
router.get('/tasks', asyncHandler(async (req, res) => {
  const query = validateRequest(z.object({
    view: z.enum(['queue', 'completed', 'full']).optional(),
    source: z.enum(['user', 'internal']).default('user'),
    selected: z.string().max(512).optional(),
    cursor: z.string().max(512).optional(),
  }), req.query);
  const settleView = (view, runningAgents) => ({
    ...view,
    user: settleTaskSourceSpawnWindow(view?.user, runningAgents),
    cos: settleTaskSourceSpawnWindow(view?.cos, runningAgents),
  });
  // The bounded views select inside the store BEFORE cloning, so a queue refresh
  // never copies archived prompt bodies (#9677). Settlement runs on the selection.
  const agentsPromise = getAgents().catch(() => []);
  if (query.view === 'completed') {
    const { limit } = validateRequest(z.object({ limit: z.coerce.number().int().min(1).max(100).default(25) }), req.query);
    return res.json(await getTaskView({ kind: 'completed', source: query.source, cursor: query.cursor, limit }));
  }
  if (query.view === 'queue') {
    const [view, agents] = await Promise.all([getTaskView({ kind: 'queue', selected: query.selected }), agentsPromise]);
    const tasks = settleView(view, runningAgentsByTaskId(agents));
    // `tasks` stays whole (open queue + the selected historical task); the derived
    // lists shrink to id/status summaries.
    const queueSource = source => {
      if (!source) return source;
      return { ...source,
        grouped: Object.fromEntries(Object.entries(source.grouped || {}).map(([key, rows]) => [key, rows.map(task => ({ id: task.id, status: task.status, spawning: task.spawning }))])),
        autoApproved: source.autoApproved?.map(task => ({ id: task.id })), awaitingApproval: source.awaitingApproval?.map(task => ({ id: task.id })) };
    };
    return res.json({ user: queueSource(tasks.user), cos: queueSource(tasks.cos) });
  }
  if (!isPaginationRequested(req.query)) {
    if (query.view === 'full') {
      const [allTasks, agents] = await Promise.all([getAllTasks(), agentsPromise]);
      return res.json(settleView(allTasks, runningAgentsByTaskId(agents)));
    }
    // Bare form: bounded projection. Every non-completed task stays whole; the
    // completed history (96% of the bytes on a long-lived install, and once
    // more inside `grouped`) shrinks to the first `view=completed` page plus
    // `completedCount`. `view=full` is the raw-store escape hatch.
    const [view, agents] = await Promise.all([getTaskView({ kind: 'bare' }), agentsPromise]);
    return res.json(settleView(view, runningAgentsByTaskId(agents)));
  }
  const { limit, offset } = parsePagination(req.query, { defaultLimit: 50, maxLimit: 500 });
  const [view, agents] = await Promise.all([getTaskView({ kind: 'window', offset, limit }), agentsPromise]);
  const runningAgents = runningAgentsByTaskId(agents);
  const { totals } = view;
  res.json({
    user: settleTaskSourceSpawnWindow(view.user, runningAgents),
    cos: settleTaskSourceSpawnWindow(view.cos, runningAgents),
    pagination: { limit, offset, userTotal: totals.user, cosTotal: totals.cos, total: totals.user + totals.cos }
  });
}));

// Source-specific bounded views: open tasks plus the first completed page.
// Further history is available through /tasks?view=completed; raw data through /tasks?view=full.
router.get('/tasks/user', asyncHandler(async (req, res) => {
  res.json((await getTaskView({ kind: 'bare' })).user);
}));

// GET /api/cos/tasks/internal - Get CoS internal tasks
router.get('/tasks/internal', asyncHandler(async (req, res) => {
  res.json((await getTaskView({ kind: 'bare' })).cos);
}));

// GET /api/cos/tasks/:id - One task with the queue it lives in. The Chief of
// Staff page reads this when a selection lands outside the lists it already
// holds, instead of re-reading the whole queue per click (#12032). Registered
// after the literal /tasks/user and /tasks/internal routes so those still win.
router.get('/tasks/:id', asyncHandler(async (req, res) => {
  const found = await findTaskWithSource(req.params.id);
  if (!found) throw new ServerError('Task not found', { status: 404, code: 'NOT_FOUND' });
  res.json(found);
}));

// POST /api/cos/tasks/reorder - Reorder tasks
router.post('/tasks/reorder', asyncHandler(async (req, res) => {
  const { taskIds } = validateRequest(cosTaskReorderBodySchema, req.body);

  const result = await reorderTasks(taskIds);
  res.json(result);
}));

// POST /api/cos/tasks/enhance - Enhance a task prompt with AI
router.post('/tasks/enhance', asyncHandler(async (req, res) => {
  const { description, context } = validateRequest(enhanceTaskSchema, req.body);
  const result = await enhanceTaskPrompt(description, context);
  res.json(result);
}));

// POST /api/cos/tasks/slashdo - Create a task from a slashdo command.
//
// The body carries the run settings the app-overview drawer collects: the
// provider/model/effort pin and `simplify` apply to every command; `target`,
// `issueAuthorFilter`, and the reviewer choices are `/do:next`-only (they shape
// the claim prompt, which self-manages its own PR + review loop). `issueContext`
// is the selected issue's content already fetched by the managed-app Issues tab;
// it avoids making the agent retrieve the same title/body again. The optional
// `overrideContext` is user guidance appended to that claim prompt.
//
// The launchable-command allowlist is the shared catalog in
// `server/lib/slashdoCatalog.js` (#3114) — the CoS quick templates read the same
// source, so the two surfaces can't drift.
router.post('/tasks/slashdo', asyncHandler(async (req, res) => {
  const {
    command, app, provider, model, effort, simplify, issueTarget, prCompletion,
    target, issueContext, overrideContext, issueAuthorFilter, reviewers, usernames, optionalReviewers,
    reviewerMaxRounds, reviewerModels, reviewerEfforts, depfreeMode
  } = validateRequest(slashdoTaskSchema, req.body);

  const workflow = getSlashdoWorkflow(command);
  if (!workflow) {
    throw new ServerError(`Invalid slashdo command. Allowed: ${SLASHDO_COMMAND_NAMES.join(', ')}`, { status: 400, code: 'VALIDATION_ERROR' });
  }

  // Resolved for EVERY command, not just `next` — so the queue row names the app
  // the way the user does, and an unknown app 404s uniformly instead of only on
  // the `next` branch.
  const appObj = await getAppById(app);
  if (!appObj) {
    throw new ServerError(`App not found: ${app}`, { status: 404, code: 'APP_NOT_FOUND' });
  }

  // `plan-task` is also a plan-only quick action, so resolve its forge target
  // before it reaches the store through this separate route.
  const planTask = command === 'plan-task'
    ? await preparePlanOnlyTask({ app, slashdoCommand: command, issueTarget }, appObj)
    : null;

  // Enforce the catalog's stack gate server-side. The Agent Operations panel only
  // offers the applicable one of `better` / `better-swift`, but the API must not
  // trust that — queuing a SwiftUI audit against a web app (or vice versa) burns
  // an agent run on a workflow that can't apply.
  if (!slashdoWorkflowAppliesTo(workflow, NON_PM2_TYPES.has(appObj.type))) {
    throw new ServerError(
      `${workflow.label} does not apply to ${appObj.name} (app type: ${appObj.type || 'unknown'})`,
      { status: 400, code: 'WORKFLOW_APP_TYPE_MISMATCH' }
    );
  }

  // Three task shapes, produced whole so the either/or is visible rather than
  // assembled from separately-mutated locals. The first two are the TARGETED
  // shapes: a command pinned to one work item, where PortOS assembles the whole
  // prompt itself and therefore must NOT also set `slashdoCommand` (that would
  // append the bundled `/do:<cmd>` body on top of the assembled prompt and
  // re-point the agent at the command's unpinned behavior).
  //
  // - `/do:next` is the work-claim consumer and is genuinely special: it routes
  //   through the same workTracker-aware logic the scheduled `claim-work` flow
  //   uses, so the manual button honors the app's per-app Work Tracker (PLAN.md /
  //   GitHub / GitLab / JIRA) instead of always draining PLAN.md.
  // - `replan` + a `target` is the Issues tab's Replan button: a second model
  //   reviews ONE already-planned issue. Untargeted, it stays the bundled
  //   backlog audit and falls through to the generic shape below.
  // - Every other command carries only the bare `slashdoCommand` and lets the
  //   prompt builder render the invocation + inline the body once the provider is
  //   known (`applySlashdoInvocation`). Eagerly inlining the body here — and
  //   hardcoding `Run /do:<cmd>` into the description — assumed a Claude host that
  //   can type slash commands; a codex/grok agent gets Agent Skills instead, so
  //   the rendered string was wrong for it (#3089's whole point).
  //
  // `workflow.settings` is the catalog's run-shape posture (see
  // WORKFLOW_OWNS_ITS_OWN_GIT / WORKFLOW_REPORTS_NO_CODE) — read from it rather
  // than restating false/false, so a future entry that genuinely wants a
  // PortOS-managed worktree gets one. `worktreeChangesExpected` declares the
  // workflow's deliverable: false for the report-shaped four (plan-task /
  // replan / review / scan), whose output is a filed issue or a printed report,
  // so downstream task bookkeeping does not score their clean tree as missing
  // code work (#3636). `simplify` comes from the request (the run drawer's toggle), not
  // the catalog.
  const { useWorktree, openPR, worktreeChangesExpected } = workflow.settings;
  let shape;
  if (command === 'replan' && target) {
    // `replan` + a pinned issue is the Issues tab's Replan button, the same
    // command/target pairing `next` uses for a pinned claim: a SECOND model
    // reviews ONE already-planned issue and comments its refinements. Without a
    // target the command stays the bundled `/do:replan` backlog audit below, so
    // the Agent Operations button is unaffected. Like the claim branch, its
    // assembled prompt IS the task prompt and carries no `slashdoCommand` —
    // appending the whole `/do:replan` body would re-point it at the backlog.
    const replan = await buildIssueReplanTask(appObj, { target, issueContext, overrideContext });
    shape = {
      description: `${workflow.label} for ${appObj.name} — review the plan on ${workTrackerLabel(replan.tracker)} issue ${replan.target}`,
      prompt: replan.prompt,
      taskMetadata: { ...replan.taskMetadata, replanTarget: replan.target },
    };
  } else if (command === 'next') {
    const claim = await buildClaimWorkTask(appObj, {
      target,
      issueContext,
      ...(overrideContext !== undefined ? { overrideContext } : {}),
      issueAuthorFilter,
      prCompletion,
      reviewers,
      usernames,
      optionalReviewers,
      reviewerMaxRounds,
      reviewerModels,
      reviewerEfforts
    });
    if (claim.target && ['github', 'gitlab'].includes(claim.tracker)) {
      await prepareAppIssueClaim(appObj, claim.target, claim.tracker);
    }
    const scope = claim.target
      ? `claim ${workTrackerLabel(claim.tracker)} item ${claim.target}`
      : `claim next ${workTrackerLabel(claim.tracker)} item`;
    shape = {
      description: `${workflow.label} for ${appObj.name} — ${scope} and ship a PR`,
      // The claim body is the agent's PROMPT, not a human note (#4153) — see
      // server/lib/cosTaskPrompt.js for the field split.
      prompt: claim.prompt,
      // claim.taskMetadata overrides the catalog posture only where it carries a
      // key. All current claim flows (plan-task / claim-issue / claim-issue-gitlab
      // / claim-issue-jira) self-manage their worktree + MR/PR, so false/false
      // remains the CoS provisioning posture. `claimFlow` is a separate
      // lifecycle marker so the prompt builder cannot mistake false/false for a
      // commit-only handoff. The spread stays for a future delegated type that
      // needs CoS-managed isolation. `worktreeChangesExpected` is one such key: the
      // claim flow derives it from the app's RESOLVED work tracker (a file
      // tracker commits its checklist, a forge tracker doesn't), which is more
      // specific than the catalog's commit-shaped default, so the spread wins.
      taskMetadata: {
        useWorktree,
        openPR,
        worktreeChangesExpected,
        ...(claim.target ? { claimTarget: claim.target } : {}),
        ...claim.taskMetadata,
        claimFlow: true
      },
    };
  } else {
    // `/do:depfree`'s removal bar rides along as the command's own flag: the
    // bundled body parses `--heavy` / `--extreme` itself, and the default bar
    // is the flag-less invocation. Ignored for every other command, whose body
    // has no such flag to read.
    const depfreeArgs = command === 'depfree' && depfreeMode && depfreeMode !== 'default'
      ? { slashdoArgs: `--${depfreeMode}` }
      : {};
    shape = {
      description: `${workflow.label} for ${appObj.name} — ${workflow.description}${depfreeArgs.slashdoArgs ? ` (${depfreeMode} mode)` : ''}`,
      slashdoCommand: command,
      taskMetadata: { useWorktree, openPR, worktreeChangesExpected, ...depfreeArgs },
    };
  }

  // `reviewLoop` stays off for every slashdo task: each `/do:*` body owns its own
  // review/PR sequence, so a CoS-managed loop on top would double-review.
  const taskData = {
    description: shape.description,
    app,
    prompt: shape.prompt,
    // Preserve the assembled claim body in the explicit durable slot too.
    // This keeps issue-page guidance attached if intake mapping changes.
    ...(shape.prompt ? { metadata: { prompt: shape.prompt } } : {}),
    slashdoCommand: shape.slashdoCommand,
    ...shape.taskMetadata,
    provider, model, effort,
    simplify: simplify === true,
    reviewLoop: false
  };
  const result = await addTask(planTask ? { ...taskData, prompt: planTask.prompt } : taskData, 'user');

  if (result?.duplicate) {
    throw new ServerError(`A task with this description is already ${result.status}`, { status: 409, code: 'DUPLICATE_TASK' });
  }

  await logTaskCreated(req, result, taskData);
  res.json(result);
}));

// POST /api/cos/tasks/jira-ticket - Queue a CoS task to implement one specific
// JIRA ticket (the per-card "play" button on the app overview sprint board).
// Reuses the claim-issue-jira prompt and appends a target-ticket constraint, so
// it stays in lockstep with the scheduled JIRA claim flow without duplicating
// the 7-phase body. Queue-only: the daemon picks it up on the next evaluation.
router.post('/tasks/jira-ticket', asyncHandler(async (req, res) => {
  const { app, ticketKey } = validateRequest(jiraTicketTaskSchema, req.body);

  const appObj = await getAppById(app);
  if (!appObj) {
    throw new ServerError(`App not found: ${app}`, { status: 404, code: 'APP_NOT_FOUND' });
  }
  if (!appObj.jira?.enabled) {
    throw new ServerError(`JIRA is not enabled for ${appObj.name}`, { status: 400, code: 'JIRA_NOT_ENABLED' });
  }

  // Assemble the claim-issue-jira prompt + target-ticket constraint in the
  // generator service (shared with the scheduled JIRA claim flow). The route
  // stays thin: validate → gate → assemble → queue.
  const { ticketKey: key, prompt, taskMetadata } = await buildJiraTicketTask(appObj, ticketKey);

  const taskData = {
    description: `Claim JIRA ticket ${key} for ${appObj.name} — implement and ship a PR`,
    app,
    prompt,
    ...taskMetadata,
    simplify: false,
    reviewLoop: false,
  };
  const result = await addTask(taskData, 'user');

  if (result?.duplicate) {
    throw new ServerError(`A task for ${key} is already ${result.status}`, { status: 409, code: 'DUPLICATE_TASK' });
  }

  await logTaskCreated(req, result, taskData);
  res.json(result);
}));

// POST /api/cos/tasks - Add a new task
router.post('/tasks', asyncHandler(async (req, res) => {
  const parsed = createCosTaskSchema.safeParse(req.body);
  if (!parsed.success) failValidation(parsed);
  const { type, isInvestigation, ...taskData } = parsed.data;
  if (taskData.targetInstanceId) await assertAssignableInstance(taskData.targetInstanceId);
  const app = await assertWorktreeCapableApp(taskData);
  // API callers can omit the UI's previewed value. Resolve against the app at
  // creation, then persist the choice so later configuration changes cannot
  // turn an in-flight draft/human handoff into an automatic merge.
  const opensPr = taskData.openPR === true || (taskData.useWorktree === true && taskData.openPR !== false);
  if (type === 'user' && !taskData.planOnly && !isInvestigation && opensPr && taskData.prCompletion === undefined) {
    taskData.prCompletion = resolveAppPrCompletion(app, taskData);
  }
  const preparedTask = await preparePlanOnlyTask(taskData);
  // A UI-queued investigation (#6043) goes through the SAME producer as an
  // auto-filed one, so it lands with the markers the shared machinery reads —
  // `metadata.isInvestigation` (recognized by `isInvestigationTask`, which is
  // also the meta-cascade guard, so its own failure can't spawn an
  // investigation of itself) and a server-derived fingerprint (dedup + the loop
  // policy) — and contributes to the shared storm counter. The client supplies
  // only the flag: it never names the fingerprint or the delivery posture.
  const delivery = isInvestigation ? CLIENT_INVESTIGATION_DELIVERY : null;
  const result = delivery
    ? (await fileInvestigationTask(
      { ...preparedTask, fingerprint: clientInvestigationFingerprint(preparedTask) },
      { taskType: type, delivery }
    )).task
    : await addTask(preparedTask, type);

  if (result?.duplicate) {
    throw new ServerError(`A task with this description is already ${result.status}`, { status: 409, code: 'DUPLICATE_TASK' });
  }

  // Log the posture the task actually FILED with, not just the submitted fields:
  // the delivery and the investigation marker are applied here, so a ledger row
  // built from `preparedTask` alone would omit them for a UI-queued repair.
  await logTaskCreated(req, result, { ...preparedTask, ...delivery, isInvestigation });
  res.json(result);
}));

// PUT /api/cos/tasks/:id - Update a task
router.put('/tasks/:id', asyncHandler(async (req, res) => {
  const { id } = req.params;
  const parsedUpdate = updateCosTaskSchema.safeParse(req.body);
  if (!parsedUpdate.success) failValidation(parsedUpdate);
  const { type, blockedReason, ...fields } = parsedUpdate.data;

  const updates = {};
  if (fields.description !== undefined) updates.description = fields.description;
  if (fields.priority !== undefined) updates.priority = fields.priority;
  if (fields.status !== undefined) updates.status = fields.status;
  if (fields.context !== undefined) updates.context = fields.context;
  if (fields.prompt !== undefined) updates.prompt = fields.prompt;
  if (fields.model !== undefined) updates.model = fields.model;
  if (fields.provider !== undefined) updates.provider = fields.provider;
  if (fields.effort !== undefined) updates.effort = fields.effort;
  // Orchestrated execution (#5992). `null` is the explicit clear the schema
  // preserves — the store re-normalizes and drops the key (absent-vs-cleared).
  if (fields.orchestrationMode !== undefined) updates.orchestrationMode = fields.orchestrationMode;
  if (fields.orchestrationProfile !== undefined) updates.orchestrationProfile = fields.orchestrationProfile;
  if (fields.temperature !== undefined) updates.temperature = fields.temperature;
  if (fields.thinking !== undefined) updates.thinking = fields.thinking;
  if (fields.app !== undefined) updates.app = fields.app;

  // Re-pin (or unpin) the federated instance this task runs on (#4520). `null`
  // is the explicit clear the schema preserves — it lands as `undefined` in the
  // metadata patch, which the store's undefined-stripping turns into a real key
  // removal, restoring opportunistic first-claim-wins. Absent leaves the pin
  // untouched (absent-vs-cleared, AGENTS.md).
  if (fields.targetInstanceId !== undefined) {
    if (fields.targetInstanceId !== null) await assertAssignableInstance(fields.targetInstanceId);
    updates.metadata = { ...updates.metadata, targetInstanceId: fields.targetInstanceId ?? undefined };
  }

  // Set blocker metadata when marking as blocked
  if (fields.status === 'blocked' && blockedReason) {
    updates.metadata = { ...updates.metadata, blocker: blockedReason };
  }

  const result = await updateTask(id, updates, type);
  if (result?.error) {
    throw new ServerError(result.error, { status: 404, code: 'NOT_FOUND' });
  }

  // An edit is not an idempotent retry — two saves of the same field are two
  // distinct operator actions — so the timestamp is part of the dedupe key.
  const happenedAt = new Date().toISOString();
  await recordCommittedTaskAction({
    type: 'cos.task.update',
    target: id,
    targetName: result?.description,
    summary: `Edited CoS task ${id}: ${Object.keys(updates).join(', ') || 'no fields'}`,
    payload: { taskId: id, ...updates },
    source: routeSource(req),
    happenedAt,
    dedupeKey: `cos.task.update:${id}:${happenedAt}`,
  });
  res.json(result);
}));

// DELETE /api/cos/tasks/:id - Delete a task
router.delete('/tasks/:id', asyncHandler(async (req, res) => {
  const { id } = req.params;
  const { type } = validateRequest(cosTaskDeleteQuerySchema, req.query);

  // Read the description BEFORE the delete: once the row is gone the ledger's
  // only handle on what was thrown away would be an opaque task id.
  // `.catch` because this read only supplies a LABEL — a task file that will not
  // parse must not turn a working delete into a 500.
  const doomed = await getTaskById(id).catch(() => null);
  const result = await deleteTask(id, type);
  if (result?.error) {
    throw new ServerError(result.error, { status: 404, code: 'NOT_FOUND' });
  }

  await recordCommittedTaskAction({
    type: 'cos.task.delete',
    target: id,
    targetName: doomed?.description,
    summary: `Deleted CoS task ${id}${doomed?.description ? `: ${doomed.description}` : ''}`,
    payload: { taskId: id, description: doomed?.description ?? null },
    source: routeSource(req),
    dedupeKey: `cos.task.delete:${id}`,
  });
  res.json(result);
}));

// POST /api/cos/tasks/:id/approve - Approve a task
router.post('/tasks/:id/approve', asyncHandler(async (req, res) => {
  const { id } = req.params;

  const result = await approveTask(id);
  if (result?.error) {
    throw new ServerError(result.error, { status: 400, code: 'BAD_REQUEST' });
  }

  await recordCommittedTaskAction({
    type: 'cos.task.approve',
    target: id,
    targetName: result?.description,
    summary: `Approved CoS task ${id}${result?.description ? `: ${result.description}` : ''}`,
    payload: { taskId: id },
    source: routeSource(req),
    dedupeKey: `cos.task.approve:${id}`,
  });
  res.json(result);
}));

// POST /api/cos/tasks/:id/challenge - A sub-agent disputes a reviewer rejection
// (#2441). Parks the task in `challenged` and consumes one bounded challenge slot;
// a second dispute on the same task is refused (409 CHALLENGE_EXHAUSTED).
router.post('/tasks/:id/challenge', asyncHandler(async (req, res) => {
  const { id } = req.params;
  const { reason, evidence, reviewer } = validateRequest(challengeTaskSchema, req.body);
  const result = await challengeTask(id, { reason, evidence, reviewer });
  if (result?.error) {
    const status = (result.code === 'CHALLENGE_EXHAUSTED' || result.code === 'CHALLENGE_BUDGET_EXHAUSTED' || result.code === 'CANNOT_CHALLENGE_COMPLETED') ? 409
      : result.code === 'NOT_FOUND' ? 404 : 400;
    throw new ServerError(result.error, { status, code: result.code || 'CHALLENGE_FAILED' });
  }
  res.json(result);
}));

// POST /api/cos/tasks/:id/challenge/resolve - Resolve a parked challenge (#2441,
// #2471). Provide EITHER an explicit `outcome` (manual verdict) OR a `recheck`
// object (auto re-run a local reviewer against the current diff and derive the
// verdict). `upheld` overturns the rejection (→ pending); `escalated` surfaces the
// unresolved dispute to the user (→ blocked + arbitration task).
router.post('/tasks/:id/challenge/resolve', asyncHandler(async (req, res) => {
  const { id } = req.params;
  const { outcome, recheck, note, resolvedBy } = validateRequest(resolveChallengeSchema, req.body);
  const result = recheck
    ? await resolveTaskChallengeWithRecheck(id, { recheck, resolvedBy })
    : await resolveTaskChallenge(id, { outcome, note, resolvedBy });
  if (result?.error) {
    const status = result.code === 'NOT_FOUND' ? 404
      : result.code === 'NOT_CHALLENGED' ? 409
      : result.code === 'RECHECK_FAILED' ? 502 : 400;
    throw new ServerError(result.error, { status, code: result.code || 'RESOLVE_FAILED' });
  }
  res.json(result);
}));

// POST /api/cos/goal-fidelity/false-positive - A follow-up investigator reports that
// a goal-fidelity finding was WRONG: the objective was delivered and the reviewer
// misjudged it. Queues a calibration task against PortOS's own repo to close the
// context gap that produced the misjudgement, deduped on the gap so many reports
// of one blind spot fold into one fix. Never 4xx on a report it cannot act on —
// the refusal reason rides in the body, because the reporting agent's job is to
// say what it found, not to retry a queue decision it does not own.
router.post('/goal-fidelity/false-positive', asyncHandler(async (req, res) => {
  const report = validateRequest(goalFidelityFalsePositiveSchema, req.body);
  const result = await reportGoalFidelityFalsePositive(report);
  res.json(result);
}));

// POST /api/cos/evaluate - Force task evaluation
router.post('/evaluate', asyncHandler(async (req, res) => {
  await evaluateTasks();
  res.json({ success: true, message: 'Evaluation triggered' });
}));

// POST /api/cos/tasks/:id/spawn - Force-spawn a pending task
router.post('/tasks/:id/spawn', asyncHandler(async (req, res) => {
  const result = await forceSpawnTask(req.params.id);
  if (result.error) {
    const message = String(result.error);
    let status = 400;
    let code = 'SPAWN_FAILED';
    if (/not found/i.test(message)) {
      status = 404;
      code = 'NOT_FOUND';
    } else if (/not pending/i.test(message)) {
      status = 409;
      code = 'TASK_NOT_PENDING';
    } else if (/no available agent slots/i.test(message)) {
      status = 429;
      code = 'NO_CAPACITY';
    }
    throw new ServerError(result.error, { status, code });
  }

  // Force-spawn is repeatable (spawn, it fails, spawn again), so each press is
  // its own row — hence the timestamp in the dedupe key.
  const happenedAt = new Date().toISOString();
  await recordCommittedTaskAction({
    type: 'cos.task.spawn',
    target: req.params.id,
    summary: `Force-spawned CoS task ${req.params.id}`,
    payload: { taskId: req.params.id },
    source: routeSource(req),
    happenedAt,
    dedupeKey: `cos.task.spawn:${req.params.id}:${happenedAt}`,
  });
  res.json(result);
}));

export default router;