delegate-agent-cli 0.18.0__tar.gz → 0.21.0__tar.gz

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.21.0}/CHANGELOG.md

@@ -5,6 +5,272 @@ 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).
 
+## [0.21.0] - 2026-07-26
+
+### Added
+
+- Added `delegate worktree gc --all`, which scans the machine-wide worktree
+  pool for worktrees whose source repository no longer exists. Such worktrees
+  were previously unreachable by any `gc` invocation, because reaping is driven
+  by the run registry inside each source repository and that registry dies with
+  the repository. The scan adds no catalog or persistent state: it reads each
+  worktree's Git backlink directly, and treats a backlink whose target is gone
+  as the sole orphan signal. The scan removes nothing at all, at any depth: a
+  missing source repository makes a worktree's uncommitted state impossible to
+  inspect, so orphans and empty pool directories alike are reported for
+  deliberate manual cleanup. Because that output invites manual deletion, every
+  uncertainty resolves away from an orphan verdict: a pointer file that cannot
+  be read, a path comparison the filesystem cannot answer, an entry too recently
+  modified to have settled, and a directory whose name does not match the pool's
+  own fingerprint contract are all reported as warnings rather than orphans.
+  That last rule is what keeps a scan of an arbitrary root from labelling
+  somebody else's directories. `--pool PATH` scans a different pool root, which
+  reaches pools stranded by an earlier `worktrees.dataHome`.
+- `capabilities refresh` and `setup` now name each harness on stderr as it is
+  probed, so a harness that hangs is identifiable rather than anonymous
+  silence. Progress output is suppressed under `--json`.
+
+### Changed
+
+- A launch now fails instead of proceeding when the configured binary for a
+  harness identifies itself as a *different* known harness. Delegate re-probes
+  `--version` when a cached capability record has refused a run, and during
+  `capabilities refresh` and `setup` (see Fixed); when that banner positively
+  names another harness — a Codex path replaced in place by Grok, say — the run
+  stops with `harness_identity_mismatch` and exit code 2, naming the configured
+  harness, the harness that answered, and the selector path.
+  Previously the launch continued against that same binary with the same Codex
+  argv, sandbox flags, and approval policy, and only the cached capability
+  metadata was discarded. This fires solely on a banner that NAMES another known
+  harness, never on uncertainty: a probe that errors, times out, exceeds its
+  output bound, or prints an unbranded banner still fails open and launches on
+  the cached record. An unbranded shape — a bare date-and-hash build ID is the
+  clearest case — is deliberately not identification, because wrapper prefixes
+  are a supported configuration and refusing a legitimate launch costs more than
+  carrying a stale record until the next refresh. The selector is scrubbed of
+  credentials before it reaches the message or the diagnostics, since a wrapper
+  prefix can carry a token inline or after a flag. Dry runs do not probe and are
+  unaffected. The refusal also names the discovery cache file for the active
+  auth profile, in its `cachePath` diagnostic and in a next action, because
+  `capabilities refresh` cannot clear this state: a refresh keeps the
+  last-known-good record whenever a probe fails, which is correct for a flaky
+  probe and wrong here, where the record itself is the problem. Without the
+  path, a wrong identification would refuse every launch with no documented way
+  out short of editing configuration.
+- A run whose cached capability record is discarded for version drift now says
+  so, naming `delegate capabilities refresh <engine>`. The record is dropped for
+  that run only and the superseded copy stays on disk, so every later launch
+  repeats the drop and loses the same discovery-sourced models and reasoning
+  levels — previously with no indication that a stale cache was the cause.
+  Selector drift stays silent, since `capabilities` already reports it under
+  `driftedHarnesses`.
+
+### Fixed
+
+- Discovery now detects a harness that was upgraded in place. Cached capability
+  records were invalidated only by comparing the configured selector, so an
+  upgrade behind an unchanged selector left stale capabilities cached
+  indefinitely and a newly supported reasoning level was rejected until a manual
+  `capabilities refresh`. Delegate now re-probes `--version` for the single
+  harness it is about to use and compares it against the version already stored
+  in the record, then rebuilds the run against the refreshed picture. The probe
+  runs only once the cached record has already cost the run something, never on
+  the ordinary path, which therefore spawns no extra process at all — and that
+  matters because the probe costs 26-668ms, worst on the Node and Bun harnesses
+  that are already slow to start. Two things trigger it: an explicit
+  `--reasoning-effort` the record refuses, and a `defaultReasoningEffort` the
+  record silently drops. The second is the one most likely to go unnoticed,
+  since a configured default degrades to a warning rather than failing the
+  launch, and it is set once and then never typed again. A probe that cannot
+  repair the default leaves the run exactly as it was: a launch that succeeded
+  is never turned into a failure. The check fails open — a probe that errors,
+  times out, or prints a banner nothing recognizes keeps the cached record, so a
+  failing probe can never prevent a launch. A banner that positively identifies
+  a *different* known harness is the exception, and it aborts the launch rather
+  than merely invalidating the record — see Changed. Each banner is matched
+  against the expected harness's own pattern before anyone else's, so a banner
+  mentioning more than one tool is read as the harness that was asked for
+  instead of whichever pattern happens to be declared earlier. Banners are read
+  with escape sequences stripped, so a colorized version line no longer freezes
+  a record permanently. A cached selector whose binary no longer exists is also
+  treated as drift.
+- Not covered, deliberately: a harness that *removes* a capability leaves its
+  cached record listing more than the harness now supports, which produces no
+  refusal and so no probe. The child rejects the effort it was handed, which is
+  loud; the one quiet case is Cursor's route table aiming a run at a superseded
+  model id. Catching either would cost a probe on every launch, which is the
+  trade this path exists to refuse. `capabilities refresh` remains the cure.
+- A dry run never probes the harness for its version. Dry run documents that it
+  neither launches a child runtime nor requires the real child binary, and the
+  drift probe is a child runtime; it now runs only on a real launch, leaving dry
+  run with the two filesystem-local checks.
+- A discovery cache carrying a newer schema than the running build is no longer
+  discarded and overwritten. It is left intact while the run degrades to
+  probing without persisting, so an older Delegate can no longer destroy a newer
+  cache. Losing that race mid-probe degrades the same way rather than failing the
+  command: `capabilities refresh` and `setup` both report `cacheWriteSkipped`,
+  `setup` additionally leaving `cacheState` at `unchanged`, and each exits
+  successfully, since only persistence was lost. The
+  schema is re-read immediately before the atomic replacement rather than before
+  the snapshot is serialized, which narrows the window in which a newer cache
+  could be published and then overwritten down to the `os.replace` call itself.
+  POSIX offers no compare-and-swap for a rename, so that last window remains.
+- The test suite no longer writes into the developer's real
+  `~/.delegate/worktrees`. Tests exercising persistent-worktree runs created
+  real pooled worktrees over temporary source repositories and orphaned them
+  permanently, because `worktrees_data_home` falls through to the user's home
+  directory with no seam a test could redirect. `HOME` is now redirected at test
+  collection time, which reaches every such resolver at once.
+
+## [0.20.0] - 2026-07-25
+
+### Added
+
+- Added typed child-failure reporting for usage/quota limits (including reset
+  details when present), expired or rejected auth tokens, and Codex thread/state
+  lookup loss. Run state, snapshots, listings, completion envelopes, and
+  synthesized reports now carry the specific error and message. The existing
+  generic public error remains `child_failed`; `usage_limit`, `auth_failed`, and
+  `codex_thread_lost` are additive typed codes. Classification reads only stderr
+  and normalized harness error/terminal events, never assistant/model output.
+- Added `delegate ps` as the first-class active-run view, equivalent to
+  `delegate runs --active`.
+- Added `delegate setup` for first-run harness discovery. It fingerprints all
+  supported installed harnesses, records available model/reasoning metadata in
+  a profile-scoped user cache, creates a minimal selector-only config when no
+  config exists, and reports discovery readiness separately from launchability.
+- Cached `models`/`capabilities` views now project profile discovery with source
+  and evidence metadata. `models <engine> --live` provides a non-persistent
+  one-off probe; `capabilities refresh` persists a full refresh for the selected
+  profile, and `capabilities refresh <engine> [...]` re-probes only the named
+  harnesses while the rest keep their last-known-good records.
+- Runtime model and reasoning metadata now distinguish the requested model,
+  argv-resolved model, capability-validation model, requested effort, resolved
+  effort, source, evidence strength, and transport.
+
+### Changed
+
+- Codex output schemas are now linted before launch. Delegate recursively
+  supplies missing `additionalProperties: false` on object schemas with a loud
+  warning, rejects partial `required` lists precisely, and passes a normalized
+  temporary copy without modifying the source schema. Object-bearing `allOf`,
+  `patternProperties`, and external or unresolvable `$ref` values fail closed
+  rather than being rewritten unsafely. Workflow Codex stages and direct
+  `--output-schema`/`outputSchema` launches share the same preflight. The
+  normalized copy preserves the source schema's property order, so
+  think-before-answer schemas keep their intended generation order.
+- On retry-safe paths, Codex thread/state lookup failures now retry once and,
+  only if the same typed failure repeats, retry through an ephemeral
+  `--ignore-user-config` launch. Retry-safe paths are read-only calls and
+  pre-tool attempts whose workspace remains unchanged; work mode also requires
+  a clean captured baseline. Envelopes and events record fallback engagement.
+- `--prompt-file /dev/stdin` and equivalent stdin descriptors now consume the
+  piped prompt once instead of conflicting with stdin as a second source.
+- Model and reasoning resolution now prefers explicit CLI/config choices and
+  exact discovered evidence before legacy workspace or bundled fallbacks.
+  Exact negative menus fail closed; partial harness evidence and Cursor inferred
+  routes remain visibly labeled rather than being promoted to model-exact facts.
+- Discovery refresh is last-known-good per harness. Successful records update
+  independently, failed probes retain the prior record and report staleness,
+  and selector drift invalidates only the affected harness without probing on
+  an ordinary launch.
+- `capabilities refresh` now writes the selected profile's private discovery
+  cache. The old workspace reasoning cache remains a lower-precedence read-only
+  compatibility source. The cached `capabilities` read reports the discovery
+  cache location in `cachePath`; the previous workspace path, when present, is
+  reported under `legacyWorkspaceCachePath`.
+- `reasoning.capabilities` config entries are now accepted for `grok` in
+  addition to `codex` and `droid`.
+- `--auth-profile` is now accepted on cached `capabilities` reads (previously
+  rejected as an invalid option combination) and on `models` and `setup`.
+- Cursor reasoning-effort routing now defers to a pinned selector when discovery
+  has no same-family route for it: the run proceeds on the pinned model and
+  records a bypass warning. When discovery does carry exact same-family routes,
+  the requested effort still routes to the matching selector, and a family that
+  omits the requested effort still fails closed.
+- Grok reasoning-effort support is once again governed by the documented CLI
+  enum (low, medium, high, xhigh, max); a bundled `grok-4.5` declaration that
+  narrowed it to low/medium/high was removed, since `grok --help` enumerates no
+  per-model efforts. Config, discovery-exact, and cached grok declarations
+  still take precedence.
+- Embedded Devin and Kimi `defaultModel` values are now `null`, deferring model
+  selection to each harness. The editable `config init` example may still pin
+  an explicit default.
+- Claude and Grok `defaultReasoningEffort` config values are now only
+  format-checked at load time instead of validated against the static enum; an
+  unsupported configured default degrades to a launch-time warning so that
+  discovery, not a hardcoded table, decides which levels are accepted.
+
+### Security
+
+- Discovery probes use fingerprinted allowlisted selectors, fixed argv with no
+  shell, closed stdin, neutral temporary working directories, bounded output,
+  timeouts, normalized cache schemas, atomic owner-only writes, and scrubbed
+  model/warning projections. Config and cache source paths remain intentionally
+  visible diagnostics. Automatic Devin discovery remains prompt-free; only the
+  explicitly requested `models devin --live` path uses its bounded prompt-like
+  invalid-model probe.
+- Setup never overwrites an existing config and refuses unsafe selectors,
+  final-component symlinks, and concurrent config races rather than mixing
+  discovery results across config states.
+
+### Fixed
+
+- Credentials appearing in a child harness quota or reset message are now
+  redacted before they reach `state.json`, `snapshot.json`, the completion
+  report, or the run envelope; Codex reports quota walls as stdout events,
+  which bypassed the stderr-tail redaction. The in-progress activity label is
+  likewise redacted when persisted, matching the progress heartbeat.
+- A Codex output schema that omits `required` entirely is now repaired to list
+  every property (in declaration order) instead of being rejected, matching how
+  a missing `additionalProperties` is handled. A partial `required` is still an
+  error.
+- The `primary` attempt banner is written once in the run's stderr log even
+  when several retry paths run in sequence.
+- `delegate ps` now reports argument errors in its own terms — unknown options,
+  `--limit`, `--harness`, and `--group` failures name `ps` instead of the
+  `runs` command it delegates to, and `ps --recent` gets the same tailored
+  redirect as `--running` and `--stale`.
+- `delegate capabilities refresh` exits 3 (missing binary) when no supported
+  harness is installed — including when an engine subset such as
+  `capabilities refresh codex` names only uninstalled harnesses — matching
+  `delegate setup` on identical machine state instead of returning the generic
+  usage code 2.
+- `delegate capabilities` no longer advertises harnesses whose configured
+  selector has drifted from the cached record, on both the cached read and
+  after a refresh — a subset refresh returns the full snapshot, so engines it
+  never probed could otherwise surface stale catalogs the launch path would
+  refuse. Excluded harnesses are named in a new `driftedHarnesses` payload
+  field and in the text output.
+- Pi catalog rows whose column count does not match the header are skipped
+  instead of being read by shifted column position, which could cache a
+  thinking-capable model as having no reasoning support (unrecoverable, since
+  Pi has no config override) or hand a non-thinking model the full effort enum.
+- A configured harness binary or argv prefix that no longer resolves while the
+  CLI is still on PATH is now reported as a stale config setting rather than an
+  uninstalled harness, and `delegate setup` names the config key and file to
+  fix instead of telling you to install a CLI you already have.
+- An unreadable `~/.factory/settings.json` (permissions or I/O error) is
+  reported as a read failure instead of being misreported as invalid JSON.
+- Two Cursor selectors that normalize to the same route family and effort now
+  drop just the ambiguous routes with a warning, instead of turning the entire
+  Cursor discovery record into an error record.
+- OpenCode catalog parsing resumes past a malformed entry's whole object, so a
+  `provider/model`-shaped line nested inside the rejected body can no longer be
+  re-read as a real selector.
+- `capabilities refresh` now hints "global options before the subcommand" for a
+  misplaced global option instead of mislabeling it `invalid_engine`, and a
+  subset refresh whose requested harnesses are all uninstalled reports
+  `requested_harnesses_not_installed` instead of the misleading
+  `no_harnesses_installed`.
+
+## [0.19.0] - 2026-07-20
+
+### Added
+
+- Codex `--reasoning-effort max` support for `gpt-5.6-sol`; other Codex models
+  still fail closed unless config or workspace capability-cache overrides opt them in.
+
 ## [0.18.0] - 2026-07-19
 
 ### Added
