delegate-agent-cli 0.27.0__tar.gz → 0.29.0__tar.gz

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/CHANGELOG.md

@@ -5,7 +5,100 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.29.0] - 2026-08-11
+
+### Added
+
+- `delegate runs` and `delegate ps` now report listing honesty: the JSON
+  payload gains `total` (pre-limit match count) and `truncated`, text mode
+  prints `showing N of M runs (raise --limit to see more)`, and a zero-row
+  result under `--group`/`--harness` explains itself — naming the status
+  filter to drop when `--running`/`--stale`/`--active` emptied the result, or
+  noting the run Registry is workspace-scoped otherwise.
+- Retained event text now carries truncation metadata on both surfaces: raw
+  `events.jsonl` `stream.line` records and normalized Snapshot `recentEvents`
+  add `truncated: true` plus `textChars` (original length) only when the
+  500-character bound actually clipped, and the final unterminated child
+  stdout line is now written to `events.jsonl` instead of silently dropped.
+  All child-controlled normalized-event strings (including tool targets,
+  `error`, and `run.completed`) are bounded through the same helper.
+- The tracked launcher shim template (`bin/delegate-profile-shim`) passes
+  through the read-only workflow actions
+  (`check|status|watch|events|result|wait|list`) without a selected profile,
+  mirroring the Python CLI's guard; a parity test fails on drift.
+- Tracked Cursor completion JSON now includes the CLI-reported token `usage`
+  object when present.
+
+### Changed
+
+- Devin model discovery now uses the prompt-free, fingerprinted
+  `devin models list --format json` catalog for setup, capability refresh, and
+  one-off live queries. Older or unauthenticated CLIs degrade to a version-only
+  record instead of receiving a prompt-like invalid-model probe.
+- Child-launch failures with `EPERM` now hint that sandboxed parent shells can
+  forbid launching harness binaries; `prompt_too_large` names the engines
+  whose prompt rides a file/stdin transport, derived from the transport table.
+- The test suite hardens hermeticity against ambient delegate-lane
+  environment (`DELEGATE_RUN_ID`, mail identity, root-provenance and profile
+  variables), and the documented discovery command is
+  `python3 -m unittest discover -s tests -t .` everywhere, including CI and
+  the contributor wiki.
+- CI and publishing now use the official Node 24 GitHub Action releases, and
+  the public publishing checklist builds exported source in isolated temporary
+  environments instead of modifying the maintainer's ambient Python install.
+
+### Fixed
+
+- An explicit `DELEGATE_CONFIG` now survives profile selection: the profile
+  shim and profile env resolution load the selected profile's credentials but
+  keep the incoming `DELEGATE_CONFIG` as the runtime-policy config instead of
+  replacing it, and codex quota fallback no longer forwards `DELEGATE_CONFIG`
+  into the fallback child environment.
+- Tracked runs now stop after an explicit harness terminal event and fail closed
+  when either raw output stream exceeds 16 MiB, preventing a completed or
+  runaway child from filling disk with cumulative stream payloads.
+- Tracked stream decoding preserves UTF-8 characters split across read chunks;
+  normalized events retain a bounded head/tail with an exact total, and raw
+  `events.jsonl` mirrors at most 500 stdout lines plus a truncation marker so
+  many short lines cannot amplify a bounded child stream into an unbounded
+  event journal or in-memory event list.
+- Tracked Cursor retries now report cumulative token usage, transient Devin
+  catalog failures retain the last-known-good catalog, and Devin help no longer
+  advertises unsupported reasoning effort.
+- Slow raw-log archival no longer holds the Registry mutation lock, concurrent
+  ambient retention passes skip instead of waiting, and transient Registry-lock
+  contention can no longer crash a tracked run's stdout drain thread.
+
+## [0.28.0] - 2026-08-05
+
+### Added
+
+- Added `delegate runs --structural` and `delegate ps --structural` for
+  content-free local status collection, including lifecycle, model, group,
+  status, timestamp, and root initiator provenance.
+- Tracked runs now retain a validated root initiator across nested Delegate
+  launches and persistent-worktree execution.
+
+### Changed
+
+- Codex quota fallback is now explicitly configured with
+  `codex.fallbackProfile`, supports arbitrary profile definitions, and keeps
+  temporary blocks by resolved credential identity rather than profile alias.
+  Default work/personal credential homes continue to interoperate with legacy
+  profile launchers without allowing remapped aliases to share state.
+- Codex-only failover no longer depends on private Claude shim names or hidden
+  runtime controls. Retry and persistent-worktree paths retain the account
+  that is actually serving the run.
+
+### Fixed
+
+- Structural run listings now exclude raw terminal/provider events and apply
+  normal secret redaction to retained fields.
+- Fallback failures persist the correct account block and provider-reported
+  reset time; a blocked fallback is skipped, and retries no longer return to a
+  blocked primary after a preflight swap.
+- Failover tests isolate their state from the user's home directory, and
+  `delegate ps --help` now advertises its supported structural view.
 
 ## [0.27.0] - 2026-08-01
 
