codex-toys 0.140.11 → 0.140.13

package/docs/pages/primitives/{deferred-queues.md → dispatch-queues.md}

@@ -1,16 +1,17 @@
 ---
-title: Deferred Queues
+title: Dispatch And Queues
 description: Durable future run intents, prompt queues, local handoffs, retries, and collection.
 ---
 
-# Deferred Queues
+# Dispatch And Queues
 
-Deferred queues give codex-toys a durable way to say "do this later" without
-leaving an agent process running. All queues are stored under the workbench state
+Dispatch is the durable "run this later" primitive. Prompt queue and local
+handoff queue are intake surfaces that create dispatch intents without leaving
+an agent process running. All dispatch state is stored under the workbench state
 root for the selected mode.
 
 ```text
-.codex/workbench/local/deferred/
+.codex/workbench/local/dispatch/
   intents/
   attempts/
   outputs/
@@ -18,26 +19,25 @@ root for the selected mode.
   collect-cursors/
 ```
 
-Actions mode uses `.codex/workbench/actions/deferred`.
+Actions mode uses `.codex/workbench/actions/dispatch`.
 
-## Deferred Runs
+## Dispatch Runs
 
-The base deferred queue stores future workbench intents. A target can be:
+The base dispatch queue stores future workbench intents. A target can be:
 
 - a direct Codex turn
 - a named workflow
 - a configured workbench task
 
 ```bash
-codex-toys workbench deferred create --params-json '{"runAt":"2026-01-01T14:00:00.000Z","target":{"kind":"turn","prompt":"Review the workbench."}}'
-codex-toys workbench deferred list --json
-codex-toys workbench deferred run-due
-codex-toys workbench deferred read <intent-id> --include-output --json
-codex-toys workbench deferred pull <intent-id> --json
-codex-toys workbench deferred collect --cursor operator --json
-codex-toys workbench deferred cancel <intent-id>
-codex-toys workbench deferred retry <intent-id>
-codex-toys workbench deferred prune --older-than-days 30 --dry-run
+codex-toys workbench dispatch create --params-json '{"runAt":"2026-01-01T14:00:00.000Z","target":{"kind":"turn","prompt":"Review the workbench."}}'
+codex-toys workbench dispatch list --json
+codex-toys workbench dispatch run-due
+codex-toys workbench dispatch read <intent-id> --include-output --json
+codex-toys workbench dispatch collect --cursor operator --json
+codex-toys workbench dispatch cancel <intent-id>
+codex-toys workbench dispatch retry <intent-id>
+codex-toys workbench dispatch prune --older-than-days 30 --dry-run
 ```
 
 One-shot intents run at most once. Retry creates a new pending intent from
@@ -46,7 +46,7 @@ terminal history and leaves the original intent, attempts, and outputs in place.
 ## Prompt Queue
 
 The prompt queue is the friendly surface for one-off prompts. It stores prompts
-as deferred turn intents with `source.kind = "prompt-queue"`.
+as dispatch turn intents with `source.kind = "prompt-queue"`.
 
 ```bash
 codex-toys workbench prompt enqueue "Draft migration notes." --queue low-priority --effort low
@@ -60,7 +60,7 @@ codex-toys workbench prompt retry <intent-id>
 
 Prompt entries can target an existing thread with `--thread-id`, set turn
 options such as `--model`, `--service-tier`, `--effort`, `--sandbox`,
-`--approval-policy`, or `--permissions`, and depend on another deferred intent:
+`--approval-policy`, or `--permissions`, and depend on another dispatch intent:
 
 ```bash
 codex-toys workbench prompt enqueue "Continue after the audit." \
@@ -73,7 +73,7 @@ codex-toys workbench prompt enqueue "Continue after the audit." \
 ## Local Handoff Queue
 
 The local handoff queue is for work discovered in one workbench that requires a
-specific local controller host or local-only capability. Handoffs are deferred
+specific local controller host or local-only capability. Handoffs are dispatch
 turn intents with `source.kind = "local-handoff"`, but generic drains skip them.
 
 ```bash
@@ -113,7 +113,7 @@ SSH is transport, not a third queue. With `--ssh`, queue commands operate on the
 remote workbench's local queue through the remote toybox.
 
 ```bash