@@ -137,7 +403,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   consistently across the CLI reference and worktree guidance.
 - Devin help and discovery surfaces now derive supported modes consistently and
   reject unknown modes before constructing executable arguments.
-
 ## [0.14.0] - 2026-07-15
 
 ### Added
@@ -483,6 +748,9 @@ Usage-audit fix wave: 82 sessions and 1,241 delegate invocations from one week o
 
 - Releases before 0.1.3 predate this changelog.
 
+[0.21.0]: https://github.com/treygoff24/delegate-agent/compare/v0.20.0...v0.21.0
+[0.20.0]: https://github.com/treygoff24/delegate-agent/compare/v0.19.0...v0.20.0
+[0.19.0]: https://github.com/treygoff24/delegate-agent/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/treygoff24/delegate-agent/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/treygoff24/delegate-agent/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/treygoff24/delegate-agent/compare/v0.15.0...v0.16.0

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: delegate-agent-cli
-Version: 0.18.0
+Version: 0.21.0
 Summary: A tiny CLI for delegating bounded agent tasks across coding-agent runtimes.
 Author: Trey Goff
 License-Expression: MIT
@@ -130,22 +130,28 @@ Install OpenCode from [opencode.ai](https://opencode.ai). Its curl installer
 normally writes the binary to `~/.opencode/bin`, which may not be on `PATH`.
 Extend `PATH` or set `opencode.binary` to the absolute binary path.
 
-Initialize a starter config and replace placeholder Droid model IDs before real Droid runs:
+Let Delegate discover the supported harnesses already on your `PATH`:
 
 ```bash
-delegate config init
-$EDITOR ~/.delegate/config.json
+delegate setup
 ```
 
-`config init` also writes missing `~/.delegate/config.work.json` and
-`~/.delegate/config.personal.json` profile overlays. For an existing install,
-run `env -u AI_PROFILE delegate config sync-profiles` to materialize any missing
-overlays without overwriting ones you already edited.
+`setup` fingerprints installed harnesses, reads their model and reasoning metadata where
+the harness exposes it, and writes a private discovery cache for the active auth profile.
+On a clean install it creates only the absolute binary selectors needed to launch the
+detected harnesses. It never rewrites an existing config, installs a harness, logs in, or
+submits a model prompt.
+
+Use `delegate config init` instead when you want the editable example config and profile
+overlays. Replace its placeholder Droid model IDs before real Droid runs. For an existing
+install, `env -u AI_PROFILE delegate config sync-profiles` creates missing overlays without
+overwriting ones you already edited.
 
 Inspect what Delegate sees:
 
 ```bash
 delegate --version       # installed version — include this in bug reports
+delegate --json setup
 delegate --json describe --summary
 delegate --json models --summary
 delegate --json describe
@@ -156,9 +162,10 @@ 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
 delegate --json capabilities
+delegate --json capabilities refresh   # refresh the active profile's discovery cache
 ```
 
-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. `delegate --json capabilities` reports reasoning-effort support without launching a child runtime.
+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.
 
 From this development checkout, use `python3 bin/delegate.py ...` instead of an installed `delegate` shim.
 
@@ -243,7 +250,12 @@ $EDITOR /tmp/delegate-task.json
 delegate --json run --input-json /tmp/delegate-task.json
 ```
 
-For Codex fan-outs that must return machine-parseable records, add `--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report injection so the schema owns the final message.
+For Codex fan-outs that must return machine-parseable records, add
+`--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report
+injection so the schema owns the final message. Codex schemas are
+strict-preflighted recursively: every property must be required, and a missing
+`additionalProperties: false` is supplied in a warned temporary copy without
+changing the source file.
 
 For a one-hop prompt that should not see the current repo or create a tracked
 run, use stateless `call` mode:
@@ -280,7 +292,16 @@ python3 bin/delegate.py workflow approve wf_0123abcdef45
 See [Delegate Workflows](docs/delegate-workflows.md) for the DSL, safety
 limits, config, and gate semantics.
 
-Reasoning effort is provider-aware. Unsupported combinations fail before launch. It changes only the requested model thinking depth/cost/latency; it does not change safe/work/call mode, sandboxing, approvals, or edit capability. Codex/Droid validate effort against model capability metadata, Cursor maps effort to configured model selection, Claude and Grok map to native `--effort`, OpenCode passes it through as `--variant`, and Pi/Oh My Pi map `low|medium|high|xhigh|max` directly to `--thinking`. Devin and Kimi do not expose a Delegate reasoning-effort flag. Explicit Codex effort can target the harness default model even when `codex.defaultModel` is unset:
+Reasoning effort is provider-aware. Unsupported combinations fail before launch.
+It changes only the requested model thinking depth/cost/latency; it does not
+change safe/work/call mode, sandboxing, approvals, or edit capability.
+Codex/Droid validate exact model metadata, Cursor selects an explicit configured
+or corroborated discovered effort route, Claude and Grok map to native
+`--effort`, OpenCode validates discovered exact variants when present and
+otherwise warns on pass-through, and Pi/Oh My Pi map to `--thinking` with
+evidence-aware validation. Devin and Kimi do not expose a Delegate
+reasoning-effort flag. Explicit Codex effort can target the harness default model
+even when `codex.defaultModel` is unset:
 
 ```bash
 delegate --json dry-run codex safe --reasoning-effort high "Review this repository. Do not edit files."
@@ -291,7 +312,9 @@ Codex model routing is deliberately model-first rather than aliasing every
 model/effort pair: define model aliases in `codex.models`, then set effort per
 run with `--reasoning-effort`. Per-model effort menus (including any efforts
 newer than the bundled data) belong in the private `reasoning.capabilities`
-config block, which overrides the bundled defaults.
+config block, which overrides the bundled defaults. Codex `max` is bundled only
+for `gpt-5.6-sol` as of 2026-07; other Codex models require an exact config or
+profile-discovery declaration, or legacy workspace-cache declaration.
 
 Fast mode is an independent per-run serving choice. `--fast` requests Codex's
 Fast service tier, `--no-fast` explicitly requests Standard, and omitting both
@@ -306,6 +329,7 @@ Inspect tracked output by alias:
 
 ```bash
 delegate runs --recent
+delegate ps                   # active and stale tracked runs
 delegate snapshot <alias-or-runId>
 delegate run-output <alias-or-runId>
 ```

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.21.0}/README.md