@@ -888,6 +981,8 @@ Usage-audit fix wave: 82 sessions and 1,241 delegate invocations from one week o
 
 - Releases before 0.1.3 predate this changelog.
 
+[0.29.0]: https://github.com/treygoff24/delegate-agent/compare/v0.28.0...v0.29.0
+[0.28.0]: https://github.com/treygoff24/delegate-agent/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/treygoff24/delegate-agent/compare/v0.26.0...v0.27.0
 [0.26.0]: https://github.com/treygoff24/delegate-agent/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/treygoff24/delegate-agent/compare/v0.24.0...v0.25.0

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/CONTRIBUTING.md

@@ -7,9 +7,9 @@ Thanks for your interest in Delegate Agent. The project is early, so small, well
 ```bash
 python3 -m venv .venv
 . .venv/bin/activate
-python -m pip install -e ".[dev]"
+python3 -m pip install -e ".[dev]"
 python3 bin/delegate.py --json describe
-python3 -m unittest discover -s tests
+python3 -m unittest discover -s tests -t .
 ```
 
 Use `python3 bin/delegate.py` from this repository when validating development changes. Do not overwrite an installed `delegate` shim, `~/.delegate/config.json`, or any live runtime unless an operator explicitly asks for promotion.
@@ -35,7 +35,7 @@ Run the narrowest useful checks for your change, then the full suite before prop
 ```bash
 python3 -m compileall -q src tests bin
 git diff --check
-python3 -m unittest discover -s tests
+python3 -m unittest discover -s tests -t .
 ruff check .
 ruff format --check .
 ```

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: delegate-agent-cli
-Version: 0.27.0
+Version: 0.29.0
 Summary: A tiny CLI for delegating bounded agent tasks across coding-agent runtimes.
 Author: Trey Goff
 License-Expression: MIT
@@ -81,7 +81,7 @@ git clone https://github.com/treygoff24/delegate-agent.git
 cd delegate-agent
 python3 -m venv .venv
 . .venv/bin/activate
-python -m pip install -e .
+python3 -m pip install -e .
 python3 bin/delegate.py --json describe
 ```
 
@@ -158,6 +158,7 @@ delegate --json describe
 delegate --json models
 delegate --json models codex          # per-engine advisory catalog
 delegate --json models cursor --live  # merge live harness probe when supported
+delegate --json models devin --live   # query Devin's prompt-free account catalog
 delegate --json models opencode --live # query every model visible to OpenCode
 delegate --json models pi --live       # query every model visible to Pi
 delegate --json models omp --live      # query every model visible to Oh My Pi
@@ -167,6 +168,8 @@ delegate --json capabilities refresh   # refresh the active profile's discovery
 
 Discover commands as you go: `delegate <command> --help` prints focused help for any command path, and `delegate --json <command> --help` returns an agent-friendly spec of its usage, arguments, and options. For launch and `dry-run` commands, `--json` and `--isolation` may also appear before inline prompt text begins, for example `delegate codex work --prompt-file task.md --json`. `delegate --json describe` includes a `commands` catalog of the whole surface. Cached `models` and `capabilities` reads launch no child process. `models <engine> --live` performs a one-off probe without updating the cache; rerun `delegate setup` or `delegate capabilities refresh` when ordinary launches should consume newly discovered models or effort levels.
 
+Codex tracked runs can opt into a one-run quota fallback with `codex.fallbackProfile`; hashed credential namespace is canonical, while default work/personal credential homes also mirror compatible legacy alias keys so existing launchers share blocks. Remapped aliases remain isolated. See [Configuration](docs/configuration.md).
+
 From this development checkout, use `python3 bin/delegate.py ...` instead of an installed `delegate` shim.
 
 ### WSL setup notes
@@ -355,6 +358,9 @@ selector explicitly. Tracked runs also carry a `resultQuality` classification
 (`ok` / `housekeeping_noop` / `empty` / `suspect_short` / `no_assistant_text`),
 and failed or cancelled runs always get a completion report — synthesized when
 the child produced none — so `--completion-report` never dead-ends.
+Each tracked raw stream is capped at 16 MiB. A child that exceeds the cap is
+terminated with `output_limit_exceeded`; a child that lingers after an explicit
+harness terminal event receives a short exit grace and is then stopped.
 
 Block on background runs instead of polling, and cancel them cleanly:
 
@@ -449,8 +455,9 @@ Delegate resolves the profile once per request and injects its env into every sp
 If `AI_PROFILE=work|personal` points at a missing profile overlay, Delegate
 blocks launch and mutation commands, but lets read-only diagnostics
 (`profiles`, `runs`, `run-output`, `snapshot`, cached `capabilities`,
-`worktree show`, `worktree list`, `describe`, `models`) continue with a
-warning. This guarantee is enforced in the Python CLI itself (`delegate_agent.cli:main`), so it holds no matter how you invoke Delegate: the
+`worktree show`, `worktree list`,
+`workflow check|status|watch|events|result|wait|list`, `describe`, `models`)
+continue with a warning. This guarantee is enforced in the Python CLI itself (`delegate_agent.cli:main`), so it holds no matter how you invoke Delegate: the
 pip console script, `python -m delegate_agent.cli`, `bin/delegate.py`, or a
 shell shim in front of any of those. The tracked launcher shim template,
 `bin/delegate-profile-shim`, applies the same check earlier, before Python

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/README.md

@@ -48,7 +48,7 @@ git clone https://github.com/treygoff24/delegate-agent.git
 cd delegate-agent
 python3 -m venv .venv
 . .venv/bin/activate
-python -m pip install -e .
+python3 -m pip install -e .
 python3 bin/delegate.py --json describe
 ```
 
