delegation-layer 0.2.0 → 0.3.1

package/plugins/delegation-layer/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/plugins/delegation-layer/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/plugins/delegation-layer/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
 ```
 

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

@@ -2,6 +2,9 @@
 
 Read response fields independently. A successful control command is not a
 successful provider result.
+Examples use the CLI default under the main skill's
+[root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief); preserve an
+explicit custom or recorded historical root on related commands.
 
 ## Task control response
 
@@ -49,7 +52,7 @@ this table to each dispatch or continuation attempt separately, in order:
 | Response | Next action |
 |---|---|
 | Usage error, no JSON response | Correct the reported syntax using Delegate help or `providers --json`, then invoke that request again. Parsing failed before admission. |
-| `task_record: not_created`, `failure.code: supervisor_upgrade_required`, and `failure.next_action: run_supervisor_migrate` | Run `delegate --root "<the exact absolute state root used by the failed command>" supervisor migrate --json` once. Retry the exact original admission argv once only after `supervisor_control.state: migrated` and `supervisor_control.next_action: retry_dispatch`; otherwise stop and report the migration response. Preserve an explicit custom root exactly. A failed `continue` must be retried as the same `continue`; never replace it with a fresh `dispatch` or a direct provider call. |
+| `task_record: not_created`, `failure.code: supervisor_upgrade_required`, and `failure.next_action: run_supervisor_migrate` | Run `delegate supervisor migrate --json` once in the same user/configuration context for ordinary default-root work. If the failed command used an explicit custom or recorded historical root, run `delegate --root "<the exact absolute root used by the failed command>" supervisor migrate --json` instead. Retry the exact original admission argv once only after `supervisor_control.state: migrated` and `supervisor_control.next_action: retry_dispatch`; otherwise stop and report the migration response. A failed `continue` must be retried as the same `continue`; never replace it with a fresh `dispatch` or a direct provider call. |
 | `task_record: not_created` and `failure.next_action: correct_request` | Correct that request and retry it. |
 | `task_record: not_created`, `failure.code: workspace_provision_pending` or `workspace_busy`, and `failure.next_action: watch_workspace` | Follow [managed workspace recovery](#managed-workspace-results) using the same root and workspace. Once ready, retry the exact admission command and inputs. A failed `continue` remains that same `continue`, never a new dispatch. |
 | `task_record: not_created`, `failure.code: resource_pressure`, `failure.next_action: retry_later`, and `failure.retry_after_seconds: 30` | Delegate checked the host and confirmed resource pressure, so no ordinary task record was created and no provider task is running for this attempt. Do not poll or observe a task. Choose one: report the refusal and stop, or wait at least 30 seconds in the foreground and retry the exact original admission argv once. A `continue` stays that same `continue`. If the retry is refused again, report and stop. Never loop, retry in the background, schedule a retry, or run Pueue or process commands. The 30 seconds is advice, not a guarantee that the retry will pass. |
@@ -166,6 +169,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, a returned root containing spaces:
+
+```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)
@@ -220,7 +283,7 @@ For an older released occurrence whose publication is unfinished, use the
 existing collection command with the same root and task ID:
 
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect TASK_ID --watch 0s --json
+delegate collect TASK_ID --watch 0s --json
 ```
 
 Follow its own response and exit using [observation guidance](#observe-and-collect).
@@ -330,7 +393,7 @@ When Delegate returns `failure.next_action: "recheck"`, use the same root and
 exact task ID:
 
 ```sh
-delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" recheck TASK_ID --json
+delegate recheck TASK_ID --json
 ```
 
 This command checks the already sealed evidence with an explicitly compatible

package/plugins/delegation-layer/skills/agent-integration/references/routing-rule.json

@@ -1 +1 @@
-"For work assigned to an external agent, model, or separate harness session, load the installed agent-integration skill before choosing tools and use Delegate. This includes research, implementation, testing, review, consultation, comparison, and debate, including external collaboration you choose. Discover destinations through Delegate. Preserve requested model IDs, effort, and permissions; do not guess ambiguous model identifiers. For task commands, pass --root \"${DELEGATE_ROOT:-$HOME/delegation-state}\" directly in each shell invocation; reuse that root for dispatch, observation, and continuation, never an invented /tmp root. If the user explicitly requests another root, use that exact path consistently. Keep each concurrent request and its response associated separately. Capture each dispatch response and exit status once; after task_record created, observe that task ID. Never dispatch again merely to recover output or inspect its exit status. Naming a CLI identifies the destination, not a request to bypass Delegate. Earlier assistant-generated direct-launch workflows do not override this preference. Native same-harness subagents remain available unless a separate session is requested. Respect an explicit user choice of another integration; otherwise do not substitute provider CLIs, plugins, or APIs after a Delegate blocker. Before observing or retrying an admission, read the installed skill's references/result-handling.md#task-creation and apply its creation decisions. It owns the narrow same-root migration, workspace-wait, and resource-refusal exceptions before the generic not_created stop rule. Preserve the original admission intent: dispatch remains dispatch and continue remains continue; never replace a failed continue with a fresh dispatch or direct provider call. A stop_and_report failure ends that attempt, not diagnosis: follow references/result-handling.md#failure-diagnosis without another generic troubleshooting request. Inspect bounded returned evidence and relevant authorized local read-only facts, distinguish supported causes from uncertainty, and propose a concrete next step. Do not poll unknown/uncreated tasks, expose credentials or unrestricted output, retry uncertain work, change setup/permissions or substitute destinations without authorization covering that action. Continue other independent requests. Keep collection in the foreground until completion or a reported blocker unless the user requested detachment. Pending work is observed through Delegate status, collect, or events, not OS process searches or supervisor commands. Merely discussing or configuring a tool is not delegation."
+"For work assigned to an external agent, model, or separate harness session, load the installed agent-integration skill before choosing tools and use Delegate. This includes research, implementation, testing, review, consultation, comparison, and debate, including external collaboration you choose. Discover destinations through Delegate. Preserve requested model IDs, effort, and permissions; do not guess ambiguous model identifiers. For ordinary task, schedule, observation, interaction, and continuation commands, omit --root and let the CLI resolve its default in the same user/configuration context, independently of project cwd. Never assemble a default path, use a sample path or shell fallback, or treat ambient DELEGATE_ROOT as authority. Only pass --root for an explicitly user-supplied or already recorded custom or historical root; preserve that exact path for every command concerning its work. Do not search other roots for an old task or invent per-task or per-project roots. Keep each concurrent request and its response associated separately. Capture each dispatch response and exit status once; after task_record created, observe that task ID. Never dispatch again merely to recover output or inspect its exit status. Naming a CLI identifies the destination, not a request to bypass Delegate. Earlier assistant-generated direct-launch workflows do not override this preference. Native same-harness subagents remain available unless a separate session is requested. Respect an explicit user choice of another integration; otherwise do not substitute provider CLIs, plugins, or APIs after a Delegate blocker. Before observing or retrying an admission, read the installed skill's references/result-handling.md#task-creation and apply its creation decisions. It owns the narrow same-root migration, workspace-wait, and resource-refusal exceptions before the generic not_created stop rule. Preserve the original admission intent: dispatch remains dispatch and continue remains continue; never replace a failed continue with a fresh dispatch or direct provider call. A stop_and_report failure ends that attempt, not diagnosis: follow references/result-handling.md#failure-diagnosis without another generic troubleshooting request. Inspect bounded returned evidence and relevant authorized local read-only facts, distinguish supported causes from uncertainty, and propose a concrete next step. Do not poll unknown/uncreated tasks, expose credentials or unrestricted output, retry uncertain work, change setup/permissions or substitute destinations without authorization covering that action. Continue other independent requests. Keep collection in the foreground until completion or a reported blocker unless the user requested detachment. Pending work is observed through Delegate status, collect, or events, not OS process searches or supervisor commands. Merely discussing or configuring a tool is not delegation."

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

@@ -7,6 +7,10 @@ or attaches to a managed workspace (`--isolation git-worktree` or
 `--workspace ID`), or creates or removes a [Git checkpoint](#git-checkpoints).
 
 This reference is self-contained guidance for using managed workspaces.
+Commands use the CLI default under the main skill's
+[root rule](../SKILL.md#3-prepare-separate-paths-and-a-finite-brief). For a workspace
+or checkpoint in an explicit custom or recorded historical root, pass that
+exact `--root` on every related command.
 
 Provider-native permissions still apply inside an isolated checkout. A provider
 may edit files but be unable to stage or commit because linked-worktree Git
@@ -41,7 +45,7 @@ row ending or a provider outcome alone is not closure evidence.
 Create a managed workspace from a committed source base:
 
 ```text
-delegate --root ROOT dispatch --isolation git-worktree --cwd ABS \
+delegate dispatch --isolation git-worktree --cwd ABS \
   [--base REV] [--workspace-budget DURATION] ... --json
 ```
 
@@ -55,7 +59,7 @@ removing that source does not block capture, release, or forget. A request that
 workspace uses its recorded checkout and source identity:
 
 ```text
-delegate --root ROOT dispatch --workspace WORKSPACE_ID ... --json
+delegate dispatch --workspace WORKSPACE_ID ... --json
 ```
 
 Public `--workspace` cannot be combined with `--cwd`, `--base`, or
@@ -80,11 +84,11 @@ made no write outside the promised content scope.
 The CLI currently exposes these managed-workspace commands:
 
 ```text