@@ -97,22 +97,28 @@ Install OpenCode from [opencode.ai](https://opencode.ai). Its curl installer
 normally writes the binary to `~/.opencode/bin`, which may not be on `PATH`.
 Extend `PATH` or set `opencode.binary` to the absolute binary path.
 
-Initialize a starter config and replace placeholder Droid model IDs before real Droid runs:
+Let Delegate discover the supported harnesses already on your `PATH`:
 
 ```bash
-delegate config init
-$EDITOR ~/.delegate/config.json
+delegate setup
 ```
 
-`config init` also writes missing `~/.delegate/config.work.json` and
-`~/.delegate/config.personal.json` profile overlays. For an existing install,
-run `env -u AI_PROFILE delegate config sync-profiles` to materialize any missing
-overlays without overwriting ones you already edited.
+`setup` fingerprints installed harnesses, reads their model and reasoning metadata where
+the harness exposes it, and writes a private discovery cache for the active auth profile.
+On a clean install it creates only the absolute binary selectors needed to launch the
+detected harnesses. It never rewrites an existing config, installs a harness, logs in, or
+submits a model prompt.
+
+Use `delegate config init` instead when you want the editable example config and profile
+overlays. Replace its placeholder Droid model IDs before real Droid runs. For an existing
+install, `env -u AI_PROFILE delegate config sync-profiles` creates missing overlays without
+overwriting ones you already edited.
 
 Inspect what Delegate sees:
 
 ```bash
 delegate --version       # installed version — include this in bug reports
+delegate --json setup
 delegate --json describe --summary
 delegate --json models --summary
 delegate --json describe
@@ -123,9 +129,10 @@ 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
 delegate --json capabilities
+delegate --json capabilities refresh   # refresh the active profile's discovery cache
 ```
 
-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. `delegate --json capabilities` reports reasoning-effort support without launching a child runtime.
+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.
 
 From this development checkout, use `python3 bin/delegate.py ...` instead of an installed `delegate` shim.
 
@@ -210,7 +217,12 @@ $EDITOR /tmp/delegate-task.json
 delegate --json run --input-json /tmp/delegate-task.json
 ```
 
-For Codex fan-outs that must return machine-parseable records, add `--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report injection so the schema owns the final message.
+For Codex fan-outs that must return machine-parseable records, add
+`--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report
+injection so the schema owns the final message. Codex schemas are
+strict-preflighted recursively: every property must be required, and a missing
+`additionalProperties: false` is supplied in a warned temporary copy without
+changing the source file.
 
 For a one-hop prompt that should not see the current repo or create a tracked
 run, use stateless `call` mode:
@@ -247,7 +259,16 @@ python3 bin/delegate.py workflow approve wf_0123abcdef45
 See [Delegate Workflows](docs/delegate-workflows.md) for the DSL, safety
 limits, config, and gate semantics.
 
-Reasoning effort is provider-aware. Unsupported combinations fail before launch. It changes only the requested model thinking depth/cost/latency; it does not change safe/work/call mode, sandboxing, approvals, or edit capability. Codex/Droid validate effort against model capability metadata, Cursor maps effort to configured model selection, Claude and Grok map to native `--effort`, OpenCode passes it through as `--variant`, and Pi/Oh My Pi map `low|medium|high|xhigh|max` directly to `--thinking`. Devin and Kimi do not expose a Delegate reasoning-effort flag. Explicit Codex effort can target the harness default model even when `codex.defaultModel` is unset:
+Reasoning effort is provider-aware. Unsupported combinations fail before launch.
+It changes only the requested model thinking depth/cost/latency; it does not
+change safe/work/call mode, sandboxing, approvals, or edit capability.
+Codex/Droid validate exact model metadata, Cursor selects an explicit configured
+or corroborated discovered effort route, Claude and Grok map to native
+`--effort`, OpenCode validates discovered exact variants when present and
+otherwise warns on pass-through, and Pi/Oh My Pi map to `--thinking` with
+evidence-aware validation. Devin and Kimi do not expose a Delegate
+reasoning-effort flag. Explicit Codex effort can target the harness default model
+even when `codex.defaultModel` is unset:
 
 ```bash
 delegate --json dry-run codex safe --reasoning-effort high "Review this repository. Do not edit files."
@@ -258,7 +279,9 @@ Codex model routing is deliberately model-first rather than aliasing every
 model/effort pair: define model aliases in `codex.models`, then set effort per
 run with `--reasoning-effort`. Per-model effort menus (including any efforts
 newer than the bundled data) belong in the private `reasoning.capabilities`
-config block, which overrides the bundled defaults.
+config block, which overrides the bundled defaults. Codex `max` is bundled only
+for `gpt-5.6-sol` as of 2026-07; other Codex models require an exact config or
+profile-discovery declaration, or legacy workspace-cache declaration.
 
 Fast mode is an independent per-run serving choice. `--fast` requests Codex's
 Fast service tier, `--no-fast` explicitly requests Standard, and omitting both
@@ -273,6 +296,7 @@ Inspect tracked output by alias:
 
 ```bash
 delegate runs --recent
+delegate ps                   # active and stale tracked runs
 delegate snapshot <alias-or-runId>
 delegate run-output <alias-or-runId>
 ```

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.21.0}/bin/delegate-profile-shim

