dsh-taskboard 0.1.2 → 0.2.0

package/lib/shared/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","names":[],"sources":["../../src/shared/protocol.ts"],"sourcesContent":["/**\n * Task domain model, state machine, urgency classes, and cron math — the\n * framework-free core shared verbatim by the host half (tools, store, routes,\n * scheduler) and, from P2 on, the browser half (board view).\n *\n * Everything here is a pure function over plain data: no imports beyond the\n * standard library, no I/O, no globals. Tests drive it directly.\n *\n * @module dsh-taskboard/shared/protocol\n */\n\n// ---------------------------------------------------------------------------\n// Status vocabulary\n// ---------------------------------------------------------------------------\n\n/**\n * Task lifecycle states. Main board columns render `backlog → todo →\n * in_progress → in_review → done`; `canceled` and `archived` are secondary\n * states collected under an \"other tasks\" tab. `blocked` is NOT a status —\n * it is a horizontal marker any non-terminal state may carry.\n */\nexport type TaskStatus =\n  | 'backlog'\n  | 'todo'\n  | 'in_progress'\n  | 'in_review'\n  | 'done'\n  | 'canceled'\n  | 'archived'\n\n/** Statuses shown as the five main board columns, in order. */\nexport const MAIN_STATUSES: readonly TaskStatus[] = [\n  'backlog',\n  'todo',\n  'in_progress',\n  'in_review',\n  'done',\n]\n\n/** Statuses collected under the secondary tab. */\nexport const SECONDARY_STATUSES: readonly TaskStatus[] = ['canceled', 'archived']\n\n/** Every valid status, main first. */\nexport const ALL_STATUSES: readonly TaskStatus[] = [...MAIN_STATUSES, ...SECONDARY_STATUSES]\n\n/**\n * Legal forward/sideways transitions. Anything not listed is rejected with\n * `invalid_transition`. `archived` is terminal.\n */\nconst TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>> = {\n  backlog: ['todo', 'canceled'],\n  todo: ['in_progress', 'backlog', 'canceled'],\n  in_progress: ['in_review', 'todo', 'canceled'],\n  in_review: ['in_progress', 'todo', 'done', 'canceled'],\n  done: ['archived'],\n  canceled: ['archived', 'todo'],\n  archived: [],\n}\n\n/**\n * Whether a status move is legal per the state machine.\n * @param from - current status.\n * @param to - requested status.\n * @returns true when the transition is allowed.\n */\nexport function canTransition(from: TaskStatus, to: TaskStatus): boolean {\n  return TRANSITIONS[from].includes(to)\n}\n\n/**\n * The claim move: the one transition that transfers ownership of a task to\n * the calling session. Guarded by the project (workspace) boundary in the\n * tool layer.\n */\nexport function isClaim(from: TaskStatus, to: TaskStatus): boolean {\n  return from === 'todo' && to === 'in_progress'\n}\n\n/** Statuses a `done` move may depart from (user confirmation only). */\nexport function canCompleteFrom(from: TaskStatus): boolean {\n  return from === 'in_review'\n}\n\n// ---------------------------------------------------------------------------\n// Urgency\n// ---------------------------------------------------------------------------\n\n/** Urgency classes with fixed UI colors. */\nexport type Urgency = 'urgent' | 'normal' | 'relaxed'\n\n/** All valid urgency values. */\nexport const URGENCIES: readonly Urgency[] = ['urgent', 'normal', 'relaxed']\n\n/** CSS color token per urgency: red / purple / blue. */\nexport const URGENCY_COLOR: Readonly<Record<Urgency, string>> = {\n  urgent: '#e5484d',\n  normal: '#8e4ec6',\n  relaxed: '#3e63dd',\n}\n\n// ---------------------------------------------------------------------------\n// Execution\n// ---------------------------------------------------------------------------\n\n/** How a task may run. */\nexport type ExecutionMode = 'claim' | 'scheduled'\n\n/**\n * Per-task execution configuration. `claim` tasks wait for an in-project\n * session to claim them; `scheduled` tasks run on the host cron scheduler.\n */\nexport interface ExecutionConfig {\n  mode: ExecutionMode\n  /** Five-field cron expression (minute hour day month weekday); required for `scheduled`. */\n  cron?: string\n  /** Next due time (epoch ms); maintained by the host scheduler. */\n  nextRunAt?: number\n  /** Last time the scheduler triggered this task (epoch ms). */\n  lastTriggeredAt?: number\n}\n\n/**\n * Parse a five-field cron expression. Supported field syntax: star, star/step\n * (`* / n` without spaces), a single number, an `a-b` range, and comma lists\n * of those. Day-of-week accepts both 0 and 7 as Sunday (normalized to 0).\n *\n * @param expr - the expression to parse.\n * @returns the match sets per field, or null when invalid.\n */\nexport function parseCron(expr: string): CronMatch | null {\n  const fields = expr.trim().split(/\\s+/)\n  if (fields.length !== 5) return null\n  const ranges: ReadonlyArray<readonly [number, number]> = [\n    [0, 59],\n    [0, 23],\n    [1, 31],\n    [1, 12],\n    [0, 7],\n  ]\n  const sets: Array<Set<number>> = []\n  for (let i = 0; i < 5; i++) {\n    const [min, max] = ranges[i]!\n    const set = new Set<number>()\n    if (!parseCronField(fields[i]!, min, max, set)) return null\n    sets.push(set)\n  }\n  const weekdays = new Set<number>()\n  for (const day of sets[4]!) weekdays.add(day === 7 ? 0 : day)\n  return { minutes: sets[0]!, hours: sets[1]!, days: sets[2]!, months: sets[3]!, weekdays }\n}\n\n/** Parsed cron field match sets. */\nexport type CronMatch = {\n  minutes: ReadonlySet<number>\n  hours: ReadonlySet<number>\n  days: ReadonlySet<number>\n  months: ReadonlySet<number>\n  weekdays: ReadonlySet<number>\n}\n\n/** Parse one cron field into a match set; false on any syntax error. */\nfunction parseCronField(field: string, min: number, max: number, out: Set<number>): boolean {\n  for (const part of field.split(',')) {\n    const [range, stepRaw] = part.split('/')\n    const step = stepRaw === undefined ? 1 : Number.parseInt(stepRaw, 10)\n    if (!Number.isInteger(step) || step < 1) return false\n    let lo: number\n    let hi: number\n    if (range === undefined || range === '') return false\n    if (range === '*') {\n      lo = min\n      hi = max\n    } else if (range.includes('-')) {\n      const [a, b] = range.split('-')\n      lo = Number.parseInt(a ?? '', 10)\n      hi = Number.parseInt(b ?? '', 10)\n      if (!Number.isInteger(lo) || !Number.isInteger(hi)) return false\n    } else {\n      lo = Number.parseInt(range, 10)\n      if (!Number.isInteger(lo)) return false\n      hi = stepRaw === undefined ? lo : max\n    }\n    if (lo < min || hi > max || lo > hi) return false\n    for (let v = lo; v <= hi; v += step) out.add(v)\n  }\n  return out.size > 0\n}\n\n/**\n * The next time at or after `from` matching the cron sets (local time),\n * or null when no match exists within four years (e.g. Feb 30).\n * @param match - parsed cron sets.\n * @param from - epoch ms start point (inclusive match candidate).\n * @returns the next match's epoch ms, or null.\n */\nexport function nextCronTime(match: CronMatch, from: number): number | null {\n  // Walk minute by minute from the next whole minute, capped at ~4 years.\n  const start = new Date(from)\n  start.setSeconds(0, 0)\n  start.setMinutes(start.getMinutes() + 1)\n  const cap = from + 4 * 366 * 24 * 60 * 60 * 1000\n  let t = start.getTime()\n  while (t <= cap) {\n    const d = new Date(t)\n    if (\n      match.months.has(d.getMonth() + 1)\n      && match.days.has(d.getDate())\n      && match.weekdays.has(d.getDay())\n      && match.hours.has(d.getHours())\n      && match.minutes.has(d.getMinutes())\n    ) {\n      return t\n    }\n    t += 60_000\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// Records\n// ---------------------------------------------------------------------------\n\n/** Who performed a write. */\nexport type Actor =\n  | { kind: 'user' }\n  | { kind: 'agent'; sessionId: string }\n\n/** A progress/report comment on a task. */\nexport type CommentRecord = {\n  id: string\n  /** Comment body (plain text; UI renders as pre-wrapped). */\n  body: string\n  /** Optimistic-concurrency version of this comment. */\n  version: number\n  createdAt: number\n  /** The session that wrote this comment; absent for user-written ones. */\n  threadId?: string\n}\n\n/** One execution attempt of a task. */\nexport type ExecutionRecord = {\n  id: string\n  /** The session this execution ran in; set once the session is really started. */\n  sessionId?: string\n  /** Trigger: manual button or the host scheduler. */\n  trigger: 'manual' | 'scheduled'\n  startedAt?: number\n  endedAt?: number\n  outcome: 'running' | 'succeeded' | 'failed' | 'cancelled'\n  error?: string\n}\n\n/** The per-model override a task may carry; absent = session default model. */\nexport type TaskModel = {\n  provider: string\n  model: string\n}\n\n/** One task on the board. */\nexport type TaskRecord = {\n  id: string\n  title: string\n  description: string\n  /** The prompt sent to a fresh session on execution; falls back to title+description. */\n  prompt: string\n  /** Owning project: a DSH workspace id. */\n  workspaceId: string\n  urgency: Urgency\n  status: TaskStatus\n  /** Horizontal marker: work cannot continue right now (any non-terminal status). */\n  blocked: boolean\n  execution: ExecutionConfig\n  model?: TaskModel\n  version: number\n  createdAt: number\n  updatedAt: number\n  createdBy: Actor\n  updatedBy: Actor\n  comments: CommentRecord[]\n  executions: ExecutionRecord[]\n  /** Soft-delete marker set by agent `taskboard_delete`; user confirms the purge. */\n  trashedAt?: number\n}\n\n/** The whole durable ledger. */\nexport type TaskLedger = {\n  schemaVersion: number\n  /** Global monotonic revision; every mutation bumps it. */\n  revision: number\n  tasks: TaskRecord[]\n}\n\n/** Current ledger format version. */\nexport const LEDGER_SCHEMA_VERSION = 1\n\n/** An empty ledger. */\nexport function emptyLedger(): TaskLedger {\n  return { schemaVersion: LEDGER_SCHEMA_VERSION, revision: 0, tasks: [] }\n}\n\n// ---------------------------------------------------------------------------\n// ids\n// ---------------------------------------------------------------------------\n\n/** Random base36 suffix. */\nfunction suffix(): string {\n  return Math.random().toString(36).slice(2, 8)\n}\n\n/** Mint a task id. */\nexport function newTaskId(): string {\n  return `t-${Date.now().toString(36)}-${suffix()}`\n}\n\n/** Mint a comment id. */\nexport function newCommentId(): string {\n  return `c-${Date.now().toString(36)}-${suffix()}`\n}\n\n/** Mint an execution id. */\nexport function newExecutionId(): string {\n  return `e-${Date.now().toString(36)}-${suffix()}`\n}\n\n// ---------------------------------------------------------------------------\n// validation helpers (input shaping for tools and routes)\n// ---------------------------------------------------------------------------\n\n/**\n * Validate and normalize a title: trimmed, 1..200 chars.\n * @param raw - the raw input.\n * @returns the normalized title.\n * @throws when empty or too long.\n */\nexport function normalizeTitle(raw: string): string {\n  const t = raw.trim()\n  if (t.length === 0 || t.length > 200) {\n    throw new Error('title must be 1..200 characters')\n  }\n  return t\n}\n\n/**\n * Validate a task prompt: trimmed, at most 8000 chars; empty becomes ''.\n * @param raw - the raw input.\n */\nexport function normalizePrompt(raw: string | undefined): string {\n  const t = (raw ?? '').trim()\n  if (t.length > 8000) throw new Error('prompt must be at most 8000 characters')\n  return t\n}\n\n/**\n * Validate and normalize a comment body: trimmed, 1..4000 chars.\n * @param raw - the raw input.\n */\nexport function normalizeBody(raw: string): string {\n  const t = raw.trim()\n  if (t.length === 0 || t.length > 4000) {\n    throw new Error('comment body must be 1..4000 characters')\n  }\n  return t\n}\n\n/**\n * Validate an urgency value.\n * @param raw - the raw input.\n */\nexport function asUrgency(raw: string): Urgency {\n  if (!URGENCIES.includes(raw as Urgency)) {\n    throw new Error(`urgency must be one of: ${URGENCIES.join(', ')}`)\n  }\n  return raw as Urgency\n}\n\n/**\n * Validate a status value.\n * @param raw - the raw input.\n */\nexport function asStatus(raw: string): TaskStatus {\n  if (!ALL_STATUSES.includes(raw as TaskStatus)) {\n    throw new Error(`status must be one of: ${ALL_STATUSES.join(', ')}`)\n  }\n  return raw as TaskStatus\n}\n\n/**\n * Validate an execution config request from raw tool/route input.\n * `scheduled` requires a valid cron; computes the first `nextRunAt` from\n * `now`.\n * @param raw - raw execution input ({@link ExecutionConfig} fields, untyped).\n * @param now - current epoch ms.\n * @returns the normalized config.\n */\nexport function normalizeExecution(\n  raw: { mode?: string; cron?: string },\n  now: number,\n): ExecutionConfig {\n  const mode = raw.mode ?? 'claim'\n  if (mode !== 'claim' && mode !== 'scheduled') {\n    throw new Error(\"execution.mode must be 'claim' or 'scheduled'\")\n  }\n  if (mode === 'claim') return { mode }\n  const cron = (raw.cron ?? '').trim()\n  const match = parseCron(cron)\n  if (match === null) throw new Error('execution.cron is not a valid 5-field cron expression')\n  const next = nextCronTime(match, now)\n  if (next === null) throw new Error('execution.cron never matches within 4 years')\n  return { mode, cron, nextRunAt: next }\n}\n\n/**\n * The effective prompt of a task: explicit prompt, or title+description.\n * @param task - the task.\n */\nexport function effectivePrompt(task: TaskRecord): string {\n  if (task.prompt.length > 0) return task.prompt\n  const head = task.title\n  return task.description.length > 0 ? `${head}\\n\\n${task.description}` : head\n}\n\n/**\n * Whether the task is currently claimed by a session (running state).\n * @param task - the task.\n */\nexport function isClaimedBy(task: TaskRecord): string | undefined {\n  return task.status === 'in_progress' && task.updatedBy.kind === 'agent'\n    ? task.updatedBy.sessionId\n    : undefined\n}\n\n/**\n * Compact list-projection of a task (token-friendly for `taskboard_list`).\n * @param task - the task.\n */\nexport type TaskSummary = {\n  id: string\n  title: string\n  workspaceId: string\n  urgency: Urgency\n  status: TaskStatus\n  blocked: boolean\n  executionMode: ExecutionMode\n  nextRunAt?: number\n  model?: TaskModel\n  version: number\n  claimOwner?: string\n  commentCount: number\n  lastExecutionOutcome?: ExecutionRecord['outcome']\n  trashed: boolean\n}\n\n/**\n * Build the compact summary of a task.\n * @param task - the task.\n */\nexport function summarize(task: TaskRecord): TaskSummary {\n  const last = task.executions.length > 0 ? task.executions[task.executions.length - 1] : undefined\n  return {\n    id: task.id,\n    title: task.title,\n    workspaceId: task.workspaceId,\n    urgency: task.urgency,\n    status: task.status,\n    blocked: task.blocked,\n    executionMode: task.execution.mode,\n    nextRunAt: task.execution.nextRunAt,\n    model: task.model,\n    version: task.version,\n    claimOwner: isClaimedBy(task),\n    commentCount: task.comments.length,\n    lastExecutionOutcome: last?.outcome,\n    trashed: task.trashedAt !== undefined,\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"protocol.js","names":[],"sources":["../../src/shared/protocol.ts"],"sourcesContent":["/**\n * Task domain model, state machine, urgency classes, and cron math — the\n * framework-free core shared verbatim by the host half (tools, store, routes,\n * scheduler) and, from P2 on, the browser half (board view).\n *\n * Everything here is a pure function over plain data: no imports beyond the\n * standard library, no I/O, no globals. Tests drive it directly.\n *\n * @module dsh-taskboard/shared/protocol\n */\n\n// ---------------------------------------------------------------------------\n// Status vocabulary\n// ---------------------------------------------------------------------------\n\n/**\n * Task lifecycle states. Main board columns render `backlog → todo →\n * in_progress → in_review → done`; `canceled` and `archived` are secondary\n * states collected under an \"other tasks\" tab. `blocked` is NOT a status —\n * it is a horizontal marker any non-terminal state may carry.\n */\nexport type TaskStatus =\n  | 'backlog'\n  | 'todo'\n  | 'in_progress'\n  | 'in_review'\n  | 'done'\n  | 'canceled'\n  | 'archived'\n\n/** Statuses shown as the five main board columns, in order. */\nexport const MAIN_STATUSES: readonly TaskStatus[] = [\n  'backlog',\n  'todo',\n  'in_progress',\n  'in_review',\n  'done',\n]\n\n/** Statuses collected under the secondary tab. */\nexport const SECONDARY_STATUSES: readonly TaskStatus[] = ['canceled', 'archived']\n\n/** Every valid status, main first. */\nexport const ALL_STATUSES: readonly TaskStatus[] = [...MAIN_STATUSES, ...SECONDARY_STATUSES]\n\n/**\n * Legal forward/sideways transitions. Anything not listed is rejected with\n * `invalid_transition`. `archived` is terminal.\n */\nconst TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>> = {\n  backlog: ['todo', 'canceled'],\n  todo: ['in_progress', 'backlog', 'canceled'],\n  in_progress: ['in_review', 'todo', 'canceled'],\n  in_review: ['in_progress', 'todo', 'done', 'canceled'],\n  done: ['archived'],\n  canceled: ['archived', 'todo'],\n  archived: [],\n}\n\n/**\n * Whether a status move is legal per the state machine.\n * @param from - current status.\n * @param to - requested status.\n * @returns true when the transition is allowed.\n */\nexport function canTransition(from: TaskStatus, to: TaskStatus): boolean {\n  return TRANSITIONS[from].includes(to)\n}\n\n/**\n * The claim move: the one transition that transfers ownership of a task to\n * the calling session. Guarded by the project (workspace) boundary in the\n * tool layer.\n */\nexport function isClaim(from: TaskStatus, to: TaskStatus): boolean {\n  return from === 'todo' && to === 'in_progress'\n}\n\n/** Statuses a `done` move may depart from (user confirmation only). */\nexport function canCompleteFrom(from: TaskStatus): boolean {\n  return from === 'in_review'\n}\n\n// ---------------------------------------------------------------------------\n// Urgency\n// ---------------------------------------------------------------------------\n\n/** Urgency classes with fixed UI colors. */\nexport type Urgency = 'urgent' | 'normal' | 'relaxed'\n\n/** All valid urgency values. */\nexport const URGENCIES: readonly Urgency[] = ['urgent', 'normal', 'relaxed']\n\n/** CSS color token per urgency: red / purple / blue. */\nexport const URGENCY_COLOR: Readonly<Record<Urgency, string>> = {\n  urgent: '#e5484d',\n  normal: '#8e4ec6',\n  relaxed: '#3e63dd',\n}\n\n// ---------------------------------------------------------------------------\n// Execution\n// ---------------------------------------------------------------------------\n\n/** How a task may run. */\nexport type ExecutionMode = 'claim' | 'scheduled'\n\n/**\n * Per-task execution configuration. `claim` tasks wait for an in-project\n * session to claim them; `scheduled` tasks run on the host cron scheduler.\n */\nexport interface ExecutionConfig {\n  mode: ExecutionMode\n  /** Five-field cron expression (minute hour day month weekday); required for `scheduled`. */\n  cron?: string\n  /** Next due time (epoch ms); maintained by the host scheduler. */\n  nextRunAt?: number\n  /** Last time the scheduler triggered this task (epoch ms). */\n  lastTriggeredAt?: number\n}\n\n/**\n * Parse a five-field cron expression. Supported field syntax: star, star/step\n * (`* / n` without spaces), a single number, an `a-b` range, and comma lists\n * of those. Day-of-week accepts both 0 and 7 as Sunday (normalized to 0).\n *\n * @param expr - the expression to parse.\n * @returns the match sets per field, or null when invalid.\n */\nexport function parseCron(expr: string): CronMatch | null {\n  const fields = expr.trim().split(/\\s+/)\n  if (fields.length !== 5) return null\n  const ranges: ReadonlyArray<readonly [number, number]> = [\n    [0, 59],\n    [0, 23],\n    [1, 31],\n    [1, 12],\n    [0, 7],\n  ]\n  const sets: Array<Set<number>> = []\n  for (let i = 0; i < 5; i++) {\n    const [min, max] = ranges[i]!\n    const set = new Set<number>()\n    if (!parseCronField(fields[i]!, min, max, set)) return null\n    sets.push(set)\n  }\n  const weekdays = new Set<number>()\n  for (const day of sets[4]!) weekdays.add(day === 7 ? 0 : day)\n  return { minutes: sets[0]!, hours: sets[1]!, days: sets[2]!, months: sets[3]!, weekdays }\n}\n\n/** Parsed cron field match sets. */\nexport type CronMatch = {\n  minutes: ReadonlySet<number>\n  hours: ReadonlySet<number>\n  days: ReadonlySet<number>\n  months: ReadonlySet<number>\n  weekdays: ReadonlySet<number>\n}\n\n/** Parse one cron field into a match set; false on any syntax error. */\nfunction parseCronField(field: string, min: number, max: number, out: Set<number>): boolean {\n  for (const part of field.split(',')) {\n    const [range, stepRaw] = part.split('/')\n    const step = stepRaw === undefined ? 1 : Number.parseInt(stepRaw, 10)\n    if (!Number.isInteger(step) || step < 1) return false\n    let lo: number\n    let hi: number\n    if (range === undefined || range === '') return false\n    if (range === '*') {\n      lo = min\n      hi = max\n    } else if (range.includes('-')) {\n      const [a, b] = range.split('-')\n      lo = Number.parseInt(a ?? '', 10)\n      hi = Number.parseInt(b ?? '', 10)\n      if (!Number.isInteger(lo) || !Number.isInteger(hi)) return false\n    } else {\n      lo = Number.parseInt(range, 10)\n      if (!Number.isInteger(lo)) return false\n      hi = stepRaw === undefined ? lo : max\n    }\n    if (lo < min || hi > max || lo > hi) return false\n    for (let v = lo; v <= hi; v += step) out.add(v)\n  }\n  return out.size > 0\n}\n\n/**\n * The next time at or after `from` matching the cron sets (local time),\n * or null when no match exists within four years (e.g. Feb 30).\n * @param match - parsed cron sets.\n * @param from - epoch ms start point (inclusive match candidate).\n * @returns the next match's epoch ms, or null.\n */\nexport function nextCronTime(match: CronMatch, from: number): number | null {\n  // Walk minute by minute from the next whole minute, capped at ~4 years.\n  const start = new Date(from)\n  start.setSeconds(0, 0)\n  start.setMinutes(start.getMinutes() + 1)\n  const cap = from + 4 * 366 * 24 * 60 * 60 * 1000\n  let t = start.getTime()\n  while (t <= cap) {\n    const d = new Date(t)\n    if (\n      match.months.has(d.getMonth() + 1)\n      && match.days.has(d.getDate())\n      && match.weekdays.has(d.getDay())\n      && match.hours.has(d.getHours())\n      && match.minutes.has(d.getMinutes())\n    ) {\n      return t\n    }\n    t += 60_000\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// Records\n// ---------------------------------------------------------------------------\n\n/** Who performed a write. */\nexport type Actor =\n  | { kind: 'user' }\n  | { kind: 'agent'; sessionId: string }\n\n/** A progress/report comment on a task. */\nexport type CommentRecord = {\n  id: string\n  /** Comment body (plain text; UI renders as pre-wrapped). */\n  body: string\n  /** Optimistic-concurrency version of this comment. */\n  version: number\n  createdAt: number\n  /** The session that wrote this comment; absent for user-written ones. */\n  threadId?: string\n}\n\n/** One execution attempt of a task. */\nexport type ExecutionRecord = {\n  id: string\n  /** The session this execution ran in; set once the session is really started. */\n  sessionId?: string\n  /** Trigger: manual button or the host scheduler. */\n  trigger: 'manual' | 'scheduled'\n  startedAt?: number\n  endedAt?: number\n  outcome: 'running' | 'succeeded' | 'failed' | 'cancelled'\n  error?: string\n}\n\n/** The per-model override a task may carry; absent = session default model. */\nexport type TaskModel = {\n  provider: string\n  model: string\n}\n\n/** One task on the board. */\nexport type TaskRecord = {\n  id: string\n  title: string\n  description: string\n  /** The prompt sent to a fresh session on execution; falls back to title+description. */\n  prompt: string\n  /** Owning project: a DSH workspace id. */\n  workspaceId: string\n  urgency: Urgency\n  status: TaskStatus\n  /** Horizontal marker: work cannot continue right now (any non-terminal status). */\n  blocked: boolean\n  execution: ExecutionConfig\n  model?: TaskModel\n  /**\n   * The session currently holding the in-progress claim (explicit claim or a\n   * live execution). Present only while `status === 'in_progress'`: any move\n   * out of in_progress releases it. `updatedBy` is audit-only — user edits no\n   * longer erase the holder.\n   */\n  claimedBy?: string\n  /** When the current holder claimed the task (epoch ms). */\n  claimedAt?: number\n  version: number\n  createdAt: number\n  updatedAt: number\n  createdBy: Actor\n  updatedBy: Actor\n  comments: CommentRecord[]\n  executions: ExecutionRecord[]\n  /** How many older execution records were pruned by the retention cap. */\n  executionsPruned?: number\n  /** Soft-delete marker set by agent `taskboard_delete`; user confirms the purge. */\n  trashedAt?: number\n}\n\n/** Retention cap: how many execution records each task keeps (oldest pruned). */\nexport const MAX_EXECUTIONS = 20\n\n/**\n * Enforce the execution-record retention cap on one task (in place): keep the\n * newest {@link MAX_EXECUTIONS} records, count the dropped ones in\n * `executionsPruned`. Running records are always the newest, never dropped.\n * @param task - the task to prune.\n */\nexport function pruneExecutions(task: TaskRecord): void {\n  if (task.executions.length <= MAX_EXECUTIONS) return\n  const dropped = task.executions.length - MAX_EXECUTIONS\n  task.executions = task.executions.slice(-MAX_EXECUTIONS)\n  task.executionsPruned = (task.executionsPruned ?? 0) + dropped\n}\n\n/** The whole durable ledger. */\nexport type TaskLedger = {\n  schemaVersion: number\n  /** Global monotonic revision; every mutation bumps it. */\n  revision: number\n  tasks: TaskRecord[]\n}\n\n/** Current ledger format version. */\nexport const LEDGER_SCHEMA_VERSION = 1\n\n/** An empty ledger. */\nexport function emptyLedger(): TaskLedger {\n  return { schemaVersion: LEDGER_SCHEMA_VERSION, revision: 0, tasks: [] }\n}\n\n// ---------------------------------------------------------------------------\n// ids\n// ---------------------------------------------------------------------------\n\n/** Random base36 suffix. */\nfunction suffix(): string {\n  return Math.random().toString(36).slice(2, 8)\n}\n\n/** Mint a task id. */\nexport function newTaskId(): string {\n  return `t-${Date.now().toString(36)}-${suffix()}`\n}\n\n/** Mint a comment id. */\nexport function newCommentId(): string {\n  return `c-${Date.now().toString(36)}-${suffix()}`\n}\n\n/** Mint an execution id. */\nexport function newExecutionId(): string {\n  return `e-${Date.now().toString(36)}-${suffix()}`\n}\n\n// ---------------------------------------------------------------------------\n// validation helpers (input shaping for tools and routes)\n// ---------------------------------------------------------------------------\n\n/**\n * Validate and normalize a title: trimmed, 1..200 chars.\n * @param raw - the raw input.\n * @returns the normalized title.\n * @throws when empty or too long.\n */\nexport function normalizeTitle(raw: string): string {\n  const t = raw.trim()\n  if (t.length === 0 || t.length > 200) {\n    throw new Error('title must be 1..200 characters')\n  }\n  return t\n}\n\n/**\n * Validate a task prompt: trimmed, at most 8000 chars; empty becomes ''.\n * @param raw - the raw input.\n */\nexport function normalizePrompt(raw: string | undefined): string {\n  const t = (raw ?? '').trim()\n  if (t.length > 8000) throw new Error('prompt must be at most 8000 characters')\n  return t\n}\n\n/**\n * Validate and normalize a comment body: trimmed, 1..4000 chars.\n * @param raw - the raw input.\n */\nexport function normalizeBody(raw: string): string {\n  const t = raw.trim()\n  if (t.length === 0 || t.length > 4000) {\n    throw new Error('comment body must be 1..4000 characters')\n  }\n  return t\n}\n\n/**\n * Validate an urgency value.\n * @param raw - the raw input.\n */\nexport function asUrgency(raw: string): Urgency {\n  if (!URGENCIES.includes(raw as Urgency)) {\n    throw new Error(`urgency must be one of: ${URGENCIES.join(', ')}`)\n  }\n  return raw as Urgency\n}\n\n/**\n * Validate a status value.\n * @param raw - the raw input.\n */\nexport function asStatus(raw: string): TaskStatus {\n  if (!ALL_STATUSES.includes(raw as TaskStatus)) {\n    throw new Error(`status must be one of: ${ALL_STATUSES.join(', ')}`)\n  }\n  return raw as TaskStatus\n}\n\n/**\n * Validate an execution config request from raw tool/route input.\n * `scheduled` requires a valid cron; computes the first `nextRunAt` from\n * `now`.\n * @param raw - raw execution input ({@link ExecutionConfig} fields, untyped).\n * @param now - current epoch ms.\n * @returns the normalized config.\n */\nexport function normalizeExecution(\n  raw: { mode?: string; cron?: string },\n  now: number,\n): ExecutionConfig {\n  const mode = raw.mode ?? 'claim'\n  if (mode !== 'claim' && mode !== 'scheduled') {\n    throw new Error(\"execution.mode must be 'claim' or 'scheduled'\")\n  }\n  if (mode === 'claim') return { mode }\n  const cron = (raw.cron ?? '').trim()\n  const match = parseCron(cron)\n  if (match === null) throw new Error('execution.cron is not a valid 5-field cron expression')\n  const next = nextCronTime(match, now)\n  if (next === null) throw new Error('execution.cron never matches within 4 years')\n  return { mode, cron, nextRunAt: next }\n}\n\n/**\n * The effective prompt of a task: explicit prompt, or title+description.\n * @param task - the task.\n */\nexport function effectivePrompt(task: TaskRecord): string {\n  if (task.prompt.length > 0) return task.prompt\n  const head = task.title\n  return task.description.length > 0 ? `${head}\\n\\n${task.description}` : head\n}\n\n/**\n * Whether the task is currently claimed by a session (running state).\n * @param task - the task.\n */\nexport function isClaimedBy(task: TaskRecord): string | undefined {\n  return task.status === 'in_progress' && task.claimedBy !== undefined ? task.claimedBy : undefined\n}\n\n/**\n * Maintain the explicit claim fields around a status change: entering\n * in_progress under a session records the holder (an execution-start or an\n * agent claim); every move out of in_progress releases the claim (handoff,\n * give-back, cancel). A user-driven move into in_progress records no holder —\n * no session works on it yet.\n * @param task - the task being written (mutated in place).\n * @param to - the target status.\n * @param now - current epoch ms.\n * @param holder - the session id claiming the task, when applicable.\n */\nexport function syncClaim(task: TaskRecord, to: TaskStatus, now: number, holder?: string): void {\n  if (to !== 'in_progress') {\n    delete task.claimedBy\n    delete task.claimedAt\n  } else if (holder !== undefined) {\n    task.claimedBy = holder\n    task.claimedAt = now\n  }\n}\n\n/**\n * Validate and normalize a pinned model: `{ provider, model }`, both\n * non-empty trimmed strings.\n * @param raw - the raw input.\n * @returns the normalized model.\n * @throws when the shape or the fields are invalid.\n */\nexport function normalizeModel(raw: unknown): TaskModel {\n  if (typeof raw !== 'object' || raw === null) {\n    throw new Error('model must be { provider: string, model: string }')\n  }\n  const { provider, model } = raw as { provider?: unknown; model?: unknown }\n  if (typeof provider !== 'string' || typeof model !== 'string') {\n    throw new Error('model must be { provider: string, model: string }')\n  }\n  const p = provider.trim()\n  const m = model.trim()\n  if (p.length === 0 || m.length === 0) {\n    throw new Error('model.provider and model.model must be non-empty strings')\n  }\n  return { provider: p, model: m }\n}\n\n/**\n * Compact list-projection of a task (token-friendly for `taskboard_list`).\n * @param task - the task.\n */\nexport type TaskSummary = {\n  id: string\n  title: string\n  workspaceId: string\n  urgency: Urgency\n  status: TaskStatus\n  blocked: boolean\n  executionMode: ExecutionMode\n  nextRunAt?: number\n  model?: TaskModel\n  version: number\n  claimOwner?: string\n  commentCount: number\n  lastExecutionOutcome?: ExecutionRecord['outcome']\n  trashed: boolean\n}\n\n/**\n * Build the compact summary of a task.\n * @param task - the task.\n */\nexport function summarize(task: TaskRecord): TaskSummary {\n  const last = task.executions.length > 0 ? task.executions[task.executions.length - 1] : undefined\n  return {\n    id: task.id,\n    title: task.title,\n    workspaceId: task.workspaceId,\n    urgency: task.urgency,\n    status: task.status,\n    blocked: task.blocked,\n    executionMode: task.execution.mode,\n    nextRunAt: task.execution.nextRunAt,\n    model: task.model,\n    version: task.version,\n    claimOwner: isClaimedBy(task),\n    commentCount: task.comments.length,\n    lastExecutionOutcome: last?.outcome,\n    trashed: task.trashedAt !== undefined,\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-taskboard",
   "description": "Agent-first task board for the DSH web GUI: host-authoritative task ledger with taskboard_* agent tools, project (= workspace) claim boundaries, per-task model execution in fresh sessions, host-side cron scheduling, and a live SSE kanban view. Mounts via the official dsh plugin system — no DSH source changes.",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {

package/src/client/api.ts

@@ -48,6 +48,8 @@ export interface TaskboardClient {
   remove(id: string, body: DeleteTaskBody): Promise<{ trashed?: boolean; purged?: boolean }>
   /** Trigger a manual run (fresh in-project session). */
   run(id: string): Promise<{ executionId: string; sessionId: string }>
+  /** Cancel the running execution (stops the agent session; task returns to todo). */
+  cancel(id: string): Promise<{ cancelled: true; executionId: string }>
   /** Subscribe to change frames; the disposer stops the stream. */
   stream(onChange: (event: ChangeEvent) => void, onGap: () => void): () => void
 }
@@ -64,6 +66,7 @@ export function createClient(): TaskboardClient {
     comment: (id, bodyText) => post(`/dsh-taskboard/tasks/${encodeURIComponent(id)}/comment`, { body: bodyText }),
     remove: (id, body) => post(`/dsh-taskboard/tasks/${encodeURIComponent(id)}/delete`, body),
     run: id => post(`/dsh-taskboard/tasks/${encodeURIComponent(id)}/run`, {}),
+    cancel: id => post(`/dsh-taskboard/tasks/${encodeURIComponent(id)}/cancel`, {}),
     stream(onChange, onGap) {
       const es = new EventSource('/dsh-taskboard/events')
       let revision: number | undefined

package/src/client/board/TaskBoard.tsx

@@ -4,10 +4,11 @@
  *
  * @module dsh-taskboard/client/board/TaskBoard
  */
-import { useSyncExternalStore } from 'react'
+import { useEffect, useState, useSyncExternalStore } from 'react'
 import type { BoardController, ControllerState } from '../controller.ts'
 import type { TaskRecord, TaskStatus, Urgency } from '../../shared/protocol.ts'
 import { MAIN_STATUSES, canTransition } from '../../shared/protocol.ts'
+import { PLUGIN_VERSION } from '../../shared/version.ts'
 import { DRAG_TYPE, TaskCard } from './TaskCard.tsx'
 import { TaskDetail } from './TaskDetail.tsx'
 import { TaskFormModal } from './TaskFormModal.tsx'
@@ -40,11 +41,30 @@ export function fmtTime(ms: number | undefined): string {
   return `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
 }
 
-/** Apply the active filters to a task list. */
-function filterTasks(state: ControllerState, tasks: TaskRecord[]): TaskRecord[] {
-  return tasks.filter(t =>
+/** A claim idle for longer than this is highlighted as stale (ms). */
+export const STALE_CLAIM_MS = 30 * 60_000
+
+/** Whether the task's claim is stale (in_progress, held, idle too long). */
+export function isStaleClaim(task: TaskRecord, now: number): boolean {
+  return task.status === 'in_progress' && task.claimedAt !== undefined && now - task.claimedAt > STALE_CLAIM_MS
+}
+
+/** Urgency sort rank (urgent first). */
+const URGENCY_RANK: Record<Urgency, number> = { urgent: 0, normal: 1, relaxed: 2 }
+
+/** Apply the active filters + search + sort to a task list. */
+export function filterTasks(state: ControllerState, tasks: TaskRecord[]): TaskRecord[] {
+  const q = state.search.trim().toLowerCase()
+  const filtered = tasks.filter(t =>
     (state.filters.workspaceId === undefined || t.workspaceId === state.filters.workspaceId)
-    && (state.filters.urgencies.length === 0 || state.filters.urgencies.includes(t.urgency)))
+    && (state.filters.urgencies.length === 0 || state.filters.urgencies.includes(t.urgency))
+    && (q.length === 0 || t.title.toLowerCase().includes(q) || t.id.toLowerCase().includes(q)))
+  if (state.sortBy === 'default') return filtered
+  const sorted = [...filtered]
+  if (state.sortBy === 'updated') sorted.sort((a, b) => b.updatedAt - a.updatedAt)
+  else if (state.sortBy === 'created') sorted.sort((a, b) => b.createdAt - a.createdAt)
+  else if (state.sortBy === 'urgency') sorted.sort((a, b) => URGENCY_RANK[a.urgency] - URGENCY_RANK[b.urgency] || b.updatedAt - a.updatedAt)
+  return sorted
 }
 
 /**
@@ -56,6 +76,12 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
     cb => controller.subscribe(cb),
     () => controller.getSnapshot(),
   )
+  // Minute ticker: re-renders stale-claim highlights even without ledger changes.
+  const [now, setNow] = useState(() => Date.now())
+  useEffect(() => {
+    const timer = setInterval(() => setNow(Date.now()), 60_000)
+    return () => clearInterval(timer)
+  }, [])
   const live = filterTasks(state, state.ledger.tasks.filter(t => t.trashedAt === undefined))
   const selected = state.selectedId === undefined ? undefined : state.ledger.tasks.find(t => t.id === state.selectedId)
   const { alert: showAlert, el: alertEl } = useAlert()
@@ -69,6 +95,13 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
           + 新建任务
         </button>
         <div className="dsh-atb-spacer" />
+        <input
+          className="dsh-atb-input dsh-atb-search"
+          value={state.search}
+          placeholder="搜索标题 / ID…"
+          spellCheck={false}
+          onChange={e => controller.setSearch(e.target.value)}
+        />
         <select
           className="dsh-atb-select"
           value={state.filters.workspaceId ?? ''}
@@ -77,6 +110,17 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
           <option value="">全部项目</option>
           {state.workspaces.map(ws => <option key={ws.id} value={ws.id}>{ws.title || ws.path}</option>)}
         </select>
+        <select
+          className="dsh-atb-select"
+          value={state.sortBy}
+          title="列内排序"
+          onChange={e => controller.setSortBy(e.target.value as typeof state.sortBy)}
+        >
+          <option value="default">默认排序</option>
+          <option value="updated">最近更新</option>
+          <option value="urgency">按紧急度</option>
+          <option value="created">创建时间</option>
+        </select>
         {(['urgent', 'normal', 'relaxed'] as const).map(u => (
           <button
             key={u}
@@ -93,6 +137,16 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
         <button type="button" className="dsh-atb-btn" onClick={() => controller.toggleSecondary()}>
           {state.secondaryOpen ? '返回看板' : '其它任务'}
         </button>
+        <button type="button" className="dsh-atb-btn" title="下载完整台账备份（JSON）" onClick={() => controller.exportJson()}>⬇ JSON</button>
+        <button type="button" className="dsh-atb-btn" title="下载任务清单（CSV）" onClick={() => controller.exportCsv()}>⬇ CSV</button>
+        <a
+          className="dsh-atb-ver"
+          href="https://github.com/cloader/dsh-taskboard"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          V{PLUGIN_VERSION}
+        </a>
       </div>
 
       {state.error !== undefined && <div className="dsh-atb-error">{state.error}</div>}
@@ -130,6 +184,7 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
                   }}
                 >
                   <div className="dsh-atb-colhead">
+                    <span className="dsh-atb-dot" data-status={status} />
                     {COLUMN_LABELS[status]}
                     <span className="dsh-atb-colcount">{columnTasks.length}</span>
                   </div>
@@ -140,6 +195,7 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
                         task={task}
                         controller={controller}
                         draggable
+                        now={now}
                         onAlert={showAlert}
                       />
                     ))}
@@ -153,7 +209,7 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
 
       {selected !== undefined && (
         <div className="dsh-atb-detailpanel">
-          <TaskDetail task={selected} controller={controller} />
+          <TaskDetail task={selected} controller={controller} now={now} />
         </div>
       )}
 
@@ -169,16 +225,42 @@ export function TaskBoard({ controller }: { controller: BoardController }) {
   )
 }
 
-/** Secondary tab: canceled/archived/trashed rows. */
+/** Secondary tab: tasks grouped into canceled / archived / trashed columns. */
 function SecondaryTab({ controller, tasks }: { controller: BoardController; tasks: TaskRecord[] }) {
-  const rows = tasks.filter(t => t.status === 'canceled' || t.status === 'archived' || t.trashedAt !== undefined)
+  // Trashed takes precedence (a trashed task still carries its old status,
+  // but what matters to the user is the pending purge).
+  const trashed = tasks.filter(t => t.trashedAt !== undefined)
+  const archived = tasks.filter(t => t.trashedAt === undefined && t.status === 'archived')
+  const canceled = tasks.filter(t => t.trashedAt === undefined && t.status === 'canceled')
+  const groups = [
+    { label: '已取消', dot: 'canceled', rows: canceled },
+    { label: '已归档', dot: 'archived', rows: archived },
+    { label: '已删除', dot: 'trashed', rows: trashed },
+  ]
+  if (trashed.length + archived.length + canceled.length === 0) {
+    return (
+      <div className="dsh-atb-secondary">
+        <div className="dsh-atb-empty">无已取消 / 已归档 / 已删除任务</div>
+      </div>
+    )
+  }
   return (
-    <div className="dsh-atb-secondary">
-      {rows.length === 0 && <div className="dsh-atb-empty">无已取消 / 已归档 / 已删除任务</div>}
-      {rows.map(task => (
-        <TaskCard key={task.id} task={task} controller={controller} />
+    <div className="dsh-atb-columns">
+      {groups.map(group => (
+        <div className="dsh-atb-column" key={group.label}>
+          <div className="dsh-atb-colhead">
+            <span className="dsh-atb-dot" data-status={group.dot} />
+            {group.label}
+            <span className="dsh-atb-colcount">{group.rows.length}</span>
+          </div>
+          <div className="dsh-atb-cards">
+            {group.rows.map(task => (
+              <TaskCard key={task.id} task={task} controller={controller} />
+            ))}
+            {group.rows.length === 0 && <div className="dsh-atb-empty">无任务</div>}
+          </div>
+        </div>
       ))}
-      {void controller}
     </div>
   )
 }

package/src/client/board/TaskCard.tsx

@@ -8,7 +8,7 @@
  */
 import type { BoardController } from '../controller.ts'
 import type { TaskRecord } from '../../shared/protocol.ts'
-import { fmtTime } from './TaskBoard.tsx'
+import { fmtTime, isStaleClaim } from './TaskBoard.tsx'
 
 const URGENCY_LABEL: Record<TaskRecord['urgency'], string> = { urgent: '紧急', normal: '一般', relaxed: '不急' }
 const OUTCOME_LABEL: Record<string, string> = { running: '执行中', succeeded: '成功', failed: '失败', cancelled: '已取消' }
@@ -21,10 +21,13 @@ export const DRAG_TYPE = 'application/x-dsh-atb-task'
  * @param task - the task record.
  * @param controller - the controller.
  * @param draggable - enable dragging.
+ * @param now - current epoch ms (stale-claim highlight).
  * @param onAlert - show an alert message (replaces native alert).
  */
-export function TaskCard({ task, controller, draggable = false, onAlert }: { task: TaskRecord; controller: BoardController; draggable?: boolean; onAlert?: (msg: string) => void }) {
+export function TaskCard({ task, controller, draggable = false, now, onAlert }: { task: TaskRecord; controller: BoardController; draggable?: boolean; now?: number; onAlert?: (msg: string) => void }) {
   const last = task.executions.length > 0 ? task.executions[task.executions.length - 1] : undefined
+  const running = task.executions.find(ex => ex.outcome === 'running')
+  const stale = now !== undefined && isStaleClaim(task, now)
   return (
     <button
       type="button"
@@ -33,7 +36,6 @@ export function TaskCard({ task, controller, draggable = false, onAlert }: { tas
       draggable={draggable}
       onDragStart={(e) => {
         // Block drag if a session is still executing this task
-        const running = task.executions.find(ex => ex.outcome === 'running')
         if (running !== undefined) {
           e.preventDefault()
           const msg = `该任务正在由【${task.title}】会话执行，不能拖动`
@@ -52,6 +54,7 @@ export function TaskCard({ task, controller, draggable = false, onAlert }: { tas
       <div className="dsh-atb-card-meta">
         <span className="dsh-atb-badge">{URGENCY_LABEL[task.urgency]}</span>
         {task.blocked && <span className="dsh-atb-badge" data-kind="blocked">受阻</span>}
+        {stale && <span className="dsh-atb-badge" data-kind="stale">⏱ 认领超时</span>}
         {task.execution.mode === 'scheduled' && (
           <span className="dsh-atb-badge" data-kind="scheduled">⏰ {fmtTime(task.execution.nextRunAt)}</span>
         )}

package/src/client/board/TaskDetail.tsx

@@ -11,7 +11,8 @@ import { useState, type ReactNode } from 'react'
 import type { BoardController } from '../controller.ts'
 import type { TaskRecord } from '../../shared/protocol.ts'
 import { canTransition } from '../../shared/protocol.ts'
-import { fmtTime } from './TaskBoard.tsx'
+import { useAlert } from './AlertModal.tsx'
+import { fmtTime, isStaleClaim } from './TaskBoard.tsx'
 
 /** Statuses a user may move this task to, per the state machine. */
 function moveTargets(task: TaskRecord): TaskRecord['status'][] {
@@ -27,10 +28,10 @@ const STATUS_LABEL: Record<string, string> = { ...MOVE_LABEL }
 const URGENCY_LABEL: Record<string, string> = { urgent: '紧急', normal: '一般', relaxed: '不急' }
 const OUTCOME_LABEL: Record<string, string> = { running: '执行中', succeeded: '成功', failed: '失败', cancelled: '已取消' }
 
-/** Compact session-id display. */
+/** Compact session-id display (execution sessions carry the taskboard infix). */
 function shortId(id: string | undefined): string {
   if (id === undefined) return ''
-  return id.replace(/^session-/, '').slice(0, 8)
+  return id.replace(/^session-(taskboard-)?/, '').slice(0, 8)
 }
 
 /** Execution duration between start and end. */
@@ -51,13 +52,28 @@ function Chip({ icon, children, tone }: { icon?: string; children: ReactNode; to
  * The detail view.
  * @param task - the task record.
  * @param controller - the controller.
+ * @param now - current epoch ms (stale-claim highlight).
  */
-export function TaskDetail({ task, controller }: { task: TaskRecord; controller: BoardController }) {
+export function TaskDetail({ task, controller, now }: { task: TaskRecord; controller: BoardController; now?: number }) {
   const [comment, setComment] = useState('')
   const [confirmDone, setConfirmDone] = useState(false)
   const [confirmPurge, setConfirmPurge] = useState(false)
+  const [confirmCancel, setConfirmCancel] = useState(false)
+  const { alert: showAlert, el: alertEl } = useAlert()
   const ws = controller.getSnapshot().workspaces.find(w => w.id === task.workspaceId)
   const canRun = task.status !== 'in_progress' && task.status !== 'done' && task.status !== 'archived'
+  const runningExecution = task.executions.find(e => e.outcome === 'running')
+  const holder = task.status === 'in_progress' ? task.claimedBy : undefined
+  const stale = now !== undefined && isStaleClaim(task, now)
+
+  /** Jump to an execution's session; prompt precisely when it cannot open. */
+  const jumpToSession = (sessionId: string): void => {
+    void controller.openSession(sessionId).then(result => {
+      if (result === 'missing') showAlert(`该会话已被删除（${shortId(sessionId)}），无法打开`)
+      else if (result === 'archived') showAlert(`该会话已归档（${shortId(sessionId)}），已从会话列表隐藏`)
+      else if (result === 'unavailable') showAlert(`会话导航不可用，会话 ID：${sessionId}`)
+    })
+  }
 
   return (
     <div className="dsh-atb-detail" data-urgency={task.urgency}>
@@ -75,6 +91,11 @@ export function TaskDetail({ task, controller }: { task: TaskRecord; controller:
               <Chip icon="⏰">{task.execution.cron} · 下次 {fmtTime(task.execution.nextRunAt)}</Chip>
             )}
             {task.blocked && <Chip icon="⛔" tone="urgent">受阻</Chip>}
+            {holder !== undefined && (
+              <Chip icon={stale ? '⏱' : '🔑'} tone={stale ? 'urgent' : undefined}>
+                {stale ? '认领超时 · ' : '由 '}{shortId(holder)} 持有
+              </Chip>
+            )}
             {task.trashedAt !== undefined && <Chip icon="🗑" tone="urgent">已删除待清除</Chip>}
             <Chip>v{task.version}</Chip>
           </div>
@@ -84,6 +105,14 @@ export function TaskDetail({ task, controller }: { task: TaskRecord; controller:
         </div>
         <div className="dsh-atb-detail-topbtns">
           <button type="button" className="dsh-atb-detail-edit" onClick={() => controller.openEditor(task.id)}>✎ 编辑</button>
+          <button
+            type="button"
+            className="dsh-atb-detail-edit"
+            title="复制此任务的全部配置为一张新卡（待办列）"
+            onClick={() => void controller.duplicate(task)}
+          >
+            ⧉ 复制
+          </button>
           {canRun && (
             <button
               type="button"
@@ -94,6 +123,25 @@ export function TaskDetail({ task, controller }: { task: TaskRecord; controller:
               ▶ 立即执行
             </button>
           )}
+          {runningExecution !== undefined && (confirmCancel
+            ? (
+              <span className="dsh-atb-confirm">
+                <span className="dsh-atb-confirm-label">停止该执行会话？</span>
+                <button type="button" className="dsh-atb-btn" data-danger="true" onClick={() => { void controller.cancel(task.id); setConfirmCancel(false) }}>停止</button>
+                <button type="button" className="dsh-atb-btn" onClick={() => setConfirmCancel(false)}>取消</button>
+              </span>
+            )
+            : (
+              <button
+                type="button"
+                className="dsh-atb-detail-run"
+                data-danger="true"
+                title={`停止执行会话 ${runningExecution.sessionId ?? ''}（任务回到待办）`}
+                onClick={() => setConfirmCancel(true)}
+              >
+                ■ 停止执行
+              </button>
+            ))}
           <button type="button" className="dsh-atb-detail-close" aria-label="关闭" onClick={() => controller.select(undefined)}>✕</button>
         </div>
       </div>
@@ -132,6 +180,17 @@ export function TaskDetail({ task, controller }: { task: TaskRecord; controller:
           <button type="button" className="dsh-atb-movebtn" data-to="blocked" onClick={() => void controller.toggleBlocked(task)}>
             {task.blocked ? '✓ 解除受阻' : '⛔ 标记受阻'}
           </button>
+          {holder !== undefined && (
+            <button
+              type="button"
+              className="dsh-atb-movebtn"
+              data-to="release"
+              title={`释放 ${holder} 的认领：任务回到待办（持有会话可能仍在工作，确认它已停止后再释放）`}
+              onClick={() => void controller.move(task.id, task.version, 'todo')}
+            >
+              🔓 释放认领
+            </button>
+          )}
         </div>
       </div>
 
@@ -181,15 +240,28 @@ export function TaskDetail({ task, controller }: { task: TaskRecord; controller:
 
       {task.executions.length > 0 && (
         <div className="dsh-atb-section">
-          <h4>执行记录<span className="dsh-atb-count2">{task.executions.length}</span></h4>
+          <h4>执行记录<span className="dsh-atb-count2">{task.executions.length}</span>
+            {task.executionsPruned !== undefined && task.executionsPruned > 0 && (
+              <span className="dsh-atb-count2" title={`更早的 ${task.executionsPruned} 条执行记录已按保留上限清理`}>+{task.executionsPruned} 已清理</span>
+            )}
+          </h4>
           <div className="dsh-atb-execlist">
-            {task.executions.map(e => (
+            {[...task.executions].reverse().map(e => (
               <div key={e.id} className="dsh-atb-exec-row">
                 <span className="dsh-atb-exec-dot" data-outcome={e.outcome} />
                 <span className="dsh-atb-exec-trigger">{e.trigger === 'manual' ? '手动' : '定时'}</span>
                 <span className="dsh-atb-exec-outcome" data-outcome={e.outcome}>{OUTCOME_LABEL[e.outcome] ?? e.outcome}</span>
                 <span className="dsh-atb-exec-time">{fmtTime(e.startedAt)}{e.endedAt !== undefined && ` · ${duration(e.startedAt, e.endedAt)}`}</span>
-                {e.sessionId !== undefined && <span className="dsh-atb-exec-session" title={e.sessionId}>🤖 {shortId(e.sessionId)}</span>}
+                {e.sessionId !== undefined && (
+                  <button
+                    type="button"
+                    className="dsh-atb-exec-session"
+                    title={`点击打开该执行会话：${e.sessionId}`}
+                    onClick={() => jumpToSession(e.sessionId!)}
+                  >
+                    🤖 {shortId(e.sessionId)} ↗
+                  </button>
+                )}
                 {e.error !== undefined && <span className="dsh-atb-exec-error" title={e.error}>{e.error.slice(0, 80)}{e.error.length > 80 ? '…' : ''}</span>}
               </div>
             ))}
@@ -210,6 +282,8 @@ export function TaskDetail({ task, controller }: { task: TaskRecord; controller:
                 )
               : <button type="button" className="dsh-atb-btn" data-danger="true" onClick={() => setConfirmPurge(true)}>🔥 物理清除（需确认）</button>)}
       </div>
+
+      {alertEl}
     </div>
   )
 }

package/src/client/board/TaskFormModal.tsx

@@ -222,7 +222,7 @@ export function TaskFormModal({ controller, task }: { controller: BoardControlle
           </Field>
 
           <Field label={editing ? '执行 Prompt' : '执行 Prompt（可选，默认 = 标题+描述）'} full>
-            <textarea value={prompt} onChange={e => setPrompt(e.target.value)} placeholder="发给执行会话的完整指令" />
+            <textarea value={prompt} onChange={e => setPrompt(e.target.value)} placeholder={'发给执行会话的完整指令。支持模板变量：{{lastExecution}}（上次执行结果）、{{lastComments}}（最近 3 条评论）'} />
           </Field>
 
           <Field label="执行方式" full>