taskchef 7.27.0 → 7.27.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.27.0",
+  "version": "7.27.1",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -137,7 +137,8 @@ $taskchef-delegate In payments, add structured logs for failed retries and test
 
 TaskChef prepares a UUID and marker, persists the task before native creation,
 creates the executor, and returns its task link. New executor instructions keep
-the assignment visible from the first line, leave one blank line, then place
+the assignment visible from the first line, add a concise local reporting
+authorization paragraph, leave one blank line, then place
 an explicit `$taskchef-executor` invocation immediately before the final
 correlation marker. That skill reads the executor's own `CODEX_THREAD_ID`, self-links, and
 reports lifecycle state. Independent outcomes may become separate executors;
@@ -155,6 +156,8 @@ For example, TaskChef generates this shape:
 ```text
 Fix duplicate charges after a retry and add a regression test.
 
+Report this task and its follow-ups to my local TaskChef dashboard. Relevant private-repository links and concise work, test, and deployment results are authorized; exclude secrets.
+
 Use $taskchef-executor to execute and report this delegated TaskChef assignment.
 <!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
 ```

package/docs/spec.md

@@ -211,7 +211,9 @@ the final link, preserving the delegate skill's immediate-return contract.
 1. The dispatcher MUST call `prepare_dispatch` once per outcome.
 2. It MUST choose exactly one configured project and exact native-project path.
 3. It MUST build the instruction with the user's outcome beginning on line 1
-   and remaining uninterrupted, followed by exactly two newline characters
+   and remaining uninterrupted, followed by one blank line and the authorization
+   `Report this task and its follow-ups to my local TaskChef dashboard. Relevant private-repository links and concise work, test, and deployment results are authorized; exclude secrets.`
+   followed by exactly two newline characters
    (one blank line), exactly one concise explicit `$taskchef-executor`
    invocation, one newline, and the returned marker on the final line. It MUST
    NOT place a blank line between the invocation and marker or inline the
@@ -528,6 +530,17 @@ MUST contain no crash output, transcript, user text, or inferred failure cause.
 **Annotations:** `readOnlyHint: false`, `destructiveHint: true`,
 `openWorldHint: false`.
 
+Reporting tool descriptions MUST identify the configured local `tasks.jsonl`
+path and local `.taskchef-usage.json` tracking side effect. GitHub URLs remain
+references in that log; reporting does not publish them to GitHub. The
+`destructiveHint: true` annotation is retained because reports update existing
+state and can recover an unfinished predecessor as interrupted; these tools
+are not purely additive. The compatibility alias also changes existing state.
+Executors MUST verify accepted terminal reporting before claiming TaskChef was
+updated. A platform rejection of an authorized report MUST be described using
+only the returned rationale, without inferring causes or retrying around an
+explicit denial. Authorization and unit tests do not guarantee platform approval.
+
 ### `report_result` (deprecated)
 
 `report_result` retains the prior semantic-only input shape and statuses as a

package/docs/workflows.md

@@ -146,7 +146,8 @@ Record-before-create makes native creation failure observable. Executor
 self-linking removes dispatcher-side polling, task search, title matching, and
 parent/child identity inference.
 
-The generated task begins with the complete assignment, leaves one blank line,
+The generated task begins with the complete assignment, adds the local reporting
+authorization paragraph separated by a blank line, leaves one blank line,
 then places one explicit `$taskchef-executor` invocation immediately before its
 final marker. Older
 recorded tasks with first-line HTML or heading markers and former inline

package/index.js