@@ -33,6 +33,75 @@ _delegate_subcommand() {
   done
 }
 
+_delegate_launch_help_request() {
+  _delegate_launch_cmd="${1:-}"
+  [ "$#" -gt 0 ] && shift
+
+  if [ "$_delegate_launch_cmd" = "dry-run" ]; then
+    case "${1:-}" in
+      --help|-h)
+        return 0
+        ;;
+    esac
+    _delegate_launch_cmd="${1:-}"
+    [ "$#" -gt 0 ] && shift
+  fi
+
+  case "$_delegate_launch_cmd" in
+    cursor|codex|kimi|claude|grok|devin|opencode|pi|omp)
+      # Parser parity: help is diagnostic only before the mode or immediately
+      # after it. Once inline prompt text starts, a later help token is data.
+      case "${1:-}" in
+        --help|-h)
+          return 0
+          ;;
+        safe|work|call)
+          case "${2:-}" in
+            --help|-h)
+              return 0
+              ;;
+          esac
+          ;;
+      esac
+      return 1
+      ;;
+    droid)
+      # Droid may place a model alias before the mode, so its last diagnostic
+      # help position is one token later than the modeless harnesses.
+      case "${1:-}" in
+        --help|-h)
+          return 0
+          ;;
+        safe|work|call)
+          case "${2:-}" in
+            --help|-h)
+              return 0
+              ;;
+          esac
+          ;;
+        *)
+          case "${2:-}" in
+            --help|-h)
+              return 0
+              ;;
+            safe|work|call)
+              case "${3:-}" in
+                --help|-h)
+                  return 0
+                  ;;
+              esac
+              ;;
+          esac
+          ;;
+      esac
+      return 1
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
 _delegate_is_readonly_request() {
   while [ "$#" -gt 0 ]; do
     case "$1" in
@@ -51,7 +120,29 @@ _delegate_is_readonly_request() {
   _cmd="${1:-}"
   [ "$#" -gt 0 ] && shift
   case "$_cmd" in
-    profiles|runs|run-output|describe|models|snapshot|agent-help|help|--help|-h|--version)
+    cursor|droid|codex|kimi|claude|grok|devin|opencode|pi|omp|dry-run)
+      _delegate_launch_help_request "$_cmd" "$@" && return 0
+      return 1
+      ;;
+  esac
+  # Non-launch command parsers treat help as diagnostic wherever accepted.
+  for _delegate_help_arg in "$@"; do
+    case "$_delegate_help_arg" in
+      --help|-h)
+        return 0
+        ;;
+    esac
+  done
+  case "$_cmd" in
+    profiles|runs|ps|run-output|describe|snapshot|agent-help|help|--help|-h|--version)
+      return 0
+      ;;
+    models)
+      for _delegate_model_arg in "$@"; do
+        if [ "$_delegate_model_arg" = "--live" ]; then
+          return 1
+        fi
+      done
       return 0
       ;;
     capabilities)