@@ -125,6 +125,7 @@ delegate --json describe
 delegate --json models
 delegate --json models codex          # per-engine advisory catalog
 delegate --json models cursor --live  # merge live harness probe when supported
+delegate --json models devin --live   # query Devin's prompt-free account catalog
 delegate --json models opencode --live # query every model visible to OpenCode
 delegate --json models pi --live       # query every model visible to Pi
 delegate --json models omp --live      # query every model visible to Oh My Pi
@@ -134,6 +135,8 @@ delegate --json capabilities refresh   # refresh the active profile's discovery
 
 Discover commands as you go: `delegate <command> --help` prints focused help for any command path, and `delegate --json <command> --help` returns an agent-friendly spec of its usage, arguments, and options. For launch and `dry-run` commands, `--json` and `--isolation` may also appear before inline prompt text begins, for example `delegate codex work --prompt-file task.md --json`. `delegate --json describe` includes a `commands` catalog of the whole surface. Cached `models` and `capabilities` reads launch no child process. `models <engine> --live` performs a one-off probe without updating the cache; rerun `delegate setup` or `delegate capabilities refresh` when ordinary launches should consume newly discovered models or effort levels.
 
+Codex tracked runs can opt into a one-run quota fallback with `codex.fallbackProfile`; hashed credential namespace is canonical, while default work/personal credential homes also mirror compatible legacy alias keys so existing launchers share blocks. Remapped aliases remain isolated. See [Configuration](docs/configuration.md).
+
 From this development checkout, use `python3 bin/delegate.py ...` instead of an installed `delegate` shim.
 
 ### WSL setup notes
@@ -322,6 +325,9 @@ selector explicitly. Tracked runs also carry a `resultQuality` classification
 (`ok` / `housekeeping_noop` / `empty` / `suspect_short` / `no_assistant_text`),
 and failed or cancelled runs always get a completion report — synthesized when
 the child produced none — so `--completion-report` never dead-ends.
+Each tracked raw stream is capped at 16 MiB. A child that exceeds the cap is
+terminated with `output_limit_exceeded`; a child that lingers after an explicit
+harness terminal event receives a short exit grace and is then stopped.
 
 Block on background runs instead of polling, and cancel them cleanly:
 
@@ -416,8 +422,9 @@ Delegate resolves the profile once per request and injects its env into every sp
 If `AI_PROFILE=work|personal` points at a missing profile overlay, Delegate
 blocks launch and mutation commands, but lets read-only diagnostics
 (`profiles`, `runs`, `run-output`, `snapshot`, cached `capabilities`,
-`worktree show`, `worktree list`, `describe`, `models`) continue with a
-warning. This guarantee is enforced in the Python CLI itself (`delegate_agent.cli:main`), so it holds no matter how you invoke Delegate: the
+`worktree show`, `worktree list`,
+`workflow check|status|watch|events|result|wait|list`, `describe`, `models`)
+continue with a warning. This guarantee is enforced in the Python CLI itself (`delegate_agent.cli:main`), so it holds no matter how you invoke Delegate: the
 pip console script, `python -m delegate_agent.cli`, `bin/delegate.py`, or a
 shell shim in front of any of those. The tracked launcher shim template,
 `bin/delegate-profile-shim`, applies the same check earlier, before Python

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/bin/delegate-profile-shim

