taskchef 5.7.2 → 5.9.0

package/skills/taskchef-delegate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-delegate
-description: "Dispatch actionable requests through the per-user TaskChef workspace into independently openable Codex project tasks. Use automatically for actionable work received in the canonical TaskChef dispatcher workspace. From any other project, use only when the user explicitly asks to delegate or split separate work into Codex tasks; TaskChef-related subject matter alone is not delegation intent. Preserve unresolved delegations for later marker-based recovery, and never use subagents, hooks, schedules, daemons, or executor-completion waiting."
+description: "Dispatch actionable requests through the per-user TaskChef workspace into independently openable Codex project tasks. Use automatically for actionable work received in the canonical TaskChef dispatcher workspace. From any other project, use only when the user explicitly asks to delegate or split separate work into Codex tasks; TaskChef-related subject matter alone is not delegation intent. Record before creation, rely on the initial TaskChef hook for provisional identity, and never wait for executor completion."
 ---
 
 # TaskChef Delegate
@@ -19,7 +19,7 @@ This does not prevent the task from using TaskChef later. Use this skill
 normally when the initial assignment explicitly asks to delegate separate
 work, or when the user later explicitly requests a new delegation.
 
-Use the bundled TaskChef `prepare_dispatch`, `record_task`, and `resolve_task`
+Use the bundled TaskChef `prepare_dispatch`, `record_task`, `resolve_task`, and `report_result`
 tools for deterministic workspace and task-record operations. Call them
 directly; never probe for them or fall back to shell CLI writes. If a required
 tool is unavailable, stop and report that the TaskChef plugin must be reloaded