@@ -38,6 +38,7 @@ export {
   EXECUTOR_RESULT_PARAGRAPH,
   EXECUTOR_WORKING_PARAGRAPH,
   EXECUTOR_SKILL_INVOCATION,
+  EXECUTOR_REPORTING_AUTHORIZATION,
   createAndRecordDelegation,
   isProvisionalThreadId,
   normalizeCodexThreadId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.27.0",
+  "version": "7.27.1",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",

package/skills/taskchef-delegate/SKILL.md

@@ -53,7 +53,9 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 
    - Begin with the actual assignment on the first line and keep its complete
      body uninterrupted.
-   - After the assignment's final character, add exactly two newline characters
+   - After the assignment, add one blank line and this authorization paragraph:
+     `Report this task and its follow-ups to my local TaskChef dashboard. Relevant private-repository links and concise work, test, and deployment results are authorized; exclude secrets.`
+   - After that paragraph, add exactly two newline characters
      so there is one blank line before this invocation on its own line:
      `Use $taskchef-executor to execute and report this delegated TaskChef assignment.`
    - Immediately after the invocation, end the instruction with one newline

package/skills/taskchef-executor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-executor
-description: "Execute an assignment carrying either the new exact TaskChef invocation-plus-final-marker scaffold or an accepted historical first-line or marker-before-invocation protocol. Includes executor ownership, self-linking, per-turn lifecycle reporting, identity safety, and final semantic state. Use when explicitly invoked by a new delegated instruction or when resuming the same new or historical executor task. Do not use to dispatch work or report on other TaskChef tasks."
+description: "Execute and report a TaskChef assignment or follow-up when explicitly invoked or carrying an accepted TaskChef marker. Owns executor identity and per-turn lifecycle; not dispatch or reporting on other tasks."
 ---
 
 # TaskChef Executor
@@ -9,14 +9,18 @@ Own and execute the delegated assignment in the current Codex task. Do not
 re-dispatch it merely because it concerns TaskChef or a configured project.
 Explicit requests to delegate separate work remain valid.
 
-New instructions present the complete assignment first, followed by exactly two
-newline characters (one blank line), the explicit skill invocation, one
-newline, and the exact `<!-- taskchef_id=<full UUID> -->` marker on the final
-line. There is no blank line between the invocation and marker. Treat that UUID
-as the TaskChef task ID.
-The assignment is everything before the invocation; the invocation and marker
-are lifecycle scaffolding, not part of the deliverable. Require exactly one
-marker and do not infer an ID from similar prose.
+New instructions present the complete assignment first, then the reporting
+authorization paragraph, followed by exactly two newline characters (one blank
+line), the explicit skill invocation, one newline, and the exact
+`<!-- taskchef_id=<full UUID> -->` marker on the final line.
+There is no blank line between the invocation and marker.
+Treat that UUID as the TaskChef task ID.
+The authorization, invocation, and marker are lifecycle scaffolding, not part
+of the deliverable. Require non-whitespace task-specific content beyond them.
+For historical first-line markers, marker-before-invocation forms, compact or
+pre-authorization prompts, former inline protocol, or an installation exposing only `report_result`, read
+[compatibility](references/compatibility.md) before interpreting the assignment.
+Require exactly one marker and do not infer an ID from similar prose.
 
 ## Start every execution turn
 
@@ -37,8 +41,8 @@ Complete this lifecycle setup before substantive assignment work:
    `turnId: null`. Do not infer a native ID, reuse an earlier prompt's
    `turnRef`, or let a retry generate a replacement UUID.
 4. Call TaskChef `report_state` with the marked task ID, self-linked thread ID,
-   this prompt's `turnRef` and optional Codex `turnId`, `status: working`, an omitted or null result summary, and a
-   concise `requestSummary` describing this turn's assignment or follow-up.
+   this prompt's `turnRef` and optional Codex `turnId`, `status: working`, an
+   omitted or null result summary, and a concise `requestSummary` describing this turn's assignment or follow-up.
    When the turn targets a known GitHub repository, include its canonical
    `https://github.com/<owner>/<repository>` URL so multi-repository projects
    retain the selected repository instead of leaving TaskChef to guess.
@@ -72,81 +76,35 @@ reuse a `turnRef` after a follow-up. If a final-report response is lost, an
 identical terminal retry is safe only while the same turn remains current. On
 a later prompt, run the start lifecycle with a new `turnRef`; TaskChef
 will preserve the predecessor as interrupted, and only the new turn may receive
-a semantic result. Say reporting failures visibly instead of claiming a tracked
-outcome.
+a semantic result.
+
+Claim TaskChef was updated only after verifying the terminal response accepted
+this task, turn, status, and summary. Report failures visibly. If the platform
+rejects an authorized report, describe it as a platform rejection of that
+report; quote only a rationale actually returned. Do not infer the reason,
+promise approval, retry around an explicit denial, or change approval settings.
+Ask the user once and wait for new authorization before retrying a denial.
 
 Request and result summaries must omit secrets, transcripts, raw command output, hidden reasoning,
 and unnecessary personal data. Identical lifecycle retries are safe; never
 replace a same-`turnRef` report with different content or let an older turn
 overwrite newer state.
 
-### Keep terminal reporting ahead of executor-ending actions
-
-Normal completion ends with the semantic terminal `report_state` callback and
-then returns normally. Never archive, hand off, close, navigate away from, or
-otherwise terminate the Codex task merely because the work or turn completed.
-An archive is authorized only when the current assignment or follow-up
-explicitly requests archiving this exact Codex task. Words such as `finish`,
-`complete`, `done`, `ship`, and ordinary cleanup do not authorize archive.
-
-When archive is explicitly authorized, finish and verify the requested work,
-read the exact task identity required by this protocol, submit the terminal
-`report_state` callback for the current `turnRef`, and verify that TaskChef
-accepted the terminal state. Only then call the native Codex archive operation.
-Archive must be the final state-changing action, and native confirmation is
-required before claiming it succeeded.
-
-Apply the same terminal-callback-first rule when the user explicitly requests
-another action that can make this executor unavailable before it reports, such
-as handing off the task or terminating or restarting the process that owns the
-TaskChef MCP transport. This ordering rule does not authorize any such action.
-If terminal reporting fails, do not archive or perform the requested
-executor-ending action; leave the executor accessible and report the lifecycle
-failure visibly. If terminal reporting succeeds but the later action fails,
-preserve the accepted `completed`, `failed`, or `needs_input` state, report only
-the later action's failure, and do not reopen the lifecycle or report `working`
-again.
-
-### Preserve repository and delivery links
-
-Treat lifecycle summaries as the durable TaskChef timeline; the dashboard does
-not scan the full Codex transcript later. Preserve known GitHub context in that
-timeline with canonical links:
-
-- Use `https://github.com/<owner>/<repository>` when identifying the repository
-  selected for a turn. Derive it from established project or Git remote
-  evidence; never guess from a similarly named directory.
-- Use the full canonical issue or pull-request URL whenever one is known. Do
-  not shorten it to bare `#123` or `PR #123` in a multi-repository project.
-- Include every delivered pull request in the result summary. If work produces
-  both a child-repository pull request and a workspace/root pull request,
-  preserve both URLs and state which repository each belongs to.
-- Keep references specific to the text being reported. Do not copy unrelated
-  links from earlier turns merely to make them visible.
-- Never invent an issue, pull request, or repository link. If repository
-  identity is genuinely unresolved, describe that ambiguity without a link.
-
-For example, a working summary may say `Update dashboard projection in
-https://github.com/favoyang/taskchef`. A terminal summary may say `Shipped the
-child change in https://github.com/favoyang/taskchef/pull/78 and the workspace
-plan in https://github.com/favoyang/skills-workspace/pull/62`.
-
-## Compatibility
-
-Existing delegated tasks may include the former inline ownership, linking, and
-`report_result` paragraphs. Continue executing those tasks here without
-re-dispatching. Prefer `report_state` when available. If an older installed
-TaskChef exposes only `report_result`, follow its inline protocol; after an
-upgrade, the deprecated `report_result` alias remains available for exact
-legacy retries. Also accept historical trailing instructions that place the
-marker before the invocation, with or without the former blank line before the
-marker; the former compact assignment-to-invocation boundary with the marker
-last; an exact HTML marker on the first line with or without the former blank
-line; or the older exact
-first-line `# taskchef_id=<full UUID>` heading. These compatibility forms do not
-change the identity or lifecycle rules above. For either first-line form, the
-assignment follows the marker. Ignore the final executor invocation and any
-recognizable former inline ownership, linking, working-state, or
-result-reporting paragraphs as lifecycle scaffolding; execute the remaining
-task-specific body. Require non-whitespace task-specific content and never
-treat an invocation by itself as an assignment.
+## Preserve delivery context
+
+Summaries are the durable TaskChef timeline; the dashboard does not scan the
+full Codex transcript later. Include the known repository's canonical
+`https://github.com/<owner>/<repository>` URL in the working `requestSummary`.
+Use full canonical issue or pull-request URLs and include every delivered PR
+in the terminal summary, including both child and workspace PRs when relevant.
+Derive links from established project or remote evidence; never invent links
+or copy unrelated links from earlier turns.
+
+## Ending actions
+
+Normal completion returns normally after accepted terminal reporting. Never
+archive, hand off, close, navigate away from, or terminate the executor merely
+because work completed. `finish`, `complete`, `done`, `ship`, and ordinary
+cleanup do not authorize archive. Only when the user explicitly requests
+archiving this exact task or another action that can make the executor
+unavailable, read [ending actions](references/ending-actions.md) first.

package/skills/taskchef-executor/references/compatibility.md

@@ -0,0 +1,22 @@
+# Compatibility
+
+Pre-authorization prompts with the invocation before the final marker use the
+entrypoint lifecycle without requiring a new authorization paragraph.
+
+Existing delegated tasks may include the former inline ownership, linking, and
+`report_result` paragraphs. Continue executing those tasks here without
+re-dispatching. Prefer `report_state` when available. If an older installed
+TaskChef exposes only `report_result`, follow its inline protocol; after an
+upgrade, the deprecated `report_result` alias remains available for exact
+legacy retries. Also accept historical trailing instructions that place the
+marker before the invocation, with or without the former blank line before the
+marker; the former compact assignment-to-invocation boundary with the marker
+last; an exact HTML marker on the first line with or without the former blank
+line; or the older exact
+first-line `# taskchef_id=<full UUID>` heading. These compatibility forms do not
+change the identity or lifecycle rules in `SKILL.md`. For either first-line form, the
+assignment follows the marker. Ignore the final executor invocation and any
+recognizable former inline ownership, linking, working-state, or
+result-reporting paragraphs as lifecycle scaffolding; execute the remaining
+task-specific body. Require non-whitespace task-specific content and never
+treat an invocation by itself as an assignment.

package/skills/taskchef-executor/references/ending-actions.md

@@ -0,0 +1,26 @@
+# Keep terminal reporting ahead of executor-ending actions
+
+Normal completion ends with the semantic terminal `report_state` callback and
+then returns normally. Never archive, hand off, close, navigate away from, or
+otherwise terminate the Codex task merely because the work or turn completed.
+An archive is authorized only when the current assignment or follow-up
+explicitly requests archiving this exact Codex task. Words such as `finish`,
+`complete`, `done`, `ship`, and ordinary cleanup do not authorize archive.
+
+When archive is explicitly authorized, finish and verify the requested work,
+read the exact task identity required by this protocol, submit the terminal
+`report_state` callback for the current `turnRef`, and verify that TaskChef
+accepted the terminal state. Only then call the native Codex archive operation.
+Archive must be the final state-changing action, and native confirmation is
+required before claiming it succeeded.
+
+Apply the same terminal-callback-first rule when the user explicitly requests
+another action that can make this executor unavailable before it reports, such
+as handing off the task or terminating or restarting the process that owns the
+TaskChef MCP transport. This ordering rule does not authorize any such action.
+If terminal reporting fails, do not archive or perform the requested
+executor-ending action; leave the executor accessible and report the lifecycle
+failure visibly. If terminal reporting succeeds but the later action fails,
+preserve the accepted `completed`, `failed`, or `needs_input` state, report only
+the later action's failure, and do not reopen the lifecycle or report `working`
+again.

package/src/delegation.js

@@ -8,6 +8,7 @@ export const EXECUTOR_LINK_PARAGRAPH = "Before any other work, read this executo
 export const EXECUTOR_WORKING_PARAGRAPH = "After a successful initial link, and at the start of every follow-up turn before substantive work, read this exact Codex thread natively to obtain the current turn ID and call TaskChef report_state with the marked task ID, the self-linked thread ID, that current turn ID, status working, summary omitted or null, and a concise requestSummary for this turn. link_task remains the first TaskChef action on the initial turn; do not report working before identity is linked. Never reuse a prior turn ID after a follow-up.";
 /** @deprecated Historical v7 inline-prompt snapshot. New delegations use taskchef-executor. */
 export const EXECUTOR_RESULT_PARAGRAPH = "Before ending, read this exact Codex thread again and call TaskChef report_state for the same current working turn with status 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.";
+export const EXECUTOR_REPORTING_AUTHORIZATION = "Report this task and its follow-ups to my local TaskChef dashboard. Relevant private-repository links and concise work, test, and deployment results are authorized; exclude secrets.";
 export const EXECUTOR_SKILL_INVOCATION = "Use $taskchef-executor to execute and report this delegated TaskChef assignment.";
 const HISTORICAL_RESULT_WITH_TURN_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with the marked task ID, this executor's self-linked thread ID, the current turn ID from an exact native read of that same thread, completed, needs_input, or failed, and a concise summary. Never reuse a prior turn ID after a follow-up. 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.";
 const HISTORICAL_RESULT_PARAGRAPH = "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.";
@@ -28,7 +29,7 @@ const HISTORICAL_INLINE_PROTOCOLS = [
 
 function hasTaskSpecificContent(lines) {
   return lines.some((line) => (
-    line.trim().length > 0 && !HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line)
+    line.trim().length > 0 && line !== EXECUTOR_REPORTING_AUTHORIZATION && !HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line)
   ));
 }
 
