delegation-layer 0.2.0 → 0.3.0

package/README.md

@@ -8,6 +8,7 @@ and retrieving results with evidence.
 · [Example](#ask-naturally)
 · [Providers](https://github.com/hishamkaram/delegation-layer/blob/main/docs/providers.md)
 · [Teams](https://github.com/hishamkaram/delegation-layer/blob/main/docs/teams.md)
+· [Start recurring tasks](docs/getting-started.md#recurring-tasks)
 · [Docs](https://github.com/hishamkaram/delegation-layer/blob/main/docs/README.md)
 
 <p align="center">
@@ -55,6 +56,10 @@ for activation and limits.
 For a manual CLI task, use the packaged
 [read-only example](skills/agent-integration/examples/read-only-task.md).
 
+For recurring work, follow the [scheduler walkthrough](docs/getting-started.md#recurring-tasks)
+to save a definition, start the scheduler in your own terminal or tmux pane,
+inspect its first result and stop or restart it.
+
 ## Help and contributing
 
 See [troubleshooting](https://github.com/hishamkaram/delegation-layer/blob/main/docs/troubleshooting.md),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Multi-provider AI agent delegation CLI and Agent Skill for running bounded coding tasks across provider CLIs.",
   "keywords": [
     "ai-agents",

package/plugins/delegation-layer/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "delegation-layer",
   "displayName": "Delegation Layer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Consult external AI harnesses and CCR-configured models for reviews, research, implementation, and debate through the resumable Delegate CLI.",
   "author": {
     "name": "Hesham Karam",

package/plugins/delegation-layer/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Consult external AI harnesses and CCR-configured models for reviews, research, implementation, and debate through the resumable Delegate CLI.",
   "author": {
     "name": "Hesham Karam",

package/plugins/delegation-layer/skills/agent-integration/examples/managed-workspace.md

@@ -34,17 +34,34 @@ else
   status_exit=$?
 fi
 printf '%s\n' "$status_exit" >"$RESPONSE.status.exit"
+cat "$RESPONSE.status"
+```
+
+Read the saved status JSON and apply
+[Observe and collect](../references/result-handling.md#observe-and-collect)
+before running another command. Run the collection below only when that
+guidance calls for it.
+
+```sh
 if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect TASK_ID --watch 5s --json >"$RESPONSE.collect"; then
   collect_exit=0
 else
   collect_exit=$?
 fi
 printf '%s\n' "$collect_exit" >"$RESPONSE.collect.exit"
+cat "$RESPONSE.collect"
 ```
 
-Continue observing that created task when collection exits `3`. Wait for the
-workspace to return to `state: retained` and inspect its final capture. Only
-after the Lead explicitly chooses release, run:
+Apply that same decision order to the collection JSON before treating exit `3`
+as pending. Cancellation, `failure.code: "task_cancelled"` or
+`failure.next_action: "stop_and_report"` ends pending polling; do not continue
+the task or dispatch a replacement. Bounded
+[failure diagnosis](../references/result-handling.md#failure-diagnosis)
+remains available. Keep observing the same task with a finite watch only when
+the canonical guidance calls for it.
+
+Before release, wait for the workspace to return to `state: retained` and inspect
+its final capture. Only after the Lead explicitly chooses release, run:
 
 ```sh
 if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" workspace release WORKSPACE_ID \
@@ -62,10 +79,11 @@ Follow the same result decisions rather than assuming either response is
 completed cleanup.
 
 Save each response and exit code once. A created task is observed with
-`status` first and collected in the foreground. Exit `3` means pending, not
-success; continue observing the same task. The Lead reviews the capture and
-owns landing any changes. `workspace release` is explicit; no automatic
-apply, commit, branch merge, TTL eviction, or provider-CLI fallback occurs.
+`status` first and collected in the foreground, following the canonical
+observation decisions before each next step. Exit `3` alone is not a reason
+to keep polling. The Lead reviews the capture and owns landing any changes.
+`workspace release` is explicit; no automatic apply, commit, branch merge,
+TTL eviction, or provider-CLI fallback occurs.
 
 ## Fork from a checkpoint
 

package/plugins/delegation-layer/skills/agent-integration/references/ccr.md

@@ -3,18 +3,21 @@
 Use this reference when asked to consult Claude Code Router (CCR), use one of
 its configured model aliases, or compare its models with other harnesses.
 CCR runs Claude Code against a configured third-party or local provider.
+`ROOT` below is the exact absolute state root selected for dispatch; use it
+unchanged for model discovery and dispatch.
 
 1. Resolve CCR through `delegate providers --json`; its profile is `ccr:print`.
 2. Preserve an explicitly requested CCR alias as `--model ALIAS`. Do not replace
    it with an upstream model ID or reject it solely because discovery omitted it.
 3. If no alias was chosen, run
-   `delegate models --provider ccr:print --cwd ABSOLUTE_WORKSPACE --json`.
+   `delegate --root ROOT models --provider ccr:print --cwd ABSOLUTE_WORKSPACE --json`.
    Choose a suitable configured alias from the available metadata and report
    the choice. Clarify when the intended model remains ambiguous. If discovery
    is unavailable and no alias is known, report the blocker; do not guess.
-4. Dispatch through Delegate with `--provider ccr:print --model ALIAS`, the brief,
-   workspace, permission, finite budget, and `--json`. Use the normal status,
-   collect, and continuation procedure from the main skill.
+4. Dispatch through Delegate with the same `--root ROOT`,
+   `--provider ccr:print --model ALIAS`, the brief, workspace, permission, finite
+   budget, and `--json`. Use the normal status, collect, and continuation procedure
+   from the main skill.
 
 CCR requires an explicit alias. Unspecified external collaboration still uses
 `dispatch --auto`; do not prefer CCR unless the request calls for it. Multiple

package/plugins/delegation-layer/skills/agent-integration/references/command-reference.md

@@ -22,7 +22,7 @@ The main skill owns [root selection](../SKILL.md#3-prepare-separate-paths-and-a-
 | `workspace`, `checkpoint` | [Git resources](workspaces.md) | Helpers, not provider turns |
 | `teams` | [Optional configuration and Member selection](#teams) | None |
 | `schedule` | [Recurring definitions](#schedules), [history and execution evidence](#schedule-history-and-execution) | None |
-| `scheduler run` | [Independent scheduler](#scheduler-runtime) | Admits due occurrences through normal dispatch |
+| `scheduler serve/status/stop` (when supported), `scheduler run` | [User-started host and compatibility runtime](#scheduler-runtime) | Due occurrences use normal dispatch; status/stop do not launch providers |
 
 Prefix every task command with `delegate --root ROOT`, using the same
 explicit root across invocations.
@@ -186,9 +186,16 @@ not prove admission, provider readiness or successful publication.
 
 ## Schedules
 
-The management commands below save and inspect definitions. They do not start
-a scheduler, launch a provider, or prove that a task ran. Start the
-[scheduler](#scheduler-runtime) separately to execute due occurrences.
+The management commands below save and inspect definitions; they do not start a
+scheduler, launch a provider themselves, or prove that a task ran. On builds with
+[host controls](#scheduler-runtime), create/resume check for a compatible live
+host after saving. When a response includes `scheduler.serve_command`, retain
+the saved ID and give that argv array intact to the user for an independent
+terminal or tmux pane. For run-only builds, use the
+[compatibility instructions](#scheduler-runtime); do not expect those host fields.
+Never start a persistent scheduler inside the agent's bounded task or submit
+another create to obtain a running scheduler.
+See [definition and host results](result-handling.md#schedule-definition-and-host-results).
 
 ```text
 delegate --root ROOT schedule create --brief FILE --cwd ABS \
@@ -235,7 +242,9 @@ delegate --root ROOT schedule delete SCHEDULE_ID --json
 - Definitions are immutable. Pause blocks future admissions; resume skips the
   interval from the stored cursor through now without catch-up. A clock behind
   the cursor leaves that cursor unchanged. Delete is terminal and retains
-  history. Pause/delete do not cancel an active occurrence.
+  history. Pause/delete do not cancel an active occurrence or require a live
+  host. Create/resume preserve the saved definition even when the host is
+  absent, starting, in backoff or otherwise not confirmed ready.
 - Only create initializes absent schedule storage. An absent store lists as
   empty; show/state commands report not found. List defaults to 50 rows, at most
   100, including paused/deleted definitions. Use the returned cursor to page.
@@ -244,8 +253,11 @@ delegate --root ROOT schedule delete SCHEDULE_ID --json
   when output or storage reports uncertainty; inspect it with show rather than
   submitting another create. Reusing an existing ID conflicts.
 
-Handler results use exit `0` for success/advisory warnings, `2` for invalid
-input/state transitions and `1` for not-found, conflicts or operational failures.
+Handler results use exit `0` for confirmed completion/advisory warnings, `2` for
+invalid input/state transitions and `1` for not-found, conflicts or operational
+failures. On builds with host controls, create/resume also use exit `3` for saved
+definitions needing user host start or pending host readiness; keep the same ID
+and follow [result handling](result-handling.md#schedule-definition-and-host-results).
 `--json` applies to handler responses; argument/usage errors retain the CLI's
 normal stderr behavior. A valid rule with no future occurrence in the supported
 timestamp range has a distinct range error, not a claim of permanent invalidity.
@@ -282,31 +294,116 @@ for freshness, no-result states, response bounds, exit codes and recovery.
 
 ## Scheduler runtime
 
+Check `delegate help` for the installed build's command surface. Use `serve`,
+`status` and `stop` only when that help advertises them; prefer `serve` for managed
+recovery. The signatures below describe the current command surface. Keep the
+same explicit absolute `ROOT` used by the schedule commands.
+
 ```text
+delegate --root ROOT scheduler serve
+delegate --root ROOT scheduler status
+delegate --root ROOT scheduler stop
 delegate --root ROOT scheduler run [--pueue-config ABS] [--json]
 ```
 
-The scheduler requires the automatic managed worker. Use colocated `delegate`
+If installed help offers only `scheduler run`, the user runs
+`delegate --root ROOT scheduler run` in an independent terminal or tmux pane and
+leaves it in the foreground. Ctrl-C in its original pane stops it; it has no
+automatic child restart. Keep the saved schedule ID and inspect
+[history and execution](#schedule-history-and-execution) for actual occurrences.
+Do not issue unsupported `scheduler status` or `scheduler stop` commands, or
+expect `start_required` or `scheduler.serve_command` fields from that build.
+The managed-host controls and response fields below apply only when installed
+help supports them.
+
+The user starts one foreground `serve` host per canonical execution root in an
+independent terminal or tmux pane and leaves it running. It manages every saved
+schedule in that root. When returned, agents give the exact
+`scheduler.serve_command` argv array to the user. Agents must not start either
+persistent scheduler command inside their own bounded task. The guard recognizes
+an explicit Delegate task-scope marker and, on Linux, native Delegate
+cgroup membership. It does not reconstruct guardian ownership or detect every
+enclosing ancestor. A successful check or missing marker does not prove
+independent placement; independent user launch remains required. Delegate
+installs no OS service, enables no reboot/login startup and
+does not automatically launch a detached host.
+
+When present, `scheduler.serve_command` preserves spaces and shell metacharacters
+as separate arguments. Human output also prints JSON argv, not an unquoted shell string.
+Preserve those boundaries; see the [scheduler response fields](result-handling.md#schedule-definition-and-host-results).
+
+Serve requires existing schedule storage; create owns initialization. A second
+host or competing `run` cannot acquire the same root's ownership. The host uses
+its retained launch context and the saved requested provider choices. For
+Team-targeted schedules, new occurrences read the pinned catalog's latest Member
+defaults through normal admission; existing task IDs retain saved settings. Use
+the intended user configuration context, or a different catalog instance fails
+admission even when Team/Member IDs match. Context changes require completed stop
+and a fresh user start; full launch environments are not persisted.
+
+While the host lives, it restarts its scheduler child after an unexpected exit,
+including a clean exit while running is still desired. A successful Start needs
+its exact child Wait before replacement; a definitively failed Start that
+created no child may retry without Wait. Retry delays are 1, 2, 4, 8, 16, 30, 60,
+120 and 300 seconds, capped at five minutes indefinitely. Five continuous healthy
+minutes reset the policy;
+elapsed healthy time and delays use monotonic timing. Create/resume/status do not
+reset cooldown. A live but unready child or uncertain launch is not replaced.
+Before the child reports Ready or scans for due work, the application's
+before-Ready check validates every current saved definition. An incompatible
+definition leaves the host degraded and stops automatic child restart for that
+incompatibility; it does not enter an endless crash/retry loop. Preserve the
+saved definitions and report the compatibility fault.
+If the host, terminal/tmux pane or machine stops, automatic recovery ends; the
+user must run serve again.
+
+`scheduler status` is passive: it does not start, migrate, repair or clean
+anything. It observes starting, ready, backoff, degraded, stopping or stopped
+state, or a compatibility runtime's `foreground` generation, and available
+attempt, bounded diagnostic and retry information. Optional
+`scheduler.fault: true` is the host owner's permanent fault decision; degraded state or
+`last_error` alone is not that decision. After a definition is saved,
+transport-only unreachability returns pending exit `3` without a top-level
+`error`; a permanent host fault returns exit `1`, retaining
+`schedule.saved: true` and the same ID.
+
+`scheduler stop` persists a stopped fence, interrupts backoff, ends admission and
+joins accepted controls, GoCron shutdown and child Wait. The host remains
+responsive to authenticated status/stop while joining its child or waiting for a
+prior execution owner. Under host ownership, it writes a closure witness once
+execution ownership is free. Completed stop requires that witness and exact
+host absence; acceptance, timeout or host death alone is not completion.
+Authenticated acceptance remains visible even if later readback fails; concrete
+faults remain visible too. SIGINT, SIGTERM and SIGHUP use the same fenced shutdown
+path. Independently admitted tasks retain their own supervisors and budgets.
+See [host result decisions](result-handling.md#schedule-definition-and-host-results).
+
+`scheduler run` runs the foreground runtime directly and remains a compatibility
+path without automatic child restart. On builds with host controls, it shares
+root ownership with serve and announces its current foreground generation,
+which an older managed-host stop
+receipt cannot hide. Status reports `scheduler.state: foreground`.
+`scheduler stop` does not terminate the raw invocation: it returns
+`stop_accepted: false` and `next_action: stop_foreground_runtime`. The user ends
+it with Ctrl-C in its original pane; prefer `scheduler serve` for managed
+recovery. The existing manual OS-service hosting option is separate from the new
+foreground host path; see [operator hosting](https://github.com/hishamkaram/delegation-layer/blob/main/docs/cli-reference.md#scheduler-hosting).
+
+Serve and run require the automatic managed worker. Use colocated `delegate`
 and `delegate-run` binaries from the same build and omit the advanced `--runner`
 override. An override selects custom ownership even when it names the bundled
-worker; startup rejects it with exit `2` before opening storage or acquiring a
-lease. Ordinary explicit custom-runner dispatch and continuation retain their
+worker. `scheduler run` rejects it with exit `2` before opening storage or
+acquiring a lease. `scheduler serve` checks existing state and schedule storage
+before rejecting the override with exit `2`, so a storage error can take
+precedence. Ordinary explicit custom-runner dispatch and continuation retain their
 existing compatibility rules. Historical custom-runner claims are not
 automatically repaired or released.
 
-This foreground command requires existing schedule storage. One process owns
-each root; a second fails busy. It uses the service launch environment and the
-saved requested provider choices. Saving a definition never starts the service.
-For Team-targeted schedules, new occurrences read the pinned catalog's latest
-Member defaults through normal admission; existing task IDs retain saved settings.
-Use the same intended user configuration context as creation, or a different
-catalog instance fails admission even when Team/Member IDs match.
-See [operator hosting](https://github.com/hishamkaram/delegation-layer/blob/main/docs/cli-reference.md#scheduler-hosting).
-
 Startup skips past appointments. Expired, overlapping or capacity-limited
 appointments are skipped with a recorded reason; no catch-up queue or automatic
-retry/continuation is added. Pause/delete prevent new claims, without canceling
-already claimed tasks. Use [history and execution](#schedule-history-and-execution)
+provider retry/continuation is added. Downtime is recorded in compact skipped
+intervals, never replayed minute by minute. Pause/delete prevent new claims,
+without canceling already claimed tasks. Use [history and execution](#schedule-history-and-execution)
 to inspect recorded work, and [result handling](result-handling.md#scheduled-execution-results)
 to collect its answer. Schedule reservation release is separate from result
 publication.
@@ -317,12 +414,12 @@ Delegate workers keep their own budgets; provider-native in-session subagents do
 not acquire independent Delegate lifetimes. The workflow owns saved progress,
 worker IDs and deduplication; unknown acknowledgment is not permission to resend.
 
-Interrupting the service joins its admission/control work before releasing its
-owner lease. Accepted lifecycle calls settle independently of the stop signal;
+Interrupting the compatibility runtime joins its admission/control work before
+releasing its owner lease. Accepted lifecycle calls settle independently of the stop signal;
 there is no shutdown-time guarantee. Already admitted tasks continue under their
-own supervisors. The
-service reports bounded identifiers/codes on stderr; `--json` selects the final
-command response, not an event stream or daemon-control protocol. Uncertain task
+own supervisors. The compatibility command reports bounded identifiers/codes on
+stderr; `--json` selects the final command response, not an event stream or
+daemon-control protocol. Uncertain task
 evidence blocks only its schedule until the existing owners can prove closure.
 
 ## Codex review

package/plugins/delegation-layer/skills/agent-integration/references/result-handling.md

@@ -166,6 +166,66 @@ asking again, but never infer it from a rejection or silently substitute a
 destination. Keep the original failed attempt reported as failed; independent
 requests and explicitly allowed recovery paths retain their existing rules.
 
+## Schedule definition and host results
+
+Use the installed build's help to check `scheduler serve/status/stop` support.
+Keep three facts separate: the definition was
+saved, the host is ready, and an occurrence produced an accepted provider result.
+Neither saving nor host readiness proves that a task ran.
+
+Schedule create/resume report confirmed persistence as `schedule.saved: true`;
+keep `schedule.id` even if the command exits nonzero. The separate top-level
+`scheduler` object carries host observation and guidance:
+
+| JSON field | Meaning |
+| --- | --- |
+| `scheduler.state` | Observed lifecycle or availability state, including `foreground` for a current raw `scheduler run`. Read it with `ready` and the process exit. |
+| `scheduler.epoch`, `scheduler.attempt` | Owner generation string and numeric child attempt, when known. Omission does not identify an owner. |
+| `scheduler.ready` | Whether this observation confirms host/child readiness; it is not an occurrence result. |
+| `scheduler.fault` | Optional `true` for a permanent fault reported by the host owner. Do not infer it from degraded state or `last_error`; omission is not proof that the whole command is fault-free. |
+| `scheduler.next_retry_at` | Optional next retry timestamp during recovery. Observation does not reset it. |
+| `scheduler.last_error` | Optional bounded host diagnostic. Keep it alongside pending or readiness facts. |
+| `scheduler.next_action` | Caller guidance, such as `start_required`, `inspect_scheduler` or `stop_foreground_runtime`. |
+| `scheduler.serve_command` | Optional exact argv array for an independent user start. Preserve every element and its argument boundary. |
+| `scheduler.stop_accepted` | Optional boolean for acceptance of this stop request. `true` is accepted, `false` is explicitly not accepted, and omission is unknown. Acceptance does not prove shutdown completed. |
+
+For `start_required`, both `schedule.next_action` and `scheduler.next_action`
+carry that guidance. `scheduler.serve_command` is JSON argv, including the
+resolved executable and exact root. Human output also prints JSON argv after
+`run independently (argv):`, for example:
+
+```text
+run independently (argv): ["/installation with spaces/delegate","--root","/state with spaces","scheduler","serve"]
+```
+
+Forward the array intact. It is not an unquoted shell command: do not join its
+elements with spaces or pass the joined text through a shell. The user starts
+serve independently with those exact argument boundaries; the agent must not
+execute it inside its bounded task. An omitted `schedule.saved` does not confirm
+persistence; preserve any ID and follow the reported storage/error guidance.
+
+| Response or observation | Next action |
+| --- | --- |
+| Create/resume saved the definition and confirmed a compatible ready host; exit `0` | Keep its schedule ID/root. The host will handle future due work; use history/execution for actual occurrence evidence. |
+| Create/resume returns exit `3`, `schedule.saved: true` and `scheduler.next_action: start_required` | The definition remains saved. Preserve the returned schedule ID/root and give `scheduler.serve_command` unchanged to the user to run in an independent terminal or tmux pane. Never start it inside the agent's bounded task, detach it in the background, or submit another create. |
+| Create/resume saved the definition but reports starting, backoff or pending readiness; exit `3` | Keep the same ID and report its host state and available retry time. Use passive scheduler status for later observation; do not create another definition, start a competing host or reset cooldown. |
+| Create/resume saved the definition but the host is temporarily unreachable; exit `3`, pending guidance and no top-level `error` | Preserve `schedule.saved: true` and the same ID. Use passive status to observe the uncertainty. A transport failure does not establish owner death or a permanent host fault. |
+| Create/resume saved the definition and the host reports `scheduler.fault: true`; exit `1` | Report the permanent fault and available `scheduler.last_error`; retain `schedule.saved: true` and the ID. For an incompatible saved definition, the before-Ready check stops automatic child restart. Repeated create, serve or status calls are not a repair. |
+| Scheduler status observes starting, ready, backoff, degraded, stopping or stopped; exit `0` | Observation completed. Report the observed state; exit `0` does not mean ready or that an occurrence succeeded. Status does not start, migrate, repair or clean resources. |
+| Scheduler stop confirms completed stop; exit `0` | The exact stopped intent has a validated owner-written closure witness and the exact host is absent. The witness follows joined child shutdown and free execution ownership. Independently admitted tasks keep their existing lifetimes. A later host needs a fresh explicit user-run serve command. |
+| Scheduler stop has `scheduler.stop_accepted: true` but completion is pending; exit `3` | Preserve its acceptance and pending state. The host remains control-responsive while joining its child or waiting for a prior execution owner. Host death before the closure witness does not complete stop. Observe the same generation; do not claim stopped, launch a replacement or repeat schedule creation. An omitted `stop_accepted` is unknown, not false. |
+| Scheduler stop has authenticated `scheduler.stop_accepted: true` and a later readback fault; exit `1` | Preserve the accepted fact and report the concrete fault. Readback failure does not revoke acceptance or establish completed shutdown. |
+| Status reports `scheduler.state: foreground`, or stop returns exit `3` with that state, `stop_accepted: false` and `next_action: stop_foreground_runtime` | The current compatibility `scheduler run` owns this generation; an older managed-host receipt cannot hide it. Public stop does not terminate it. Have the user end that invocation with Ctrl-C in its original pane. Prefer managed `scheduler serve` afterward. |
+| Invalid input/state; exit `2`, or concrete operational/compatibility/cleanup fault; exit `1` | Report the error and retain any saved ID or accepted-control fact. A concrete fault joined to pending work remains a fault; it is not a pending-only result. |
+
+If the host dies, its pane closes or the machine reboots, the user must start
+serve again. Child crash recovery applies only while that host remains alive.
+An absent heartbeat or unresponsive endpoint is uncertainty, not permission to
+replace an owner. Do not install a service or invoke a detached bootstrap as a
+recovery step. Pause/delete affect future claims and need no live host; they do
+not cancel already admitted occurrences. [Scheduler runtime](command-reference.md#scheduler-runtime)
+owns launch, backoff and calendar behavior.
+
 ## Scheduled execution results
 
 Use [schedule history and execution](command-reference.md#schedule-history-and-execution)

package/skills/agent-integration/examples/managed-workspace.md

@@ -34,17 +34,34 @@ else
   status_exit=$?
 fi
 printf '%s\n' "$status_exit" >"$RESPONSE.status.exit"
+cat "$RESPONSE.status"
+```
+
+Read the saved status JSON and apply
+[Observe and collect](../references/result-handling.md#observe-and-collect)
+before running another command. Run the collection below only when that
+guidance calls for it.
+
+```sh
 if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect TASK_ID --watch 5s --json >"$RESPONSE.collect"; then
   collect_exit=0
 else
   collect_exit=$?
 fi
 printf '%s\n' "$collect_exit" >"$RESPONSE.collect.exit"
+cat "$RESPONSE.collect"
 ```
 
-Continue observing that created task when collection exits `3`. Wait for the
-workspace to return to `state: retained` and inspect its final capture. Only
-after the Lead explicitly chooses release, run:
+Apply that same decision order to the collection JSON before treating exit `3`
+as pending. Cancellation, `failure.code: "task_cancelled"` or
+`failure.next_action: "stop_and_report"` ends pending polling; do not continue
+the task or dispatch a replacement. Bounded
+[failure diagnosis](../references/result-handling.md#failure-diagnosis)
+remains available. Keep observing the same task with a finite watch only when
+the canonical guidance calls for it.
+
+Before release, wait for the workspace to return to `state: retained` and inspect
+its final capture. Only after the Lead explicitly chooses release, run:
 
 ```sh
 if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" workspace release WORKSPACE_ID \
@@ -62,10 +79,11 @@ Follow the same result decisions rather than assuming either response is
 completed cleanup.
 
 Save each response and exit code once. A created task is observed with
-`status` first and collected in the foreground. Exit `3` means pending, not
-success; continue observing the same task. The Lead reviews the capture and
-owns landing any changes. `workspace release` is explicit; no automatic
-apply, commit, branch merge, TTL eviction, or provider-CLI fallback occurs.
+`status` first and collected in the foreground, following the canonical
+observation decisions before each next step. Exit `3` alone is not a reason
+to keep polling. The Lead reviews the capture and owns landing any changes.
+`workspace release` is explicit; no automatic apply, commit, branch merge,
+TTL eviction, or provider-CLI fallback occurs.
 
 ## Fork from a checkpoint
 

package/skills/agent-integration/references/ccr.md

@@ -3,18 +3,21 @@
 Use this reference when asked to consult Claude Code Router (CCR), use one of
 its configured model aliases, or compare its models with other harnesses.
 CCR runs Claude Code against a configured third-party or local provider.
+`ROOT` below is the exact absolute state root selected for dispatch; use it
+unchanged for model discovery and dispatch.
 
 1. Resolve CCR through `delegate providers --json`; its profile is `ccr:print`.
 2. Preserve an explicitly requested CCR alias as `--model ALIAS`. Do not replace
    it with an upstream model ID or reject it solely because discovery omitted it.
 3. If no alias was chosen, run
-   `delegate models --provider ccr:print --cwd ABSOLUTE_WORKSPACE --json`.
+   `delegate --root ROOT models --provider ccr:print --cwd ABSOLUTE_WORKSPACE --json`.
    Choose a suitable configured alias from the available metadata and report
    the choice. Clarify when the intended model remains ambiguous. If discovery
    is unavailable and no alias is known, report the blocker; do not guess.
-4. Dispatch through Delegate with `--provider ccr:print --model ALIAS`, the brief,
-   workspace, permission, finite budget, and `--json`. Use the normal status,
-   collect, and continuation procedure from the main skill.
+4. Dispatch through Delegate with the same `--root ROOT`,
+   `--provider ccr:print --model ALIAS`, the brief, workspace, permission, finite
+   budget, and `--json`. Use the normal status, collect, and continuation procedure
+   from the main skill.
 
 CCR requires an explicit alias. Unspecified external collaboration still uses
 `dispatch --auto`; do not prefer CCR unless the request calls for it. Multiple

package/skills/agent-integration/references/command-reference.md

@@ -22,7 +22,7 @@ The main skill owns [root selection](../SKILL.md#3-prepare-separate-paths-and-a-
 | `workspace`, `checkpoint` | [Git resources](workspaces.md) | Helpers, not provider turns |
 | `teams` | [Optional configuration and Member selection](#teams) | None |
 | `schedule` | [Recurring definitions](#schedules), [history and execution evidence](#schedule-history-and-execution) | None |
-| `scheduler run` | [Independent scheduler](#scheduler-runtime) | Admits due occurrences through normal dispatch |
+| `scheduler serve/status/stop` (when supported), `scheduler run` | [User-started host and compatibility runtime](#scheduler-runtime) | Due occurrences use normal dispatch; status/stop do not launch providers |
 
 Prefix every task command with `delegate --root ROOT`, using the same
 explicit root across invocations.
@@ -186,9 +186,16 @@ not prove admission, provider readiness or successful publication.
 
 ## Schedules
 
-The management commands below save and inspect definitions. They do not start
-a scheduler, launch a provider, or prove that a task ran. Start the
-[scheduler](#scheduler-runtime) separately to execute due occurrences.
+The management commands below save and inspect definitions; they do not start a
+scheduler, launch a provider themselves, or prove that a task ran. On builds with
+[host controls](#scheduler-runtime), create/resume check for a compatible live
+host after saving. When a response includes `scheduler.serve_command`, retain
+the saved ID and give that argv array intact to the user for an independent
+terminal or tmux pane. For run-only builds, use the
+[compatibility instructions](#scheduler-runtime); do not expect those host fields.
+Never start a persistent scheduler inside the agent's bounded task or submit
+another create to obtain a running scheduler.
+See [definition and host results](result-handling.md#schedule-definition-and-host-results).
 
 ```text
 delegate --root ROOT schedule create --brief FILE --cwd ABS \
@@ -235,7 +242,9 @@ delegate --root ROOT schedule delete SCHEDULE_ID --json
 - Definitions are immutable. Pause blocks future admissions; resume skips the
   interval from the stored cursor through now without catch-up. A clock behind
   the cursor leaves that cursor unchanged. Delete is terminal and retains
-  history. Pause/delete do not cancel an active occurrence.
+  history. Pause/delete do not cancel an active occurrence or require a live
+  host. Create/resume preserve the saved definition even when the host is
+  absent, starting, in backoff or otherwise not confirmed ready.
 - Only create initializes absent schedule storage. An absent store lists as
   empty; show/state commands report not found. List defaults to 50 rows, at most
   100, including paused/deleted definitions. Use the returned cursor to page.
@@ -244,8 +253,11 @@ delegate --root ROOT schedule delete SCHEDULE_ID --json
   when output or storage reports uncertainty; inspect it with show rather than
   submitting another create. Reusing an existing ID conflicts.
 
-Handler results use exit `0` for success/advisory warnings, `2` for invalid
-input/state transitions and `1` for not-found, conflicts or operational failures.
+Handler results use exit `0` for confirmed completion/advisory warnings, `2` for
+invalid input/state transitions and `1` for not-found, conflicts or operational
+failures. On builds with host controls, create/resume also use exit `3` for saved
+definitions needing user host start or pending host readiness; keep the same ID
+and follow [result handling](result-handling.md#schedule-definition-and-host-results).
 `--json` applies to handler responses; argument/usage errors retain the CLI's
 normal stderr behavior. A valid rule with no future occurrence in the supported
 timestamp range has a distinct range error, not a claim of permanent invalidity.
@@ -282,31 +294,116 @@ for freshness, no-result states, response bounds, exit codes and recovery.
 
 ## Scheduler runtime
 
+Check `delegate help` for the installed build's command surface. Use `serve`,
+`status` and `stop` only when that help advertises them; prefer `serve` for managed
+recovery. The signatures below describe the current command surface. Keep the
+same explicit absolute `ROOT` used by the schedule commands.
+
 ```text
+delegate --root ROOT scheduler serve
+delegate --root ROOT scheduler status
+delegate --root ROOT scheduler stop
 delegate --root ROOT scheduler run [--pueue-config ABS] [--json]
 ```
 
-The scheduler requires the automatic managed worker. Use colocated `delegate`
+If installed help offers only `scheduler run`, the user runs
+`delegate --root ROOT scheduler run` in an independent terminal or tmux pane and
+leaves it in the foreground. Ctrl-C in its original pane stops it; it has no
+automatic child restart. Keep the saved schedule ID and inspect
+[history and execution](#schedule-history-and-execution) for actual occurrences.
+Do not issue unsupported `scheduler status` or `scheduler stop` commands, or
+expect `start_required` or `scheduler.serve_command` fields from that build.
+The managed-host controls and response fields below apply only when installed
+help supports them.
+
+The user starts one foreground `serve` host per canonical execution root in an
+independent terminal or tmux pane and leaves it running. It manages every saved
+schedule in that root. When returned, agents give the exact
+`scheduler.serve_command` argv array to the user. Agents must not start either
+persistent scheduler command inside their own bounded task. The guard recognizes
+an explicit Delegate task-scope marker and, on Linux, native Delegate
+cgroup membership. It does not reconstruct guardian ownership or detect every
+enclosing ancestor. A successful check or missing marker does not prove
+independent placement; independent user launch remains required. Delegate
+installs no OS service, enables no reboot/login startup and
+does not automatically launch a detached host.
+
+When present, `scheduler.serve_command` preserves spaces and shell metacharacters
+as separate arguments. Human output also prints JSON argv, not an unquoted shell string.
+Preserve those boundaries; see the [scheduler response fields](result-handling.md#schedule-definition-and-host-results).
+
+Serve requires existing schedule storage; create owns initialization. A second
+host or competing `run` cannot acquire the same root's ownership. The host uses
+its retained launch context and the saved requested provider choices. For
+Team-targeted schedules, new occurrences read the pinned catalog's latest Member
+defaults through normal admission; existing task IDs retain saved settings. Use
+the intended user configuration context, or a different catalog instance fails
+admission even when Team/Member IDs match. Context changes require completed stop
+and a fresh user start; full launch environments are not persisted.
+
+While the host lives, it restarts its scheduler child after an unexpected exit,
+including a clean exit while running is still desired. A successful Start needs
+its exact child Wait before replacement; a definitively failed Start that
+created no child may retry without Wait. Retry delays are 1, 2, 4, 8, 16, 30, 60,
+120 and 300 seconds, capped at five minutes indefinitely. Five continuous healthy
+minutes reset the policy;
+elapsed healthy time and delays use monotonic timing. Create/resume/status do not
+reset cooldown. A live but unready child or uncertain launch is not replaced.
+Before the child reports Ready or scans for due work, the application's
+before-Ready check validates every current saved definition. An incompatible
+definition leaves the host degraded and stops automatic child restart for that
+incompatibility; it does not enter an endless crash/retry loop. Preserve the
+saved definitions and report the compatibility fault.
+If the host, terminal/tmux pane or machine stops, automatic recovery ends; the
+user must run serve again.
+
+`scheduler status` is passive: it does not start, migrate, repair or clean
+anything. It observes starting, ready, backoff, degraded, stopping or stopped
+state, or a compatibility runtime's `foreground` generation, and available
+attempt, bounded diagnostic and retry information. Optional
+`scheduler.fault: true` is the host owner's permanent fault decision; degraded state or
+`last_error` alone is not that decision. After a definition is saved,
+transport-only unreachability returns pending exit `3` without a top-level
+`error`; a permanent host fault returns exit `1`, retaining
+`schedule.saved: true` and the same ID.
+
+`scheduler stop` persists a stopped fence, interrupts backoff, ends admission and
+joins accepted controls, GoCron shutdown and child Wait. The host remains
+responsive to authenticated status/stop while joining its child or waiting for a
+prior execution owner. Under host ownership, it writes a closure witness once
+execution ownership is free. Completed stop requires that witness and exact
+host absence; acceptance, timeout or host death alone is not completion.
+Authenticated acceptance remains visible even if later readback fails; concrete
+faults remain visible too. SIGINT, SIGTERM and SIGHUP use the same fenced shutdown
+path. Independently admitted tasks retain their own supervisors and budgets.
+See [host result decisions](result-handling.md#schedule-definition-and-host-results).
+
+`scheduler run` runs the foreground runtime directly and remains a compatibility
+path without automatic child restart. On builds with host controls, it shares
+root ownership with serve and announces its current foreground generation,
+which an older managed-host stop
+receipt cannot hide. Status reports `scheduler.state: foreground`.
+`scheduler stop` does not terminate the raw invocation: it returns
+`stop_accepted: false` and `next_action: stop_foreground_runtime`. The user ends
+it with Ctrl-C in its original pane; prefer `scheduler serve` for managed
+recovery. The existing manual OS-service hosting option is separate from the new
+foreground host path; see [operator hosting](https://github.com/hishamkaram/delegation-layer/blob/main/docs/cli-reference.md#scheduler-hosting).
+
+Serve and run require the automatic managed worker. Use colocated `delegate`
 and `delegate-run` binaries from the same build and omit the advanced `--runner`
 override. An override selects custom ownership even when it names the bundled
-worker; startup rejects it with exit `2` before opening storage or acquiring a
-lease. Ordinary explicit custom-runner dispatch and continuation retain their
+worker. `scheduler run` rejects it with exit `2` before opening storage or
+acquiring a lease. `scheduler serve` checks existing state and schedule storage
+before rejecting the override with exit `2`, so a storage error can take
+precedence. Ordinary explicit custom-runner dispatch and continuation retain their
 existing compatibility rules. Historical custom-runner claims are not
 automatically repaired or released.
 
-This foreground command requires existing schedule storage. One process owns
-each root; a second fails busy. It uses the service launch environment and the
-saved requested provider choices. Saving a definition never starts the service.
-For Team-targeted schedules, new occurrences read the pinned catalog's latest
-Member defaults through normal admission; existing task IDs retain saved settings.
-Use the same intended user configuration context as creation, or a different
-catalog instance fails admission even when Team/Member IDs match.
-See [operator hosting](https://github.com/hishamkaram/delegation-layer/blob/main/docs/cli-reference.md#scheduler-hosting).
-
 Startup skips past appointments. Expired, overlapping or capacity-limited
 appointments are skipped with a recorded reason; no catch-up queue or automatic
-retry/continuation is added. Pause/delete prevent new claims, without canceling
-already claimed tasks. Use [history and execution](#schedule-history-and-execution)
+provider retry/continuation is added. Downtime is recorded in compact skipped
+intervals, never replayed minute by minute. Pause/delete prevent new claims,
+without canceling already claimed tasks. Use [history and execution](#schedule-history-and-execution)
 to inspect recorded work, and [result handling](result-handling.md#scheduled-execution-results)
 to collect its answer. Schedule reservation release is separate from result
 publication.
@@ -317,12 +414,12 @@ Delegate workers keep their own budgets; provider-native in-session subagents do
 not acquire independent Delegate lifetimes. The workflow owns saved progress,
 worker IDs and deduplication; unknown acknowledgment is not permission to resend.
 
-Interrupting the service joins its admission/control work before releasing its
-owner lease. Accepted lifecycle calls settle independently of the stop signal;
+Interrupting the compatibility runtime joins its admission/control work before
+releasing its owner lease. Accepted lifecycle calls settle independently of the stop signal;
 there is no shutdown-time guarantee. Already admitted tasks continue under their
-own supervisors. The
-service reports bounded identifiers/codes on stderr; `--json` selects the final
-command response, not an event stream or daemon-control protocol. Uncertain task
+own supervisors. The compatibility command reports bounded identifiers/codes on
+stderr; `--json` selects the final command response, not an event stream or
+daemon-control protocol. Uncertain task
 evidence blocks only its schedule until the existing owners can prove closure.
 
 ## Codex review

package/skills/agent-integration/references/result-handling.md

@@ -166,6 +166,66 @@ asking again, but never infer it from a rejection or silently substitute a
 destination. Keep the original failed attempt reported as failed; independent
 requests and explicitly allowed recovery paths retain their existing rules.
 
+## Schedule definition and host results
+
+Use the installed build's help to check `scheduler serve/status/stop` support.
+Keep three facts separate: the definition was
+saved, the host is ready, and an occurrence produced an accepted provider result.
+Neither saving nor host readiness proves that a task ran.
+
+Schedule create/resume report confirmed persistence as `schedule.saved: true`;
+keep `schedule.id` even if the command exits nonzero. The separate top-level
+`scheduler` object carries host observation and guidance:
+
+| JSON field | Meaning |
+| --- | --- |
+| `scheduler.state` | Observed lifecycle or availability state, including `foreground` for a current raw `scheduler run`. Read it with `ready` and the process exit. |
+| `scheduler.epoch`, `scheduler.attempt` | Owner generation string and numeric child attempt, when known. Omission does not identify an owner. |
+| `scheduler.ready` | Whether this observation confirms host/child readiness; it is not an occurrence result. |
+| `scheduler.fault` | Optional `true` for a permanent fault reported by the host owner. Do not infer it from degraded state or `last_error`; omission is not proof that the whole command is fault-free. |
+| `scheduler.next_retry_at` | Optional next retry timestamp during recovery. Observation does not reset it. |
+| `scheduler.last_error` | Optional bounded host diagnostic. Keep it alongside pending or readiness facts. |
+| `scheduler.next_action` | Caller guidance, such as `start_required`, `inspect_scheduler` or `stop_foreground_runtime`. |
+| `scheduler.serve_command` | Optional exact argv array for an independent user start. Preserve every element and its argument boundary. |
+| `scheduler.stop_accepted` | Optional boolean for acceptance of this stop request. `true` is accepted, `false` is explicitly not accepted, and omission is unknown. Acceptance does not prove shutdown completed. |
+
+For `start_required`, both `schedule.next_action` and `scheduler.next_action`
+carry that guidance. `scheduler.serve_command` is JSON argv, including the
+resolved executable and exact root. Human output also prints JSON argv after
+`run independently (argv):`, for example:
+
+```text
+run independently (argv): ["/installation with spaces/delegate","--root","/state with spaces","scheduler","serve"]
+```
+
+Forward the array intact. It is not an unquoted shell command: do not join its
+elements with spaces or pass the joined text through a shell. The user starts
+serve independently with those exact argument boundaries; the agent must not
+execute it inside its bounded task. An omitted `schedule.saved` does not confirm
+persistence; preserve any ID and follow the reported storage/error guidance.
+
+| Response or observation | Next action |
+| --- | --- |
+| Create/resume saved the definition and confirmed a compatible ready host; exit `0` | Keep its schedule ID/root. The host will handle future due work; use history/execution for actual occurrence evidence. |
+| Create/resume returns exit `3`, `schedule.saved: true` and `scheduler.next_action: start_required` | The definition remains saved. Preserve the returned schedule ID/root and give `scheduler.serve_command` unchanged to the user to run in an independent terminal or tmux pane. Never start it inside the agent's bounded task, detach it in the background, or submit another create. |
+| Create/resume saved the definition but reports starting, backoff or pending readiness; exit `3` | Keep the same ID and report its host state and available retry time. Use passive scheduler status for later observation; do not create another definition, start a competing host or reset cooldown. |
+| Create/resume saved the definition but the host is temporarily unreachable; exit `3`, pending guidance and no top-level `error` | Preserve `schedule.saved: true` and the same ID. Use passive status to observe the uncertainty. A transport failure does not establish owner death or a permanent host fault. |
+| Create/resume saved the definition and the host reports `scheduler.fault: true`; exit `1` | Report the permanent fault and available `scheduler.last_error`; retain `schedule.saved: true` and the ID. For an incompatible saved definition, the before-Ready check stops automatic child restart. Repeated create, serve or status calls are not a repair. |
+| Scheduler status observes starting, ready, backoff, degraded, stopping or stopped; exit `0` | Observation completed. Report the observed state; exit `0` does not mean ready or that an occurrence succeeded. Status does not start, migrate, repair or clean resources. |
+| Scheduler stop confirms completed stop; exit `0` | The exact stopped intent has a validated owner-written closure witness and the exact host is absent. The witness follows joined child shutdown and free execution ownership. Independently admitted tasks keep their existing lifetimes. A later host needs a fresh explicit user-run serve command. |
+| Scheduler stop has `scheduler.stop_accepted: true` but completion is pending; exit `3` | Preserve its acceptance and pending state. The host remains control-responsive while joining its child or waiting for a prior execution owner. Host death before the closure witness does not complete stop. Observe the same generation; do not claim stopped, launch a replacement or repeat schedule creation. An omitted `stop_accepted` is unknown, not false. |
+| Scheduler stop has authenticated `scheduler.stop_accepted: true` and a later readback fault; exit `1` | Preserve the accepted fact and report the concrete fault. Readback failure does not revoke acceptance or establish completed shutdown. |
+| Status reports `scheduler.state: foreground`, or stop returns exit `3` with that state, `stop_accepted: false` and `next_action: stop_foreground_runtime` | The current compatibility `scheduler run` owns this generation; an older managed-host receipt cannot hide it. Public stop does not terminate it. Have the user end that invocation with Ctrl-C in its original pane. Prefer managed `scheduler serve` afterward. |
+| Invalid input/state; exit `2`, or concrete operational/compatibility/cleanup fault; exit `1` | Report the error and retain any saved ID or accepted-control fact. A concrete fault joined to pending work remains a fault; it is not a pending-only result. |
+
+If the host dies, its pane closes or the machine reboots, the user must start
+serve again. Child crash recovery applies only while that host remains alive.
+An absent heartbeat or unresponsive endpoint is uncertainty, not permission to
+replace an owner. Do not install a service or invoke a detached bootstrap as a
+recovery step. Pause/delete affect future claims and need no live host; they do
+not cancel already admitted occurrences. [Scheduler runtime](command-reference.md#scheduler-runtime)
+owns launch, backoff and calendar behavior.
+
 ## Scheduled execution results
 
 Use [schedule history and execution](command-reference.md#schedule-history-and-execution)