taskchef 1.0.1 → 1.0.2

package/BACKLOG.md

@@ -17,14 +17,35 @@ This document contains capabilities intentionally excluded from the v1 MVP.
 
 ## Reconciliation and continuity
 
-- Add event-driven, scheduled, or background reconciliation only if interactive
-  reconciliation proves insufficient.
+- Prototype one standalone Codex Scheduled Task per dispatcher workspace. Run
+  it in the local project, not an isolated worktree, so updates reach the
+  canonical `tasks/*/task.json` records. Default to every 15 minutes and let the
+  user choose another cadence when enabling it.
+- Use a durable prompt that explicitly invokes `$taskchef-reconcile`, names the
+  dispatcher workspace, processes every candidate in sequential batches of at
+  most eight thread snapshots, and reports only changed, blocked, finished, or
+  failed records. An unchanged run produces one concise no-change result.
+- Add an atomic per-workspace reconciliation lease before enabling schedules.
+  One run acquires it, releases it on completion, and skips when another run
+  holds it. Treat a lease older than 30 minutes as stale and report its recovery.
+- Do not retry failed snapshots within the same run. Report the affected task
+  IDs and let the next scheduled run retry them.
+- Keep the scheduled task active when there are no candidates so later
+  delegations are discovered without re-enabling it. Only the user pauses or
+  deletes the schedule. Test the durable prompt manually before enabling it.
+- Keep scheduled reconciliation opt-in. Ordinary delegation must not wait for
+  or invoke `$taskchef-reconcile`; users can request it explicitly to refresh
+  outdated states.
 - Evaluate heartbeat behavior, restart recovery, and recovery after the
   dispatcher task is deleted.
 - Add a reconciliation cursor only when repeated full snapshots become costly
   or incorrect.
 - Determine whether thread status alone is sufficient after Codex or machine
   restarts.
+- Decide whether `$taskchef-bootstrap` should be renamed to
+  `$taskchef-workspace` or split into setup and project-management skills.
+  Until then, keep project listing and configuration in `$taskchef-bootstrap`
+  rather than mixing workspace administration into delegation.
 
 ## Grouping and history
 

package/README.md

@@ -106,6 +106,9 @@ taskchef task reconcile-candidates --json --workspace <workspace>
 thread IDs. Pass `--include-finished` only for an explicit full refresh or when
 a finished executor is known to have received new work.
 
+Delegation does not reconcile task states first. Ask the dispatcher to refresh
+or fix outdated task states when you want it to run `$taskchef-reconcile`.
+
 ## Complete CLI
 
 ```text

package/SPEC.md

@@ -21,10 +21,11 @@ TaskChef is not an agent runtime, scheduler, or background service.
 6. TaskChef records the returned `threadId`, changes the status to `running`,
    and returns immediately without waiting.
 7. The user may open and prompt any delegated task directly.
-8. The next user prompt in the dispatcher triggers one bounded reconciliation
-   of active `running` and `blocked` threads.
+8. When the user asks to refresh or fix outdated task states, TaskChef performs
+   one bounded reconciliation of active `running` and `blocked` threads.
 9. Reconciliation updates each task's current status and result, then returns
-   control without waiting for future activity.
+   control without waiting for future activity. Ordinary delegation does not
+   trigger reconciliation first.
 
 Multiple ongoing tasks may target the same project.
 
@@ -51,10 +52,10 @@ implementation utilities remain in the source repository.
 ## Dispatcher instructions
 
 TaskChef owns a marked block in the workspace `AGENTS.md`. The block tells
-Codex to use `taskchef-bootstrap` for workspace setup and repair, use
-`taskchef-reconcile` once for active work, then use
-`taskchef-delegate` for actionable requests without completing delegated work
-in the dispatcher thread.
+Codex to use `$taskchef-bootstrap` for workspace setup and administration and
+`$taskchef-delegate` for actionable requests without completing delegated work
+in the dispatcher thread. The final instruction reserves `$taskchef-reconcile`
+for user-requested refreshes or repairs of outdated task states.
 
 `workspace init` copies the canonical file when `AGENTS.md` does not exist. When it
 does exist, bootstrap preserves unrelated user content and adds or refreshes
@@ -242,7 +243,8 @@ TaskChef does not wait for delegated tasks to finish.
 
 ## Reconciliation workflow
 
-The next user prompt in the dispatcher triggers reconciliation:
+When the user asks to refresh or fix outdated task states, TaskChef uses
+`$taskchef-reconcile` to perform one bounded pass:
 
 1. use `task reconcile-candidates --json` to load only `running` and `blocked`
    task records with executor thread IDs;
@@ -253,8 +255,8 @@ The next user prompt in the dispatcher triggers reconciliation:
 
 The native Codex thread is the live source of truth between reconciliations.
 `task.json` is only the latest reconciled snapshot. It may still say `running`
-after the executor has finished and before the user next prompts the
-dispatcher.
+after the executor has finished and until the user explicitly requests a
+reconciliation pass.
 
 Reconciliation must be safe to repeat. TaskChef has no reconciliation timestamp,
 event cursor, event log, callback, or automatic workspace update.
@@ -300,8 +302,8 @@ The MVP is successful when:
 4. Both `threadId` values are recorded.
 5. The dispatcher returns without waiting for execution.
 6. The user can open and prompt either delegated task directly.
-7. The next dispatcher prompt reconciles each active thread once without
-   reading finished executor threads.
+7. A user request to refresh outdated states reconciles each active thread once
+   without reading finished executor threads; ordinary delegation does not.
 8. Status and result snapshots are updated correctly.
 9. Two ongoing tasks may target the same project without data collisions.
 10. The workspace contains dispatcher instructions, configuration, task

package/assets/{AGENTS.md.template → taskchef-dispatcher-instructions.md}

@@ -3,16 +3,16 @@
 
 This repository is a TaskChef dispatcher workspace.
 
-- Use `taskchef-bootstrap` when initializing or refreshing this workspace,
+- Use `$taskchef-bootstrap` when initializing or refreshing this workspace,
   changing or listing its configured projects, running TaskChef doctor,
   repairing its managed instructions, or upgrading its TaskChef skill links.
-- For every ordinary user prompt, use `taskchef-reconcile` first to refresh
-  active recorded work once.
-- For every actionable work request, then use `taskchef-delegate`
+- For every actionable work request, use `$taskchef-delegate`
   automatically, even when the user does not explicitly say "delegate" or
   mention TaskChef.
 - Do not perform delegated work directly in the dispatcher thread.
-- Return immediately after dispatch, as required by `taskchef-delegate`.
+- 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-reconcile` only when the user asks to refresh or fix outdated
+  TaskChef task states.
 <!-- taskchef:dispatcher-instructions:end -->