@@ -32,27 +32,29 @@ explicitly requested benchmark artifact.
 - Keep only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` in a dispatcher
   workspace.
 - Use real Codex tasks, never collaboration or subagent tools.
-- Never use hooks, callbacks, schedules, daemons, indefinite polling, or
-  background monitors.
-- Use only bounded provisional-ID resolution after `create_thread` returns a
-  provisional client ID. Use the fixed marker-based workflow below.
+- Use only TaskChef's `UserPromptSubmit` hook: it resolves initial identity and
+  provides read-only current-turn context on follow-up prompts. Never infer
+  lifecycle state from hooks.
+- Never use schedules, daemons, polling, thread-discovery retries, or background
+  monitors.
 - Never wait for delegated work after executor creation.
 - Never collect transcripts or hidden reasoning.
 
 ## Dispatch
 
-1. In parallel, call `prepare_dispatch` and list the native Codex projects
-   once. The preparation tool resolves the
-   canonical workspace, loads and validates the configured routing targets,
+1. Split the request into the smallest independently useful outcomes. Include
+   constraints, expected testing, and reporting in every instruction.
+2. In parallel, list the native Codex projects once and call `prepare_dispatch`
+   exactly once for each outcome. Every preparation produces a distinct task
+   UUID and marker; never reuse either across executors. The preparation tool
+   resolves the canonical workspace, loads and validates the configured routing targets,
    generates the lowercase full UUID task ID, and returns `preparedAt` plus the
    exact first-line marker. Use
    `$taskchef-bootstrap` if the workspace is missing or unhealthy.
-   The tool resolves `TASKCHEF_WORKSPACE`, then
+   The tool resolves an absolute (or `~/`-prefixed) `TASKCHEF_WORKSPACE`, then
    `~/.agents/taskchef`; do not substitute the current project. Reject the
    dispatcher workspace itself as a target. Never take a pre-creation thread
    snapshot.
-2. Split the request into the smallest independently useful outcomes. Include
-   constraints, expected testing, and reporting in every instruction.
 3. Classify against configured `name`, every URL in the `githubRepos` list, and
    `description`. Use `path` only as checkout identity. Managed `*-workspace`
    projects advertise their child or sub-repositories in this list.
@@ -64,103 +66,59 @@ explicitly requested benchmark artifact.
    matches. Ask instead of guessing when no project or several projects match.
 4. Resolve the selected configured path against the already-loaded native
    projects and require an exact match. Do not list native projects again.
-5. Use the task ID, preparation time, and marker returned by the preparation
-   tool.
+5. For each outcome, use only its corresponding task ID, preparation time, and
+   marker returned by its own preparation call.
    Prefix the complete executor instruction with
    exactly `<!-- taskchef_id=<full UUID> -->` as the first line, followed by a
-   blank line, this executor-role paragraph, another blank line, and the
-   instruction body. Add the paragraph as one line in the created input:
+   blank line, this executor-role paragraph, another blank line, the result
+   paragraph below, another blank line, and the instruction body:
 
    > This task owns the delegated assignment. Execute it in this task; do not re-dispatch it merely because it concerns TaskChef or a configured project. Explicit requests to delegate separate work remain valid.
 
+   > Before ending, call the TaskChef report_result MCP tool with completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.
+
    Preserve this
    marked instruction for recording, and note the creation time. The exact
    random marker is the sole correlation proof.
-6. Create one real Codex task using the exact configured project, a local
+6. Before creating each executor, call `record_task` exactly once with `id`,
+   `project`, `title`, the marked `instruction`, and `threadId: null`. This
+   closes the hook race: the entry exists before the executor can submit its
+   initial prompt.
+7. Create one real Codex task using the exact configured project, a local
    environment on its executor host, the marked instruction, and a short title.
-7. When `create_thread` returns a durable `threadId`, immediately call
-   `record_task` once. Send exactly `id`,
-   `project`, `title`, `instruction`, and `threadId`. Use the configured project
-   path for `project`, and send the marked instruction unchanged.
-   Never persist a provisional `clientThreadId` or
-   `pendingWorktreeId` as `threadId`. Never persist `hostId`, status, results,
-   transcripts, or hidden reasoning.
-8. When creation returns only `clientThreadId` or `pendingWorktreeId`, keep it
-   only for the created-thread directive and diagnostic reporting. It is not a
-   durable ID and cannot be passed to thread tools or converted directly.
-   Immediately record the marked instruction with `threadId: null` using the
-   tool from step 7, then resolve the durable ID with this bounded workflow:
-
-   - The supported Codex surface has no provisional-ID resolver. Do not inspect
-     the tool surface for one after creation and do not pass the provisional ID
-     to tools that require `threadId`.
-   - Take at most two post-creation `list_threads` snapshots with limit 50. The
-     nominal schedule is 10 and 30 seconds after
-     the provisional result. Treat the first checkpoint as due, not expired: if
-     nullable recording or other required work finishes after 10 seconds, take
-     the first snapshot immediately. Start the second snapshot no sooner than
-     20 seconds after the first snapshot actually started. Useful candidate
-     work counts toward that interval; when it finishes sooner, wait only the
-     remainder. Never suppress either snapshot merely because an earlier step
-     ran late, and never take a third snapshot.
-   - Filter Codex candidates by the expected host, project, creation time
-     (allow five seconds of clock skew), and worktree environment whenever
-     those fields are present. Use the title only to prioritize reads; Codex
-     may normalize it, so never exclude a candidate because its title differs.
-   - Read every remaining candidate with `read_thread`, requesting one turn and
-     no command output. Issue all independent reads together in exactly one
-     programmatic batch per snapshot. Do not probe for batching support and do
-     not fall back to serial tool-call round trips. When the required batch
-     cannot be executed, preserve the nullable record as unresolved. Inspect
-     only the
-     structured
-     `userMessage.content[].codexDelegation.input`; do not trust titles,
-     summaries, previews, plain-text echoes, or assistant output as proof.
-   - Accept a candidate only when the structured input's first line is exactly
-     the task's `<!-- taskchef_id=<full UUID> -->` marker and exactly one
-     candidate matches. Require an immediately following blank line. Reject old
-     heading-style markers, malformed comments, missing blank separators, and
-     marker-like text anywhere else. Reject any discovered thread ID equal to
-     the provisional identifier or in its `local:` namespace. Then call
-     `resolve_task` once to atomically fill the nullable field.
-   - Treat snapshot, candidate-read, wait, and task-resolution
-     failures as indeterminate. If the workflow ends with zero exact matches,
-     multiple matches, or errors, leave the already-recorded `threadId: null`,
-     clearly report the unresolved reason and provisional diagnostic ID, and
-     never guess.
-
-9. If executor creation fails, do not record a task. If recording fails
-   after creation, still return the created task and clearly say that it is not
-   in the task log. Do not delete the executor.
-10. Return immediately after immediate recording or the bounded ID-resolution
-    workflow. Emit the appropriate created-thread directive, but label a
-    client-thread directive as provisional when resolution failed. Treat a
-    nullable record as preserved but unresolved, not as a durable task link. Do
-    not read an executor for progress and never wait for executor work
-    completion.
+8. If creation returns a durable `threadId`, call `resolve_task` immediately.
+   If creation returns only `clientThreadId`, `pendingWorktreeId`, or a `local:`
+   ID, retain it only for the created-thread directive. Return immediately; the
+   initial TaskChef hook will atomically fill the durable root thread ID. Never
+   list, read, wait for, or poll threads to resolve it.
+
+9. If executor creation fails, call `report_result` for the already-recorded
+   task with `failed`, null thread/turn IDs, and a concise creation error.
+10. Emit the appropriate created-thread directive and return immediately.
+    Treat a nullable record as preserved but not yet linked. Do not read an
+    executor for progress and never wait for executor work completion.
 
 The bundled structured tools are the only dispatch-time path to the canonical
 workspace. They reuse the same exact-field validation, locking, atomic writes,
 and one-way nullable resolution as the CLI without shell parsing, stdin, or
-per-command filesystem escalation. The package exports pure repository
-canonicalization and unique URL matching helpers from `src/github.js`, plus
-marker, candidate-filtering, and injected-adapter orchestration helpers from
-`src/delegation.js`, for deterministic tests and hosts that can supply
-thread-tool callbacks. The standalone Node CLI cannot call desktop thread
-tools; perform thread discovery in Codex. Keep the CLI for bootstrap, manual
-inspection, and recovery outside delegation.
+per-command filesystem escalation. The package exports repository routing,
+marker, and record-before-create orchestration helpers for deterministic tests.
+Keep the CLI for bootstrap, manual inspection, and recovery outside delegation.
 
 ## Later resolution
 
-When a later Codex workflow finds exactly one durable thread whose structured
-delegated input contains an unresolved task's exact marker, call `resolve_task`
-once. Never edit `tasks.jsonl` directly. The tool permits only an idempotent
-one-way transition from `threadId: null` to one unique durable thread ID.
+The trusted initial hook normally resolves an unresolved task. For manual
+recovery, require one exact structured marker match, then call `resolve_task`
+once. Never edit `tasks.jsonl` directly. Resolution is an idempotent one-way
+transition from `threadId: null` to one unique durable root thread ID.
 
-## End-to-end evaluation
+## Legacy benchmark compatibility
 
-When explicitly asked to benchmark delegation, measure one real task without
-waiting for executor completion. Start from
+The schema-v1 benchmark fixtures below describe the removed snapshot resolver
+and remain only for historical-result validation. Do not use that resolver for
+new delegation benchmarks. A future benchmark schema should measure record,
+creation, initial-hook resolution, and result callback without polling. The
+legacy fixture starts from
 `<plugin-root>/assets/e2e-benchmark-example.json`. Capture one ISO start/end
 interval for the parallel preparation/project-list operation, followed by
 sequential non-overlapping creation, recording, and optional provisional

package/skills/taskchef-report/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: taskchef-report
-description: "Report the live state of Codex tasks recorded in a TaskChef task history. Use only when the user asks for status, outcomes, or a report about delegated work. Queries each relevant task once, may resolve a nullable thread ID from one exact marker match, never polls or waits, and never persists status or results."
+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 history and report the current state
-of its Codex tasks once.
+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
@@ -15,7 +15,8 @@ all deterministic task-log operations.
 ## Report
 
 1. Run `<plugin-root>/bin/taskchef.js workspace path --json`. The CLI resolves
-   `--workspace`, then `TASKCHEF_WORKSPACE`, then `~/.agents/taskchef`; never
+   `--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
@@ -26,28 +27,60 @@ all deterministic task-log operations.
      `<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. Separate entries whose `threadId` is `null`. For those entries, take one
-   `list_threads` snapshot with limit 50, filter by available project metadata,
-   and inspect candidate structured delegated inputs. Use title only to
-   prioritize candidates, never to exclude them. Require the exact first line
-   `<!-- taskchef_id=<full lowercase UUID> -->` and an immediately following
-   blank line; reject old heading-style markers, malformed comments, and missing
-   blank separators. When exactly one candidate has that exact prefix, run
-   `<plugin-root>/bin/taskchef.js task resolve <task-id> --thread-id <thread-id> --json`.
-   Do not resolve zero or multiple matches. Report unmatched entries as
-   recorded but unresolved and do not pass them to native thread tools.
-3. Query every resolved or previously durable thread exactly once using
-   immediate native snapshots, with no more than eight targets per call.
-4. Summarize the live state and any reported outcome for each requested task.
-   Distinguish active work, requests for user input, completed work, and failed
-   or partial attempts.
-5. Treat each Codex task as the source of truth. The task log records what
-   TaskChef submitted, but it does not contain the task's current state.
-6. Never edit `tasks.jsonl` directly. Use `task resolve` only for one exact
-   marker match. Never persist status, results, transcripts, or hidden
-   reasoning. Do not poll or wait for future activity.
+2. For an overview, select only attention-worthy candidates before detailed
+   reads:
+   - always include `working`, `needs_input`, null-status legacy entries, 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. Treat `updatedBy: mcp`, `status: failed`, and null thread/turn IDs as a fresh
+   executor-creation failure. No live read is possible or needed; report the
+   stored failure summary, not unresolved. Otherwise, only a snapshot with
+   `updatedBy: mcp` is a cached semantic result. A
+   dispatcher- or hook-written `working` snapshot has no semantic callback and
+   requires one live task query when selected; if the task is inactive and no
+   callback exists, report the outcome as unknown rather than treating
+   `working` as fresh. When identity is certain and metadata says the thread is
+   inactive, trust the latest MCP result by default in a broad overview. 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 the cached result `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 stored `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 cached result stale rather than overwriting it.
+6. Never edit `tasks.jsonl` directly during reporting. The initial hook normally
+   resolves null identity; manual recovery may call `task resolve` only after
+   one exact structured marker match. 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, identify it by task ID and say that its marker
-remains available for later recovery. If a recorded thread cannot be read,
-identify it by task ID and thread ID, then continue with the remaining entries.
+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/src/cli.js

@@ -2,6 +2,7 @@ import { access, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 
 import { openWorkspaceInCodex } from "./codex-app.js";
+import { createDashboardServer } from "./dashboard.js";
 import { resolveWorkspacePath } from "./workspace-path.js";
 
 import {
@@ -169,10 +170,15 @@ function taskDetails(task) {
   return [
     `Title: ${singleLineDetail(task.title)}`,
     `Project: ${singleLineDetail(task.project.name)}`,
+    `Status: ${singleLineDetail(task.status ?? "unknown")}`,
+    `Summary: ${singleLineDetail(task.summary ?? "-")}`,
     `Project path: ${singleLineDetail(task.project.path)}`,
     `Created: ${singleLineDetail(task.createdAt)}`,
+    `Updated: ${singleLineDetail(task.updatedAt ?? "-")}`,
+    `Updated by: ${singleLineDetail(task.updatedBy ?? "-")}`,
     `Task ID: ${singleLineDetail(task.id)}`,
     `Thread ID: ${singleLineDetail(task.threadId ?? "-")}`,
+    `Turn ID: ${singleLineDetail(task.turnId ?? "-")}`,
     "Instruction:",
     task.instruction,
   ].join("\n");
@@ -381,11 +387,12 @@ async function taskList(args) {
   const result = { taskCount: dispatches.length, tasks: dispatches };
   const fullId = args.includes("--full-id");
   print(result, args, (value) => table(
-    ["TITLE", "PROJECT", "CREATED", "ID", "THREAD ID"],
+    ["TITLE", "PROJECT", "STATUS", "UPDATED", "ID", "THREAD ID"],
     value.tasks.map((dispatch) => [
       dispatch.title,
       dispatch.project?.name,
-      dispatch.createdAt,
+      dispatch.status ?? "unknown",
+      dispatch.updatedAt ?? dispatch.createdAt,
       displayId(dispatch.id, fullId),
       displayId(dispatch.threadId, fullId),
     ]),
@@ -403,11 +410,51 @@ async function taskSummary(args) {
   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");
+  const port = Number(value);
+  if (port > 65_535) throw new Error("--port must be an integer from 0 to 65535");
+  return port;
+}
+
+async function dashboard(args) {
+  validateCommandArgs(args, 1, {
+    values: ["--port", "--workspace"],
+    switches: ["--json"],
+  });
+  const server = await createDashboardServer({
+    workspace: workspaceRoot(args),
+    port: dashboardPort(args),
+  });
+  print({
+    schemaVersion: 1,
+    url: server.url,
+    workspace: server.monitor.workspace,
+  }, args, (value) => [
+    `TaskChef dashboard: ${value.url}`,
+    `Workspace: ${value.workspace}`,
+    "Press Ctrl+C to stop.",
+  ].join("\n"));
+
+  let stop;
+  await new Promise((resolve) => {
+    stop = resolve;
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  process.off("SIGINT", stop);
+  process.off("SIGTERM", stop);
+  await server.close();
+  return 0;
+}
+
 function usage() {
   process.stdout.write(`TaskChef workspace utility
 
 Usage:
   taskchef help
+  taskchef dashboard [--port <number>] [--json] [--workspace <path>]
   taskchef doctor [--json] [--workspace <path>]
   taskchef workspace path [--json] [--workspace <path>]
   taskchef workspace init [--register-codex] [--codex-cli <path>] [--json] [--workspace <path>]
@@ -429,6 +476,8 @@ Project import reads a JSON
 array from a file, or from standard input when the source is '-' or omitted.
 Workspace resolution precedence is --workspace, TASKCHEF_WORKSPACE, then
 ~/.agents/taskchef.
+The dashboard binds to 127.0.0.1 and reads the canonical task log without
+modifying dispatcher-workspace files.
 `);
 }
 
@@ -437,6 +486,7 @@ export async function runCli(args) {
     usage();
     return 0;
   }
+  if (args[0] === "dashboard") return dashboard(args);
   if (args[0] === "doctor") return doctor(args);
   if (args[0] === "workspace" && args[1] === "path") return workspacePath(args);
   if (args[0] === "workspace" && args[1] === "init") return initialize(args);