@@ -5,6 +5,7 @@
 # AI_PROFILE shells to matching ~/.delegate/config.<profile>.json files, while
 # letting known read-only diagnostics run when the profile config is missing.
 
+_delegate_incoming_config="${DELEGATE_CONFIG-}"
 _delegate_profile_config="${HOME}/.delegate/config.${AI_PROFILE:-}.json"
 
 _delegate_subcommand() {
@@ -198,6 +199,31 @@ _delegate_is_readonly_request() {
           ;;
       esac
       ;;
+    workflow)
+      # The parser consumes --json tokens before the action, so the action is
+      # the first non-option token after `workflow`; trailing flags/paths
+      # never decide classification.
+      while [ "$#" -gt 0 ]; do
+        case "$1" in
+          --json)
+            shift
+            ;;
+          *)
+            break
+            ;;
+        esac
+      done
+      # Parity with profile_guard.READ_ONLY_WORKFLOW_ACTIONS is enforced by
+      # tests; update both together.
+      case "${1:-}" in
+        check|status|watch|events|result|wait|list)
+          return 0
+          ;;
+        *)
+          return 1
+          ;;
+      esac
+      ;;
     *)
       return 1
       ;;
@@ -208,11 +234,11 @@ _delegate_profile_fix_message() {
   cat >&2 <<EOF
 delegate: AI_PROFILE=${AI_PROFILE} but ${_delegate_profile_config} is missing/unreadable; refusing to run a launch or mutation command on the wrong account.
 Fix: create the profile config from config.example.json, or run 'env -u AI_PROFILE delegate config sync-profiles' to materialize missing profile overlays.
-Temporary bypasses: 'env -u AI_PROFILE delegate ...' uses the base config (work Claude, ambient Codex), or set 'DELEGATE_CONFIG=/path/to/config.json delegate ...'.
+Temporary bypass: 'env -u AI_PROFILE delegate ...' uses the base config (work Claude, ambient Codex).
 EOF
 }
 
-if [ -z "${DELEGATE_CONFIG:-}" ] && [ -n "${AI_PROFILE:-}" ]; then
+if [ -n "${AI_PROFILE:-}" ]; then
   case "${AI_PROFILE}" in
     personal|work)
       if [ ! -r "$_delegate_profile_config" ]; then
@@ -229,6 +255,9 @@ if [ -z "${DELEGATE_CONFIG:-}" ] && [ -n "${AI_PROFILE:-}" ]; then
         # ponytail: current keys.zsh files are plain exports; switch to parsing if
         # they ever need zsh-only syntax.
         [ -f "$_delegate_keys" ] && . "$_delegate_keys"
+        if [ -n "$_delegate_incoming_config" ]; then
+          export DELEGATE_CONFIG="$_delegate_incoming_config"
+        fi
       fi
       ;;
     *)

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/docs/agent-setup.md

@@ -7,7 +7,7 @@ This guide covers both human setup and non-interactive setup for agents or CI jo
 1. Install Delegate from the source repository:
 
    ```bash
-   python3 -m pip install "delegate-agent @ git+https://github.com/treygoff24/delegate-agent.git"
+   python3 -m pip install "delegate-agent-cli @ git+https://github.com/treygoff24/delegate-agent.git"
    ```
 
    For a development checkout, prefer:
@@ -15,7 +15,7 @@ This guide covers both human setup and non-interactive setup for agents or CI jo
    ```bash
    python3 -m venv .venv
    . .venv/bin/activate
-   python -m pip install -e .
+   python3 -m pip install -e .
    python3 bin/delegate.py --json describe
    ```
 
@@ -243,7 +243,7 @@ where needed:
 
 ```bash
 python3 -m compileall -q src tests bin
-python3 -m unittest discover -s tests
+python3 -m unittest discover -s tests -t .
 ```
 
 Real runtime authentication is only required for integration smoke tests that intentionally launch a child agent.

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/docs/cli-reference.md

@@ -169,7 +169,7 @@ matches an alias key; otherwise it is passed through verbatim as a raw model ID
 both. With neither, Droid uses `droid.defaultModel` when set. Discover aliases
 and advisory catalogs with `delegate models`, `delegate models <engine>`, and
 `delegate models <engine> --live`. Every harness except Claude exposes a live