@@ -134,7 +135,7 @@ export function parseTaskChefMarker(instruction) {
     }
 
     const containsInlineScaffold = rest.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
-    if (!containsInlineScaffold) return rest.join("\n").trim().length > 0;
+    if (!containsInlineScaffold) return hasTaskSpecificContent(rest);
     return HISTORICAL_INLINE_PROTOCOLS.some((protocol) => {
       const prefix = ["", ...protocol.flatMap((line) => [line, ""])];
       if (!prefix.every((line, index) => rest[index] === line)) return false;
@@ -216,10 +217,13 @@ export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
   if (bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line))) {
     throw new Error("instruction contains reserved historical TaskChef lifecycle scaffolding");
   }
+  if (bodyLines.includes(EXECUTOR_REPORTING_AUTHORIZATION)) {
+    throw new Error("instruction contains reserved TaskChef reporting authorization");
+  }
   const id = requireUuid(taskId);
   return {
     id,
-    instruction: `${body}\n\n${EXECUTOR_SKILL_INVOCATION}\n${taskChefMarker(id)}`,
+    instruction: `${body}\n\n${EXECUTOR_REPORTING_AUTHORIZATION}\n\n${EXECUTOR_SKILL_INVOCATION}\n${taskChefMarker(id)}`,
   };
 }
 

