@phnx-labs/agents-cli 1.22.53 → 1.22.55

package/CHANGELOG.md

@@ -1,5 +1,213 @@
 # Changelog
 
+## 1.22.55
+
+- **Managed shares generate their Open Graph cover server-side (PHNX-2835).** Publishing HTML to `share.agents-cli.sh` no longer launches local Chromium. The Worker lazily renders a deterministic 1200×630 AGI card with Satori and resvg-wasm, bundles Inter and JetBrains Mono, inherits the canonical page's visibility gate, and caches the PNG in R2. BYO endpoints keep their local screenshot fallback. An explicit missing `AGENTS_SHARE_BROWSER` or `PUPPETEER_EXECUTABLE_PATH` now fails loudly instead of silently falling through. Source: `cli/src/lib/share/{capture,publish,worker-template}.ts`.
+
+- **`agents routines status --json` — the daemon-owned scheduler status surface (PHNX-3215).** `routines status` printed human-only scheduler health and upcoming fires with no machine-readable form; the JSON that existed (`routines list --json`) is definition-shaped and does not answer "did this routine fire here, and is one running right now?" The new `--json` emits a `scheduler` block (state, pid, heartbeat age, enabled/total counts) plus a `routines` array where each row carries the routine's single **owner device** (`ownerDevice`, with `ambiguousDevicePin` when `devices:` names more than one), whether it fires here (`runsHere`), the last local fire's outcome and error (`lastStatus`, `failureReason`, `lastRunStartedAt`/`CompletedAt`), and any **in-flight spawn** (`inFlight: { runId, pid, startedAt, triggerKind }`) — surfaced only for a run that is genuinely live on this device (a live local child or a host-placed run), never a provisional pre-spawn claim. The routine set and counts are the schedulable ones (matching plain `routines status`), so the JSON never inflates totals with discoverable-but-unmaterialised project routines. Source: `cli/src/lib/scheduling/routines.ts` (`buildRoutineStatusRows`), `cli/src/commands/routines.ts`.
+
+### Fixed
+
+- Daemon service restarts now replace periodic timers instead of multiplying their tick rate, and a timed-out tick parks until its real work settles instead of overlapping teardown or another tick. Live-session metadata publishing, monitor evaluation, heartbeat/process reconciliation, tmux and browser-task reaping, broker self-heal, and signed webhook ingress now run under the per-service supervisor with measured health and isolated failure handling.
+
+- **`agents view --json` and `agents devices harnesses/accounts --json` no longer leak the internal `'stale'` sentinel in their usage-error fields (PHNX-3348).** Without `--refresh`, a read-only usage lookup on a never-cached account returns the internal `USAGE_NOT_COLLECTED_MARKER` (`'stale'`) — a cache signal, not a message — and the JSON builders emitted it verbatim (as `usageError`, and as `quota.unavailableReason`), contradicting those fields' "human-readable" contract. Both surfaces now normalize through a new shared `usageErrorForDisplay` to a plain-language, actionable string (`Usage not collected yet — run \`agents view --refresh\` to fetch it.`); every genuine, already-human error passes through unchanged, and the human terminal renders were already correct and are untouched. Source: `cli/src/lib/accounting/usage.ts`, `cli/src/commands/view.ts`, `cli/src/lib/view-types.ts`, `cli/src/lib/devices/harness-inventory.ts`.
+
+- **`agents artifacts share open <target>` — open your own published page signed in as the owner, so its inline visibility control is actually usable (PHNX-3370).** The shared page's `Public`/`Unlisted`/… chip is an interactive dropdown only for the signed-in owner, but nothing ever handed a browser the login it needed — the Worker could *redeem* a `phoenix_ticket` cookie yet nothing *minted* one, so opening your own link left the chip a static cue. Now the share Worker mints a short-lived, single-use, self-signed login ticket at `POST /__ticket` (authenticated by the caller's Phoenix bearer — it grants nothing the caller didn't already have, and is domain-separated from the identity cookie so neither can be replayed as the other), and `share open` appends it to your page URL so the browser trades it for the `__share` cookie and the chip becomes a live control. Managed (Phoenix) endpoints only; run `agents artifacts share update` once to redeploy a Worker that predates the mint route. `agents artifacts share visibility <target> <level>` remains the no-browser way to re-scope in place. Source: `cli/src/commands/share.ts`, `cli/src/lib/share/worker-template.ts`.
+
+- **The new human task taxonomy actually applies to existing sessions now.** The traces topic classifier's output changed (Feature work / Bug fixes / Refactor / … in 1.22.54), but `classifyTopic`'s result is cached per-session in `session_topics` keyed by `SESSION_TOPIC_EXTRACTOR_VERSION` — which wasn't bumped, so every already-classified session stayed a cache hit at v1 with its old `Engineering`/`Operations` label and `agents traces sync` kept re-uploading the *old* labels. Bumped the version 1→2 so every session re-classifies with the new taxonomy on the next sync, and the Evals console treemap reflects it. Source: `cli/src/lib/session/db.ts`.
+
+- **`agents view claude` shows live session + week usage bars again on a personal device (RUSH-2392).** A foreground `agents view` at a TTY on a `personal` device now falls through to the interactive Claude login for the usage read — the only credential carrying the `user:profile` scope the usage endpoint needs — so `agents view --refresh` repopulates the session (5h) + week (7d) window for every signed-in account instead of showing `S: █████ unavailable` on idle homes. `3f3554c51` (RUSH-1822) had removed that fallback for *every* caller to stop the daemon's unattended usage/auth-health loops from firing the interactive token at Anthropic and getting the fleet logged out; that guarantee is intact — the read is now gated by `allowInteractiveUsageLogin(role, isTTY)`, so every background caller (daemon usage warm, auth-health probe, watchdog) and every `--json`/piped reader stays setup-token-only and default-closed. #2987's blanket-wording change was treating the symptom; this restores the data. A usage read still never *refreshes* an access token — an expired interactive login reports `expired-credential`. Source: `cli/src/lib/accounting/usage.ts`, `cli/src/commands/view.ts`, `cli/docs/secrets.md`, `cli/docs/specifications.md`.
+
+## 1.22.54
+
+- **`agents accounts mint claude` (also `agents auth mint claude`) mints a
+  setup-token and seeds it — the first-class close of the mint-auth recipe
+  (PHNX-2364).** `claude setup-token` is driven through the same injectable PTY
+  driver `agents fleet login` uses; the authorize URL is opened on this machine;
+  the captured value is accepted only when it is a single-line `sk-ant-oat01-…`
+  token (the #1767 TTY-banner capture is refused). The command seeds a named
+  provider account (policy never) for `agents run --account` / `agents accounts
+  sync` **and** the reserved FILE-BASED `auth` bundle keyed per email, which
+  usage/probe reads. `--token-stdin` skips the browser dance; `--fleet` /
+  `--device` syncs both bundles to workers. `--json` (including `--code --json`)
+  emits only the machine-readable result on stdout — progress URLs are
+  suppressed, matching `agents fleet login`. Native rotating OAuth is never
+  copied. Other harnesses fail loud (`agents fleet login` for device-code,
+  `agents accounts add` for API keys). `agents setup accounts` surfaces the
+  same step in the onboarding hub. Source: `cli/src/lib/auth-mint.ts`,
+  `cli/src/commands/auth-mint.ts`, `cli/src/commands/setup-accounts.ts`.
+
+- **Reserve the `auth` secrets bundle as file-backed (PHNX-2365 / SEC-GAP-3).**
+  `agents secrets create/import auth` now forces the file backend and fails
+  loud on keychain or vault, instead of letting a keychain-backed `auth`
+  bundle be silently ignored by usage/probe. `resolveClaudeSetupToken` throws
+  the same error rather than returning null, and `agents doctor` emits
+  `auth-bundle-wrong-backend`. Source: `cli/src/lib/secrets/bundles.ts`,
+  `cli/src/lib/claude-account-token.ts`.
+
+- **Auto-sync the reserved `auth` bundle across the fleet (PHNX-2371).**
+  File-backend `secrets export --device` no longer forwards
+  `AGENTS_SECRETS_PASSPHRASE` (that keyed remotes to a secret their daemons
+  lacked while still printing "Imported N key(s)"). Import and remote push
+  now read-back-verify decryptability. The daemon `auth-sync` service, plus
+  `fleet apply` and `repo push/pull user`, push a local file-backed `auth`
+  bundle to pinned devices that lack it. Source: `cli/src/lib/secrets/reserved-sync.ts`,
+  `cli/src/lib/secrets/remote.ts`, `cli/src/lib/daemon/auth-sync-service.ts`.
+
+- **The menu-bar helper no longer permanently forgets refresh children after a crash (PHNX-2413).** Child ownership is persisted before spawn in a versioned, cross-process-locked registry, completed with PID/PGID/start-time/executable/argv identity, and recoverable from an unguessable provenance marker carried by the group-leading supervisor if the helper dies in the spawn-to-registration window. Reaping now retains individual ambiguous entries and registry I/O failures for retry, and deletes a child only after its process group is confirmed absent. Existing two-field records migrate conservatively. Source: `cli/menubar/Sources/MenubarHelper/ChildProcess.swift`.
+
+- **Honor an OpenCode custom-harness `--model` pin (PHNX-2577).** `agents run`
+  of a harness forked from opencode now forwards the pinned model as
+  `--model` on `opencode run`. OpenCode does not read `OPENCODE_MODEL`, so the
+  pin previously vanished and the host used its configured default. Source:
+  `cli/src/lib/profiles.ts`, `cli/src/lib/exec.ts`.
+
+- **`agents accounts` now fails with a clean CLI error instead of an uncaught Node stack (PHNX-2578).** A missing or locked `--from-secrets` bundle, or `inspect` of an unknown name, prints the user-facing message and exits 1. Ctrl+C at the add/set-key secret prompt still exits 130 with no error. Source: `cli/src/commands/accounts.ts`.
+
+- **`agents monitors add` no longer auto-starts the daemon when `daemon.enabled` is false (PHNX-2637).** The kill switch already stopped `routines add`/`start`/`catchup` and webhook auto-start; `monitors add` called `startDaemon()` directly and brought the daemon up (and wrote the systemd autostart symlink) on a box whose config disabled it. Auto-start now goes through the same `assertDaemonEnabled()` gate: the monitor is still created, the refusal names `agents daemon enable`, and the engine-pickup wait is skipped. Source: `cli/src/commands/monitors.ts`.
+
+- **Unpinned dispatch no longer dies on a logged-out default version (PHNX-2685).** Version selection now consults per-device auth state: a logged-out (or revoked) workspace/global default yields to a signed-in sibling on the execution device instead of spawning into a credential-less home, and fails loud naming each excluded version when nothing is signed in. `--strategy pinned` still forces a *rate-limited* default; an explicit `@version` pin is unchanged. Off macOS, a Claude home whose `.credentials.json` is missing (and which has no setup-token) reports signed out even when leftover `.claude.json` still names an email. Source: `cli/src/lib/accounting/rotate.ts`, `cli/src/lib/agent-spec/agents.ts`, `cli/src/commands/exec.ts`.
+
+- **Codex `permissions list` now shows deny rules, and a later apply with no deny clears them (PHNX-2703).** `toCanonical` used to skip `.codex/rules/agents-deny.rules`, so `agents permissions list codex` omitted every forbid the writer had already emitted. The reader now inverts that file, and the writer deletes it when a later apply has an empty deny so a removed forbid does not persist. Source: `cli/src/lib/permissions-registry.ts`, `cli/src/lib/permissions.ts`.
+
+- **Content search returns indexed transcripts the listing page missed (PHNX-2767).** `agents sessions "tmux pane"` intersected FTS hits with the in-memory pool (cwd-scoped, default-capped at 50), so grep-visible project transcripts dropped out and the query returned 0. FTS hits are now unioned with the pool and hydrated from the index when the page does not already hold them. `--project` / `--agent` / `--routine` still apply after that union, so a content hit outside the requested scope does not reappear as a multi-match. Source: `cli/src/lib/session/discover.ts`, `cli/src/commands/sessions.ts`.
+
+- **A non-ASCII share title / `--label` / `--meta` value now publishes in full instead of degrading to `(unnamed)` or dropping glyphs (PHNX-2786).** `publishToEndpoint` still sends the latin1-safe folded value in `x-share-<field>` (so an already-deployed Worker keeps rendering exactly as before — the ByteString crash stays fixed), and now ALSO sends a percent-encoded `x-share-<field>-u` companion plus an `x-share-encoding: percent` opt-in whenever the fold was lossy. An updated Worker (`agents artifacts share update`) prefers the decoded companion, so a Japanese/Arabic/Hindi title or an emoji renders as written; a Worker that predates the scheme ignores the unknown headers and folds gracefully. `--meta` rides its whole raw object in one percent-encoded `x-share-meta-u` companion. Source: `cli/src/lib/share/publish.ts`, `cli/src/lib/share/worker-template.ts`.
+
+- **Claude Code's native per-project memory now survives an agent version upgrade (PHNX-2817).** `getVersionHomePath` gives every installed Claude version its own isolated HOME, so `.claude/projects/<project-key>/memory/*.md` — the freeform notes Claude writes into itself, distinct from the `agents memory` resource — was a THIRD, unmanaged per-version copy: a note written under one version was invisible under another (empty dir, no symlink, no copy). Every version home's copy is now a symlink into one canonical dir shared across versions for that project, wired into the same sync path as `agents memory` (`agents sync` / `agents run` / `agents doctor --fix`); a pre-existing real directory's content is migrated into the canonical dir once instead of discarded. Source: `cli/src/lib/memory.ts`, `cli/src/lib/installations/versions.ts`.
+
+- **`agents monitors` `--run` no longer records `ok` just because the agent
+  exited 0 (PHNX-2842).** A fire's frozen `ok` was reconciled against the run's
+  later status (RUSH-2690), but `completed` still counted as success — so a
+  merge-on-green monitor whose agent ran, hunted the fleet, and never merged
+  showed `ok` while the PR stayed OPEN. `run`/`routine` actions now take an
+  optional `postcondition` (CLI: `--postcondition <cmd>`, YAML:
+  `action.postcondition`) — a shell command, `{event}` interpolated, that must
+  exit 0 after the run settles. `agents monitors runs`/`view` then show `no
+  effect` (not `ok`) when it fails, and persist the result on the fire record.
+  `--run` without a postcondition still records `ok` on `completed` and warns
+  at add time. Source: `cli/src/lib/monitors/{state,config,engine}.ts`,
+  `cli/src/commands/monitors.ts`.
+
+Provider accounts created with `accounts add` now resolve silently in headless
+`--account` launches on macOS. Their `policy never` credentials are stored
+without a biometry ACL and are read through the policy-aware secrets bundle
+path instead of being rejected by the raw-keychain Touch ID guard.
+
+- **`agents ssh <box> agents browser …` is gated by `browser.remote-control` (PHNX-3065).** The `--device` passthrough already stamped `AGENTS_FLEET_REMOTE=1` so the far-side consent gate could refuse a drive when remote-control is off. `agents ssh` built its invocation with only askpass vars in the local env — which OpenSSH does not forward — so a browser drive over ssh skipped the gate entirely. `buildSshInvocation` now prefixes an `agents browser` / `ag browser` / standalone `browser` remote command with the same `markFleetRemote` helper the fan-out uses (`env AGENTS_FLEET_REMOTE=1 …` on POSIX, `$env:AGENTS_FLEET_REMOTE='1'; …` on PowerShell). Non-browser commands and interactive logins stay unmarked. Source: `cli/src/lib/devices/connect.ts`, `cli/src/lib/hosts/passthrough.ts`.
+
+- **Feed terminal answers now write a resolution tombstone (PHNX-3074).**
+  The TypeScript `recordAnswer` / `removeBlock` paths already recorded
+  `resolutions/<id>.json` before clearing an open block, but the Python
+  `UserPromptSubmit` hook (the path that fires when a human types in the
+  TUI) unlinked the block with no tombstone. A later `reconcileAttention`
+  consumer would then resurrect that generation from a stale session
+  re-read at the same cursor. The hook now writes an `answered` tombstone
+  (generation + `sourceCursor` from the still-present block) before
+  unlink, matching the TS writer. Source: `cli/src/lib/feed/feed.ts`.
+
+- **Daemon PATH now includes `~/.rush/bin` and `~/.local/bin` (PHNX-3075).**
+  systemd/launchd pin a PATH that never sources a login shell, so `which rush`
+  failed inside the daemon even when an interactive shell on the same box
+  resolved `~/.rush/bin/rush`. Monitor `notify` actions and dispatched
+  `agents run` children inherit that PATH and silently never delivered
+  (`rush CLI not found on PATH`) while the watcher kept polling. Both
+  user-bin dirs now sit after the agents shim and Node dirs (so a
+  `~/.local/bin/agents` cannot shadow the daemon binary) and before the
+  platform system dirs. Source: `cli/src/lib/daemon/daemon.ts`.
+
+- **Kimi expired usage state says "run Kimi once" and `--json --refresh` exposes the refresh result (PHNX-3198).** An expired Kimi OAuth credential used to render "re-auth for usage", even though a normal Kimi launch refreshes its own token. The usage error now reads "run Kimi once". `agents view <agent> --refresh --json` now actually forces a live refresh and includes a `usageError` field on each version so programmatic consumers see why a snapshot is missing. Source: `cli/src/lib/accounting/usage.ts`, `cli/src/commands/view.ts`, `cli/src/lib/view-types.ts`.
+
+- **Share metadata can be corrected without republishing (PHNX-3278).** `agents artifacts share edit <target>` now sets/removes labels and merges, replaces, or removes validated arbitrary metadata through an authenticated Worker `PATCH`. The Worker streams the exact stored body back to R2 while preserving HTTP metadata, publication time, visibility, expiry, provenance, cover, and revisions, and deliberately creates no revision. `agents artifacts share list --meta key=value` is repeatable and filters exact metadata values in both human and `--list-json` output. Reserved keys and missing targets fail loudly.
+
+- **Fail loud when codex's Linux sandbox can't start, instead of landing zero tools (PHNX-3285).**
+  Codex ≥0.146 sandboxes its `read-only` and `workspace-write` runs on Linux with a
+  bundled bubblewrap that needs an unprivileged user namespace. On Ubuntu 23.10+
+  (`kernel.apparmor_restrict_unprivileged_userns=1`) that's denied, so bwrap dies with
+  `bwrap: setting up uid map: Permission denied` and a **headless** codex run — an
+  `agents teams` codex teammate, or `agents run codex`, always headless + sandboxed —
+  burned a turn and wrote nothing while still reporting a completed turn. `agents run`
+  now preflights the box before spawning a headless sandboxed codex and **fails loud**
+  with the one-time fix, rather than silently under-delivering. The preflight is scoped
+  to codex + Linux + a headless + sandboxed (non-`skip`) run — an interactive TUI, a
+  `--mode skip` (no-sandbox) run, macOS/Windows, and every other harness are untouched,
+  and the intended `auto`=workspace-write + `approval_policy=never` config is preserved,
+  never downgraded to `danger-full-access`. `cli/scripts/enable-codex-sandbox.sh`
+  re-enables unprivileged userns on a box (sysctl drop-in, idempotent, self-verifying)
+  so codex's sandbox works with its isolation intact; run it once per fleet worker.
+  Source: `cli/src/lib/linux-userns.ts`, `cli/src/lib/exec.ts` (`codexSandboxPreflight`),
+  `cli/scripts/enable-codex-sandbox.sh`.
+
+- **New `hook-manifest` self-heal check — a hook registered at an unresolvable path no longer fails silently.** `resolveHookScriptPath` only resolves a manifest `script:` under `<root>/hooks/`, and `resolveContainedHookPath` rejects any candidate escaping that root; an entry pointing anywhere else returns `null` and the hook is dropped with no error, no warning, and no trace in `agents doctor`. This is how `main-branch-guard` — declared in `agents.yaml` as `rules/subrules/truly-agentic-git-workflow/main-branch-guard.sh`, authored and covered by a 100+ case suite — reached zero of 25 settings files across three machines, and stayed there until four agent sessions had already written into a primary checkout it exists to prevent. The check walks the manifest, resolves every relative `script:`, and reports each one that resolves to nothing. Detect-only: guessing where a script was meant to live could wire the wrong file into a `PreToolUse` gate, so it names the broken entry instead. Absolute scripts (subrule-composed hooks, which bypass the `hooks/` resolver) and `enabled: false` entries are skipped. Source: `cli/src/lib/self-heal/checks/hook-manifest.ts`. (PHNX-3312)
+
+- **Device-scope is now the DEFAULT for new config keys, not a hardcoded set (PHNX-3315).**
+  Routing a `Meta` key used to hinge on a decorative `Record<keyof Meta, 'central' | 'device'>`
+  string map whose values nothing consumed — the real split was a hand-written
+  destructure, so a newly added key that nobody wired silently landed in the synced
+  top-level `agents.yaml` (`central`), the very trap behind the recurring per-box
+  churn and key-loss. Classification is now an OPT-IN `CENTRAL_META_KEYS` allowlist
+  that DRIVES routing: a key not explicitly marked fleet-shared is device-scoped by
+  default and round-trips through this box's `devices/<host>/agents.yaml` under its
+  own name, with no bespoke wiring — so a slipped-through key can never leak to the
+  shared file. A compile-time check keeps the classification exhaustive (a nudge,
+  not a safety gate — the runtime default is still the safe per-box file), and a
+  foreign key an older CLI does not model but a newer one wrote to central is left
+  in place and preserved verbatim (never relocated). Behavior-identical for every
+  existing key. Source: `cli/src/lib/state.ts`.
+- **`agents sync status` now surfaces config drift — a box that hasn't drained its device-scoped state (PHNX-3315).**
+  The one-shot fold-and-delete migrations (P1's frozen-header heal + central
+  `browser:` tombstone drain; P2's `fleet.discovery`/`fleet.ignored`, `hosts:`, and
+  device-scoped `accounts:` folds) run on config access, so a converged box shows
+  nothing — but a box that never re-synced kept carrying that state centrally, and
+  it was INVISIBLE: the report only showed per-agent "N missing", so the un-drained
+  box was found the hard way, as a mystery `agents repo pull` conflict. A distinct
+  drift line now flags (1) a stale top-level `agents.yaml` header (!= the current
+  header) and (2) any lingering central `fleet` / `hosts` / `accounts` (device-scoped)
+  / `browser` block that should have folded into the device doc. The detector is
+  read-only and never triggers the migration; the machine-readable
+  `UnifiedSyncStatus` gains a `config` field. Source: `cli/src/lib/config-drift.ts`
+  (new), `cli/src/lib/{sync-status,state}.ts`, `cli/src/commands/status.ts`.
+
+- **Root `--help` now surfaces the measured front-door groups and points to the full surface (PHNX-3320).** `agents --help` renders the ten most-used groups (Quick start: setup, view, run, sessions; Most-used: teams, browser, secrets, devices, accounts, add) and a pointer to `agents --help-all`, which lists all 69 command groups. Previously 29 groups were never mentioned on root help. Source: `cli/src/lib/help.ts`, `cli/src/cli/command-registry.ts`, `cli/src/bootstrap.ts`.
+
+- **`agents focus <id> --attach-only` now names the real session id in its recovery hint when the live row has not registered one yet (PHNX-3356).** A live IDE/plain-terminal session with no `sessionId` used to print the literal `agents sessions resume <id>` placeholder even though the caller already had the indexed id. Attach-only still refuses rather than forking. Source: `cli/src/commands/go.ts`, `cli/src/commands/focus.ts`.
+
+- **Every `agents insights` subcommand now honors `--json` / `--since` / `--by` (PHNX-3360).** These flags share their long names with the `insights` parent command, so commander bound them to the parent at parse time and the subcommand actions — which read their own `opts()` — never saw them: `--json` printed the human table (invalid for machine callers), `--by` fell back to the default agent grouping, and `--since` was ignored (7d default). The whole group is affected — `output`, `cost`, `mix`, `trends`, `recipes`, `query`, and the per-recipe leaves — and all now read `command.optsWithGlobals()`. Unblocks the `yc:workweave` shipped-output engine, which shells `agents insights output --by project --json`. Source: `cli/src/commands/output.ts`, `cli/src/commands/cost.ts`, `cli/src/lib/analytics/mix-commands.ts`.
+
+- **`agents sessions` content search now indexes what the agent ANSWERED, not just what you asked (PHNX-3363).** `session_text`'s extractor pushed only `role === 'user'` text — every harness parser's assistant branch recorded tokens/skills/tools but never the reply itself — so `agents sessions "<an assistant-only phrase>"` returned 0 hits even when the transcript on disk plainly had it. Every harness parser (Claude, Codex, Gemini, Rush, Hermes, Muse, Droid, Cursor) now accumulates the agent's answer text the same way it already accumulates the user's prompt text, into a new `session_text.assistant` FTS5 column with a lower BM25 weight than `content` (an equivalent user-prompt match still ranks first). A `scan_ledger.extractor_version` + `CONTENT_INDEX_VERSION` (`lib/session/db.ts`) lever makes the change-detector (`filterChangedEntries`) re-extract an already-indexed, byte-unchanged session on its next scan — the mechanism that backfills every existing session's assistant text without a destructive `DELETE FROM scan_ledger` (which would also drop the Claude/Codex resumable `parser_state`). `ftsSearch`'s FTS5-tier hit now carries a short bm25 `snippet()` excerpt (auto-picking the best-matching column), surfaced on `SessionMeta.snippet` and included, unlike `_matchedTerms`/`_bm25Score`, in `--json` output. Source: `cli/src/lib/session/db.ts`, `cli/src/lib/session/discover.ts`.
+
+- **`agents artifacts share visibility <target> <level>` changes a published page's visibility in place.** Until now the only way to re-scope an already-shared page (public ↔ unlisted ↔ me ↔ org) was a full re-publish or a delete. The new verb re-stamps only the visibility on the stored object: the slug — and so the URL — is preserved, the body is untouched, and (like `agents artifacts share edit`) it is a metadata-only rewrite that creates no revision. It reuses the delete target parser (full URL, `<user>/<slug>`, or a bare slug in your namespace) and the same `PATCH` metadata-edit route/client — visibility is a first-class edit field alongside `label`, never a `--meta` entry (`visibility` is reserved). `me`/`org` require a Phoenix session and fail loud with an `agents auth login` hint when signed out; `org` is refused on a public-inbox email domain. A BYO endpoint whose deployed Worker predates the visibility edit fails loud (`agents artifacts share update`) rather than silently reporting success. **Adds a `visibility` field to the Worker `PATCH` route, so already-provisioned BYO endpoints must run `agents artifacts share update` to pick it up (their template reads `outdated` until then); the managed endpoint is updated by the release.** Source: `cli/src/commands/share.ts`, `cli/src/lib/share/worker-template.ts`, `cli/src/lib/share/publish.ts`.
+
+- **The cross-platform CI matrix moved off the release path to a nightly lane (PHNX-3237).** The six-job `ci.yml` matrix (ubuntu + macOS + Windows × Node 22/24) used to fire on every `release/**` branch — 16-53 min of macOS-10×/Windows-2×-billed work that gated nothing: it is not a required check, and `release.sh` gates the merge on `test` + `gitleaks` and the publish on an exact-tree attestation, never this matrix. Worse, a macOS-only failure had it red on every recent release, adding a false "release is failing" signal. It now runs on a nightly schedule plus manual `workflow_dispatch`, so cross-platform regressions are still caught without putting slow, billed, non-gating work on the release. Source: `.github/workflows/ci.yml`, `.github/workflows/ci.test.ts`.
+
+- **A release-tree attestation can now inherit the suite result instead of re-running the full suite (PHNX-3237).** An ordinary release ran the ~13k-test suite twice — once for the default-branch tree, once for the `chore(release)` commit tree — even though the second differs from the first only by the version bump, the folded changelog, and the regenerated command-index. New `release-attestation.sh derive --base <green-attestation.json> --tarball <release.tgz>` mints the release-tree record by inheriting the base's suite pass, verifying that the tree diff touches **only** `package.json`, `.changelog/**`, `CHANGELOG.md`, and `docs/command-index.{md,json}` — it fails closed on any other changed path, so a code change can never ride a stale pass. `release-attestation-produce.sh --inherit-suite-from <base.json>` uses it to skip the suite while still building + packing the real release-tree tarball, cutting the second full-suite run per release. The derived record inherits the base's lockfile/policy/toolchain identity, which the allowlist proves are byte-identical to the release tree's, so the release's `require()` still keys to it exactly. Source: `cli/scripts/release-attestation.sh`, `cli/scripts/release-attestation-produce.sh`.
+
+- **`agents view` names why a Claude usage bar is empty instead of printing a blanket "usage unavailable" (#2987).** Three distinct states shared one generic label, so an operator chasing empty bars was sent to `claude setup-token` for a remedy that cannot work. (1) A signed-in Claude account with no provisioned setup-token reported the shared `usageNoCredentialError` — "sign in, or provision a long-lived token" — advice whose first half the usage path will never honour: a read-only caller resolves only a file-based setup-token and never the interactive login (RUSH-1822), so an account that IS signed in still reads as unreadable. It now reports `usage unavailable (no usage credential)` and states both constraints, including that a setup-token cannot read usage either (RUSH-2392). (2) `headless-scope` was listed with the generic bucket in `formatUsageErrorKindLabel`, so the RUSH-2392 phrase appeared only on the surface that also passes the `headless` flag — every other caller printed "usage unavailable" for the same account. It now renders `usage unavailable (headless)` from the classified kind alone. (3) The read-only cache-miss sentinel (`'stale'`, now the exported `USAGE_NOT_COLLECTED_MARKER`) had no classification arm and fell through to `'rejected'`, so a cold cache — no request made, nothing failed — rendered as a failure; it classifies as `not-collected` and renders `usage pending`. Source: `cli/src/lib/accounting/usage.ts`, `cli/docs/secrets.md`.
+
+- **`agents insights` now breaks the `Bash` lump down by binary.** The tool mix used to render every shell call as one undifferentiated `Bash` bar (and one `failed tool loop: Bash` line), which said nothing about *what* ran. Two new sections split it by the actual executable + subcommand, reusing the existing `bucketKey` classifier: **Shell commands** (`git commit`, `gh pr`, `agents ssh`, `find`, `ssh→git pull`, …) and **Shell command failures** (which binary was running when a tool loop failed). It is cross-harness — keyed on the command string, which Codex's `exec_command` carries too, not just Claude's `Bash`. The Actions block also now prints a one-line pointer to drill a sample session id into its full timeline (`agents sessions trace <id>`); the report itself stays aggregate by contract (SES-IF-4c). Source: `cli/src/lib/session/insights.ts`, `cli/src/commands/insights.ts`.
+
+- **`release.sh --apply` from a non-interactive shell now fails loudly instead of exiting 0 having published nothing (PHNX-3176).** The confirmation gate reads `[y/N]` from stdin; with no TTY (a backgrounded run, a sandbox, `< /dev/null`) `read` gets EOF, the prompt default-declines, and the script exited **0** having done nothing — no attestation, no PR, no tag, no publish. A caller that backgrounded the release, checked `$?`, and saw 0 then believed a release shipped when none did, which is exactly how a silent version gap opens. `--apply` without a TTY and without `--yes` now aborts with a non-zero exit before any work, naming `--yes` as the sanctioned non-interactive path. The internal `--home-base-phase` / `--orchestration-phase` re-execs are exempt (they inherit the already-checked stdin). Source: `cli/scripts/release.sh`.
+
+- **The release attestation no longer dead-loops on a changed `computer-mac` helper (PHNX-2943).** `release-attestation-produce.sh` never rebuilds `computer-mac` (it is signed on a separate macOS path), so when its source drifted it died telling the operator to run `publish-computer-helper-mac.sh` and re-run — but that script recorded nothing, so the re-run hit the identical error forever (workaround used live cutting 1.22.43). The publish script now uploads a `computer-mac-input-digest.txt` sidecar naming the exact source it built from, and the producer records the published binary against the current source **only after** that sidecar matches (verifying the downloaded zip against its `.sha256`). A mismatch, a missing sidecar, or an undownloadable release fails closed with the exact publish command, so a stale binary can never be attested against changed source. Source: `cli/scripts/release-attestation-produce.sh`, `cli/scripts/publish-computer-helper-mac.sh`.
+
+- **`release.sh` now refuses to fold the changelog queue when an earlier release's version-bump PR is still open, closing a cross-version note-misattribution (PHNX-3084).** The decoupled release (RUSH-2395) merges the version-bump PR asynchronously after publish; if that merge is stuck on a CHANGELOG conflict, v1.2.3's `.changelog/next/*` fragments stay queued on `main`, and a later `release.sh 1.2.4` re-read them and folded v1.2.3's notes under v1.2.4. The same-target `STUCK_BUMP_PR` retry only ever queried `release/v<current-target>`, so it was blind to an OTHER version's stuck PR. Before folding, `release.sh` now detects any other open `release/v*` bump PR (via the new unit-tested `scripts/release-other-bump-prs.sh`) and fails loud with the exact merge command, rather than silently re-attributing an earlier version's release notes. Source: `cli/scripts/release.sh`, `cli/scripts/release-other-bump-prs.sh`.
+
+- **Shared images / videos / PDFs now get the attribution bar too, via a viewer page (PHNX-3332).** The attribution bar only injects into HTML; a directly-shared non-HTML asset had no "shared by / visibility" chrome. Now a **browser** navigating to a shared image, video, audio, or PDF gets a lightweight viewer page — the same attribution bar on top, the asset centered below. A **non-browser fetch** (Accept without `text/html`: an `<img src>`, an OG crawler, curl) still gets the **raw bytes**, so embeds and social previews are never broken; the viewer's own media element points back at the asset with `?raw` (which also re-runs the me/org gate, so a private asset stays private inside its own viewer). Non-viewable types (JSON, arbitrary downloads) are served raw. Source: `cli/src/lib/share/worker-template.ts`.
+
+- **The share attribution bar now always shows the sharer's avatar.** Every shared page (and every asset viewer page) renders an avatar in the bar next to "Shared by …": a coloured initials circle derived from the handle, always present, so a share is never faceless — especially useful for an org/company share where knowing *who* posted it matters. When the sharer is signed in, the CLI stamps a Gravatar (keyed on a SHA-256 of the lowercased email — only the hash lands in public metadata, never the raw address) so a real profile photo layers over the initials; if the user has no Gravatar the photo request 404s and the bar cleanly falls back to the initials circle (`onerror`, honoured because the share page sets no CSP). Source: `cli/src/lib/share/worker-template.ts` (render + `x-share-avatar` → `customMetadata.avatar`), `cli/src/lib/share/publish.ts` (`resolveShareAvatar`). Deployed by re-running `agents artifacts share update`; a hosted-photo pipeline for users without a Gravatar is tracked as a follow-up.
+
+- **Shared pages now show page stats and let the owner change visibility inline.** The attribution bar injected on every shared HTML page gained a right-side stats cluster — `👁 <n> views · updated <rel>` — where views is a per-slug visitor count (owner views and `?raw`/embed fetches are not counted) and the relative time comes from the page's last write. For the page's owner (the signed-in viewer whose handle is the namespace), the visibility chip becomes a live control: click it for an inline dropdown of Public / Unlisted / Only you / Anyone at your org, pick a level, and the bar PATCHes the same in-place edit route `share visibility` uses (with `credentials:'include'`), flipping the chip optimistically and reverting with the server's error text on failure (e.g. org from a public-inbox domain). Everyone else keeps today's static read-only cue. The view counter is a separate `__views/<path>` R2 object, so counting a view never rewrites the page (which would corrupt "last updated"). Source: `cli/src/lib/share/worker-template.ts` (`renderAttributionBar` owner control + stats, `readViews`/`writeViews`, `gateVisibility`, owner-cookie write principal in `authorizeWrite`). Because this changes the Worker template, a deployed endpoint reads `outdated` until its owner redeploys with **`agents artifacts share update`** — a pure Worker update, no new bindings.
+
+- **`agents artifacts share list` can now show the owner's hidden pages.** The default remains the public gallery (`--scope public`). Pass `--scope unlisted|me|org` or `--all` to include pages that are hidden from the public listing; the CLI sends the owner's bearer and a `scope=mine` hint to the Worker's JSON listing route, which returns hidden pages only after verifying the caller owns the namespace. Each human row now shows the page's visibility so public vs hidden is obvious at a glance. Source: `cli/src/commands/share.ts` (`--scope`/`--all` filter, owner bearer forwarding, visibility column), `cli/src/lib/share/worker-template.ts` (`resolveListingScope` + owner-gated hidden inclusion in `renderListing`). The Worker change only takes effect on a live endpoint after its owner runs `agents artifacts share update`.
+
+---
+type: fix
+---
+
+`agents sessions trace` now recognizes a session's shell steps consistently across every surface. The "is this tool a shell command?" test lived as six hand-synced copies that had drifted apart — the tool-call indexer treated Codex's `exec`/`execute`/`run_command` as shell, but the trajectory model, the directory-touched scan, and both the HTML and stream renderers each used a narrower or differently-cased list. They now share one case-insensitive `isShellExecTool` predicate (`shell-programs.ts`), so a Codex or Droid shell step is colored, program-resolved, and counted the same as Claude's `Bash` everywhere the trace reads it.
+
+- **Phoenix Evals topic buckets now read as human task types, not five generic labels.** The session-topic classifier (`agents traces sync`) collapsed every code session into `Engineering` and every ops session into `Operations`, so the console treemap showed coarse, robotic labels. `classifyTopic` now emits the taxonomy the approved console mockup always intended — **Feature work · Bug fixes · Refactor · Debugging · Code review · Release · Blog & docs · Fleet / ops** — as an ordered rules table (still metadata/tool-mix only, no transcript read), keyed within the five stable `TraceTopicGroup` groups so the treemap grouping and existing consumers don't move. One-time: a session previously bucketed as `engineering`/`operations`/`content` re-keys on next sync, so `bucketHistory`/`driftSignals` show a single-day discontinuity the day this ships, then track the new keys. Source: `cli/src/lib/traces/classify.ts`.
+
 ## 1.22.53
 
 - **Custom-harness runs launched via a profile now show their real harness name in agents sessions instead of 'claude' (PHNX-2935).**

package/README.md

@@ -194,7 +194,7 @@ agents run claude@ --device auto        # pick the device, then choose there
 agents run claude@ --device yosemite-s0 # choose from one device's accounts
 ```
 
-`--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one. When a Claude run reports a session limit, agents-cli records the stated reset time, shows `session-limited` in `agents view`, and excludes that account until the reset. When every account is rate-limited, the run exits nonzero naming each excluded account and the earliest window reset (use `--strategy pinned` to force the default) -- it never launches into an exhausted account.
+`--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one. When a Claude run reports a session limit, agents-cli records the stated reset time, shows `session-limited` in `agents view`, and excludes that account until the reset. When every account is rate-limited, the run exits nonzero naming each excluded account and the earliest window reset (use `--strategy pinned` to force a rate-limited default) -- it never launches into an exhausted account. A logged-out default is never forced: unpinned dispatch picks a signed-in version on the execution device instead of dying on a credential-less default home.
 
 ### Don't care which harness? `agents run auto`
 
@@ -523,7 +523,7 @@ agents add claude@2.0.65     # Install a specific version
 agents add codex@latest       # Install latest
 agents add codex@oldest       # Install the oldest published version
 agents view                   # See everything installed
-agents accounts add work --provider anthropic --auth setup-token
+agents accounts mint claude --account work   # mint a setup-token into a named account
 agents run claude --account work
 ```
 
@@ -959,6 +959,9 @@ agents browser refs                  # Get interactive element refs
 agents browser click 42              # Click element ref 42
 agents browser type 15 --text "hello"  # Type into element ref 15
 agents browser screenshot            # Smart resizing, token-efficient
+agents browser record start --fps 10 --duration 40
+# Drive the page, then finalize a playable WebM under the task's recordings/ dir.
+agents browser record stop
 agents browser tabs                  # List tabs open for the current task
 agents browser tab focus tab123      # Switch focus to another tab
 agents browser done                  # Close task's tabs when finished
@@ -973,6 +976,11 @@ printf '%s\n' \
   | agents browser stream --task "$AGENTS_BROWSER_TASK"
 ```
 
+Recording resolves ffmpeg automatically. It reuses a usable binary on `PATH` or
+under `~/.agents/.cache`, and when none exists it installs through Homebrew on
+macOS, apt on Debian/Ubuntu, or the available platform package manager. If the
+automatic path cannot run, the error names the exact manual install command.
+
 ### Why this works where Playwright fails
 
 Playwright and Puppeteer spin up fresh browser instances with automation flags. Sites like LinkedIn, Google, and most finance apps detect and block them immediately.
@@ -1070,6 +1078,8 @@ Distinct from **Accounts** below: this is *your human identity*; those are the *
 Give a provider credential a durable name once, reuse it everywhere -- across harnesses, across machines.
 
 ```bash
+agents accounts mint claude                  # drive `claude setup-token`, seed a named account + reserved auth bundle
+agents accounts mint claude --token-stdin    # already have a token
 agents accounts add work --provider anthropic --auth setup-token
 agents accounts add gateway --provider openrouter --auth api-key \
   --from-secrets openrouter.ai:OPENROUTER_API_KEY  # import from an existing secrets bundle
@@ -1083,6 +1093,8 @@ agents run claude --account work
 agents harness add deepinfra --account deepinfra
 ```
 
+`agents accounts mint claude` (also `agents auth mint claude`) is the first-class replacement for the mint-auth recipe: it drives `claude setup-token` in a PTY, captures a well-formed `sk-ant-oat01-` token, and seeds both the named account and the reserved file-based `auth` bundle that usage/probe reads. Native rotating OAuth is never copied.
+
 One provider account **is** one `agents secrets` bundle -- `agents accounts add` creates it with secrets policy `never`, so a background agent launch on that account never raises Touch ID. `agents accounts` (no subcommand) lists provider bundles next to harness-native signed-in identities so you see both kinds of credential together; `accounts list` / `inspect <name>` / `set-key <name>` (rotate) / `rename` / `remove` manage a bundle by its stable id, independent of its current label. `accounts switch <harness>` is the fast picker over that default -- it writes the same binding as `set-default`, and balanced rotation already honors it.
 
 Harness-native OAuth logins (Claude Code's own `/login`, `codex login`, and so on) stay exactly where the harness put them -- agi-cli discovers and displays them but never copies, renames, or converts them into a provider bundle. Native `accounts name` / `attach` is only for harnesses agents-cli can isolate today (claude, codex, grok; muse when an email is present). A device-scoped login (kimi, droid, …) is refused with a named reason; provider `accounts add --provider` is unrestricted. Native **labels** (`agents accounts label codex personal`) bind to a stable identityKey on the central account row in `agents.yaml`, which `agents repo push/pull` already syncs fleet-wide, so `codex#personal` selects the same login on every box. `accounts sync <name> --device <device>` is the only way a **provider** account credential crosses machines, and it's explicit: nothing copies OAuth automatically. Selection order for a run is explicit `--account`, then `accounts set-default` / `switch` for that harness, then the harness's native/balanced account behavior.
@@ -1152,6 +1164,7 @@ agents routines add daily-digest \
   --prompt "Review yesterday's PRs and summarize key changes"
 
 agents routines list                   # All jobs + next run times
+agents routines status                 # Scheduler health + next fires (add --json for owner device, last fire, last error, in-flight run per routine)
 agents routines run daily-digest       # Test it now, ignore the schedule
 agents routines logs daily-digest      # Last execution — status + report (add --full for raw stdout)
 agents routines runs daily-digest      # Every attempt, including blocked/skipped pre-session runs
@@ -1219,7 +1232,7 @@ on `SIGHUP reload`.
 There is no `agents daemon jobs` -- scheduled work is always `agents routines`
 (see `agents routines stats` for per-routine failure detail). `disable` is a
 device-local kill switch: with it set, `routines add`/`routines start`/
-`routines catchup`/webhook triggers stop auto-starting the daemon, mirroring
+`routines catchup`/`monitors add`/webhook triggers stop auto-starting the daemon, mirroring
 `systemctl disable` -- `agents daemon start` still works as the explicit
 override.
 
@@ -1242,6 +1255,12 @@ agents monitors add ci-red \
   --run claude --prompt 'CI failed: {event}. Diagnose and fix.' \
   --device yosemite-s0
 
+# Merge-on-green: ok only if the PR actually merged, not just because the agent exited 0
+agents monitors add merge-1682 \
+  --poll 'gh pr view 1682 --json state --jq .state' 2m --match OPEN \
+  --run claude --prompt 'Rebase-merge #1682: {event}' \
+  --postcondition 'gh pr view 1682 --json state --jq .state | grep -qx MERGED'
+
 # A fleet box goes unreachable or overloaded -> notify (watch the fleet itself)
 agents monitors add box-down --watch-device mac-mini --on-change --notify telegram
 
@@ -1253,7 +1272,7 @@ agents monitors test ci-red    # Dry-run: evaluate the source once, show what it
 agents monitors list           # Every monitor: source, owner device, last fired
 ```
 
-Sources: a command's stdout (`--watch` / `--poll`), an HTTP endpoint (`--poll-http`), a file (`--watch-file`), or a fleet device's reachability + load (`--watch-device`). Push sources -- a signed webhook (`--on`) and a WebSocket (`--ws`) -- are accepted today and delivered through a receiver wired in a follow-up. Conditions: fire on any change (`--on-change`), on a regex (`--match`), or `--every` tick -- deduped by a native state store, so a monitor stays silent until something *actually* changes. Actions: `--run <agent>` (the event is injected into the prompt as `{event}`), `--routine`, `--notify`, or `--webhook-out`. Pin a monitor to one owner device with `--device` (exactly-once), or offload the action elsewhere with `--run-on`. Runs in the routines daemon; `agents monitors pause` / `resume` any time.
+Sources: a command's stdout (`--watch` / `--poll`), an HTTP endpoint (`--poll-http`), a file (`--watch-file`), or a fleet device's reachability + load (`--watch-device`). Push sources -- a signed webhook (`--on`) and a WebSocket (`--ws`) -- are accepted today and delivered through a receiver wired in a follow-up. Conditions: fire on any change (`--on-change`), on a regex (`--match`), or `--every` tick -- deduped by a native state store, so a monitor stays silent until something *actually* changes. Actions: `--run <agent>` (the event is injected into the prompt as `{event}`), `--routine`, `--notify`, or `--webhook-out`. A `--run`/`--routine` action can take `--postcondition '<cmd>'` — a shell command that must exit 0 after the agent settles, otherwise `agents monitors runs` records `no effect` rather than `ok`. Pin a monitor to one owner device with `--device` (exactly-once), or offload the action elsewhere with `--run-on`. Runs in the routines daemon; `agents monitors pause` / `resume` any time.
 
 ---
 
@@ -1270,8 +1289,14 @@ agents traces setup                                         # provision the priv
 agents artifacts share plan.html --slug fleet --expire 30d  # → https://<base>/fleet
 agents artifacts share plan.html --label "Q3 fleet plan" --meta kind=plan   # human title + structured metadata
 agents artifacts share plan.html --json                     # URL object for plan-render hooks
-agents artifacts share list --agent claude                  # everything published, filterable
+agents artifacts share list --agent claude                  # public gallery, filterable
+agents artifacts share list --meta kind=plan                # exact, repeatable metadata filters
+agents artifacts share list --all                           # include hidden unlisted/me/org pages
+agents artifacts share list --scope me                      # just the owner-only pages
+agents artifacts share edit fleet --label "Final fleet plan" --meta status=final
 agents artifacts share revisions fleet                      # prior versions kept under a slug
+agents artifacts share visibility fleet me                  # re-scope a published page in place (public|unlisted|me|org)
+agents artifacts share open fleet                           # open your page signed in, so its in-page visibility control is live
 agents artifacts share status                               # show the endpoint
 agents artifacts unshare fleet                              # take a published link (+ its OG cover) down
 ```
@@ -1283,9 +1308,28 @@ Cloudflare account, bucket, or write token — and `share status` / `list` / `re
 / `unshare` talk to that same endpoint. The handle is the local-part of the signed-in
 email (`muqsitnawaz@gmail.com` → `muqsitnawaz`); the page slug is readable plus a
 short view-id. HTML is stored as one object: local images are inlined, `file://` TOC
-links become in-page hashes, so the published page is actually viewable. `--visibility unlisted` (hidden aliases
+links become in-page hashes, so the published page is actually viewable. The managed
+Worker lazily renders and caches the branded 1200×630 Open Graph card at `<slug>.png`,
+so publishing from Linux does not require a local Chromium; BYO endpoints keep the
+local screenshot fallback. `--visibility unlisted` (hidden aliases
 `--unlisted` / `--private`) is a capability URL: GET still works, the gallery hides it,
-and the Worker sends `X-Robots-Tag: noindex`. **BYO Cloudflare** remains: `setup` reads
+and the Worker sends `X-Robots-Tag: noindex`. `--visibility me` is visible only to
+you (the signed-in owner); `--visibility org` is visible to anyone at your email
+**domain** — derived from your own address, so it needs a **workspace** Google
+account and is refused on a public-inbox domain (`gmail.com`, `outlook.com`,
+`icloud.com`, …). Both need a Phoenix session and are identity-gated at read time (a
+stranger is redirected to sign in, then 404s). `share visibility <target> <level>`
+re-scopes an **already-published** page in place — the slug/URL is preserved and the
+body is untouched (a metadata-only change, like `share edit`, so no revision) — so you
+can promote a draft to `public` or pull a link back to `me`/`org` without re-publishing
+(`me`/`org` need a Phoenix session; `org` needs a workspace domain). The served page
+also carries an **in-page visibility control** — a chip you can switch right on the page
+— but it is interactive only for the signed-in owner, and a plain link has no login;
+`share open <target>` mints a short-lived, single-use login ticket and opens your page
+with it so the chip becomes a live dropdown. Sign-in is a
+single **Phoenix ID** (Google-only device-code OAuth, `agents auth login`) — see
+[`docs/share.md`](cli/docs/share.md) for the full identity + visibility model.
+**BYO Cloudflare** remains: `setup` reads
 a Cloudflare API token from your `cloudflare.com` secrets bundle (or `--token`), creates
 an R2 bucket, uploads a tiny Worker, and enables the free `*.workers.dev` subdomain (or
 maps `--domain share.example.com` when the token owns the zone). Writes are bearer-gated
@@ -1304,8 +1348,14 @@ captured automatically from the exec env and git — never invented, only sent w
 present. `--label`/`--title` names a share (else one is derived from the HTML
 `<title>`, frontmatter, or filename, with a nudge — never a blocking prompt); `--meta
 key=value` attaches structured metadata (`kind`, `project`, `ticket`, `status`, ...).
-`agents artifacts share list --agent <name> | --session <id> | --label-contains <substr>` filters
-by any of it, so the listing is a real "what have I shared" gallery, not just slugs.
+`agents artifacts share list --agent <name> | --session <id> | --label-contains <substr>
+| --meta <key=value>` filters by provenance, title, or exact structured metadata, so
+the listing is a real "what have I shared" gallery, not just slugs. By default it mirrors
+the public gallery; `--scope unlisted|me|org` (or `--all`) includes your hidden pages and
+marks each row with its visibility so you can tell public from private at a glance.
+`agents artifacts share edit <slug>` changes only the label/arbitrary metadata in place:
+the URL, exact body, HTTP metadata, publication time, visibility, expiry, provenance,
+cover, and revision history stay unchanged.
 Republishing an existing slug keeps the prior version as a revision by default
 (`--no-revision` to skip); `agents artifacts share revisions <slug>` shows the retained
 history, newest first.