-model probe; see [Discovery](#discovery) for the evidence and Devin caveats.
+model probe; see [Discovery](#discovery) for the evidence each probe records.
 
 `--reasoning-effort LEVEL` is optional and parsed only before prompt text begins.
 Engines with exact capability metadata reject unsupported model/effort pairs
@@ -334,6 +334,39 @@ delegate grok call "Summarize this context in three bullets."
 delegate --isolation worktree grok work "Implement the feature in a persistent worktree."
 ```
 
+### `delegate devin`
+
+Wraps Devin CLI print mode. Safe mode is unsupported because Devin may perform
+filesystem surveys through its generic `exec` tool, which Delegate cannot allow
+without weakening the read-only boundary.
+
+```bash
+delegate [--json] [--isolation auto|none|worktree] devin work [--model <alias-or-model>] [--progress] [--timeout SECONDS] [--forbid-commit] [--prompt-file PATH] [prompt...]
+delegate [--json] devin call [--read-only] [--timeout SECONDS] [--model <alias-or-model>] [--prompt-file PATH] [prompt...]
+```
+
+- `call --read-only` passes a Delegate-generated `--agent-config` deny-list for
+  edit, write, exec, and `mcp__*`, plus `--permission-mode auto`. Work and
+  default call use `--permission-mode dangerous` because non-interactive Devin
+  rejects unapproved edit/exec tools.
+- Prompt text is materialized in a private temporary file and passed with
+  Devin `--prompt-file` plus `-p`; dry-run argv and tracked manifests do not
+  contain the prompt.
+- Model selection uses `--model` (an alias from `devin.models` or a raw model
+  ID), the run-input JSON `model`, or `devin.defaultModel`. Unknown names are
+  left to Devin validation. `--reasoning-effort` is unsupported.
+- Setup, capability refresh, and `models devin --live` use the prompt-free
+  `devin models list --format json` catalog. Catalog failures degrade to
+  version-only metadata without prompting Devin.
+
+Examples:
+
+```bash
+delegate devin work "Implement the scoped task; report changed files and tests."
+delegate devin call --read-only "Score this answer against the rubric."
+delegate --isolation worktree devin work "Implement the feature in a persistent worktree."
+```
+
 ### `delegate opencode`
 
 Wraps OpenCode's non-interactive `run` command.
@@ -671,7 +704,11 @@ Typical dry-run JSON fields:
 
 `isolation` is a human-readable summary combining `effectiveIsolation` and `isolationLifecycle` (e.g. `"worktree temporary"`, `"worktree persistent"`, `"none"`). Depend on the structured fields rather than parsing it. A push dry-run also includes `mailPushAdapter` with the audit status and the internal hook command; unverified harnesses include the pull-degradation warning.
 
-When a profile is active, dry-run and completion payloads add `authProfile` (the resolved profile name) and, when a Codex fallback profile is configured, `fallbackProfile`. Dry-run also adds `profileEnv` (the injected env map, with values redacted). These keys are omitted when no profile is active.
+When a profile is active, dry-run and completion payloads add `authProfile`
+(the resolved profile name). Codex dry-runs also always add `fallbackProfile`
+(the configured profile name or `null`); completion payloads add it only when
+a fallback is configured. Dry-run also adds `profileEnv` (the injected env map,
+with values redacted). Profile metadata is omitted when no profile is active.
 
 For Cursor, Claude, Grok, OpenCode, Pi, Oh My Pi, Droid, and Kimi safe mode, an explicit `--isolation none`
 is normalized to `auto` with a warning because those safe contracts depend on
@@ -849,7 +886,7 @@ Automatic setup and refresh use these evidence sources:
 | Kimi | Models in the active Kimi configuration | Provider metadata may advertise efforts, but Delegate has no Kimi effort transport and still rejects `--reasoning-effort`. |
 | Claude | No model enumeration | The native effort enum is harness-wide evidence. |
 | Grok | Models visible to the active account | Exact config, discovery, or bundled declarations win; otherwise the native effort enum is harness-wide compatibility evidence and model-specific support remains unknown. |
-| Devin | No prompt-free model enumeration | Automatic discovery records only installation/version; Delegate has no Devin effort transport. |
+| Devin | Family slugs, aliases, and concrete variants visible to the active account | The prompt-free JSON catalog carries display names; Delegate has no Devin effort transport. |
 | OpenCode | Harness catalog | Listed variants are `exact` for that model; models without exact variant evidence retain the documented unvalidated pass-through path. |
 | Pi | Harness catalog | Thinking support is model-specific, but available labels come from a harness-wide enum and are reported as partial model evidence. |
 | Oh My Pi | Harness catalog | A model's explicit `thinking` array is exact; missing arrays use harness-partial compatibility rather than fabricated model evidence. |
@@ -884,6 +921,8 @@ stale and ordinary launches ignore only that harness's record until refresh.
 Cached reads never run `--version` merely to test staleness, and neither does an
 ordinary launch: a cached record can only be short of what the harness now
 supports, never claim more, so one that satisfies the run is used as-is.
+Existing Devin version-only cache records therefore remain valid but contain no
+live catalog until `delegate capabilities refresh devin` is run.
 
 A launch re-probes `--version` for its own harness only when the cached record
 has already cost the run something: it refused an explicit `--reasoning-effort`,
@@ -909,11 +948,9 @@ policy to another. Dry runs never probe at all.
 
 All automatic probes run with `shell=False`, stdin closed, a neutral temporary
 working directory, bounded output, and a timeout. They pass the active profile
-environment but do not carry a task prompt. Devin is the explicit exception on
-the opt-in one-off surface: `models devin --live` uses a bounded invalid-model,
-prompt-like invocation to make Devin print its available-model error. Setup and
-`capabilities refresh` never use that Devin invocation; they run `--version`
-only.
+environment but do not carry a task prompt. Devin uses the same prompt-free
+`models list --format json` metadata command for setup, capability refresh, and
+`models devin --live`; failures degrade to a version-only partial record.
 
 Discovery output applies best-effort credential scrubbing, so secret-shaped
 model IDs or diagnostic values may appear as `***`. Exact values should come
@@ -1008,7 +1045,7 @@ repo copy or persistent worktree itself.
 Tracked runs return bounded parent-facing output and store local metadata under `.delegate/` in the source workspace.
 
 ```bash
-delegate runs [--active|--running|--stale|--recent] [--harness HARNESS] [--group NAME] [--limit N]
+delegate runs [--active|--running|--stale|--recent] [--harness HARNESS] [--group NAME] [--limit N] [--structural]
 delegate runs prune [--older-than DAYS] [--dry-run]
 delegate ps [--harness HARNESS] [--group NAME] [--limit N]
 delegate snapshot [--latest HARNESS] [--no-redact] <handle>
@@ -1055,8 +1092,18 @@ creating a Run or writing a prompt record.
 | Include dirty | `includeDirty` | `--include-dirty` | Source and explicit values are creation-only and are dropped for ordinary resume with a note. | Retained only as a drop decision; on a persistent/attached source, explicit `--include-dirty` is rejected because attachment does not create or sync a worktree. |
 
 `delegate runs` defaults to recent runs. `--active` preserves the legacy active view and includes both live `running` runs and `stale` runs. Use `--running` for only live tracked processes and `--stale` for runs recorded as running whose PID is missing or dead. `--active`, `--running`, `--stale`, and `--recent` are mutually exclusive. `--group NAME` filters by launch group and the runs table shows a `group` column when any visible run has one.
+`--structural` omits content-bearing run fields and emits only identity, lifecycle, model,
+timestamp, group/mode, and `initiatorRoot` metadata. It is intended for local status collectors.
+JSON output (`delegate.runs.v1`) includes `total` (post-filter match count before `--limit`)
+and `truncated` (`true` when `total` exceeds the returned `runs` length). Text mode appends
+`showing N of M runs (raise --limit to see more)` when truncated. A zero-row result with
+`--group` or `--harness` adds a `warnings` entry (and a matching text `warning:` line): when
+the scope filters match Runs that `--active`/`--running`/`--stale` then excluded, it names
+the status flag to drop; otherwise it notes the Registry is workspace-scoped and `--cwd PATH`
+targets another workspace's Registry — it does not claim the filter matches elsewhere.
 `delegate ps` is the shorter first-class form of `delegate runs --active` and
-accepts the same harness, group, and limit selectors.
+accepts the same harness, group, limit, and structural selectors (including `total`,
+`truncated`, and the empty-filter workspace-scope warning).
 
 `delegate runs prune` removes old terminal Run records from the workspace Registry so they stop accumulating forever. Only runs whose effective status is terminal (`succeeded`, `failed`, `cancelled`, or `stale` from a dead child) and whose last Registry activity is older than the threshold (default 30 days; override with `--older-than DAYS`) are eligible. Effectively running runs are always skipped, and persistent-worktree runs are skipped unless their worktree is recorded as removed or missing — pruning the record of a live worktree would orphan it from `worktree list`/`show`/`remove`. Pruning deletes the per-Run directory (Snapshot, Manifest, logs, events, Completion Report) and the retained raw-log archive; worktree paths on disk are never touched. `--dry-run` reports what would be removed without changing anything. JSON output uses schema `delegate.runs-prune.v1` with `planned`, `removed`, `skipped` (each entry carries a `reason`), and `errors` sections.
 
@@ -1111,10 +1158,17 @@ Common JSON fields for tracked run completion:
 
 Persistent worktree completions also include `branch`, `worktree`, a
 `workSummary`, and (when requested) `commitPolicy`. `workSummary` reports dirty
-state, changed file count, diff stat, and commits created by the child. When a
-Codex usage-limit fallback fires, the completion payload also includes
-`codexAuthFallback` metadata (reason, the primary and fallback profile names,
-both exit codes, and a redacted primary stderr tail).
+state, changed file count, diff stat, and commits created by the child. Tracked
+Cursor completions include `usage` when the Cursor CLI reports it, using
+`basis: "reported"` and camel-case token fields such as `inputTokens` and
+`outputTokens`. When a Codex usage-limit fallback fires, the completion payload
+also includes `codexAuthFallback` metadata (reason, the primary and fallback
+profile names, both exit codes, and a redacted primary stderr tail). The
+fallback is Codex-only and is enabled only by `codex.fallbackProfile`; Delegate
+remembers temporary blocks by hashed credential namespace (`CODEX_HOME/auth.json` plus
+`codex.profile`) as canonical state. Default work/personal credential homes
+also mirror compatible legacy alias keys so existing launchers share blocks;
+remapped aliases remain isolated.
 
 Snapshot JSON uses schema `delegate.snapshot.v1` and includes fields such as `alias`, `runId`, `harness`, `status`, `rawStatus`, `effectiveStatus`, `staleReason`, `nextActions`, `cwd`, `executionCwd`, `workspaceRoot`, `assistantText`, `recentEvents`, `warnings`, `exitCode`, reasoning metadata, terminal metadata, and isolation/worktree metadata when applicable. `workspaceRoot` is also exported to the child as `WORKSPACE_ROOT`, so commands can anchor workspace-relative paths after changing directories. Inspection commands do not rewrite a stale run's recorded state; they expose the raw recorded status plus the effective status computed from the current PID check. Run-output and worktree show output include `requestedHandle`, `resolvedHandle`, and `resolutionKind` (`literal`, `latest`, or `latest_model`) when a handle resolves indirectly. For bare harness handles, snapshot, run-output, and wait also report `resolvedRunId`, `resolvedAlias`, `resolvedWorkspace`, `resolvedAge`, and `resolvedAgeSeconds`. Resolutions older than 24 hours add a `bare_handle_stale` warning suggesting `--cwd` or an explicit handle.
 
@@ -1136,6 +1190,28 @@ Work-mode attempts are never replayed after tool activity or a workspace change.
 
 Run-output JSON uses schema `delegate.run-output.v1` and returns selected completion report, stdout, and/or stderr content. By default, secret-like strings are redacted unless `--no-redact` is supplied. Tracked runs finish in one of the terminal statuses `succeeded`, `failed`, or `cancelled`; explicit harness cancellation/error terminal events override an exit-zero child status.
 
+Tracked stdout and stderr logs are capped independently at 16 MiB. Exceeding a
+cap terminates the child and records `output_limit_exceeded` plus an
+`outputLimit` object naming the stream and byte limit. After an explicit
+terminal-success event, Delegate gives the harness one second to exit and then
+stops a lingering process; successful envelopes disclose this as
+`stoppedAfterCompletion: true`. Harnesses must emit that terminal event only
+after flushing their final payload.
+
+Each tracked Run also keeps `events.jsonl`, an append-only raw diagnostic mirror
+of child stdout lines as `{"kind":"stream.line","stream":"stdout","text":...}`
+records (including a final unterminated line when the child exits mid-line).
+The mirror retains at most 500 stdout-line records, followed by one
+`stream.lines_truncated` marker when additional lines are omitted. Normalized
+progress events also appear in Snapshot `recentEvents`; it retains the first
+100 and latest 400 events while reporting the full `eventsTotal`. Both surfaces
+bound child-controlled event strings to 500 characters, including the `…`
+sentinel when clipped. Truncated `message`/raw-line text adds `textChars`; other
+normalized fields add `<field>Chars` (for example `targetChars`). Short fields
+omit truncation metadata.
+Retained event text is not redacted — treat `events.jsonl` and `recentEvents`
+as sensitive diagnostic artifacts.
+
 Safe runs and read-only call runs that exit successfully with `resultQuality=empty`
 retry once with the original prompt plus a plain-text final-answer instruction.
 Pure and slash pass-through prompts, and write-capable calls, do not retry. Retried

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/docs/configuration.md

@@ -265,6 +265,11 @@ Controls local run recording.
 - `retention.enabled`: whether raw logs are eligible for archive-only retention.
 - `retention.rawLogDays`: non-negative number of days before bulky raw logs may be archived.
 
+Ambient retention is best-effort. Archive I/O is serialized separately from
+Registry mutations, so a slow archive cannot block run progress, inspection,
+or cancellation; if another retention pass is already active, a concurrent
+ambient pass returns immediately.
+
 ### `cursor`
 
 ```json
@@ -336,7 +341,7 @@ Controls local run recording.
 - `models`: optional map of local aliases to Codex model IDs for `--model` / JSON `model`. Alias keys must not collide with mode names, equal the engine's own name, or start with `-`.
 - `defaultReasoningEffort`: optional non-empty effort string. When a Codex model resolves (run input or `codex.defaultModel`) and supports the level, Delegate emits a Codex config override; otherwise the run proceeds without reasoning effort and records a warning. An explicit `--reasoning-effort` flag fails closed for unsupported levels, but can target the Codex harness default model when no model is configured.
 - `profile`: optional Codex CLI config overlay name. It is config-only; JSON run input cannot set it.
-- `fallbackProfile`: optional top-level `profiles.definitions` name for one quota-limit retry on tracked Codex runs. The fallback profile must define `env.CODEX_HOME`.
+- `fallbackProfile`: optional top-level `profiles.definitions` name for Codex-only quota fallback. The fallback profile must define `env.CODEX_HOME`. Tracked Codex runs persist temporary usage-limit blocks under `~/.ai-profiles/runtime/failover/`; hashed credential namespace (`CODEX_HOME/auth.json` plus `codex.profile`) is canonical, while default work/personal credential homes also mirror compatible legacy alias keys so existing launchers share blocks. Remapped aliases remain isolated. If both the primary and fallback credential namespaces are blocked, Delegate keeps the primary attempt and does not launch the known-blocked fallback.
 - `workSandbox`: `read-only`, `workspace-write`, or `danger-full-access` for Codex work mode when full bypass is not enabled.
 - `ephemeral`: include Codex `--ephemeral` in JSON-streaming runs.
 - `ignoreUserConfig`: include Codex `--ignore-user-config`.

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/docs/development.md

@@ -59,8 +59,12 @@ Run focused tests first, then the broader checks before handoff:
 ```bash
 python3 -m compileall -q src tests bin
 git diff --check
-python3 -m unittest discover -s tests
+python3 -m unittest discover -s tests -t .
 ```
 
+`-t .` makes discovery import `tests/__init__.py`, which shims `src` onto
+`sys.path` and strips ambient env. Unittest prints its `Ran N tests / OK`
+summary to stderr — pipe with `2>&1` when capturing output.
+
 Required CI does not need real Cursor, Droid, Codex, Claude, Grok, Devin,
 OpenCode, Pi, Oh My Pi, or Kimi binaries.

{delegate_agent_cli-0.27.0 → delegate_agent_cli-0.29.0}/docs/live-runtime.md

@@ -28,7 +28,8 @@ When `AI_PROFILE=work|personal` is set and the matching
 `~/.delegate/config.<profile>.json` overlay is missing, Delegate blocks launch
 and mutation commands but allows read-only diagnostics (`profiles`, `runs`,
 `run-output`, `snapshot`, cached `capabilities`, `worktree show`,
-`worktree list`, `describe`, `models`) with a warning. This check runs inside
+`worktree list`, `workflow check|status|watch|events|result|wait|list`,
+`describe`, `models`) with a warning. This check runs inside
 `delegate_agent.cli:main` (`src/delegate_agent/profile_guard.py`), so it applies
 regardless of entrypoint: the installed pip console script, `python -m
 delegate_agent.cli`, or `bin/delegate.py`. Some local installs additionally put
@@ -38,8 +39,11 @@ check even earlier, before Python starts. `AI_PROFILE` values other than
 `work`/`personal` are not recognized profiles; Delegate warns and runs on the
 base account rather than failing closed, since there is no config filename
 convention to check against. Fix a half-configured install with
-`env -u AI_PROFILE delegate config sync-profiles`, or bypass once with
-`env -u AI_PROFILE delegate ...` or an explicit `DELEGATE_CONFIG=...`.
+`env -u AI_PROFILE delegate config sync-profiles`, or bypass profile selection
+once with `env -u AI_PROFILE delegate ...`.
+In profile-aware shell installs, profile selection loads credentials; an
+incoming explicit `DELEGATE_CONFIG` remains the runtime-policy config only
+after the selected profile overlay passes validation.
 
 ## Do not promote implicitly