delegation-layer 0.2.0 → 0.3.1

package/skills/agent-integration/evals/evals.json

@@ -10,7 +10,7 @@
     {
       "name": "normal-dispatch",
       "prompt": "Run one bounded task through the available agent provider.",
-      "expected": ["dispatch --auto", "--json", "save task_id", "status", "collect"]
+      "expected": ["dispatch --auto", "omit --root on ordinary commands", "--json", "save task_id", "status", "collect"]
     },
     {
       "name": "model-discovery-when-needed",
@@ -68,9 +68,29 @@
       "expected": ["use status with returned task_id", "read saved dispatch response if needed", "do not dispatch again to print an exit code", "exactly one admitted task for the assignment"]
     },
     {
-      "name": "supplied-root-across-shell-calls",
+      "name": "ambient-root-ignored-across-shell-calls",
       "prompt": "DELEGATE_ROOT is already set. Consult a separate external agent and answer its questions; each shell tool call starts a new shell.",
-      "expected": ["use supplied DELEGATE_ROOT on dispatch, status, collect, reply, steer, and continue", "resolve the same root in each shell call", "no invented task-specific root"]
+      "expected": ["omit --root on dispatch, status, collect, reply, steer, and continue", "ambient DELEGATE_ROOT has no root-selection authority", "CLI resolves its default in the same user/configuration context", "no assembled default, shell fallback, sample path, or per-task root"]
+    },
+    {
+      "name": "ordinary-root-from-another-project",
+      "prompt": "DELEGATE_ROOT is unset. An admitted task was dispatched without --root in project A. Observe and continue it from project B in the same user/configuration context.",
+      "expected": ["omit --root on status, collect, and continue", "use the recorded task ID", "CLI default is independent of project cwd", "no path guessed from project A or B", "no search across roots"]
+    },
+    {
+      "name": "explicit-root-across-shell-calls",
+      "prompt": "For this isolated test, I explicitly choose the state root /state/custom with spaces. Consult a separate external agent and answer its questions; each shell tool call starts a new shell.",
+      "expected": ["pass --root with the exact single argument /state/custom with spaces on dispatch, status, collect, reply, steer, and continue", "quote the root in shell commands", "save and reassign absolute brief and response paths in each needed shell invocation", "no ambient variable or fallback overrides the explicit choice"]
+    },
+    {
+      "name": "historical-root-continuation",
+      "prompt": "An eligible predecessor task has recorded historical root /state/legacy with spaces. Continue that exact task and collect its successor. The current CLI default is different.",
+      "expected": ["pass the exact recorded --root argument /state/legacy with spaces on continue, status, and collect", "use the exact predecessor and returned successor IDs", "no fresh dispatch", "do not move or search for the task in the default root"]
+    },
+    {
+      "name": "ordinary-schedule-root",
+      "prompt": "Create a recurring task in this project, then inspect its definition, history, and execution from another project in the same user/configuration context. No custom state root was requested.",
+      "expected": ["omit --root on schedule create, list, show, history, and execution", "keep the definition's own project --cwd", "no per-project root", "do not start a persistent scheduler inside the agent task", "forward any returned scheduler.serve_command argv intact"]
     },
     {
       "name": "pending-without-questions",

package/skills/agent-integration/examples/json-results.md

@@ -1,8 +1,11 @@
 # JSON decision sketch
 
+Use the created task's exact ID as `TASK_ID` and follow the main skill's
+[root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief).
+
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" status "$TASK_ID" --json
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect "$TASK_ID" --watch 5s --json
+delegate status TASK_ID --json
+delegate collect TASK_ID --watch 5s --json
 ```
 
 Apply [result handling](../references/result-handling.md) to each response and

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

@@ -3,14 +3,18 @@
 Use this example for independent write work that should be isolated in a
 retained Git worktree. The source must be a Git checkout and the state root
 must remain outside provider-writable workspaces.
+Commands use the CLI default under the main skill's
+[root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief); preserve any
+explicit custom or recorded historical root on all related commands.
 
 ```sh
 SOURCE="$PWD"
-BRIEF="$(mktemp)"
-RESPONSE="$(mktemp)"
+BRIEF="$(mktemp)" || exit 1
+RESPONSE="$(mktemp)" || exit 1
 printf '%s\n' 'Implement the requested change and report the files changed.' >"$BRIEF"
+printf 'Saved response: %s\n' "$RESPONSE"
 
-if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --auto \
+if delegate dispatch --auto \
   --brief "$BRIEF" --cwd "$SOURCE" \
   --permission workspace-write --isolation git-worktree \
   --base HEAD --workspace-budget 5m --budget 30m --json >"$RESPONSE"; then
@@ -26,28 +30,51 @@ Read the saved JSON before running another command. When
 `task_record: "created"`, use its `task_id` as `TASK_ID` below. When no task
 was created, follow the [result decisions](../references/result-handling.md#managed-workspace-results);
 do not run task status or collection against that nonexistent record.
+Each later block is a separate shell invocation. Replace `ABS_SAVED_RESPONSE`
+with the printed absolute response path and the ID placeholders with the actual
+returned IDs; reassign the path in each invocation.
 
 ```sh
-if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" status TASK_ID --json >"$RESPONSE.status"; then
+RESPONSE="ABS_SAVED_RESPONSE"
+if delegate status TASK_ID --json >"$RESPONSE.status"; then
   status_exit=0
 else
   status_exit=$?
 fi
 printf '%s\n' "$status_exit" >"$RESPONSE.status.exit"
-if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect TASK_ID --watch 5s --json >"$RESPONSE.collect"; then
+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
+RESPONSE="ABS_SAVED_RESPONSE"
+if delegate 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 \
+RESPONSE="ABS_SAVED_RESPONSE"
+if delegate workspace release WORKSPACE_ID \
   --budget 5m --json >"$RESPONSE.release"; then
   release_exit=0
 else
@@ -62,10 +89,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
 
@@ -77,8 +105,9 @@ owns every response decision.
 
 ```sh
 SOURCE="$PWD"
-RESPONSE="$(mktemp)"
-if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" checkpoint create \
+RESPONSE="$(mktemp)" || exit 1
+printf 'Saved response: %s\n' "$RESPONSE"
+if delegate checkpoint create \
   --cwd "$SOURCE" --budget 5m --json >"$RESPONSE.checkpoint"; then
   checkpoint_exit=0
 else
@@ -91,9 +120,12 @@ cat "$RESPONSE.checkpoint"
 Exit `3` with `checkpoint.id` and `next_action: "watch_checkpoint"` means the
 request was accepted, not captured. Use that `checkpoint.id` as
 `CHECKPOINT_ID`. Do not run `create` again.
+For the later checkpoint blocks, replace `ABS_SAVED_RESPONSE` with the absolute
+response path printed by this checkpoint invocation.
 
 ```sh
-if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" checkpoint status CHECKPOINT_ID \
+RESPONSE="ABS_SAVED_RESPONSE"
+if delegate checkpoint status CHECKPOINT_ID \
   --watch 30s --json >"$RESPONSE.checkpoint.status"; then
   checkpoint_status_exit=0
 else
@@ -112,7 +144,8 @@ dispatch example, replacing `--base HEAD` with `--base COMMIT_OID`. Report a
 When the Lead no longer needs the checkpoint, remove it explicitly:
 
 ```sh
-if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" checkpoint remove CHECKPOINT_ID \
+RESPONSE="ABS_SAVED_RESPONSE"
+if delegate checkpoint remove CHECKPOINT_ID \
   --budget 5m --json >"$RESPONSE.checkpoint.remove"; then
   checkpoint_remove_exit=0
 else

package/skills/agent-integration/examples/read-only-task.md

@@ -2,6 +2,8 @@
 
 Run from the intended workspace, outside Delegate's private state root.
 Use a catalog provider ID in place of `--auto` when a destination was named.
+This example uses the CLI default under the main skill's
+[root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief).
 Prepare paths and dispatch in this same shell invocation:
 
 ```sh
@@ -13,7 +15,7 @@ Inspect the workspace and summarize the current test failures. Do not edit files
 You are the assigned worker; perform this task without delegating it.
 EOF
 printf 'Saved response: %s\n' "$RESPONSE"
-if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --auto \
+if delegate dispatch --auto \
   --brief "$BRIEF" --cwd "$WORKSPACE" \
   --permission read-only --budget 30m --json >"$RESPONSE"; then
   dispatch_exit=0

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

@@ -3,6 +3,9 @@
 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.
+Use the CLI default under the main skill's
+[root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief); preserve any
+explicit custom or recorded historical root 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
@@ -12,9 +15,10 @@ CCR runs Claude Code against a configured third-party or local provider.
    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
+   `--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/collaboration.md

@@ -45,7 +45,7 @@ RECEIPTS="$(mktemp -d)" || exit 1
 # Set these absolute paths and catalog IDs in this same tool invocation.
 # BRIEF_A and BRIEF_B contain the real independent assignments.
 (
-  if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_A" \
+  if delegate dispatch --provider "$PROVIDER_A" \
     --brief "$BRIEF_A" --cwd "$WORKSPACE_A" \
     --permission read-only --budget 30m --json \
     >"$RECEIPTS/review-a.json" 2>"$RECEIPTS/review-a.stderr"; then
@@ -56,7 +56,7 @@ RECEIPTS="$(mktemp -d)" || exit 1
   printf '%s\n' "$dispatch_exit" >"$RECEIPTS/review-a.exit"
 ) &
 (
-  if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_B" \
+  if delegate dispatch --provider "$PROVIDER_B" \
     --brief "$BRIEF_B" --cwd "$WORKSPACE_B" \
     --permission read-only --budget 30m --json \
     >"$RECEIPTS/review-b.json" 2>"$RECEIPTS/review-b.stderr"; then

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

@@ -22,15 +22,17 @@ 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.
+The commands below use the CLI default and omit `--root`. The advanced override
+syntax is `delegate --root ABS COMMAND ...`; use it only for an explicitly
+supplied or already recorded custom or historical root, preserved exactly under
+the main skill's [root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief).
 
 ## Dispatch
 
 ```text
-delegate --root ROOT dispatch [--auto | --provider ID] --brief FILE \
+delegate dispatch [--auto | --provider ID] --brief FILE \
   --cwd ABS [--id TASK_ID] [--permission MODE] [--budget DURATION] \
   [--model MODEL] [--effort EFFORT] [--native-timeout DURATION] \
   [--interactive] [--review-target TARGET] [--resume-task TASK_ID] \
@@ -170,8 +172,8 @@ setup, even when there is no matching Team or project default.
 After a task record is created, inspect the same ID and root:
 
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" status TASK_ID --json
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect TASK_ID --watch 5s --json
+delegate status TASK_ID --json
+delegate collect TASK_ID --watch 5s --json
 ```
 
 Dispatch/status/collect optionally expose top-level `team`, the admitted
@@ -186,23 +188,30 @@ 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 \
+delegate schedule create --brief FILE --cwd ABS \
   [--auto | --provider ID] --cron 'MIN HOUR DOM MONTH DOW' \
   [--timezone ZONE] [--id SCHEDULE_ID] [--model MODEL] [--effort EFFORT] \
   [--permission MODE] [--budget DURATION] [--native-timeout DURATION] \
   [--review-target TARGET] \
   [--team-scope user|project --team TEAM_ID --member MEMBER_ID] \
   [--project-root ABS] --json
-delegate --root ROOT schedule list [--after SCHEDULE_ID] [--limit N] --json
-delegate --root ROOT schedule show SCHEDULE_ID --json
-delegate --root ROOT schedule pause SCHEDULE_ID --json
-delegate --root ROOT schedule resume SCHEDULE_ID --json
-delegate --root ROOT schedule delete SCHEDULE_ID --json
+delegate schedule list [--after SCHEDULE_ID] [--limit N] --json
+delegate schedule show SCHEDULE_ID --json
+delegate schedule pause SCHEDULE_ID --json
+delegate schedule resume SCHEDULE_ID --json
+delegate schedule delete SCHEDULE_ID --json
 ```
 
 - Requested provider options remain as supplied, including omissions. Creation
@@ -235,17 +244,23 @@ 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.
-- 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.
+  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.
+- Among schedule management commands, only create initializes absent 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.
 - Create/state responses are compact. Show returns saved requested choices and
   brief metadata, not brief contents, with a 2 MiB response limit. Keep the ID
   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.
@@ -253,8 +268,8 @@ timestamp range has a distinct range error, not a claim of permanent invalidity.
 ### Schedule history and execution
 
 ```text
-delegate --root ROOT schedule history SCHEDULE_ID [--before RFC3339Nano] [--limit N] --json
-delegate --root ROOT schedule execution TASK_ID --json
+delegate schedule history SCHEDULE_ID [--before RFC3339Nano] [--limit N] --json
+delegate schedule execution TASK_ID --json
 ```
 
 `history` returns occurrence summaries and compact skipped intervals together,
@@ -282,31 +297,121 @@ 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. They use
+the same CLI default as ordinary schedule commands; preserve an explicit custom
+or historical root when the schedule is bound to one.
+
 ```text
-delegate --root ROOT scheduler run [--pueue-config ABS] [--json]
+delegate scheduler serve
+delegate scheduler status
+delegate scheduler stop
+delegate 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 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).
+
+Explicit `serve` may initialize absent scheduler storage through the same
+scheduler owner lease used by `schedule create`. It can become ready with no
+definitions; later creates reach that running host without a restart. Existing
+root identity and data stay in place; invalid existing storage fails explicitly.
+Passive reads and low-level `run` do not initialize absent storage. 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 +422,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
@@ -355,8 +460,8 @@ A checkpoint is Git-content evidence, not a provider outcome.
 ## Providers and capabilities
 
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" providers --json
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" capabilities --provider PROVIDER_ID --json
+delegate providers --json
+delegate capabilities --provider PROVIDER_ID --json
 ```
 
 `providers` returns `schema_version: 1` and a sorted `providers` array.
@@ -393,7 +498,7 @@ them. Keep defaults when no explicit choice is needed. Resolve a natural-languag
 name through native discovery:
 
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" models \
+delegate models \
   --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
 ```
 
@@ -436,7 +541,7 @@ reason codes and return no model facts.
 Use static preflight when readiness was requested, not before every task:
 
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" preflight \
+delegate preflight \
   --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
   --permission REQUESTED_MODE --json
 ```

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

@@ -22,7 +22,7 @@ When `status` or `collect` reports a timed-out turn with:
 run:
 
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" continue \
+delegate continue \
   --task PREDECESSOR_TASK_ID \
   --brief FOLLOW_UP_BRIEF \
   --budget 30m \
@@ -35,8 +35,11 @@ indefinitely for a publication that the interrupted turn cannot complete.
 
 The follow-up brief is optional. If it is omitted, Delegation Layer reuses the
 validated predecessor brief. A successful continuation returns a new task ID
-and links it to the predecessor. Observe and collect the new ID separately. Always retain the original state
-root, even if a returned command hint omits it. Permission is inherited; do not
+and links it to the predecessor. Observe and collect the new ID separately.
+Follow the main skill's [root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief):
+ordinary continuation omits `--root` in the same user/configuration context;
+an explicit custom or recorded historical root must be retained exactly, even
+if a returned command hint omits it. Permission is inherited; do not
 add `--permission` to `continue`. Apply
 [task creation](result-handling.md#task-creation) before retrying or observing.
 Any authorized admission retry remains the argv-equivalent `continue`;
@@ -85,7 +88,7 @@ observe that successor instead; if its creation is uncertain, follow the
    `workspace.id` from the task response; never guess an ID or path:
 
    ```sh
-   delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" workspace status \
+   delegate workspace status \
      WORKSPACE_ID --watch 30s --json
    ```
 

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

@@ -62,7 +62,7 @@ question. A printed question alone is not a pending reply request.
    together with the exact answers. Submit the reply:
 
    ```sh
-   delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" reply "$task_id" \
+   delegate reply "$task_id" \
      --request "$request_id" --answers "$answers_file" \
      --id "$message_id" --json
    ```
@@ -70,9 +70,10 @@ question. A printed question alone is not a pending reply request.
 6. Keep collecting. A receipt is not task completion. Only the task's
    authoritative `outcome` establishes the final result.
 
-Use the same root expression for dispatch, collection, reply, and steering.
-If the user explicitly chose another root, use that exact path for all of
-them. The other variables stand for actual values saved from this task;
+Follow the main skill's [root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief)
+for dispatch, collection, reply, and steering. The examples use the CLI default;
+preserve an explicit custom or recorded historical root for all of them.
+The variables stand for actual values saved from this task;
 reassign them in each shell invocation if your tool does not preserve variables.
 A pending response without questions means keep collecting, not inspect OS
 processes or dispatch a replacement task.
@@ -86,7 +87,7 @@ reply IDs and earlier steering IDs. Submit it; for a lost response, follow the
 [delivery rules](#interpret-delivery-precisely) with the same ID and content:
 
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" steer "$task_id" \
+delegate steer "$task_id" \
   --brief "$guidance_file" --id "$steering_message_id" --json
 ```