package/src/mcp.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import {
@@ -169,6 +170,7 @@ export function createTaskChefMcpServer({
   logDashboardDiagnostic,
   usageTracker = createUsageTracker({ workspace }),
 } = {}) {
+  const reportingDestination = `Store lifecycle state and summaries in the configured local TaskChef dashboard log ${JSON.stringify(path.resolve(workspace, "tasks.jsonl"))}. GitHub URLs are stored as references, not published to GitHub. Also triggers local Codex usage tracking in ${JSON.stringify(path.resolve(workspace, ".taskchef-usage.json"))}. Exclude secrets. `;
   const server = new McpServer(
     { name: "taskchef", version: TASKCHEF_VERSION },
     {
@@ -297,7 +299,7 @@ export function createTaskChefMcpServer({
     {
       title: "Report TaskChef state",
       description:
-        "Report this self-linked executor turn's lifecycle state. Use one stable turnRef for working and its terminal report; pass the native Codex turn ID as both turnRef and turnId when available, otherwise pass a client-generated UUID turnRef and null turnId. Preserve known repository context and delivered links. Exact retries are idempotent; stale or mismatched turnRefs are rejected.",
+        reportingDestination + "Report this self-linked executor turn's lifecycle state. Use one stable turnRef for working and its terminal report; pass the native Codex turn ID as both turnRef and turnId when available, otherwise pass a client-generated UUID turnRef and null turnId. Preserve known repository context and delivered links. Exact retries are idempotent; stale or mismatched turnRefs are rejected.",
       inputSchema: {
         taskId: z.string().min(1),
         threadId: z.string().min(1).nullable(),
@@ -326,7 +328,7 @@ export function createTaskChefMcpServer({
     {
       title: "Report TaskChef result (deprecated)",
       description:
-        "Deprecated compatibility alias for semantic results. New executors must use report_state working at turn start and report_state again with needs_input, completed, or failed before ending. This alias preserves legacy callers by implicitly starting the supplied newer turn before storing its result.",
+        reportingDestination + "Deprecated compatibility alias for semantic results. New executors must use report_state working at turn start and report_state again with needs_input, completed, or failed before ending. This alias preserves legacy callers by implicitly starting the supplied newer turn before storing its result.",
       inputSchema: {
         taskId: z.string().min(1),
         threadId: z.string().min(1).nullable(),