package/package.json

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

package/skills/taskchef-delegate/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: taskchef-delegate
-description: "Dispatch actionable requests from an initialized TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in a TaskChef workspace, explicit delegation, splitting work across projects, or retrying pending executor creation. Dispatch must return immediately and must never use subagents, hooks, schedules, or foreground waiting. Use taskchef-bootstrap instead for workspace setup or configuration changes."
+description: "Dispatch actionable requests from an initialized TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in a TaskChef workspace, explicit delegation, splitting work across projects, or retrying pending executor creation. Dispatch must return immediately and must never use subagents, hooks, schedules, or foreground waiting."
 ---
 
 # TaskChef Delegate
 
 Create real Codex tasks from a TaskChef data workspace and return immediately.
-Use `taskchef-reconcile` first when the current prompt has active recorded tasks.
 
 Resolve this linked skill with `realpath`. The TaskChef source root is two
-parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` for
-all deterministic workspace and task-record operations.
+parents above the skill directory. Use the TaskChef executable under that root
+for all deterministic workspace and task-record operations.
 
 ## Boundaries
 
@@ -24,20 +23,28 @@ all deterministic workspace and task-record operations.
 
 ## Dispatch
 
-1. Run `project list --json` to load and validate the configured routing
-   targets. Use `taskchef-bootstrap` if the workspace is missing or unhealthy.
+1. Run
+   `<source-root>/bin/taskchef.js project list --json --workspace <workspace>`
+   to load and validate the configured routing targets. Use
+   `$taskchef-bootstrap` if the workspace is missing or unhealthy.
 2. Split the request into the smallest independently useful outcomes. Include
    constraints, expected testing, and reporting in every instruction.
 3. Classify against configured `name`, `githubRepo`, and `description`. Use
    `path` only as checkout identity. Ask when metadata does not produce one
    clear project match.
 4. Resolve native projects once and require the exact configured path.
-5. Reuse a matching pending record for an explicit retry; otherwise create one
-   pending record before executor creation.
+5. For an explicit retry, require the exact task ID and run
+   `<source-root>/bin/taskchef.js task show <task-id> --json --workspace <workspace>`.
+   Reuse the record only when its status is `pending`; ask for the task ID when
+   it is missing and reject retries of non-pending records. For new work, run
+   `<source-root>/bin/taskchef.js task create --json --workspace <workspace>`
+   with the task record JSON on stdin before executor creation.
 6. Create one real Codex task per record using the exact saved project and a
    local environment on its executor host.
-7. Immediately record every returned `threadId` with status `running`. Never
-   persist `hostId`.
+7. Immediately run
+   `<source-root>/bin/taskchef.js task update <task-id> --json --workspace <workspace>`
+   with the `running` status and returned `threadId` on stdin. Never persist
+   `hostId`.
 8. Leave a failed creation pending. Do not invent an ID or delete the record.
 9. Return immediately with a created-thread directive for every success. Do
    not read or wait for a newly created executor.

package/skills/taskchef-reconcile/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-reconcile
-description: "Reconcile active TaskChef task records with their visible Codex executor threads. Use at the start of ordinary prompts in a TaskChef workspace, for TaskChef status or progress requests, after delegated work may have completed or blocked, or for an explicitly requested full refresh. Performs one bounded snapshot pass and never polls or waits for future activity."
+description: "Reconcile active TaskChef task records with their visible Codex executor threads. Use only when the user asks to refresh, fix, or repair outdated TaskChef task states. Performs one bounded snapshot pass and never polls or waits for future activity."
 ---
 
 # TaskChef Reconcile

package/src/workspace.js

@@ -20,7 +20,10 @@ import path from "node:path";
 import { promisify } from "node:util";
 
 const execFile = promisify(execFileCallback);
-const DISPATCHER_INSTRUCTIONS_URL = new URL("../assets/AGENTS.md.template", import.meta.url);
+const DISPATCHER_INSTRUCTIONS_URL = new URL(
+  "../assets/taskchef-dispatcher-instructions.md",
+  import.meta.url,
+);
 const DISPATCHER_INSTRUCTIONS_START = "<!-- taskchef:dispatcher-instructions:start -->";
 const DISPATCHER_INSTRUCTIONS_END = "<!-- taskchef:dispatcher-instructions:end -->";
 const TASKCHEF_SKILL_NAMES = [