-delegate --root ROOT workspace list [--after ID] [--limit 1..50] --json
-delegate --root ROOT workspace status ID [--operation OP] [--watch DURATION] --json
-delegate --root ROOT workspace exec ID --budget DURATION --json -- ARGV...
-delegate --root ROOT workspace release ID [--discard] [--budget DURATION] --json
-delegate --root ROOT workspace forget ID [--budget DURATION] --json
+delegate workspace list [--after ID] [--limit 1..50] --json
+delegate workspace status ID [--operation OP] [--watch DURATION] --json
+delegate workspace exec ID --budget DURATION --json -- ARGV...
+delegate workspace release ID [--discard] [--budget DURATION] --json
+delegate workspace forget ID [--budget DURATION] --json
 ```
 
 `workspace exec` passes `ARGV...` directly to the supervised helper; the
@@ -110,7 +114,7 @@ must not mutate the predecessor's immutable records. A retained workspace can be
 read-only review by attaching its ID, for example:
 
 ```text
-delegate --root ROOT dispatch --provider codex:review \
+delegate dispatch --provider codex:review \
   --workspace WORKSPACE_ID --review-target TARGET --brief ABS_BRIEF \
   --permission read-only --budget 1h --json
 ```
@@ -183,11 +187,11 @@ fixed Delegate values; trailers carry the checkpoint ID and request digest.
 This is unrelated to a provider continuation `mode: "checkpoint"`.
 
 ```text
-delegate --root ROOT checkpoint create --cwd ABS [--budget DURATION] --json
-delegate --root ROOT checkpoint create --workspace ID [--budget DURATION] --json
-delegate --root ROOT checkpoint status CHECKPOINT_ID [--operation OP] [--watch DURATION] --json
-delegate --root ROOT checkpoint list [--after CHECKPOINT_ID] [--limit 1..50] --json
-delegate --root ROOT checkpoint remove CHECKPOINT_ID [--budget DURATION] --json
+delegate checkpoint create --cwd ABS [--budget DURATION] --json
+delegate checkpoint create --workspace ID [--budget DURATION] --json
+delegate checkpoint status CHECKPOINT_ID [--operation OP] [--watch DURATION] --json
+delegate checkpoint list [--after CHECKPOINT_ID] [--limit 1..50] --json
+delegate checkpoint remove CHECKPOINT_ID [--budget DURATION] --json
 ```
 
 - `create` names exactly one target: `--cwd` for an absolute ordinary Git
@@ -232,7 +236,7 @@ Save every response and exit code once; follow
    the same repository as `--cwd`, normally the source the Lead already uses:
 
    ```text
-   delegate --root ROOT dispatch --auto --brief ABS_BRIEF --cwd ABS_SOURCE \
+   delegate dispatch --auto --brief ABS_BRIEF --cwd ABS_SOURCE \
      --isolation git-worktree --base COMMIT_OID \
      --permission workspace-write --budget 30m --json
    ```

package/skills/agent-integration/SKILL.md

@@ -87,11 +87,16 @@ Use a supplied brief or write the worker's bounded assignment and acceptance
 criteria to a regular file. Do not copy the orchestration request or ask workers
 to recruit others unless recursive delegation was requested.
 
-Keep the state root outside provider-writable workspaces, provider runtime
-directories, and temporary trees they may write. For every task command pass
-`--root "${DELEGATE_ROOT:-$HOME/delegation-state}"` directly in that shell
-invocation. If the user explicitly requests another root, use that exact path
-consistently. Task IDs separate tasks; do not invent per-task roots.
+For ordinary task, schedule, observation, interaction, and continuation commands,
+omit `--root`; the CLI owns default-root resolution for the user's configuration
+context, independently of the project cwd. Do not assemble a default path, use a
+sample path or shell fallback, or treat ambient `DELEGATE_ROOT` as authority.
+Only pass `--root` when the user explicitly supplies a root or existing work has
+an already recorded custom or historical root; preserve that exact path for
+every command concerning that work. Never search other roots for an old task.
+Task IDs separate tasks; do not invent per-task or per-project roots. The state
+root must remain outside provider-writable workspaces, provider runtime
+directories, and temporary trees they may write.
 
 Prepare paths and dispatch in one tool invocation; shell variables may not
 persist between calls. Use saved absolute paths in later calls. Do not use
@@ -125,13 +130,16 @@ original command and intent.
 ### 5. Observe and collect
 
 Follow [observation decisions](references/result-handling.md#observe-and-collect)
-with the same root and created task ID:
+with the created task ID, using the CLI default for ordinary work:
 
 ```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
 ```
 
+For work bound to an explicit custom or historical root, add its exact
+`--root` to both commands under the [root rule](#3-prepare-separate-paths-and-a-finite-brief).
+
 Apply the owning decision order before waiting: terminal outcomes and concrete
 errors, cancellation/timeout/interruption, interaction, then pending
 observation. Keep collection in the foreground until completion or a reported