-codex-toys --ssh <target> --cwd <remote-workbench> workbench deferred list --json
+codex-toys --ssh <target> --cwd <remote-workbench> workbench dispatch list --json
 codex-toys --ssh <target> --cwd <remote-workbench> workbench prompt run-due --limit 1
 codex-toys --ssh <target> --cwd <remote-workbench> workbench handoff collect --cursor operator --json
 ```

package/docs/pages/primitives/feed.md

@@ -1,16 +1,16 @@
 ---
 title: Feed
-description: RSS and Atom intake, durable items, cursors, and ack-aware dispatch.
+description: RSS, Atom, and manual intake, durable items, cursors, and ack-aware dispatch.
 ---
 
 # Feed
 
-Feed is the durable external signal intake primitive. It polls RSS or Atom
-sources, normalizes entries into feed items, records source checkpoints, and lets
-consumers collect items with named cursors.
+Feed is the durable signal intake primitive. It polls RSS or Atom sources,
+normalizes entries into feed items, records source checkpoints, accepts
+manual/local event items, and lets consumers collect items with named cursors.
 
 Feed does not decide what a signal means. A workflow, workbench task, dashboard,
-or product function decides whether to enqueue a prompt, create a deferred run,
+or product function decides whether to enqueue a prompt, create a dispatch run,
 or ignore the item.
 
 ## Config
@@ -44,6 +44,7 @@ codex-toys feed source list --json
 codex-toys feed poll --source project-releases --json
 codex-toys feed item list --source project-releases --status new --json
 codex-toys feed item read <item-id> --json
+codex-toys feed item append --source hq-dispatch-results --params-json '{"externalId":"run-123","title":"Dispatch result","raw":{"status":"completed"}}' --json
 codex-toys feed collect --cursor radar --limit 50 --no-advance --json
 codex-toys feed cursor advance --cursor radar --item <item-id> --json
 codex-toys feed dispatch --source project-releases --cursor radar --target workbench-task:release-check --json
@@ -87,6 +88,7 @@ under an Actions environment.
 ```ts
 import {
   advanceFeedCursor,
+  appendFeedItem,
   collectFeedItems,
   createFeedContext,
   dispatchFeedItems,
@@ -100,6 +102,13 @@ const config = await loadFeedConfig(context);
 
 await pollFeedSources(context, config, { sourceId: "project-releases" });
 
+await appendFeedItem(context, {
+  sourceId: "hq-dispatch-results",
+  externalId: "run-123",
+  title: "Dispatch result",
+  raw: { status: "completed" }
+});
+
 const batch = await collectFeedItems(context, {
   cursor: "radar",
   limit: 50,
@@ -121,9 +130,9 @@ await dispatchFeedItems(context, config, {
 
 ## Boundary
 
-Feed owns source config, polling, HTTP checkpoints, item dedupe, durable item
-storage, collection cursors, cursor advancement, ack-aware dispatch mechanics,
-and pruning.
+Feed owns source config, polling, HTTP checkpoints, manual/local item append,
+item dedupe, durable item storage, collection cursors, cursor advancement,
+ack-aware dispatch mechanics, and pruning.
 
 Products own source catalogs, scoring, filtering, prompt templates, dashboards,
-deferred-run policy, and external writes.
+dispatch-run policy, and external writes.

package/docs/pages/primitives/workbench.md

@@ -35,17 +35,18 @@ repo `.codex` home so CI work can use repo-local skills and memories.
 ```bash
 codex-toys workbench doctor
 codex-toys workbench doctor --mode actions --json
-codex-toys workbench tick --mode local
 codex-toys workbench run <task-id> --mode actions
+codex-toys workbench dispatch run-due --mode actions
 codex-toys workbench overview --json
-codex-toys workbench init actions --forgejo
+codex-toys workbench init actions --forgejo [--image <ref>|--no-image]
 ```
 
 `doctor` reports mode, roots, config, memory presence, task health, latest runs,
-queue health, and local runner visibility when available.
+and queue health.
 
-`tick` creates due scheduled task intents, runs due deferred work, and evaluates
-reactive rules. `run <task-id>` runs one configured task immediately.
+`run <task-id>` runs one configured task immediately. `dispatch run-due` drains
+durable queued dispatch work. Clocks are owned by the host scheduler: systemd
+timers for local machines and Actions schedules for repository autonomy.
 
 ## Config
 
@@ -58,26 +59,23 @@ id = "daily-check"
 enabled = true
 kind = "workflow"
 workflow = "release-check"
-schedule = "0 14 * * *"
+history = "latest"
 
 [[workbench.tasks]]
 id = "node-version"
 enabled = true
 kind = "command"
 command = ["node", "--version"]
-schedule = "0 * * * *"
-
-[[workbench.reactive]]
-id = "repair-failing-task"
-enabled = true
-task = "*"
-consecutive_failures_gte = 3
-kind = "skill"
-skill = "skill-repair"
+history = "full"
 ```
 
-Task ids should be lowercase slug-like ids. Schedules use five-field cron
-syntax.
+Task ids should be lowercase slug-like ids. `history = "full"` is the default
+and writes per-run status and output files. `history = "latest"` overwrites
+stable latest status and output files for that task.
+
+Task-level schedules and reactive rule blocks are not workbench config
+surfaces. Put recurrence in systemd timers or Actions workflow schedules and
+have those schedulers call explicit codex-toys commands.
 
 ## Task Kinds
 
@@ -100,9 +98,16 @@ codex-toys workbench init actions --forgejo
 codex-toys workbench init actions --github
 ```
 
-The generated runner prepares auth, runs `workbench tick --mode actions`,
-cleans up runtime-only files, and preserves durable workbench state. Durable
-state may include:
+For the full GitHub Actions schedule setup, see
+[Repository autonomy](../guides/repository-autonomy).
+
+The generated runner prepares auth, runs `workbench dispatch run-due --mode actions`,
+cleans up runtime-only files, and preserves durable workbench state. By default
+it runs inside `ghcr.io/peezy-tech/codex-toys-actions:latest`, which supplies
+Node, VitePlus, native Codex CLI, codex-toys, Git, and common shell tools. Pass
+`--image <ref>` to use a custom image built from that base image, or `--no-image`
+to generate a workflow that installs the runtime during every run. Durable state
+may include:
 
 ```text
 .codex/memories/
@@ -121,7 +126,7 @@ where that history belongs in git.
 
 - fetch and doctor summary
 - queue counts and compact intents
-- latest deferred output status
+- latest dispatch output status
 - workflows
 - functions
 - recent cwd threads

package/docs/pages/primitives/workflow.md

@@ -165,7 +165,8 @@ method, not a direct app-server method.
 
 ## Workbench Tasks
 
-Workbench tasks can run named workflows on a schedule or from `workbench run`:
+Workbench tasks can run named workflows from `workbench run`, dispatch targets,
+or feed dispatch:
 
 ```toml
 [workbench]
@@ -176,9 +177,9 @@ id = "release-check"
 enabled = true
 kind = "workflow"
 workflow = "release-check"
-schedule = "0 14 * * *"
 ```
 
-Scheduled workflow tasks create deferred run intents, so scheduled work and
-one-shot deferred work share the same claiming, attempt, output, retry, and
-collection path.
+Use systemd timers or Actions schedules to call explicit commands when a
+workflow should run on a clock. Durable dispatch and feed dispatch can also
+target the workflow-backed task so queued work shares the same attempt, output,
+retry, and collection path.

package/docs/pages/reference/packages.md

@@ -37,6 +37,7 @@ Feed intake helpers:
 
 - `.codex/feed.toml` config
 - RSS/Atom polling and normalization
+- manual/local feed item append
 - source checkpoints
 - durable feed item storage
 - collection cursors
@@ -45,6 +46,7 @@ Feed intake helpers:
 
 ```ts
 import {
+  appendFeedItem,
   createFeedContext,
   loadFeedConfig,
   pollFeedSources,
@@ -58,8 +60,8 @@ Workbench runtime and policy helpers:
 
 - workflow script execution and workflow host helpers
 - remote workflow toybox methods
-- workbench doctor, tick, task execution, and Actions scaffolding
-- deferred runs, prompt queue, and local handoff queue
+- workbench doctor, task execution, dispatch drains, and Actions scaffolding
+- dispatch runs, prompt queue, and local handoff queue
 - delegation methods and state
 - workbench functions
 - workbench and host overview
@@ -88,6 +90,16 @@ Actions-mode helpers:
 These helpers prepare repo-local auth for Actions mode and clean runtime-only
 files without deleting durable workbench state.
 
+## `ghcr.io/peezy-tech/codex-toys-actions`
+
+Actions-mode runner image. Use
+`ghcr.io/peezy-tech/codex-toys-actions:<version>` to pin the runtime to a
+codex-toys release, or build a custom image from it when a workbench needs extra
+system packages. The generated Actions-mode workflow uses
+`ghcr.io/peezy-tech/codex-toys-actions:latest` by default. The OpenAI Codex
+release feed publishes `codex-<codex-version>` tags that bake native Codex into
+the image before the bindings workflow runs.
+
 ## `codex-toys/remote`
 
 SSH-backed transport and preflight helpers. This package creates toybox

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-toys",
-	"version": "0.140.11",
+	"version": "0.140.13",
 	"description": "Codex CLI and umbrella runtime export for bridge, toybox, feed, remote, workbench, actions, proxy, and kits.",
 	"type": "module",
 	"license": "Apache-2.0",