taskchef 7.15.3 → 7.15.5

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.15.3",
+  "version": "7.15.5",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",
@@ -29,7 +29,7 @@
     ],
     "websiteURL": "https://github.com/favoyang/taskchef",
     "defaultPrompt": [
-      "$taskchef-bootstrap Set up TaskChef in this folder.",
+      "$taskchef-bootstrap Set up TaskChef and index my Codex projects.",
       "$taskchef-delegate Dispatch this request to the right project.",
       "$taskchef-executor Execute this delegated TaskChef assignment.",
       "$taskchef-copilot Explain TaskChef outcomes and recommend the next action."

package/README.md

@@ -36,7 +36,7 @@ puts the `taskchef` CLI on `PATH`. TaskChef installs no hooks, schedules,
 daemons, login items, system services, or background identity search and needs
 no elevated permissions.
 
-## Bootstrap and configure
+## Bootstrap and index projects
 
 Ask the bootstrap skill to create the per-user dispatcher:
 
@@ -48,25 +48,33 @@ The canonical workspace is `~/.agents/taskchef`. TaskChef owns only:
 
 ```text
 AGENTS.md       managed dispatcher instructions plus user additions
-taskchef.json   schema-2 configured projects and routing metadata
+taskchef.json   schema-2 Codex project index and delegation metadata
 tasks.jsonl     one task snapshot per line (schema 9; schema 4-8 migration supported)
 ```
 
-List or change routing targets conversationally:
+Index or inspect Codex projects conversationally:
 
 ```text
-$taskchef-bootstrap List my configured TaskChef projects.
-$taskchef-bootstrap Add /workspace/payments as payments. It owns authorization, capture, refunds, and retries.
+$taskchef-bootstrap List my indexed Codex projects.
+$taskchef-bootstrap Index /workspace/payments as payments. It owns authorization, capture, refunds, and retries.
+$taskchef-bootstrap Reindex after the Codex projects I added today.
 ```
 
-The bootstrap skill has two onboarding paths. For a folder already saved as a
-local Codex project, it requires an exact canonical-path match before adding and
-verifying the TaskChef project. For a new folder, or an existing folder not yet
-saved by Codex, it creates the directory only when explicitly requested, opens
-the canonical path with the validated Codex Desktop CLI's `codex app <path>`
-mechanism, re-lists native projects, and requires the same exact match before
-adding it to TaskChef. An open request without a verified native project is
-reported as partial setup, not delegation-ready.
+TaskChef indexes existing Codex projects for delegation. The index stores
+canonical paths and routing metadata; it never indexes repository contents or
+creates another kind of project. For a folder already saved as a local Codex
+project, the bootstrap skill requires an exact canonical-path match before
+writing and verifying its TaskChef index entry. For a new folder, or an existing
+folder not yet saved by Codex, it creates the directory only when explicitly
+requested, opens the canonical path with the validated Codex Desktop CLI's
+`codex app <path>` mechanism, re-lists native projects, and requires the same
+exact match before indexing it. An open request without a verified native
+project is reported as partial setup, not delegation-ready.
+
+Reindexing catches TaskChef up with newly saved Codex projects by comparing
+exact canonical paths and indexing missing requested projects. It preserves
+existing curated entries and does not silently remove projects or overwrite
+metadata.
 
 Codex CLI resolution follows the same contract as
 `workspace init --register-codex`: an explicit `--codex-cli` path wins, then
@@ -84,12 +92,17 @@ taskchef project add /workspace/payments --name payments \
 taskchef project list
 ```
 
+The CLI command writes TaskChef metadata only; it does not query Codex. Before
+using it directly, verify that `/workspace/payments` exactly matches the
+canonical path of an existing local Codex project. The bootstrap skill performs
+that native-project check for you.
+
 A project may advertise several GitHub repositories with repeated
 `--github-repo`. Explicit values replace automatic origin detection and form
 the complete advertised list, so include the origin when it should remain
 routable. A managed `*-workspace` should advertise every relevant child or
 subrepository canonical GitHub URL, plus the workspace repository itself when
-applicable, so issue and pull-request links select the correct routing project.
+applicable, so issue and pull-request links select the correct Codex project.
 TaskChef accepts Git roots and ordinary local folders on the same execution
 host. Unsupported configuration schemas are rejected and are never rewritten
 automatically.

package/docs/spec.md

@@ -143,6 +143,25 @@ the final link, preserving the delegate skill's immediate-return contract.
    TaskChef MUST atomically close it as `interrupted` before appending the new
    working turn; the executor MUST NOT report semantic `failed` for recovery.
 
+Normal executor completion MUST stop after the terminal callback and return
+normally. It MUST NOT archive, hand off, close, navigate away from, or otherwise
+terminate the Codex task merely because work completed. Archive is authorized
+only by an explicit request in the current assignment or follow-up for that
+exact Codex task; `finish`, `complete`, `done`, `ship`, and ordinary cleanup do
+not imply authorization.
+
+For an explicitly authorized archive, the executor MUST finish and verify the
+work, read its exact task identity, submit the current turn's terminal
+`report_state`, verify TaskChef accepted that state, and only then invoke the
+native archive operation as the final state-changing action. It MUST require
+native confirmation before claiming archive succeeded. The same callback-first
+ordering applies to any separately authorized action that can make the executor
+unavailable before reporting, including handoff or terminating or restarting
+the process that owns the TaskChef MCP transport; this rule does not itself
+authorize those actions. A terminal reporting failure MUST prevent the later
+action and leave the executor accessible. Failure of a later action MUST NOT
+change or reopen the already accepted semantic terminal state.
+
 Request and result summaries are the durable source for dashboard related-link
 projection; TaskChef does not scan full Codex transcripts. When known, an
 executor MUST preserve the selected repository as a canonical GitHub repository

package/docs/workflows.md

@@ -12,7 +12,7 @@ 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-bootstrap/SKILL.md` | Initialize the workspace and maintain the Codex project index. |
 | `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. |
@@ -163,6 +163,16 @@ sequenceDiagram
 A native approval prompt is not a semantic result. `needs_input` is reserved
 for a user decision or fact required to proceed.
 
+Ordinary completion returns after the terminal callback; it does not archive,
+hand off, close, navigate away from, or otherwise terminate the native Codex
+task. An archive requires an explicit request in the current assignment or
+follow-up for that exact task. `finish`, `complete`, `done`, `ship`, and cleanup
+alone do not authorize it. Any explicitly requested action that could make the
+executor unavailable must follow, never precede, an accepted terminal callback.
+If reporting fails, the later action is forbidden and the executor remains
+accessible. If the later action fails, its error does not reopen or replace the
+accepted semantic state.
+
 ## Follow-up turns
 
 Turn refs are freshness tokens for semantic callbacks. The workspace rejects a

package/package.json

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

package/skills/taskchef-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-bootstrap
-description: "Initialize, diagnose, or refresh TaskChef dispatcher workspaces, project configuration, task history, and managed AGENTS.md instructions. Use when creating a TaskChef workspace, adding, importing, listing, or removing configured projects, running TaskChef doctor, or repairing dispatcher setup. Do not dispatch user work or report on executor threads."
+description: "Initialize, diagnose, or refresh TaskChef dispatcher workspaces, the Codex project index, task history, and managed AGENTS.md instructions. Use when creating a TaskChef workspace, indexing or reindexing Codex projects, importing, listing, or removing indexed projects, running TaskChef doctor, or repairing dispatcher setup. Do not dispatch user work or report on executor threads."
 ---
 
 # TaskChef Bootstrap
@@ -50,12 +50,17 @@ all deterministic workspace operations.
    End without dispatching unless the user
    separately requested work.
 
-## Onboard a routing project
+## Index Codex projects
 
-Configure only projects local to the TaskChef workspace's execution host.
-Remote connection projects are outside the v1 contract. Never configure the
-TaskChef dispatcher workspace or a directory containing it as a routing target;
-the dispatcher is the inbox, while routing projects own delegated work.
+TaskChef's project index is the local list of Codex projects available for
+delegation. It stores canonical paths and routing metadata such as curated
+names, descriptions, Git status, and GitHub repositories. It does not index
+repository contents or create a second kind of project.
+
+Index only Codex projects local to the TaskChef workspace's execution host.
+Remote connection projects are outside the v1 contract. Never index the
+TaskChef dispatcher workspace or a directory containing it; the dispatcher is
+the inbox, while indexed Codex projects own delegated work.
 
 ### Existing Codex project
 
@@ -63,16 +68,18 @@ the dispatcher is the inbox, while routing projects own delegated work.
    with `realpath` and require an exact canonical-path match in that list. A
    similar name, a parent or child directory, and a remote connection project
    are not matches.
-2. Add the exact path with `project add <canonical-path> --name <curated-name>
-   --description <curated-description> --json`. The CLI detects Git status, the
-   exact Git root, and a canonical GitHub `origin` when no repository option is
+2. Index the exact path with the existing `project add <canonical-path> --name
+   <curated-name> --description <curated-description> --json` CLI workflow.
+   Despite the command's historical `add` name, this writes one TaskChef index
+   entry for an existing Codex project. The CLI detects Git status, the exact
+   Git root, and a canonical GitHub `origin` when no repository option is
    supplied. Repeated `--github-repo <canonical-url>` arguments replace that
    detection and form the complete advertised repository list, so repeat the
    origin explicitly when it should remain routable. Use `--no-github` when the
    user intentionally wants an empty list.
-3. Run `project list --json` and require one saved TaskChef project with the
-   exact canonical path and intended routing metadata. Only then report that it
-   is ready for delegation.
+3. Run `project list --json` and require one indexed entry with the exact
+   canonical path and intended routing metadata. Only then report that the
+   Codex project is ready for delegation through TaskChef.
 
 ### New or not-yet-saved Codex folder
 
@@ -93,30 +100,50 @@ the dispatcher is the inbox, while routing projects own delegated work.
 3. Re-list native local Codex projects and require an exact canonical-path
    match. Opening is a request, not proof that Codex saved the project. If the
    exact match is absent, report that the folder was opened or registration was
-   requested but Codex registration remains unverified; do not add it to
+   requested but Codex registration remains unverified; do not index it in
    TaskChef or call it delegation-ready.
-4. After Codex verification, add the project as in the existing-project path.
-   Run `project list --json` and verify the exact saved TaskChef project. Report
+4. After Codex verification, index the project as in the existing-project path.
+   Run `project list --json` and verify the exact TaskChef index entry. Report
    delegation readiness only after both the native Codex match and TaskChef
-   registration are verified.
+   indexing are verified.
 
-For a managed `*-workspace` routing project, advertise every relevant child or
+For a managed `*-workspace` Codex project, advertise every relevant child or
 subrepository with repeated `--github-repo <canonical-github-url>` arguments,
 including the workspace repository itself when it can own issue or pull-request
 links. These explicit values are the complete list; automatic origin detection
 does not supplement them. This lets TaskChef route each canonical GitHub URL to
 the correct workspace rather than guessing from the folder name.
 
-## Manage configured projects
+### Reindex after Codex changes
+
+When the user asks TaskChef to reindex or catch up after saving more projects in
+Codex, list native local Codex projects once and run `project list --json` once
+before mutation. Compare exact canonical paths, then index each requested
+eligible Codex project that is missing from TaskChef by following the
+appropriate path above, sharing the batch verification instead of relisting
+after each write. After all additions, run `project list --json` once more and
+verify every intended canonical path and its routing metadata before reporting
+the index as current.
+
+Do not call `project add` for a path already in the TaskChef index; it rejects
+duplicate paths and must not be presented as a metadata refresh. Preserve
+existing curated entries, and do not remove entries merely because they are
+absent from the current Codex list. Refreshing or removing an existing entry
+requires an explicit user request and the project-management workflows below.
+
+## Manage the project index
 
 1. Bulk import with `project import <file|-> --json`. Input is a JSON array of
    objects containing `path` plus optional `name`, `description`, and
-   `githubRepos`, which is always a JSON array of GitHub repository URLs. Import
-   merges by canonical path, preserves an existing name or description when
-   omitted, and unions existing and imported repository lists without
-   duplicates. Use `--replace` only when the user explicitly requests
-   replacement.
-2. Inspect configured projects with `project list --json`. Remove by name with
+   `githubRepos`, which is always a JSON array of GitHub repository URLs. Before
+   importing, list native local Codex projects once, canonicalize every input
+   path, and require an exact local-project match for every entry. Reject or
+   report every unmatched path instead of indexing it. Import merges by
+   canonical path, preserves an existing name or description when omitted, and
+   unions existing and imported repository lists without duplicates. Use
+   `--replace` only when the user explicitly requests replacement. Run
+   `project list --json` afterward and verify every imported entry.
+2. Inspect indexed projects with `project list --json`. Remove by name with
    `project remove`. Existing task entries keep their project snapshots.
 
 Example managed-workspace import entry:

package/skills/taskchef-executor/SKILL.md

@@ -80,6 +80,33 @@ 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