taskchef 7.12.2 → 7.13.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.12.2",
+  "version": "7.13.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",
@@ -20,7 +20,7 @@
   "interface": {
     "displayName": "TaskChef",
     "shortDescription": "Dispatch work to the right Codex project task.",
-    "longDescription": "Route work to visible Codex project tasks, cache their latest semantic result, and query fresh reports on demand.",
+    "longDescription": "Route work to visible Codex project tasks, monitor them in the dashboard, and get concise cached-first coordination briefs.",
     "developerName": "Favo Yang",
     "category": "Productivity",
     "capabilities": [
@@ -32,7 +32,7 @@
       "$taskchef-bootstrap Set up TaskChef in this folder.",
       "$taskchef-delegate Dispatch this request to the right project.",
       "$taskchef-executor Execute this delegated TaskChef assignment.",
-      "$taskchef-report Report on work in the TaskChef task history."
+      "$taskchef-copilot Explain TaskChef outcomes and recommend the next action."
     ],
     "brandColor": "#D97706",
     "composerIcon": "./assets/taskchef.svg",

package/README.md

@@ -136,27 +136,47 @@ inline executor protocol still parses, self-links, and may use the deprecated
 `report_result` alias. The v7 inline-paragraph named exports remain as deprecated
 historical snapshots, but new delegations use the executor skill and `report_state`.
 
-## View and report tasks
+## View tasks and ask copilot
 
-Ask the dispatcher for an on-demand report:
+The dashboard is the primary monitoring and browsing UI. Ask copilot when you
+want a concise explanation or recommendation:
 
 ```text
-Report on the work TaskChef has dispatched.
+$taskchef-copilot What finished, what needs attention, and what should I do next?
 ```
 
-The reporting skill combines cached semantic results with one bounded live
-metadata snapshot. It does not poll or write inferred status. File-backed
-inspection is also available:
+Copilot starts from TaskChef's normalized cached brief. It uses live Codex
+metadata only when you explicitly request fresh/live verification or a focused
+task presents a meaningful contradiction, and it never polls. It can identify
+the exact executor, explain or draft a same-assignment follow-up, and—with your
+explicit authorization—continue that existing task. It never automatically
+retries failures, interrupts working tasks, or redelegates an executor. New
+independent work still belongs to `$taskchef-delegate`. In the dispatcher, an
+explicit instruction to answer, resume, or continue a named existing task
+routes to copilot; it re-reads that exact task before sending.
+
+The former `$taskchef-report` skill is not packaged as an alias because a
+second discoverable skill would preserve ambiguous behavior. Explicit
+historical invocations are understood as requests for `$taskchef-copilot` and
+receive a brief rename notice.
+
+File-backed inspection is also available:
 
 ```sh
+taskchef task brief
+taskchef task brief c0f010ff
+taskchef task brief --project payments
 taskchef task list
 taskchef task list --project payments
 taskchef task show c0f010ff
 taskchef task summary
 ```
 
-Add `--json` for structured output. `task show` accepts a full task UUID or
-an unambiguous eight-character prefix.
+Add `--json` for structured output. `task brief` returns the stable schema-1
+cached coordination model and omits terminal tasks older than seven days from
+overviews unless `--all` is supplied. Focused task and project briefs retain
+their full selected scope. Task IDs accept a full UUID or an unambiguous
+eight-character prefix.
 
 ## Dashboard
 

package/assets/taskchef-dispatcher-instructions.md

@@ -9,18 +9,26 @@ This folder is the canonical per-user TaskChef dispatcher workspace.
 - Use `$taskchef-bootstrap` when initializing or refreshing this workspace,
   changing or listing its configured projects, running TaskChef doctor,
   or repairing its managed instructions.
-- For every actionable work request, use `$taskchef-delegate`
-  automatically, even when the user does not explicitly say "delegate" or
-  mention TaskChef.
+- When the user asks to answer, follow up, resume, or continue the same
+  recorded assignment in its existing executor task, use `$taskchef-copilot`
+  before the general delegation rule. A direct imperative that names the exact
+  existing task is explicit send authorization, but copilot must immediately
+  re-read that exact task and apply its state and identity guardrails.
+- For every other actionable request that asks for an independent new outcome,
+  use `$taskchef-delegate` automatically, even when the user does not explicitly
+  say "delegate" or mention TaskChef.
 - GitHub issue and pull-request URLs may identify any repository advertised by
   a configured project, including child repositories of managed workspaces.
 - Do not perform delegated work directly in the dispatcher thread.
 - Return immediately after dispatch, as required by `$taskchef-delegate`.
 - Answer directly only when the user explicitly asks about TaskChef itself or
   explicitly says not to delegate.
-- Use `$taskchef-report` only when the user asks for a live report about
-  delegated work. Reports query the recorded Codex tasks once and do not
-  write status or results to this workspace.
+- Use `$taskchef-copilot` when the user asks what delegated work finished,
+  what needs attention, why it failed or needs input, or what should happen
+  next, including same-assignment continuation in an exact existing executor.
+  Copilot uses the cached TaskChef brief by default; the dashboard is the
+  primary monitoring and browsing UI. Live verification is explicit or
+  contradiction-driven, focused, and never polled.
 - Explicit invocations of TaskChef skills from other Codex projects use this
   same workspace and task history through TaskChef's global resolution rules.
 - Every final response in this dispatcher workspace must end with this exact

package/docs/firstmate-taskchef-comparison.md

@@ -170,10 +170,10 @@ semantic `failed`.
 `needs_input` is reserved for a real semantic decision, not a native approval
 prompt.
 
-**Fact:** The report skill treats cached results as evidence, takes one recent
-Codex metadata snapshot, and performs targeted exact-thread reads only for
-selected anomalies or freshness checks. It never polls or writes inferred
-state.
+**Fact:** The copilot skill explains normalized cached briefs by default and
+uses live Codex metadata only for an explicit fresh/live request or a focused
+meaningful contradiction. It recommends safe next actions, never polls, and
+never writes inferred state.
 
 ### FirstMate
 
@@ -198,8 +198,9 @@ This navigation check does not prove schema 4 or 5 self-link provenance. The
 dashboard does not refresh native task state, submit replies, or show
 transcripts or token usage.
 
-**Fact:** The user can also ask for a live TaskChef report or inspect the data
-CLI. Executor work remains visible in normal Codex desktop tasks.
+**Fact:** The user can also ask TaskChef copilot for a concise cached brief or
+focused live verification, or inspect the data CLI. Executor work remains
+visible in normal Codex desktop tasks.
 
 ### FirstMate
 
@@ -218,7 +219,7 @@ harness adapter.
 | --- | --- | --- |
 | Codex | Built around native Codex projects, tasks, thread reads, and desktop deep links. | Codex is one verified harness; desktop tasks are not its worker runtime. |
 | GitHub | Configured repository URLs aid routing; delivery remains the executor project's concern. | GitHub CLI, PR state, and configured delivery modes are part of supervised shipping workflows. |
-| Skills | Four plugin skills with narrow bootstrap, delegate, executor, and report responsibilities. | Internal firstmate-only skills plus standalone public skills; AGENTS.md routes conditional procedures. |
+| Skills | Four plugin skills with narrow bootstrap, delegate, executor, and conversational coordination responsibilities. | Internal firstmate-only skills plus standalone public skills; AGENTS.md routes conditional procedures. |
 | MCP | Four primary local TaskChef tools plus one deprecated compatibility alias own deterministic identity and state writes. | FirstMate describes itself as an agent distribution rather than an MCP product; deterministic behavior lives largely in scripts. |
 | Runtime extensions | Extend plugin skills/MCP/CLI/dashboard or compose native Codex capabilities. | Add or verify harness adapters, session backends, dispatch profiles, operational scripts, and optional integrations. |
 

package/docs/spec.md

@@ -28,7 +28,7 @@ is dated research, not contract.
 | **Last semantic result** | The final result-history entry, exposed through the derived `lastResult` compatibility alias. |
 | **Current turn ID** | The canonical Codex UUIDv7 returned by an exact native read of the linked executor for the turn being reported. |
 | **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots and bounded native actions. |
-| **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-report`. |
+| **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-copilot`. |
 
 ## Components and ownership
 
@@ -39,8 +39,9 @@ is dated research, not contract.
 - `taskchef-executor` MUST own executor assignment ownership, self-linking,
   exact thread/turn identity, per-turn state reporting, failure behavior,
   privacy, and idempotency. It MUST NOT dispatch the owned assignment again.
-- `taskchef-report` MUST own on-demand reporting. It MUST NOT poll or persist
-  inferred state.
+- `taskchef-copilot` MUST own conversational outcome explanation, attention,
+  and next-action recommendations. It MUST use cached normalized briefs by
+  default and MUST NOT poll or persist inferred state.
 - The MCP server MUST expose `ensure_dashboard`, four primary lifecycle tools,
   and the deprecated `report_result` compatibility alias specified below.
 - The CLI MAY administer and inspect the workspace, but MUST NOT provide a
@@ -320,15 +321,40 @@ low-level opaque direct records. It does not accept `working`. New executor
 instructions MUST use `report_state`. Successful mutation upgrades schema 4/5/6/7
 to schema 8; unsupported schemas remain rejected.
 
-## Reporting and dashboard
-
-A semantic result is cached evidence, not permanent live truth. Reports SHOULD
-use one bounded native metadata snapshot. Active or approval-waiting native
-state overrides cache. An inactive task does not prove completion. Focused
-reports MAY read a selected task once when metadata is newer or evidence is
-uncertain. Reports MUST NOT poll or classify assistant prose.
-
-Task lists, summaries, and broad reports MUST use the final result by default.
+## Copilot and dashboard
+
+A semantic result is cached evidence, not permanent live truth. The dashboard
+MUST remain the primary monitoring and browsing UI. Copilot MUST start from the
+schema-1 normalized cached brief and explain what finished, what needs
+attention, why, and the recommended next action. It MUST NOT need to interpret
+historical task schema versions. A working task's current summary MUST remain
+null; any prior semantic result MUST be exposed separately as a clearly
+historical `lastOutcome`. A link-pending task with no exact thread identity MUST
+recommend passive waiting or inspection, never retry or continuation.
+
+Copilot MAY take one bounded native metadata snapshot only when the user
+explicitly requests fresh/live verification or a focused task presents a
+meaningful contradiction. Active or approval-waiting native state overrides
+cache. An inactive task does not prove completion. Copilot MAY read the exact
+selected task once for an explicit focused live-verification request or to
+resolve a focused contradiction. It MUST NOT poll, wait, perform exhaustive
+live audits, or classify assistant prose.
+
+Copilot MAY identify the exact existing executor, explain or draft a
+same-assignment follow-up, and continue that executor only with explicit user
+authorization. It MUST NOT automatically retry failures, interrupt working
+tasks, or redelegate an existing executor. Independent new work MUST route
+through delegation. Managed dispatcher routing MUST give same-assignment
+answer, follow-up, resume, and continue requests precedence over the blanket
+new-work delegation rule. A direct imperative naming the exact existing task
+MAY constitute send authorization, but copilot MUST re-read that exact task
+immediately before sending.
+
+The published plugin MUST NOT package `taskchef-report` as a discoverable alias.
+Its historical explicit name is a documented rename hint handled by copilot,
+not a second workflow.
+
+Task lists, summaries, and broad briefs MUST use the final result by default.
 The dashboard MUST bind only to loopback, validate the current workspace
 snapshot, and avoid sessions or shared client state. `GET /api/health` MUST
 return only the bounded service identity, health schema, exact TaskChef and

package/docs/workflows.md

@@ -13,11 +13,11 @@ research.
 | `skills/taskchef-delegate/SKILL.md` | Split, route, record-before-create, create, return. |
 | `skills/taskchef-executor/SKILL.md` | Own, self-link, execute, and report every executor turn. |
 | `skills/taskchef-bootstrap/SKILL.md` | Initialize current workspace and configure projects. |
-| `skills/taskchef-report/SKILL.md` | Select cached tasks and perform bounded live checks. |
+| `skills/taskchef-copilot/SKILL.md` | Explain normalized cached briefs and coordinate safe next actions. |
 | `src/mcp.js` | Dashboard ensure, four primary lifecycle tools, one deprecated alias, shutdown ownership, and MCP annotations. |
 | `src/delegation.js` | UUID marker, concise executor-skill invocation shape, and creation-failure handling. |
 | `src/workspace.js` | Current schemas, validation, locking, atomic JSONL writes, linking, and result freshness. |
-| `src/cli.js` | Administration, inspection, diagnostics, and dashboard startup. |
+| `src/cli.js` | Administration, normalized cached briefs, inspection, diagnostics, and dashboard startup. |
 | `src/dashboard.js` | Versioned health identity, validated compact snapshots, SSE fan-out, on-demand details, and bounded open actions. |
 | `src/dashboard-manager.js` | Concurrent singleton ensure, exact listener reuse, conflicts, and owned shutdown. |
 
@@ -29,7 +29,7 @@ per-user default.
 
 The generated managed `AGENTS.md` block makes dashboard maintenance a
 best-effort prelude to every dispatcher turn and keeps response ordering
-centralized instead of duplicating it across delegate/report skills.
+centralized instead of duplicating it across delegate/copilot skills.
 
 ```mermaid
 sequenceDiagram

package/index.js

@@ -1,4 +1,5 @@
 export {
+  buildCopilotBrief,
   addProject,
   buildTaskSummary,
   canonicalDirectory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.12.2",
+  "version": "7.13.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -38,7 +38,7 @@
     "skills/taskchef-bootstrap",
     "skills/taskchef-delegate",
     "skills/taskchef-executor",
-    "skills/taskchef-report"
+    "skills/taskchef-copilot"
   ],
   "engines": {
     "node": ">=18"

package/skills/taskchef-copilot/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: taskchef-copilot
+description: "Explain and coordinate TaskChef executor outcomes from cached task briefs. Use when the user asks what finished, what needs attention, why a delegated task failed or needs input, what should happen next, asks to answer, follow up, resume, or continue the same recorded assignment in its existing task, or explicitly invokes the historical $taskchef-report name. The dashboard remains the primary monitoring UI. Use live Codex metadata only for an explicit fresh/live request or a meaningful focused contradiction, and never poll."
+---
+
+# TaskChef Copilot
+
+Act as TaskChef's conversational coordination assistant. Give a concise brief
+about finished work, attention, cause, and the safest next action. The dashboard
+is the primary place to browse and monitor the task history.
+
+Resolve this skill directory with `realpath`. The TaskChef plugin root is two
+parents above it. Invoke `<plugin-root>/bin/taskchef.js` for deterministic
+TaskChef data reads.
+
+## Cached brief first
+
+1. Select the smallest scope that answers the request:
+   - exact task: `task brief <task-id> --json`;
+   - configured project: `task brief --project <name-or-path> --json`;
+   - overview: `task brief --json`.
+   Use `task list --json` once only when a title or description must first be
+   matched. Ask when multiple tasks plausibly match.
+2. Treat the returned schema-1 brief as the stable model. Do not interpret raw
+   task-log schema versions or read `tasks.jsonl` directly. The brief already
+   normalizes state, current summary, explicitly historical `lastOutcome`,
+   attention, next action, interrupted-turn count, link-pending identity, and
+   the default seven-day overview window. Never present `lastOutcome` as the
+   result of a newer working request.
+3. Lead with the useful answer: what finished, what needs attention, why, and
+   what action should happen next. Keep overviews short and mention the omitted
+   old-terminal count when nonzero. Link or identify the exact existing
+   executor task when its durable thread ID is available.
+
+## Live verification is exceptional
+
+Use native Codex metadata only when the user explicitly asks for a fresh,
+current, or live verification, or when a focused task has a meaningful
+contradiction such as the user observing activity that conflicts with the
+cached brief.
+
+- Take one bounded metadata snapshot and match only the exact stored thread ID.
+- For one focused task, read that exact existing task once when the user
+  explicitly requests live verification or when needed to resolve a meaningful
+  contradiction. Do not read transcripts or classify assistant prose.
+- Active or native-approval state may override the cached presentation. An
+  inactive task does not prove semantic completion. If verification fails,
+  present the cached brief with a freshness warning.
+- Never poll, wait, repeatedly refresh, or perform a broad exhaustive live
+  audit.
+
+## Coordination and continuation
+
+- Explain or draft a focused follow-up for the exact existing executor task.
+- Continue that task only after the user explicitly authorizes sending the
+  follow-up. A direct imperative naming the exact existing task is explicit
+  send authorization. Re-read the exact target immediately before sending and
+  preserve its durable identity.
+- Never automatically retry a failure, interrupt a working task, or redelegate
+  an existing executor as a new task.
+- A missing executor link calls for passive waiting or identity inspection,
+  not a retry, continuation, or reason to create another executor.
+- Keep same-assignment follow-up in the existing executor task. Independent new
+  work with its own outcome belongs to `$taskchef-delegate`.
+- If scope is mixed, separate the proposed existing-task follow-up from the new
+  work and ask for authorization before either mutation.
+
+## Historical invocation
+
+`taskchef-report` was renamed rather than retained as a packaged alias because
+a second discoverable skill would preserve ambiguous reporting behavior. If a
+user explicitly writes `$taskchef-report`, briefly note the rename and fulfill
+the request through this cached-first copilot workflow.

package/skills/taskchef-copilot/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Copilot"
+  short_description: "Explain outcomes and recommend next actions"
+  default_prompt: "Use $taskchef-copilot to give a concise cached brief of TaskChef work and recommend the safest next action."

package/src/cli.js

@@ -7,6 +7,7 @@ import { resolveWorkspacePath } from "./workspace-path.js";
 
 import {
   addProject,
+  buildCopilotBrief,
   buildTaskSummary,
   doctorWorkspace,
   filterTasks,
@@ -414,6 +415,43 @@ async function taskSummary(args) {
   return 0;
 }
 
+async function taskBrief(args) {
+  const hasTaskId = Boolean(args[2] && !args[2].startsWith("--"));
+  validateCommandArgs(args, hasTaskId ? 3 : 2, {
+    values: ["--workspace", "--project"],
+    switches: ["--all", "--json"],
+  });
+  if (hasTaskId && args.includes("--project")) {
+    throw new Error("task brief accepts either a task ID or --project, not both");
+  }
+  const taskId = hasTaskId
+    ? (await readTaskForShow(workspaceRoot(args), args[2])).id
+    : null;
+  const brief = await buildCopilotBrief(workspaceRoot(args), {
+    taskId,
+    project: option(args, "--project", null),
+    includeOldTerminal: args.includes("--all"),
+  });
+  print(brief, args, (value) => {
+    const rows = value.tasks.map((task) => [
+      task.title,
+      task.project.name,
+      task.state,
+      task.attention?.kind ?? "-",
+      task.nextAction.kind,
+      displayId(task.id, false),
+    ]);
+    return [
+      `Cached TaskChef brief (${value.scope})`,
+      table(["TITLE", "PROJECT", "STATE", "ATTENTION", "NEXT ACTION", "ID"], rows),
+      value.omittedTerminalCount > 0
+        ? `Omitted old terminal tasks: ${value.omittedTerminalCount}`
+        : null,
+    ].filter(Boolean).join("\n");
+  });
+  return 0;
+}
+
 function dashboardPort(args) {
   const value = option(args, "--port", "3210");
   if (!/^\d+$/.test(value)) throw new Error("--port must be an integer from 0 to 65535");
@@ -481,6 +519,7 @@ Usage:
   taskchef project remove <name> [--json] [--workspace <path>]
   taskchef dispatch prepare [--json] [--workspace <path>]
   taskchef task record [--json] [--workspace <path>]
+  taskchef task brief [<task-id-or-8-character-prefix> | --project <name-or-path>] [--all] [--json] [--workspace <path>]
   taskchef task show <task-id-or-8-character-prefix> [--json] [--workspace <path>]
   taskchef task list [--project <name-or-path>] [--ascending] [--full-id] [--json] [--workspace <path>]
   taskchef task summary [--json] [--workspace <path>]
@@ -515,6 +554,7 @@ export async function runCli(args) {
   if (args[0] === "project" && args[1] === "remove") return projectRemove(args);
   if (args[0] === "dispatch" && args[1] === "prepare") return dispatchPrepare(args);
   if (args[0] === "task" && args[1] === "record") return taskRecord(args);
+  if (args[0] === "task" && args[1] === "brief") return taskBrief(args);
   if (args[0] === "task" && args[1] === "show" && args[2]) return taskShow(args);
   if (args[0] === "task" && args[1] === "list") return taskList(args);
   if (args[0] === "task" && args[1] === "summary") return taskSummary(args);

package/src/workspace.js

@@ -1581,6 +1581,148 @@ export async function buildTaskSummary(workspaceRoot) {
   };
 }
 
+const COPILOT_RECENT_TERMINAL_DAYS = 7;
+
+function sortTasksByNewestUpdate(tasks) {
+  return tasks
+    .map((task, index) => ({ task, index }))
+    .sort((left, right) => (
+      Date.parse(right.task.updatedAt) - Date.parse(left.task.updatedAt)
+      || left.index - right.index
+    ))
+    .map(({ task }) => task);
+}
+
+function taskBriefEntry(task) {
+  const linkPending = task.threadId === null && task.status === "working";
+  const creationFailure = task.threadId === null && task.status === "failed";
+  const interruptedTurnCount = task.turns.filter(
+    (turn) => turn.result?.status === "interrupted",
+  ).length;
+  let attention = null;
+  let nextAction;
+  if (linkPending) {
+    attention = {
+      kind: "link_pending",
+      reason: "The executor has not linked its durable Codex task identity yet.",
+    };
+    nextAction = {
+      kind: "wait",
+      instruction: "Wait for the existing executor to self-link; recover its exact identity before proposing any continuation.",
+      requiresExplicitAuthorization: false,
+    };
+  } else if (task.status === "needs_input") {
+    attention = {
+      kind: "needs_input",
+      reason: task.summary,
+    };
+    nextAction = {
+      kind: "continue_existing_task",
+      instruction: "Provide the missing decision or fact in the existing executor task.",
+      requiresExplicitAuthorization: true,
+    };
+  } else if (task.status === "failed") {
+    attention = {
+      kind: creationFailure ? "creation_failed" : "failed",
+      reason: task.summary,
+    };
+    nextAction = creationFailure ? {
+      kind: "inspect_creation_failure",
+      instruction: "Review the creation failure before deciding whether to dispatch new work.",
+      requiresExplicitAuthorization: true,
+    } : {
+      kind: "continue_existing_task",
+      instruction: "Review the failure and authorize a focused follow-up in the existing executor task if appropriate.",
+      requiresExplicitAuthorization: true,
+    };
+  } else if (task.status === "working") {
+    nextAction = {
+      kind: "wait",
+      instruction: "No action is recommended while the existing executor is working.",
+      requiresExplicitAuthorization: false,
+    };
+  } else {
+    nextAction = {
+      kind: "none",
+      instruction: "No follow-up is required unless the user has a new request.",
+      requiresExplicitAuthorization: false,
+    };
+  }
+  return {
+    id: task.id,
+    title: task.title,
+    project: {
+      name: task.project.name,
+      path: task.project.path,
+    },
+    threadId: task.threadId,
+    state: task.status,
+    summary: task.summary,
+    lastOutcome: task.lastResult === null ? null : {
+      status: task.lastResult.status,
+      summary: task.lastResult.summary,
+      turnId: task.lastResult.turnId,
+      updatedAt: task.lastResult.updatedAt,
+    },
+    requestSummary: task.latestTurn?.requestSummary ?? null,
+    updatedAt: task.updatedAt,
+    attention,
+    nextAction: {
+      ...nextAction,
+      taskId: task.id,
+      threadId: task.threadId,
+    },
+    liveCheck: {
+      recommended: false,
+      reason: null,
+    },
+    interruptedTurnCount,
+  };
+}
+
+export async function buildCopilotBrief(workspaceRoot, {
+  project = null,
+  taskId = null,
+  includeOldTerminal = false,
+  now = () => new Date().toISOString(),
+} = {}) {
+  if (project !== null && taskId !== null) {
+    throw new Error("copilot brief accepts either project or taskId, not both");
+  }
+  let tasks = project === null
+    ? await listTasks(workspaceRoot)
+    : await filterTasks(workspaceRoot, { project });
+  if (taskId !== null) {
+    const id = requireSafeId(taskId, "taskId");
+    tasks = tasks.filter((task) => task.id === id);
+    if (tasks.length === 0) throw new Error(`task not found: ${id}`);
+  }
+  const generatedAt = requireTimestamp(now(), "copilot brief timestamp");
+  const recentCutoff = Date.parse(generatedAt)
+    - COPILOT_RECENT_TERMINAL_DAYS * 24 * 60 * 60 * 1_000;
+  const focused = taskId !== null || project !== null;
+  const selected = [];
+  let omittedTerminalCount = 0;
+  for (const task of sortTasksByNewestUpdate(tasks)) {
+    const terminal = task.status === "completed" || task.status === "failed";
+    const oldTerminal = terminal && Date.parse(task.updatedAt) < recentCutoff;
+    if (!focused && !includeOldTerminal && oldTerminal) {
+      omittedTerminalCount += 1;
+      continue;
+    }
+    selected.push(taskBriefEntry(task));
+  }
+  return {
+    schemaVersion: 1,
+    mode: "cached",
+    scope: taskId !== null ? "task" : project !== null ? "project" : "overview",
+    generatedAt,
+    taskCount: selected.length,
+    omittedTerminalCount,
+    tasks: selected,
+  };
+}
+
 export async function doctorWorkspace(workspaceRoot) {
   const root = path.resolve(workspaceRoot);
   const checks = [];

package/skills/taskchef-report/SKILL.md

@@ -1,91 +0,0 @@
----
-name: taskchef-report
-description: "Report useful current state for Codex tasks recorded by TaskChef. Use only when the user asks for delegated-task status, outcomes, or a report. Prefer cached semantic results, filter old terminal tasks from overviews, use one cheap live metadata snapshot to override active or approval-waiting tasks, and reserve detailed reads for anomalies. Never poll or wait."
----
-
-# TaskChef Report
-
-Read the canonical per-user TaskChef task snapshots and report useful current
-state once. A stored result is cached semantic evidence, not permanent truth.
-
-Resolve this skill directory with `realpath`. The TaskChef plugin root is two
-parents above the skill directory. Invoke `<plugin-root>/bin/taskchef.js` for
-all deterministic task-log operations.
-
-## Report
-
-1. Run `<plugin-root>/bin/taskchef.js workspace path --json`. The CLI resolves
-   `--workspace`, then an absolute (or `~/`-prefixed) `TASKCHEF_WORKSPACE`, then
-   `~/.agents/taskchef`; never
-   infer the history from the current project. Select only the tasks the user
-   asked about:
-   - For an exact task ID, run
-     `<plugin-root>/bin/taskchef.js task show <task-id> --json`.
-   - For a project, run
-     `<plugin-root>/bin/taskchef.js task list --project <name-or-path> --json`.
-   - For a title or other description, run
-     `<plugin-root>/bin/taskchef.js task list --json`
-     once, then select matching entries. Ask the user if the match is ambiguous.
-   - Use the full list only when the user asks for an overview of the task history.
-2. For an overview, select only attention-worthy candidates before detailed
-   reads:
-   - always include `working`, `needs_input`, and entries with a null
-     `threadId`;
-   - include `completed` and `failed` entries updated during the last seven
-     days;
-   - omit older terminal entries by default and report the omitted count;
-   - include any omitted task whose Codex metadata appears as active or awaiting
-     native approval in the recent-thread snapshot.
-   Explicit task, title, or project requests override this age filter.
-3. Take one recent `list_threads` metadata snapshot for the whole report. This
-   is a cheap contradiction check across many tasks, not one call per task.
-   Match only exact durable `threadId` values. A metadata status that is active
-   or awaiting native approval immediately overrides a cached result without a
-   detailed read. Native approval is live Codex state, not a `needs_input`
-   callback. An inactive status never proves semantic completion; it only
-   permits a trustworthy cached MCP result to stand.
-4. In schema 8, treat `turns` as the ordered request/result timeline. Each turn
-   pairs a bounded `requestSummary` with one semantic result, a TaskChef-generated
-   `interrupted` outcome, or null while work is in progress. Describe an
-   interrupted historical turn plainly as interrupted/abandoned, never failed.
-   `latestTurn` is the compact current pair.
-   `results` and `lastResult` remain derived compatibility projections; do not
-   expect interrupted outcomes in either projection and do not pair the latest
-   request with an earlier result. Treat a failed result with
-   null thread and turn IDs as a fresh executor-creation failure. Schema 4/5/6
-   snapshots normalize their semantic results into legacy turns with a null
-   request summary without rewriting their log line. Schema 7 timelines remain
-   readable but cannot contain the schema-8 interrupted outcome.
-   No live read is possible or needed for that creation failure. When identity is certain and
-   metadata says the thread is inactive, trust the latest semantic result by
-   default in a broad overview unless a newer working state makes it historical.
-   Do not read every idle terminal task in an overview merely because native
-   `updatedAt` is later: callbacks normally run before Codex finalizes the same
-   turn, and overview performance matters more than investigating every rare
-   missed callback.
-
-   For a focused task, title, or project report, perform at most one detailed
-   read for each selected inactive task when matched metadata `updatedAt` is
-   later than `lastResult.updatedAt`, by any amount. Read once as well
-   when there is no semantic callback, identity or metadata is uncertain or
-   contradictory, or the user explicitly requests a fully live result. If
-   focused metadata is not newer, trust the cache. Absence from the bounded
-   recent snapshot is not by itself a reason to read every cached terminal
-   overview entry. Batch immediate native reads with no more than eight targets
-   per call. When a detailed read occurs, compare the latest structured turn ID
-   and native turn state with `lastResult.turnId`: a newer turn without a callback
-   makes the cache stale, while an interrupted or cancelled callback turn
-   cannot prove completion. Never classify assistant prose.
-5. Report each task as one of: working, needs input, awaiting native approval,
-   completed, failed, unresolved, or unknown. Show the cached summary when it
-   remains fresh. If a newer turn exists without a callback, describe the live
-   state and label the preserved result historical or stale rather than overwriting it.
-6. Never edit `tasks.jsonl` directly during reporting. A null identity is
-   executor link-pending and must be retried by that executor. Never persist inferred status,
-   transcripts, prose classifications, or hidden reasoning. Do not poll or wait.
-
-If the task history is empty, say that TaskChef has not recorded any tasks. If
-a task has no durable thread ID and is not a stored creation failure, identify
-it by task ID and say that its marker remains available for recovery. If live
-metadata or a targeted read fails, use the cached result with an explicit
-freshness warning and continue.

package/skills/taskchef-report/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "TaskChef Report"
-  short_description: "Report on dispatched Codex tasks"
-  default_prompt: "Use $taskchef-report to query the live state of work in the TaskChef task history once."