diff --git a/.codex/skills/herdr-pre-release-audit/SKILL.md b/.codex/skills/herdr-pre-release-audit/SKILL.md new file mode 100644 index 00000000..d3a24d46 --- /dev/null +++ b/.codex/skills/herdr-pre-release-audit/SKILL.md @@ -0,0 +1,20 @@ +--- +name: herdr-pre-release-audit +description: Audit herdr release readiness by comparing commits since the base release against next-release changelog and docs. Use when asked to run or apply the repo's pre-release audit, validate docs/next before release, inspect issue refs that release CI will close, or finalize release docs for herdr. +--- + +# Herdr Pre-release Audit + +Use this skill only inside the herdr repository. + +Read `references/pre-release-audit.md` and follow its workflow. Treat it as the source of truth for: + +- choosing the release base ref +- inspecting first-parent history and merged PRs +- auditing `docs/next/CHANGELOG.md` +- auditing `docs/next/README.md` and staged website docs +- checking issue reference lines +- deciding when to run `just release-docs-check` +- producing the final release-readiness report + +Do not edit files during the audit unless the user explicitly asks to apply fixes. When applying fixes, keep changes scoped to the files named in the reference workflow. diff --git a/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md b/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md new file mode 100644 index 00000000..4858f598 --- /dev/null +++ b/.codex/skills/herdr-pre-release-audit/references/pre-release-audit.md @@ -0,0 +1,121 @@ +--- +description: Audit next-release docs and changelog before release +--- +Audit release readiness for this repo. + +Optional starting ref override: `$1` +Extra user intent/context: `${@:2}` + +Process: + +1. Determine the base ref. + - If `$1` is non-empty and looks like a ref/tag, use it. + - Otherwise use the latest release tag, preferring the repo's semver tag style: + ```bash + git describe --tags --abbrev=0 + ``` + +2. Inspect the range from base ref to `HEAD`. + - Use first-parent history for release context: + ```bash + git log --first-parent --reverse --format='%H%x09%s' ..HEAD + ``` + - Also inspect full commits and commit bodies when needed: + ```bash + git log --reverse --format='%H%x09%s%n%b' ..HEAD + ``` + +3. Detect merged PRs if any. + - Look for first-parent subjects that indicate PR merges, including squash merges like `title (#123)`. + - If GitHub CLI is available and the PR number is known, use it to fetch PR title/body for context. + - Treat a merged PR as the primary release unit. + - Do **not** also list individual commits that belong to that PR. + +4. Handle direct commits separately. + - Any commit in the range not represented by a merged PR should be considered on its own. + +5. Infer what matters. + - For each PR or direct commit, inspect changed files and diff stats. + - Read the most relevant files in full when needed to understand user-facing impact. + - Ignore pure housekeeping unless it has release value: + - version bumps + - release/tag commits + - changelog-only commits + - formatting-only changes + - comment-only/doc-only changes unless they materially affect users + +6. Audit `docs/next/CHANGELOG.md` and issue references. + - Treat root `CHANGELOG.md` as the latest released changelog. + - Treat `docs/next/CHANGELOG.md` as the next-release changelog. + - Compare meaningful user-facing changes in the commit range against `docs/next/CHANGELOG.md`. + - Flag missing entries for new features, bug fixes, removals, breaking changes, defaults, compatibility changes, user-visible command/config/API behavior, and security-relevant changes. + - Do not require changelog entries solely for internal client/server protocol version bumps. Mention protocol only when the release intentionally changes user-facing compatibility guidance beyond the normal restart requirement. + - Inspect commit bodies for issue reference lines in the form `refs #`. + - Flag normal commits that use GitHub closing keywords like `fixes #`, `closes #`, or `resolves #`, because they close issues before release when they land on `master`. + - For each shipped issue reference, check whether the changelog has a matching user-facing entry that mentions `#` when appropriate. + - For each merged external human PR, check whether the changelog entry mentions the PR number and thanks the contributor in the existing style, e.g. `(#129, thanks @username)`. If the PR primarily ships an issue fix, include both the issue and PR numbers when useful, e.g. `(#128, #129, thanks @username)`. Do not add thanks text for maintainer-owned bots or automation accounts such as `kangal-bot` or `dependabot`. + - Do not require or add GitHub closing keywords like `fixes #`, `closes #`, or `resolves #` to changelog entries or release notes. + - List shipped issue references under `Issue references to close after release:` so the release operator can verify what release CI will close after the GitHub Release is published. + - Flag stale entries that do not appear to correspond to shipped changes in the range. + - Flag entries that are too implementation-focused or unclear for end users. + - Preserve the existing changelog style and sections: `Added`, `Changed`, `Fixed`, `Removed`, and `Breaking Changes` when applicable. + +7. Audit next-release public docs. + - Treat root `README.md` and `website/src/content/docs/` as the latest released public docs. + - Treat `docs/next/README.md` as the next-release root README, and `docs/next/website/src/content/docs/` as the full next-release mirror of website docs. + - Compare meaningful user-facing changes in the range against next-release docs first. + - Flag missing release docs for new or changed features, commands, config keys, protocol behavior, integrations, defaults, and compatibility notes. + - Compare `docs/next/README.md` against root `README.md`, and compare the staged website-doc mirror against `website/src/content/docs/`. Flag each difference as intended to ship in this release, stale, or needing user decision. + - Also audit example config snippets for release readiness. + +8. Verify finalization state. + - Before `just release`, approved `docs/next/README.md` must be copied to root `README.md`, approved staged website docs must be copied from `docs/next/website/src/content/docs/` to `website/src/content/docs/`, and the deleted root doc files must stay deleted. + - Run or recommend: + ```bash + just release-docs-check + ``` + - This check must include root `README.md`, root `CHANGELOG.md`, the removed root doc files, and exact 1:1 sync between `docs/next/website/src/content/docs/` and `website/src/content/docs/`. + - Do not run `just release` unless the working tree is clean and the docs check passes. + +9. Apply changes only when asked. + - Do not edit files during the audit unless the user explicitly asks you to apply fixes. + - When asked to apply audit fixes, update `docs/next/CHANGELOG.md`, `docs/next/README.md`, and any required staged website docs under `docs/next/website/src/content/docs/`. + - When asked to finalize release docs, copy approved next-release README and changelog into root, copy approved staged website docs into `website/src/content/docs/`, then run `just release-docs-check`. + +Output format: + +```md +Release readiness: READY | NOT READY + +Base: +Range: ..HEAD +Meaningful shipped changes: yes | no + +Changelog: OK | MISSING ENTRIES | NEEDS ATTENTION +Missing: +- + +Docs: OK | MISSING | INACCURATE | NEEDS DECISION +Missing: +- + +Wrong or questionable: +- + +Issue refs: OK | NEEDS ATTENTION +Will close after release: +- # + +Accepted/no action: +- + +Root docs finalized: YES | NO + + +Required before release: +1. +``` + +Keep the main output glanceable. Put commit inventories, excluded housekeeping, and commands run in an appendix only when they materially help the operator. + +If the range has no meaningful user-facing changes, say that plainly instead of forcing entries. diff --git a/CHANGELOG.md b/CHANGELOG.md index bcca1d36..9b8ea1ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,20 @@ ## Unreleased +### Added +- Added pane copy mode at `prefix+[` with keyboard navigation, visual selection, and clipboard yank support. (#231) +- Added `foreground_cwd` to pane and agent API/CLI responses so integrations can inspect the active foreground process directory without changing the existing pane/workspace `cwd` semantics. (#345) +- Added read-only `agent_session` metadata to pane and agent API/CLI responses when official integrations report native session references. + +### Fixed +- Live handoff now preserves terminal state when transferring supported running panes to a replacement server. +- WSL clipboard writes now prefer OSC 52 before WSLg clipboard tools, so mouse selection and double-click copy populate Windows clipboard history in Windows Terminal. (#333) +- Incomplete host terminal OSC default-color replies no longer get misread as Alt-key input and forwarded into panes, preventing interactive prompts such as `gh auth login --web` from aborting on split `ESC ]` input. (#279, #306, #344) +- Workspace rename prompts and background notifications now use live cwd-derived workspace labels instead of stale session labels. (#332) +- `herdr session stop` no longer fails on zero-duration socket timeouts when the stop deadline is nearly exhausted. +- Update preview instructions now wrap long package-manager commands instead of truncating the shell command suffix. +- Restored native agent resume panes now fall back to a shell when the resumed agent exits instead of closing the whole pane. + ## [0.6.4] - 2026-05-27 ### Fixed diff --git a/README.md b/README.md index 912af360..ea35bf42 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ not a gui window, not a web dashboard, not electron. herdr runs inside whatever - **workspaces** — organized around git repos or folder names, each with its own tabs and panes - **tabs** — first-class in the socket api and cli -- **mouse-native** — click panes/tabs/workspaces/agents, drag borders, drag-select text to copy, double-click tokens to copy, right-click menus; not keyboard-only +- **copy-friendly** — drag-select text, double-click tokens, or use keyboard copy mode with `prefix+[`, `h/j/k/l`, `{`/`}`, `v`, and `y` - **notifications** — sounds and toasts for background events; tab-aware suppression - **18 built-in themes** — catppuccin, terminal, tokyo night, gruvbox, one, solarized, kanagawa, rosé pine, vesper, and light variants for the main palettes - **session persistence** — pane processes survive client detach; sessions restore panes after full restart, with opt-in recent screen history @@ -195,7 +195,7 @@ automatic detection works out of the box. process name matching plus terminal ou | antigravity cli | ✓ | ✓ | ✓ | | kimi code cli | ✓ | ✓ | ✓ | | [github copilot cli](https://github.com/features/copilot) | ✓ | ✓ | ✓ | -| qoder cli | ✓ | ✓ | ✓ | +| [qodercli](https://qoder.com/cli) | ✓ | ✓ | ✓ | | [kiro cli](https://kiro.dev/docs/cli/) | ✓ | ✓ | — | detected but not fully tested: gemini cli, cline. @@ -204,7 +204,7 @@ for agents outside the built-in list, herdr still works as a terminal multiplexe ### direct integrations -the built-in pi, omp, claude code, codex, opencode, hermes, and qoder cli integrations forward semantic state to herdr over the socket api. install with: +the built-in pi, omp, claude code, codex, opencode, hermes, and qodercli integrations forward semantic state to herdr over the socket api. install with: ```bash herdr integration install pi @@ -297,7 +297,7 @@ full logging and environment variable details: [configuration docs](https://herd ## docs - [configuration](https://herdr.dev/docs/configuration/) — keybindings, themes, notifications, environment variables -- [integrations](https://herdr.dev/docs/integrations/) — pi, omp, claude code, codex, opencode, hermes, qoder cli integrations +- [integrations](https://herdr.dev/docs/integrations/) — pi, omp, claude code, codex, opencode, hermes, qodercli integrations - [`SKILL.md`](./SKILL.md) — reusable agent skill - [socket api](https://herdr.dev/docs/socket-api/) — socket protocol and cli reference diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md index 6c68d510..9b8ea1ab 100644 --- a/docs/next/CHANGELOG.md +++ b/docs/next/CHANGELOG.md @@ -5,10 +5,15 @@ ### Added - Added pane copy mode at `prefix+[` with keyboard navigation, visual selection, and clipboard yank support. (#231) - Added `foreground_cwd` to pane and agent API/CLI responses so integrations can inspect the active foreground process directory without changing the existing pane/workspace `cwd` semantics. (#345) +- Added read-only `agent_session` metadata to pane and agent API/CLI responses when official integrations report native session references. ### Fixed +- Live handoff now preserves terminal state when transferring supported running panes to a replacement server. - WSL clipboard writes now prefer OSC 52 before WSLg clipboard tools, so mouse selection and double-click copy populate Windows clipboard history in Windows Terminal. (#333) -- Incomplete host terminal OSC default-color replies no longer get misread as Alt-key input and forwarded into panes, preventing interactive prompts such as `gh auth login --web` from aborting on split `ESC ]` input. (#279, #344) +- Incomplete host terminal OSC default-color replies no longer get misread as Alt-key input and forwarded into panes, preventing interactive prompts such as `gh auth login --web` from aborting on split `ESC ]` input. (#279, #306, #344) +- Workspace rename prompts and background notifications now use live cwd-derived workspace labels instead of stale session labels. (#332) +- `herdr session stop` no longer fails on zero-duration socket timeouts when the stop deadline is nearly exhausted. +- Update preview instructions now wrap long package-manager commands instead of truncating the shell command suffix. - Restored native agent resume panes now fall back to a shell when the resumed agent exits instead of closing the whole pane. ## [0.6.4] - 2026-05-27 diff --git a/website/src/content/docs/cli-reference.mdx b/website/src/content/docs/cli-reference.mdx index ed51ce1e..ad837142 100644 --- a/website/src/content/docs/cli-reference.mdx +++ b/website/src/content/docs/cli-reference.mdx @@ -129,9 +129,15 @@ herdr pane report-agent \ --state idle|working|blocked|unknown \ [--message TEXT] \ [--custom-status TEXT] \ - [--seq N] + [--seq N] \ + [--agent-session-id ID] \ + [--agent-session-path PATH] ``` +`pane get`, `pane list`, `agent get`, and `agent list` include a read-only `agent_session` object when an official integration has reported a native session reference. If no native session reference is stored, the field is omitted. + +Those commands include `foreground_cwd` when Herdr can resolve the cwd of the foreground process controlling the pane. The existing `cwd` field remains the pane/workspace cwd used for labels and follow-cwd behavior. + Report display-only pane metadata without taking over semantic state: ```bash diff --git a/website/src/content/docs/configuration.mdx b/website/src/content/docs/configuration.mdx index 765a0b0f..936cc3ac 100644 --- a/website/src/content/docs/configuration.mdx +++ b/website/src/content/docs/configuration.mdx @@ -124,6 +124,7 @@ next_tab = "prefix+n" switch_tab = "prefix+1..9" rename_tab = "prefix+shift+t" close_tab = "prefix+shift+x" +copy_mode = "prefix+[" focus_pane_left = "prefix+h" focus_pane_down = "prefix+j" focus_pane_up = "prefix+k" diff --git a/website/src/content/docs/quick-start.mdx b/website/src/content/docs/quick-start.mdx index 7dc6e019..b6b1728b 100644 --- a/website/src/content/docs/quick-start.mdx +++ b/website/src/content/docs/quick-start.mdx @@ -53,6 +53,10 @@ Herdr is mouse-native. You can click panes, tabs, workspaces, and agents; drag b Ctrl-click opens pane links when your terminal sends the modified click to Herdr. This works for OSC 8 hyperlinks and visible `http://` or `https://` URLs. The portable terminal-native fallback is Shift-Ctrl-click on Linux or Shift-Cmd-click on macOS. +## Copy from the keyboard + +Press `prefix+[` to enter copy mode for the focused pane. Use `h/j/k/l`, `w/b/e`, and `{`/`}` to move, `v` or Space to start a selection, `y` or Enter to copy it, and `q` or Esc to leave without copying. + ## Manage named sessions Named sessions are separate Herdr server namespaces. Use them when you want fully separate runtime state. diff --git a/website/src/content/docs/socket-api.mdx b/website/src/content/docs/socket-api.mdx index 3b12d928..8525c33b 100644 --- a/website/src/content/docs/socket-api.mdx +++ b/website/src/content/docs/socket-api.mdx @@ -163,6 +163,23 @@ Integrations report agent state with `pane.report_agent`. `custom_status` is visual. It can show a short label like `indexing` without changing semantic behavior. +Official integrations can also report a native session reference. `pane.get`, `pane.list`, `agent.get`, and `agent.list` expose a read-only `agent_session` object when Herdr has a stored native session reference: + +```json +{ + "agent_session": { + "source": "herdr:codex", + "agent": "codex", + "kind": "id", + "value": "..." + } +} +``` + +If no native session reference is stored, the field is omitted. + +`pane.get`, `pane.list`, `agent.get`, and `agent.list` also expose `foreground_cwd` when Herdr can resolve the cwd of the process currently controlling the pane PTY. The existing `cwd` field remains the pane/workspace cwd used for labels, follow-cwd behavior, and restored session state. + Use `pane.report_metadata` when a user hook wants to customize presentation without taking over lifecycle state from a Herdr integration. ```json