diff --git a/README.md b/README.md index f1521a8..09f5f9c 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,8 @@ Canonical, reviewable documentation for the StructuPath Herdr Suite, published a The product surface is organized by workflow readiness: - **Explore / Swarm** is the ready first workflow: bounded parallel candidates, reviewable worktrees, and operator-selected harvest. -- **Deliver / Conductor** is an attended Stage 2 lifecycle: task-bound role panes, strict run state, private report outboxes, deterministic integration, exact-SHA gates, and archival stand-down. -- **Browser** and **Guard** are supporting visibility and advisory text-policy capabilities. +- **Deliver / Conductor** is an attended Stage 3 lifecycle: task-bound roles, exact-SHA gates, operator approval receipts, single-local-ref apply, and archival stand-down on exactly Herdr 0.7.5. +- **Browser** provides Chromium launch, external attach, shared sessions, and agent-browser recording. **Guard** provides text policy and an optional fail-open harness reporter. The four plugins can be installed together, but they do not form one automatic runtime pipeline. @@ -21,11 +21,11 @@ The four plugins can be installed together, but they do not form one automatic r ## Truthful suite boundaries - Swarm agents commit locally; the operator reviews and selects what merges. A clean-slot selection can perform the merge after preview, so selection is the approval action. -- Guard is advisory/best-effort rendered-text policy for agent TUIs; it is not a sandbox or authorization boundary. -- Conductor creates and harvests its own worktrees and does not delegate either operation to Swarm. The pinned runtime provides strict task/report contracts and exact-SHA gates, but no approval receipts or approval-aware apply, suite adapter, unattended automation, or automatic recovery. +- Guard's pane watcher is advisory/best-effort. Its optional Claude Code hook can deny reported Bash calls before execution but fails open on unavailable or malformed responses; it is not a sandbox or same-user security boundary. +- Conductor creates and harvests its own worktrees. It supports attended preview, unauthenticated operator receipts, and one-local-ref apply. It does not delegate to Swarm or provide a suite adapter, unattended automation, or general automatic recovery. - Write-capable agents and plugins are trusted same-user principals. Worktrees isolate changes for review, not security. - Compatibility/testing claims are plugin-specific and pinned in `data/plugins.json`; there is no blanket suite-wide tested-version or marketplace claim. -- Conductor exposes five actions: `assemble`, `board`, `status`, `harvest`, and `stand-down`. +- Conductor exposes seven actions: `assemble`, `board`, `status`, `harvest`, `preview`, `apply`, and `stand-down`. ## Build and check diff --git a/data/plugins.json b/data/plugins.json index 4472aa5..2c28bd9 100644 --- a/data/plugins.json +++ b/data/plugins.json @@ -7,48 +7,83 @@ "name": "Browser", "id": "structupath.browser", "repository": "https://github.com/StructuPath/herdr-browser", - "commit": "952e1601006cce2ca45edef56676d18a1f016151", + "commit": "5fc6a9a52b4f817f21a531c288f36c3820bf93ca", "version": "0.7.0", "min_herdr_version": "0.7.0", - "tested_herdr_versions": ["0.7.4"], + "tested_herdr_versions": [ + "0.7.4" + ], "manifest_sha256": "975685f637d75b2f4b0151b7cecbb3eaa1fb3b8849c13a356e3ebfb5a90fea8a", - "actions": ["open", "close", "browse", "record-start", "record-stop"] + "actions": [ + "open", + "close", + "browse", + "record-start", + "record-stop" + ] }, { "slug": "guard", "name": "Guard", "id": "structupath.guard", "repository": "https://github.com/StructuPath/herdr-guard", - "commit": "7327dc4f310987e05059a20cec7d8fc50bbf0cc5", - "version": "0.1.1", + "commit": "12e3fd6f7d65bd4c846f5da23cb2f24ee617cd48", + "version": "0.2.0", "min_herdr_version": "0.7.5", - "tested_herdr_versions": ["0.7.5"], - "manifest_sha256": "36cd8ab09f82f07f56e08d15013221d4f5a46a8c2d3aca1255581b24c70dc50b", - "actions": ["open", "pause", "resume", "test", "reset-rules"] + "tested_herdr_versions": [ + "0.7.5" + ], + "manifest_sha256": "a56fb32ccb97d91dba6462c483120156208075bd52c36c1366590b0215326769", + "actions": [ + "open", + "pause", + "resume", + "test", + "reset-rules" + ] }, { "slug": "swarm", "name": "Swarm", "id": "structupath.swarm", "repository": "https://github.com/StructuPath/herdr-swarm", - "commit": "0dc0a2b0a77e590d854fafd5eae0e76dbcc00017", - "version": "0.1.0", + "commit": "4f0e2a7fcf25c94437e323bf1fa56a53fb4f34fb", + "version": "0.3.0", "min_herdr_version": "0.7.4", - "tested_herdr_versions": ["0.7.4", "0.7.5"], - "manifest_sha256": "54b3806f30816115743dd7d6e908c09c352d90b006a6f7885d46e292373d47b4", - "actions": ["fanout", "status", "harvest", "abort", "prune"] + "tested_herdr_versions": [ + "0.7.4", + "0.7.5" + ], + "manifest_sha256": "c4d7a6d653bb94ea6e0a3efef4fe3722d5b826ee24e7895fc8ba2439b119b0f5", + "actions": [ + "fanout", + "status", + "harvest", + "abort", + "prune" + ] }, { "slug": "conductor", "name": "Conductor", "id": "structupath.conductor", "repository": "https://github.com/StructuPath/herdr-conductor", - "commit": "712863c34d6126c9d95fa3b9bd6caf5220cbfc43", - "version": "0.3.0", + "commit": "bf67d318067c60318dcd7089897f513bfefe3af7", + "version": "0.4.0", "min_herdr_version": "0.7.5", - "tested_herdr_versions": ["0.7.5"], - "manifest_sha256": "95958ade511f422b65a07f3d4a305581cdb236e1cd616da7d6c57aa0660aa35e", - "actions": ["assemble", "board", "status", "harvest", "stand-down"] + "tested_herdr_versions": [ + "0.7.5" + ], + "manifest_sha256": "b8898d549216485c2bd599a101808030ce534b9c32625b6e6bdc51da04644672", + "actions": [ + "assemble", + "board", + "status", + "harvest", + "preview", + "apply", + "stand-down" + ] } ] } diff --git a/docs-src/Browser.md b/docs-src/Browser.md index a08bdff..e59c2c5 100644 --- a/docs-src/Browser.md +++ b/docs-src/Browser.md @@ -11,7 +11,7 @@ Repo: [StructuPath/herdr-browser](https://github.com/StructuPath/herdr-browser) | Plugin release | `0.7.0` | | Minimum Herdr | `0.7.0` | | Explicitly tested Herdr | `0.7.4` | -| Evidence commit | `952e1601006cce2ca45edef56676d18a1f016151` | +| Evidence commit | `5fc6a9a52b4f817f21a531c288f36c3820bf93ca` | The [pinned source](https://github.com/StructuPath/herdr-browser/tree/952e1601006cce2ca45edef56676d18a1f016151) includes the merged session-preservation and stream-recovery fixes. The manifest version remains 0.7.0; the commit identifies the exact implementation behind this guide. diff --git a/docs-src/Conductor.md b/docs-src/Conductor.md index 62aa8a7..85a695e 100644 --- a/docs-src/Conductor.md +++ b/docs-src/Conductor.md @@ -1,24 +1,22 @@ # 🎩 Deliver with Conductor (`structupath.conductor`) -**Attended Stage 2 delivery.** Conductor `0.3.0` coordinates task-bound builders, validators, and reviewers as visible Herdr agent panes. A human or trusted orchestrating agent explicitly drives every transition. This release is operational for strict task/report contracts and exact-SHA gates on exactly Herdr `0.7.5`; it is not an approval system, suite adapter, unattended pipeline, automatic recovery service, cryptographic attestation system, or same-user security boundary. +**Attended Stage 3 delivery.** Conductor `0.4.0` coordinates task-bound builders, validators, and reviewers as visible Herdr agent panes, then supports an explicitly approved fast-forward of one local ref. An operator drives every transition and records each approval receipt. It requires exactly Herdr `0.7.5`, protocol `17`, API schema `1`; it is not an authenticated approval system, suite adapter, unattended pipeline, general automatic recovery service, cryptographic attestation system, or same-user security boundary. -Repo: [StructuPath/herdr-conductor](https://github.com/StructuPath/herdr-conductor) · [Release `v0.3.0`](https://github.com/StructuPath/herdr-conductor/releases/tag/v0.3.0) · Detailed reference: the repo [README](https://github.com/StructuPath/herdr-conductor/tree/v0.3.0#readme) +Repo: [StructuPath/herdr-conductor](https://github.com/StructuPath/herdr-conductor) · Detailed reference: the repo [README](https://github.com/StructuPath/herdr-conductor#readme) ## Pinned evidence | Field | Value | | --- | --- | -| Plugin release | `0.3.0` | +| Plugin release | `0.4.0` | | Minimum Herdr | `0.7.5` | | Explicitly tested Herdr | `0.7.5` | -| Runtime candidate | `0ed952992ef1559808da4d25a2e7166d075b1ce9` | -| Evidence commit | `712863c34d6126c9d95fa3b9bd6caf5220cbfc43` | -| Manifest SHA-256 | `95958ade511f422b65a07f3d4a305581cdb236e1cd616da7d6c57aa0660aa35e` | -| Live evidence digest | `8547d5cd3215bf79cdb973437de867e803baba1a86d80916eb0ca8b5f2d8bcfd` | +| Evidence commit | `bf67d318067c60318dcd7089897f513bfefe3af7` | +| Manifest SHA-256 | `b8898d549216485c2bd599a101808030ce534b9c32625b6e6bdc51da04644672` | -The release retains an immutable [Stage 2 source manifest](https://github.com/StructuPath/herdr-conductor/blob/v0.3.0/docs/evidence/stage2-runtime-source-manifest.json) and [installed-Herdr live contract report](https://github.com/StructuPath/herdr-conductor/blob/v0.3.0/docs/evidence/2026-07-28-stage2-live-contracts.md). Historical [B0 identity-capability evidence](https://github.com/StructuPath/herdr-conductor/blob/v0.3.0/docs/evidence/2026-07-28-herdr-0.7.5-identity-capability.md) and the [Stage 1 B4 lifecycle report](https://github.com/StructuPath/herdr-conductor/blob/v0.3.0/docs/evidence/2026-07-28-stage1-b4-live-smoke.md) remain compatibility evidence. These are sanitized, operator-observed local records—not cryptographic remote attestation or authentication against malicious same-UID processes. +The retained [Stage 2 source manifest](https://github.com/StructuPath/herdr-conductor/blob/712863c34d6126c9d95fa3b9bd6caf5220cbfc43/docs/evidence/stage2-runtime-source-manifest.json) and [installed-Herdr live contract report](https://github.com/StructuPath/herdr-conductor/blob/712863c34d6126c9d95fa3b9bd6caf5220cbfc43/docs/evidence/2026-07-28-stage2-live-contracts.md) are historical compatibility evidence, not a live validation of Stage 3. These are sanitized, operator-observed local records—not cryptographic remote attestation or authentication against malicious same-UID processes. Older and newer Herdr binaries do not satisfy Conductor's exact 0.7.5 requirement; passing local tests is not evidence that another Herdr version is supported. -## All five actions +## All seven actions | Action ID | Attended behavior | | --- | --- | @@ -26,17 +24,20 @@ The release retains an immutable [Stage 2 source manifest](https://github.com/St | `structupath.conductor.board` | Print one passive lifecycle snapshot for the invoking repository/workspace; it does not open, focus, or mutate a pane. | | `structupath.conductor.status` | Print context-bound task, report, integration, gate, and exact live-identity status. | | `structupath.conductor.harvest` | Collect terminal reports, reject invalid committed reports durably, perform deterministic zero-or-one-CAS integration, and dispatch reviewer/validator tasks at the exact observed integration SHA. | +| `structupath.conductor.preview` | Journal the proposed local-ref fast-forward, exact integration and target observations, and gate assertions; return the exact approval command. | +| `structupath.conductor.apply` | Consume a matching operator approval receipt once, then perform or resolve the attempt's single local-ref compare-and-swap. | | `structupath.conductor.stand-down` | Revalidate each complete live pane/agent tuple before close, archive strict authority, and retain all worktrees, branches, tasks, reports, outboxes, gate sources, recordings, logs, artifacts, and Guard files. | Conductor owns this lifecycle. It does **not** invoke Swarm or provide an automatic Conductor→Swarm pipeline. Supported composition remains human-selected and sequential. ## Attended quickstart -Create `.herdr-conductor.json` in a clean Git repository: +Use Herdr exactly 0.7.5, Node.js 20 or current LTS, Python 3.11+, and Git with 40-hex SHA-1 object IDs. Create `.herdr-conductor.json` in a clean Git repository. This first-run example explicitly disables apply: ```json { - "version": 2, + "version": 3, + "apply": null, "state_root": { "kind": "default" }, "worktree_root": ".conductor-worktrees", "roles": [ @@ -78,7 +79,7 @@ Create `.herdr-conductor.json` in a clean Git repository: } ``` -Then explicitly drive the lifecycle from that Herdr workspace: +Commit `.herdr-conductor.json` before assembly so the repository is clean, then explicitly drive the lifecycle from that Herdr workspace: ```bash herdr plugin action invoke assemble --plugin structupath.conductor @@ -93,6 +94,20 @@ herdr plugin action invoke stand-down --plugin structupath.conductor `assemble` returns exact task paths, source roots, outbox slots, and task-bound publisher commands. Reports are closed canonical JSON supplied through bounded stdin. Producer collection and exact-SHA gate collection may require separate attended `harvest` invocations. Harvest and stand-down are mutating attended actions. Failed or uncertain external effects become `needs_attention` and are never silently replayed. +### Optional attended apply + +To enable apply for a new run, set `apply` to `{ "target_ref": "refs/heads/release" }` before assembly. The named local branch must already exist, differ from the integration branch, be checked out in no worktree, and remain exactly at the run's integration base. The proposed change must be a nonempty, rename-free fast-forward. Configuration v2 remains supported with apply disabled; do not edit a run-bound configuration mid-run. + +After producer and gate collection, use this sequence instead of standing down immediately: + +1. Invoke `herdr plugin action invoke preview --plugin structupath.conductor`. +2. Review the exact target, diff, gate assertions, and preview entry digest. +3. Follow the exact `npm run apply:approve` command returned by preview and provide the operator's canonical approve or reject receipt through stdin. Do not manufacture a receipt from a generic example or treat a worker's `approve` report as operator consent. +4. Invoke `herdr plugin action invoke apply --plugin structupath.conductor` only for the reviewed, approved attempt. +5. Inspect status, then invoke stand-down when finished. + +The receipt is consumed durably before any Git effect and cannot be reused. A moved target records an unapplied outcome with zero target changes. Only the attended apply action can resolve an uncertain apply publication from an exact target-SHA observation; other ambiguous operations remain refused. Rejected or voided attempts permit a fresh preview, up to eight attempts. Apply never pushes, tags, publishes, deploys, or updates multiple refs. + ## Trust and completion limits - State is strict, non-executable private JSON indexed by physical Git common-directory and Herdr workspace identity. Atomic writes, repository locks, generations, canonical digests, and hash-chained journals are cooperative coordination controls—not authentication. @@ -101,5 +116,5 @@ herdr plugin action invoke stand-down --plugin structupath.conductor - Missing, malformed, duplicate, foreign, stale, replayed, ambiguous, dirty, or durability-uncertain authority fails closed. Integration performs exactly zero or one target compare-and-swap. - Herdr `0.7.5` closes by `pane_id`. Conductor re-reads the full workspace, pane, terminal, agent, cwd, run, and generation tuple immediately before close, but a same-user TOCTOU window remains. - The repository lock does not stop unrelated Git or same-user processes. Worktrees are review boundaries, not sandboxes. Guard observes rendered text and cannot prove prevention. -- Stage 2 does not provide approval receipts, approval consumption, approval-aware apply, automatic recovery, suite adapters, unattended orchestration, automatic cleanup/prune, or Browser promotion. Those remain later-stage work. +- Stage 3 receipts are unauthenticated same-user operator records, not signatures or authorization proof. Apply changes one configured local ref; it does not provide general automatic recovery, suite adapters, unattended orchestration, automatic cleanup/prune, or Browser promotion. - Stand-down closes only identity-proven panes and archives authority. It does not remove worktrees, branches, tasks, outboxes, reports, gate sources, artifacts, recordings, logs, or Guard files; retained resources continue consuming disk. diff --git a/docs-src/Guard.md b/docs-src/Guard.md index 9b88333..942cf12 100644 --- a/docs-src/Guard.md +++ b/docs-src/Guard.md @@ -1,6 +1,6 @@ # 🛡️ Guard (`structupath.guard`) -**Supporting text-policy capability.** Guard is an **advisory, best-effort** cross-agent command policy layer for Herdr. It audits and alerts on matching terminal text and may interrupt visible shell input, but it is not a sandbox or authorization boundary for agent TUIs. +**Supporting text-policy capability.** Guard has two paths: an advisory pane watcher that audits, alerts, and attempts interrupts, and an optional harness reporter that evaluates reported Bash commands before execution. Neither path is a sandbox or a same-user security boundary. Repo: [StructuPath/herdr-guard](https://github.com/StructuPath/herdr-guard) · Detailed reference: the repo [README](https://github.com/StructuPath/herdr-guard#readme) @@ -8,12 +8,12 @@ Repo: [StructuPath/herdr-guard](https://github.com/StructuPath/herdr-guard) · D | Field | Value | | --- | --- | -| Plugin release | `0.1.1` | +| Plugin release | `0.2.0` | | Minimum Herdr | `0.7.5` | | Explicitly tested Herdr | `0.7.5` | -| Evidence commit | `7327dc4f310987e05059a20cec7d8fc50bbf0cc5` | +| Evidence commit | `12e3fd6f7d65bd4c846f5da23cb2f24ee617cd48` | -The `v0.1.1` tag target passed sequential one-shot RPC, dedicated subscription, reconnect, terminal rendering, replay suppression, and default/named-session recovery checks on Herdr 0.7.5/protocol 17. Guard records an interrupt request as accepted or failed; neither result proves command prevention. +Historical `v0.1.1` evidence covers sequential one-shot RPC, dedicated subscription, reconnect, terminal rendering, replay suppression, and default/named-session recovery on Herdr 0.7.5/protocol 17. It does not certify the new reporter in a live Herdr session. Guard records an interrupt request as accepted or failed; neither result proves command prevention. ## Actions @@ -25,7 +25,21 @@ The `v0.1.1` tag target passed sequential one-shot RPC, dedicated subscription, | `structupath.guard.test` | Dry-run text against the active policy without executing it | | `structupath.guard.reset-rules` | Back up and reseed the default rules | -## Honest coverage contract +## First run + +Use Herdr `>=0.7.5`, Node.js `>=20.10`, Python `>=3.11`, and Bash. Locking uses `lockf` on macOS or `flock` on Linux. Check which executable your shell selects before installing: + +```bash +command -v herdr +herdr --version +herdr plugin install StructuPath/herdr-guard +herdr plugin list +herdr plugin action list +``` + +Open Guard and use its Test action to evaluate sample text without executing it. Installation does not automatically configure a harness hook. The source checkout also provides `npm run build`, `npm run validate`, and the read-only `npm run doctor` setup check. + +## Honest pane coverage contract | Pane | Guard sees | Interrupt guarantee | | --- | --- | --- | @@ -37,8 +51,20 @@ The `v0.1.1` tag target passed sequential one-shot RPC, dedicated subscription, Guard performs text matching, not intent analysis. An agent running as the same user can disable the plugin, use unseen channels, or act outside observed terminal text. Use native agent hooks, sandboxing, and operating-system controls for authoritative enforcement. +## Optional harness reporter + +Version 0.2.0 includes a Claude `PreToolUse` Bash hook adapter. Wire it explicitly using the repository README instructions. The hook reports raw command text and its working directory to Guard's local Unix socket; policy uses the reported directory. Interrupt-tier matches return a deny decision, alert-tier matches request permission, and other commands are allowed. + +The adapter fails open if the socket is missing, times out, or returns an invalid response. Audit records cannot prove the harness honored a decision. This is a command-text policy check, not prompt analysis or a substitute for native enforcement. + +The socket defaults to `$XDG_STATE_HOME/herdr-guard/reporter.sock`, falling back to `~/.local/state/herdr-guard/reporter.sock`, separate from plugin state, in a private directory. Run only one owner per socket; a `HERDR_GUARD_REPORTER_SOCKET` override must agree between Guard and the hook. + ## Policy and trust Rules live at `$HERDR_PLUGIN_CONFIG_DIR/rules.json` and support `audit`, `alert`, and `interrupt` severities with regex or substring matching. Workspace `.herdr-guard.json` rules are capped at `alert`; repository-controlled regex and interrupt rules are rejected. The plugin itself is ordinary local code with the user's privileges. Review the source and policy before use, and protect audit logs because they can contain sensitive metadata even after redaction. + +## Upgrading + +Upgrades preserve existing `rules.json`. New default patterns therefore do not silently replace a reviewed policy. To adopt the defaults, review them first, then explicitly use Reset rules, which backs up the existing file before reseeding. Version 0.2.0 includes broader destructive-command, exfiltration, tampering, and evasion patterns. A force-with-lease push is audit-tier in the defaults, not silently ignored. diff --git a/docs-src/Home.md b/docs-src/Home.md index 34d450e..2b88876 100644 --- a/docs-src/Home.md +++ b/docs-src/Home.md @@ -2,8 +2,8 @@ Herdr-native tools for human-supervised agent work, built and maintained by [StructuPath](https://github.com/StructuPath). **Explore** is the ready first -workflow. **Deliver** is an attended Stage 2 lifecycle with strict task/report -contracts. Browser and Guard provide supporting visibility and text-policy capabilities. +workflow. **Deliver** is an attended Stage 3 lifecycle with strict task/report +contracts and approved single-ref apply. Browser and Guard provide supporting visibility and text-policy capabilities. This repository is the canonical suite documentation source; each plugin README remains the detailed runtime reference. @@ -11,34 +11,36 @@ This repository is the canonical suite documentation source; each plugin README [Explore with Swarm](Swarm) when you have one bounded coding task and want to compare several implementations. Swarm records a base SHA, gives each agent a separate worktree and branch, reports concrete change counts, and lets the operator preview and harvest a selected candidate. -The operator defines the comparison criterion, reviews diffs and tests, and chooses what lands. Agents commit locally and never push. +The operator defines the comparison criterion, reviews diffs and tests, and chooses what lands. Agents commit locally; the operator can explicitly publish a candidate branch for PR review. ## Deliver is attended -[Deliver with Conductor](Conductor) is an attended Stage 2 workflow: visible +[Deliver with Conductor](Conductor) is an attended Stage 3 workflow: visible role panes, repository/workspace-bound strict state, immutable task contracts, private report outboxes, deterministic one-CAS integration, exact-SHA reviewer -and validator gates, and archival stand-down. +and validator gates, operator approval receipts, single-ref apply, and archival stand-down. -The pinned runtime does not provide approval receipts or approval-aware apply, -suite adapters, unattended automation, automatic recovery, cryptographic report -attestation, or protection against malicious same-UID processes. +Apply receipts are unauthenticated same-user operator records. The pinned runtime +does not provide suite adapters, unattended automation, general automatic recovery, +cryptographic report attestation, or protection against malicious same-UID processes. +Conductor requires exactly Herdr 0.7.5; its manifest minimum is not a promise of +compatibility with later versions. ## Supporting trust capabilities - [Browser](Browser) launches local Chromium, attaches to an existing automation browser, or shares an agent-browser session. Recording is available for agent-browser sessions only. Sessions are a trusted same-user boundary, and recordings may contain sensitive content. -- [Guard](Guard) observes rendered terminal text and offers advisory/best-effort policy. It is not a sandbox or authorization boundary for agent TUIs. +- [Guard](Guard) observes rendered terminal text with best-effort interrupts and offers an optional pre-execution harness reporter. Its Claude Code hook can deny reported Bash calls but fails open when unavailable; Guard is not a sandbox or protection against same-user bypass. ## Pinned compatibility evidence | Plugin | ID | Pinned release | Minimum Herdr | Explicitly tested | Purpose | | --- | --- | --- | --- | --- | --- | | [Browser](Browser) | `structupath.browser` | `0.7.0` | `0.7.0` | `0.7.4` | Chromium launch, CDP attach, shared sessions, and agent-browser recording | -| [Guard](Guard) | `structupath.guard` | `0.1.1` | `0.7.5` | `0.7.5` | Supporting advisory text policy, audit, alert, and best-effort interrupt request | -| [Swarm](Swarm) | `structupath.swarm` | `0.1.0` | `0.7.4` | `0.7.4`, `0.7.5` | Ready Explore workflow: parallel candidates and review-first harvest | -| [Conductor](Conductor) | `structupath.conductor` | `0.3.0` | `0.7.5` | `0.7.5` | Attended Deliver Stage 2: strict tasks/reports, one-CAS integration, exact-SHA gates, and archival stand-down | +| [Guard](Guard) | `structupath.guard` | `0.2.0` | `0.7.5` | `0.7.5` | Text policy plus optional fail-open harness reporter | +| [Swarm](Swarm) | `structupath.swarm` | `0.3.0` | `0.7.4` | `0.7.4`, `0.7.5` | Parallel candidates, review-first harvest, and PR publication | +| [Conductor](Conductor) | `structupath.conductor` | `0.4.0` | `0.7.5` | `0.7.5` | Attended Stage 3: exact-SHA gates, preview, approval receipts, and single-ref apply | -Versions are plugin-specific evidence pinned in [`data/plugins.json`](https://github.com/StructuPath/herdr-suite-site/blob/main/data/plugins.json), not a claim that every plugin was tested on one suite-wide Herdr version. Guard 0.1.1 passed its non-destructive Herdr 0.7.5 live smoke. Guard remains best-effort rendered-text policy: an accepted interrupt request is observable, but command prevention is unknown. +Versions are plugin-specific source evidence pinned in [`data/plugins.json`](https://github.com/StructuPath/herdr-suite-site/blob/main/data/plugins.json), not a claim that every plugin was tested on one suite-wide Herdr version. Recorded Herdr versions include retained historical compatibility evidence; they do not certify every new feature. Guard's accepted interrupt requests and harness verdicts do not prove command prevention. ## Composition and supervision boundaries @@ -47,9 +49,9 @@ These plugins can be installed together, but the current runtime is not a single | Component | System provides | Operator remains responsible for | | --- | --- | --- | | Explore / Swarm | Worktree fan-out, change counts, previews, guarded harvest | Task bounds, candidate review, tests, slot selection, cleanup | -| Deliver / Conductor | Task-bound role panes, private report outboxes, deterministic integration, exact-SHA gates, and stand-down | Work direction, assertion review, approval decisions, conflicts, and ambiguous recovery | +| Deliver / Conductor | Task-bound roles, exact-SHA gates, preview, receipt-bound local-ref apply, and stand-down | Work direction, assertion review, operator receipts, conflicts, and ambiguous recovery | | Browser | Chromium launch, external attach, and shared-session recording | Session privacy, action review, sensitive recording handling | -| Guard | Best-effort text matching, audit, alerts, interrupt attempts | Authoritative hooks, sandboxing, access control, log protection | +| Guard | Text matching, audit, interrupt attempts, and optional harness verdicts | Hook wiring, fail-open behavior, sandboxing, access control, log protection | Herdr plugins and write-capable agents run as the same operating-system user. Treat them as **trusted same-user principals**. Worktrees reduce accidental file collisions and make changes reviewable; they are not sandboxes and do not prevent a worker from accessing other same-user files or processes. @@ -59,7 +61,7 @@ Herdr plugins and write-capable agents run as the same operating-system user. Tr # Ready first workflow herdr plugin install StructuPath/herdr-swarm -# Attended Stage 2 delivery +# Attended Stage 3 delivery (exactly Herdr 0.7.5) herdr plugin install StructuPath/herdr-conductor # Supporting visibility and policy @@ -79,3 +81,11 @@ herdr status server ``` `plugin list` confirms that a manifest parsed and is enabled; `plugin action list` confirms action registration. See each plugin page for its exact actions, prerequisites, and limits. + +## Keep the suite current + +In each source checkout, run `npm run build` and `npm run validate` for Browser, Swarm, and Guard; Conductor uses `npm run check`. Browser, Swarm, and Guard also provide a read-only `npm run doctor` to identify missing prerequisites and the selected Herdr binary. Check `command -v herdr` and `herdr --version` when multiple installations exist. Do not assume a newer Herdr satisfies Conductor's exact 0.7.5 contract. + +After an upgrade, verify action registration and run one bounded workflow in a separate test repository before larger work. Preserve reviewed Guard rules, explicitly wire any reporter hook, and review Swarm setup hooks and agent presets. Add Chromium through Browser's documented launch mode when visual QA is needed; it is already a supported capability. + +For each change, repeat build, relevant tests, and workflow validation until passing, then publish a reviewable PR. Update these guides and the pinned manifest evidence together whenever versions, actions, or supported behavior change. diff --git a/docs-src/Swarm.md b/docs-src/Swarm.md index 0146748..2eaa96d 100644 --- a/docs-src/Swarm.md +++ b/docs-src/Swarm.md @@ -8,10 +8,12 @@ Repo: [StructuPath/herdr-swarm](https://github.com/StructuPath/herdr-swarm) · D | Field | Value | | --- | --- | -| Plugin release | `0.1.0` | +| Plugin release | `0.3.0` | | Minimum Herdr | `0.7.4` | | Explicitly tested Herdr | `0.7.4`, `0.7.5` | -| Evidence commit | `0dc0a2b0a77e590d854fafd5eae0e76dbcc00017` | +| Evidence commit | `4f0e2a7fcf25c94437e323bf1fa56a53fb4f34fb` | + +The pinned source also records a [bounded Herdr 0.8.2 live smoke](https://github.com/StructuPath/herdr-swarm/blob/4f0e2a7fcf25c94437e323bf1fa56a53fb4f34fb/docs/readiness.md): fan-out, committed work, merge, automatic archive, abort, and prune dry-run. It found and fixed archive-state reconciliation and the newer runtime's `done` agent state. These are unreleased fixes on version 0.3.0; broad compatibility evidence remains 0.7.4/0.7.5. ## Actions @@ -19,7 +21,7 @@ Repo: [StructuPath/herdr-swarm](https://github.com/StructuPath/herdr-swarm) · D | --- | --- | | `structupath.swarm.fanout` | Prompt for task/slots and create one worktree, branch, and agent per slot | | `structupath.swarm.status` | Show each slot's state, branch, and committed/uncommitted counts | -| `structupath.swarm.harvest` | Review and merge selected slot branches back to the recorded base | +| `structupath.swarm.harvest` | Review and merge selected slot branches, or explicitly publish a branch for PR review | | `structupath.swarm.abort` | Stop agents and remove clean plugin-owned worktrees while keeping branches | | `structupath.swarm.prune` | Dry-run, then explicitly prune eligible merged branches or backup refs | @@ -78,6 +80,8 @@ with the clearest failure-path test. Fresh worktrees omit ignored dependencies, `.env` files, and caches. If every agent fails immediately, add a reviewed plugin-config `setup.sh` or tell agents to install required dependencies, then start a new run. +Setup logs preserve command output verbatim. Keep credentials out of setup output and review logs before sharing them. + ### 4. Inspect every credible candidate Open Status and use `1`–`9` to visit each slot. Compare committed and uncommitted counts against the recorded fork SHA. A 0.7.5+ slot can remain labeled `working` after it finishes until Harvest previews it; state is informative, not a completion gate. @@ -94,11 +98,19 @@ Use `q` to leave Status or Harvest without selecting a candidate. Invoke Abort t A first Explore run is successful when one chosen branch is merged without conflict, its tests pass on the base, the resulting diff meets the stated comparison criterion, and skipped work remains recoverable on branches until deliberate pruning. +## Publish for PR review + +In Harvest, press `p`, then select a slot to publish its branch. The script equivalent is `scripts/harvest-step.sh publish ` from the installed plugin root. Publication uses an ordinary push to `origin`, or the explicit `HERDR_SWARM_PUBLISH_REMOTE` override; it never force-pushes and does not create a GitHub PR itself. + +After a remote PR is merged, preview again. Harvest recognizes merge ancestry and squash merges whose tree changes are contained in the base. Prune uses ancestry, so squash-merged branches may remain for deliberate review. + ## Safety and trust boundary Swarm isolates working trees and provides reviewable branches; it does not sandbox agents. Write agents are trusted same-user principals and can access anything their operating-system user can access. Agents are instructed to commit locally and never push, while the operator remains the merge gate. -Harvest uses review-first, `--no-ff` merges and checks base drift. Dirty discards first create backup refs. Abort keeps branches, and prune is dry-run/env-gated. Ignored files remain outside Git's safety net; inspect the archive inventory before removing a worktree. +Harvest uses review-first, `--no-ff` merges and checks base drift. Dirty discards first create backup refs. Abort keeps branches, and prune is dry-run/env-gated. Active runs resolve by physical repository identity; conflicting generations are refused rather than guessed. + +Ignored files remain outside Git's safety net. Removal requires the exact one-use `cleanup_approval` JSON returned by the inventory preview, bound to the resource, path, run, generation, and inventory digest. A generic yes is insufficient, and changed inventory invalidates approval. This also applies to ignored files in detached merge worktrees. ## Scripted fan-out @@ -109,7 +121,7 @@ HERDR_SWARM_SLOTS=3 \ HERDR_SWARM_PRESETS=claude,claude,codex \ HERDR_SWARM_TASK_FILE=/path/brief.md \ HERDR_SWARM_DETRITUS=rename \ -HERDR_WORKSPACE_ID= \ +HERDR_WORKSPACE_ID='replace-with-repo-workspace-id' \ bash "$(herdr plugin list --json | jq -r '.plugins[] | select(.id=="structupath.swarm").root')/scripts/fanout-pane.sh" ``` @@ -121,6 +133,6 @@ Per-slot overrides remain interactive-only. If a zero-TTY input is missing, the - Abort stops the active run and preserves branches; it never deletes branches. - Prune is a dry run by default and is separately gated for merged branches and backup refs. - Closing the parent workspace stops Swarm agents silently. Committed work remains harvestable; uncommitted editor state may not. -- Ignored files are not included in WIP commits or discard snapshots. Inspect the archive-time inventory before acknowledging worktree removal. +- Ignored files are not included in WIP commits or discard snapshots. Review the archive inventory and supply its exact one-use cleanup approval before removal. Use the plugin README's [Safety model](https://github.com/StructuPath/herdr-swarm#safety-model) and [Uninstall / cleanup](https://github.com/StructuPath/herdr-swarm#uninstall--cleanup) sections before destructive cleanup. diff --git a/docs/browser/index.html b/docs/browser/index.html index 0a7743a..ef1577a 100644 --- a/docs/browser/index.html +++ b/docs/browser/index.html @@ -1,6 +1,7 @@ + Browser guide — Herdr Suite docs @@ -70,7 +71,7 @@

Pinned evidence

Evidence commit -952e1601006cce2ca45edef56676d18a1f016151 +5fc6a9a52b4f817f21a531c288f36c3820bf93ca diff --git a/docs/conductor/index.html b/docs/conductor/index.html index da62882..93bff28 100644 --- a/docs/conductor/index.html +++ b/docs/conductor/index.html @@ -1,13 +1,14 @@ + Deliver · Conductor guide — Herdr Suite docs - + - + @@ -16,7 +17,7 @@ - + @@ -45,8 +46,8 @@
Docs / Plugins

🎩 Deliver with Conductor (structupath.conductor)

-

Attended Stage 2 delivery. Conductor 0.3.0 coordinates task-bound builders, validators, and reviewers as visible Herdr agent panes. A human or trusted orchestrating agent explicitly drives every transition. This release is operational for strict task/report contracts and exact-SHA gates on exactly Herdr 0.7.5; it is not an approval system, suite adapter, unattended pipeline, automatic recovery service, cryptographic attestation system, or same-user security boundary.

-

Repo: StructuPath/herdr-conductor · Release v0.3.0 · Detailed reference: the repo README

+

Attended Stage 3 delivery. Conductor 0.4.0 coordinates task-bound builders, validators, and reviewers as visible Herdr agent panes, then supports an explicitly approved fast-forward of one local ref. An operator drives every transition and records each approval receipt. It requires exactly Herdr 0.7.5, protocol 17, API schema 1; it is not an authenticated approval system, suite adapter, unattended pipeline, general automatic recovery service, cryptographic attestation system, or same-user security boundary.

+

Repo: StructuPath/herdr-conductor · Detailed reference: the repo README

Pinned evidence

@@ -58,7 +59,7 @@

Pinned evidence

- + @@ -69,25 +70,17 @@

Pinned evidence

- - - - - + - - - - - +
Plugin release0.3.00.4.0
Minimum Herdr 0.7.5
Runtime candidate0ed952992ef1559808da4d25a2e7166d075b1ce9
Evidence commit712863c34d6126c9d95fa3b9bd6caf5220cbfc43bf67d318067c60318dcd7089897f513bfefe3af7
Manifest SHA-25695958ade511f422b65a07f3d4a305581cdb236e1cd616da7d6c57aa0660aa35e
Live evidence digest8547d5cd3215bf79cdb973437de867e803baba1a86d80916eb0ca8b5f2d8bcfdb8898d549216485c2bd599a101808030ce534b9c32625b6e6bdc51da04644672
-

The release retains an immutable Stage 2 source manifest and installed-Herdr live contract report. Historical B0 identity-capability evidence and the Stage 1 B4 lifecycle report remain compatibility evidence. These are sanitized, operator-observed local records—not cryptographic remote attestation or authentication against malicious same-UID processes.

-

All five actions

+

The retained Stage 2 source manifest and installed-Herdr live contract report are historical compatibility evidence, not a live validation of Stage 3. These are sanitized, operator-observed local records—not cryptographic remote attestation or authentication against malicious same-UID processes. Older and newer Herdr binaries do not satisfy Conductor's exact 0.7.5 requirement; passing local tests is not evidence that another Herdr version is supported.

+

All seven actions

@@ -113,6 +106,14 @@

All five actions

+ + + + + + + + @@ -120,9 +121,10 @@

All five actions

Collect terminal reports, reject invalid committed reports durably, perform deterministic zero-or-one-CAS integration, and dispatch reviewer/validator tasks at the exact observed integration SHA.
structupath.conductor.previewJournal the proposed local-ref fast-forward, exact integration and target observations, and gate assertions; return the exact approval command.
structupath.conductor.applyConsume a matching operator approval receipt once, then perform or resolve the attempt's single local-ref compare-and-swap.
structupath.conductor.stand-down Revalidate each complete live pane/agent tuple before close, archive strict authority, and retain all worktrees, branches, tasks, reports, outboxes, gate sources, recordings, logs, artifacts, and Guard files.

Conductor owns this lifecycle. It does not invoke Swarm or provide an automatic Conductor→Swarm pipeline. Supported composition remains human-selected and sequential.

Attended quickstart

-

Create .herdr-conductor.json in a clean Git repository:

+

Use Herdr exactly 0.7.5, Node.js 20 or current LTS, Python 3.11+, and Git with 40-hex SHA-1 object IDs. Create .herdr-conductor.json in a clean Git repository. This first-run example explicitly disables apply:

{
-  "version": 2,
+  "version": 3,
+  "apply": null,
   "state_root": { "kind": "default" },
   "worktree_root": ".conductor-worktrees",
   "roles": [
@@ -163,7 +165,7 @@ 
Attended quickstart

   ]
 }
-

Then explicitly drive the lifecycle from that Herdr workspace:

+

Commit .herdr-conductor.json before assembly so the repository is clean, then explicitly drive the lifecycle from that Herdr workspace:

herdr plugin action invoke assemble --plugin structupath.conductor
 herdr plugin action invoke status --plugin structupath.conductor
 herdr plugin action invoke board --plugin structupath.conductor
@@ -174,6 +176,17 @@ 
Attended quickstart

 herdr plugin action invoke stand-down --plugin structupath.conductor

assemble returns exact task paths, source roots, outbox slots, and task-bound publisher commands. Reports are closed canonical JSON supplied through bounded stdin. Producer collection and exact-SHA gate collection may require separate attended harvest invocations. Harvest and stand-down are mutating attended actions. Failed or uncertain external effects become needs_attention and are never silently replayed.

+

Optional attended apply

+

To enable apply for a new run, set apply to { "target_ref": "refs/heads/release" } before assembly. The named local branch must already exist, differ from the integration branch, be checked out in no worktree, and remain exactly at the run's integration base. The proposed change must be a nonempty, rename-free fast-forward. Configuration v2 remains supported with apply disabled; do not edit a run-bound configuration mid-run.

+

After producer and gate collection, use this sequence instead of standing down immediately:

+
    +
  1. Invoke herdr plugin action invoke preview --plugin structupath.conductor.
    2. +
  2. Review the exact target, diff, gate assertions, and preview entry digest.
    3. +
  3. Follow the exact npm run apply:approve command returned by preview and provide the operator's canonical approve or reject receipt through stdin. Do not manufacture a receipt from a generic example or treat a worker's approve report as operator consent.
    4. +
  4. Invoke herdr plugin action invoke apply --plugin structupath.conductor only for the reviewed, approved attempt.
    5. +
  5. Inspect status, then invoke stand-down when finished.
    6. +
+

The receipt is consumed durably before any Git effect and cannot be reused. A moved target records an unapplied outcome with zero target changes. Only the attended apply action can resolve an uncertain apply publication from an exact target-SHA observation; other ambiguous operations remain refused. Rejected or voided attempts permit a fresh preview, up to eight attempts. Apply never pushes, tags, publishes, deploys, or updates multiple refs.

Trust and completion limits

  • State is strict, non-executable private JSON indexed by physical Git common-directory and Herdr workspace identity. Atomic writes, repository locks, generations, canonical digests, and hash-chained journals are cooperative coordination controls—not authentication.
    • @@ -182,7 +195,7 @@

    Trust and completion limits

  • Missing, malformed, duplicate, foreign, stale, replayed, ambiguous, dirty, or durability-uncertain authority fails closed. Integration performs exactly zero or one target compare-and-swap.
  • Herdr 0.7.5 closes by pane_id. Conductor re-reads the full workspace, pane, terminal, agent, cwd, run, and generation tuple immediately before close, but a same-user TOCTOU window remains.
  • The repository lock does not stop unrelated Git or same-user processes. Worktrees are review boundaries, not sandboxes. Guard observes rendered text and cannot prove prevention.
    • -
  • Stage 2 does not provide approval receipts, approval consumption, approval-aware apply, automatic recovery, suite adapters, unattended orchestration, automatic cleanup/prune, or Browser promotion. Those remain later-stage work.
    • +
  • Stage 3 receipts are unauthenticated same-user operator records, not signatures or authorization proof. Apply changes one configured local ref; it does not provide general automatic recovery, suite adapters, unattended orchestration, automatic cleanup/prune, or Browser promotion.
  • Stand-down closes only identity-proven panes and archives authority. It does not remove worktrees, branches, tasks, outboxes, reports, gate sources, artifacts, recordings, logs, or Guard files; retained resources continue consuming disk.
diff --git a/docs/guard/index.html b/docs/guard/index.html index 5ac396b..4619655 100644 --- a/docs/guard/index.html +++ b/docs/guard/index.html @@ -1,13 +1,14 @@ + Guard guide — Herdr Suite docs - + - + @@ -16,7 +17,7 @@ - + @@ -45,7 +46,7 @@
Docs / Plugins

🛡️ Guard (structupath.guard)

-

Supporting text-policy capability. Guard is an advisory, best-effort cross-agent command policy layer for Herdr. It audits and alerts on matching terminal text and may interrupt visible shell input, but it is not a sandbox or authorization boundary for agent TUIs.

+

Supporting text-policy capability. Guard has two paths: an advisory pane watcher that audits, alerts, and attempts interrupts, and an optional harness reporter that evaluates reported Bash commands before execution. Neither path is a sandbox or a same-user security boundary.

Repo: StructuPath/herdr-guard · Detailed reference: the repo README

Pinned evidence

@@ -58,7 +59,7 @@

Pinned evidence

- + @@ -70,11 +71,11 @@

Pinned evidence

- +
Plugin release0.1.10.2.0
Minimum Herdr
Evidence commit7327dc4f310987e05059a20cec7d8fc50bbf0cc512e3fd6f7d65bd4c846f5da23cb2f24ee617cd48
-

The v0.1.1 tag target passed sequential one-shot RPC, dedicated subscription, reconnect, terminal rendering, replay suppression, and default/named-session recovery checks on Herdr 0.7.5/protocol 17. Guard records an interrupt request as accepted or failed; neither result proves command prevention.

+

Historical v0.1.1 evidence covers sequential one-shot RPC, dedicated subscription, reconnect, terminal rendering, replay suppression, and default/named-session recovery on Herdr 0.7.5/protocol 17. It does not certify the new reporter in a live Herdr session. Guard records an interrupt request as accepted or failed; neither result proves command prevention.

Actions

@@ -106,7 +107,16 @@

Actions

-

Honest coverage contract

+

First run

+

Use Herdr >=0.7.5, Node.js >=20.10, Python >=3.11, and Bash. Locking uses lockf on macOS or flock on Linux. Check which executable your shell selects before installing:

+
command -v herdr
+herdr --version
+herdr plugin install StructuPath/herdr-guard
+herdr plugin list
+herdr plugin action list
+
+

Open Guard and use its Test action to evaluate sample text without executing it. Installation does not automatically configure a harness hook. The source checkout also provides npm run build, npm run validate, and the read-only npm run doctor setup check.

+

Honest pane coverage contract

@@ -144,9 +154,15 @@

Honest coverage contract

Guard performs text matching, not intent analysis. An agent running as the same user can disable the plugin, use unseen channels, or act outside observed terminal text. Use native agent hooks, sandboxing, and operating-system controls for authoritative enforcement.

+

Optional harness reporter

+

Version 0.2.0 includes a Claude PreToolUse Bash hook adapter. Wire it explicitly using the repository README instructions. The hook reports raw command text and its working directory to Guard's local Unix socket; policy uses the reported directory. Interrupt-tier matches return a deny decision, alert-tier matches request permission, and other commands are allowed.

+

The adapter fails open if the socket is missing, times out, or returns an invalid response. Audit records cannot prove the harness honored a decision. This is a command-text policy check, not prompt analysis or a substitute for native enforcement.

+

The socket defaults to $XDG_STATE_HOME/herdr-guard/reporter.sock, falling back to ~/.local/state/herdr-guard/reporter.sock, separate from plugin state, in a private directory. Run only one owner per socket; a HERDR_GUARD_REPORTER_SOCKET override must agree between Guard and the hook.

Policy and trust

Rules live at $HERDR_PLUGIN_CONFIG_DIR/rules.json and support audit, alert, and interrupt severities with regex or substring matching. Workspace .herdr-guard.json rules are capped at alert; repository-controlled regex and interrupt rules are rejected.

The plugin itself is ordinary local code with the user's privileges. Review the source and policy before use, and protect audit logs because they can contain sensitive metadata even after redaction.

+

Upgrading

+

Upgrades preserve existing rules.json. New default patterns therefore do not silently replace a reviewed policy. To adopt the defaults, review them first, then explicitly use Reset rules, which backs up the existing file before reseeding. Version 0.2.0 includes broader destructive-command, exfiltration, tampering, and evasion patterns. A force-with-lease push is audit-tier in the defaults, not silently ignored.

diff --git a/docs/index.html b/docs/index.html index b467d26..5b6a1c3 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,6 +1,7 @@ + Overview — Herdr Suite docs @@ -47,24 +48,26 @@

Herdr Suite: supervised AgentOps

Herdr-native tools for human-supervised agent work, built and maintained by StructuPath. Explore is the ready first -workflow. Deliver is an attended Stage 2 lifecycle with strict task/report -contracts. Browser and Guard provide supporting visibility and text-policy capabilities.

+workflow. Deliver is an attended Stage 3 lifecycle with strict task/report +contracts and approved single-ref apply. Browser and Guard provide supporting visibility and text-policy capabilities.

This repository is the canonical suite documentation source; each plugin README remains the detailed runtime reference.

Start with Explore

Explore with Swarm when you have one bounded coding task and want to compare several implementations. Swarm records a base SHA, gives each agent a separate worktree and branch, reports concrete change counts, and lets the operator preview and harvest a selected candidate.

-

The operator defines the comparison criterion, reviews diffs and tests, and chooses what lands. Agents commit locally and never push.

+

The operator defines the comparison criterion, reviews diffs and tests, and chooses what lands. Agents commit locally; the operator can explicitly publish a candidate branch for PR review.

Deliver is attended

-

Deliver with Conductor is an attended Stage 2 workflow: visible +

Deliver with Conductor is an attended Stage 3 workflow: visible role panes, repository/workspace-bound strict state, immutable task contracts, private report outboxes, deterministic one-CAS integration, exact-SHA reviewer -and validator gates, and archival stand-down.

-

The pinned runtime does not provide approval receipts or approval-aware apply, -suite adapters, unattended automation, automatic recovery, cryptographic report -attestation, or protection against malicious same-UID processes.

+and validator gates, operator approval receipts, single-ref apply, and archival stand-down.

+

Apply receipts are unauthenticated same-user operator records. The pinned runtime +does not provide suite adapters, unattended automation, general automatic recovery, +cryptographic report attestation, or protection against malicious same-UID processes. +Conductor requires exactly Herdr 0.7.5; its manifest minimum is not a promise of +compatibility with later versions.

Supporting trust capabilities

  • Browser launches local Chromium, attaches to an existing automation browser, or shares an agent-browser session. Recording is available for agent-browser sessions only. Sessions are a trusted same-user boundary, and recordings may contain sensitive content.
    • -
  • Guard observes rendered terminal text and offers advisory/best-effort policy. It is not a sandbox or authorization boundary for agent TUIs.
    • +
  • Guard observes rendered terminal text with best-effort interrupts and offers an optional pre-execution harness reporter. Its Claude Code hook can deny reported Bash calls but fails open when unavailable; Guard is not a sandbox or protection against same-user bypass.

Pinned compatibility evidence

@@ -90,30 +93,30 @@

Pinned compatibility evidence

- + - + - + - + - + - +
Guard structupath.guard0.1.10.2.0 0.7.5 0.7.5Supporting advisory text policy, audit, alert, and best-effort interrupt requestText policy plus optional fail-open harness reporter
Swarm structupath.swarm0.1.00.3.0 0.7.4 0.7.4, 0.7.5Ready Explore workflow: parallel candidates and review-first harvestParallel candidates, review-first harvest, and PR publication
Conductor structupath.conductor0.3.00.4.0 0.7.5 0.7.5Attended Deliver Stage 2: strict tasks/reports, one-CAS integration, exact-SHA gates, and archival stand-downAttended Stage 3: exact-SHA gates, preview, approval receipts, and single-ref apply
-

Versions are plugin-specific evidence pinned in data/plugins.json, not a claim that every plugin was tested on one suite-wide Herdr version. Guard 0.1.1 passed its non-destructive Herdr 0.7.5 live smoke. Guard remains best-effort rendered-text policy: an accepted interrupt request is observable, but command prevention is unknown.

+

Versions are plugin-specific source evidence pinned in data/plugins.json, not a claim that every plugin was tested on one suite-wide Herdr version. Recorded Herdr versions include retained historical compatibility evidence; they do not certify every new feature. Guard's accepted interrupt requests and harness verdicts do not prove command prevention.

Composition and supervision boundaries

These plugins can be installed together, but the current runtime is not a single automatic pipeline.

@@ -132,8 +135,8 @@

Composition and supervision boundaries

- - + + @@ -142,8 +145,8 @@

Composition and supervision boundaries

- - + +
Deliver / ConductorTask-bound role panes, private report outboxes, deterministic integration, exact-SHA gates, and stand-downWork direction, assertion review, approval decisions, conflicts, and ambiguous recoveryTask-bound roles, exact-SHA gates, preview, receipt-bound local-ref apply, and stand-downWork direction, assertion review, operator receipts, conflicts, and ambiguous recovery
Browser
GuardBest-effort text matching, audit, alerts, interrupt attemptsAuthoritative hooks, sandboxing, access control, log protectionText matching, audit, interrupt attempts, and optional harness verdictsHook wiring, fail-open behavior, sandboxing, access control, log protection
@@ -152,7 +155,7 @@

Install by capability

# Ready first workflow
 herdr plugin install StructuPath/herdr-swarm
 
-# Attended Stage 2 delivery
+# Attended Stage 3 delivery (exactly Herdr 0.7.5)
 herdr plugin install StructuPath/herdr-conductor
 
 # Supporting visibility and policy
@@ -167,6 +170,10 @@ 
Health checks

 herdr status server

plugin list confirms that a manifest parsed and is enabled; plugin action list confirms action registration. See each plugin page for its exact actions, prerequisites, and limits.

+

Keep the suite current

+

In each source checkout, run npm run build and npm run validate for Browser, Swarm, and Guard; Conductor uses npm run check. Browser, Swarm, and Guard also provide a read-only npm run doctor to identify missing prerequisites and the selected Herdr binary. Check command -v herdr and herdr --version when multiple installations exist. Do not assume a newer Herdr satisfies Conductor's exact 0.7.5 contract.

+

After an upgrade, verify action registration and run one bounded workflow in a separate test repository before larger work. Preserve reviewed Guard rules, explicitly wire any reporter hook, and review Swarm setup hooks and agent presets. Add Chromium through Browser's documented launch mode when visual QA is needed; it is already a supported capability.

+

For each change, repeat build, relevant tests, and workflow validation until passing, then publish a reviewable PR. Update these guides and the pinned manifest evidence together whenever versions, actions, or supported behavior change.

diff --git a/docs/swarm/index.html b/docs/swarm/index.html index a2c3734..e6ba00c 100644 --- a/docs/swarm/index.html +++ b/docs/swarm/index.html @@ -1,6 +1,7 @@ + Explore · Swarm guide — Herdr Suite docs @@ -58,7 +59,7 @@

Pinned evidence

Plugin release -0.1.0 +0.3.0 Minimum Herdr @@ -70,10 +71,11 @@

Pinned evidence

Evidence commit -0dc0a2b0a77e590d854fafd5eae0e76dbcc00017 +4f0e2a7fcf25c94437e323bf1fa56a53fb4f34fb +

The pinned source also records a bounded Herdr 0.8.2 live smoke: fan-out, committed work, merge, automatic archive, abort, and prune dry-run. It found and fixed archive-state reconciliation and the newer runtime's done agent state. These are unreleased fixes on version 0.3.0; broad compatibility evidence remains 0.7.4/0.7.5.

Actions

@@ -93,7 +95,7 @@

Actions

- + @@ -140,6 +142,7 @@

3. Enter one bounded task and comparison criterion

.

Fresh worktrees omit ignored dependencies, .env files, and caches. If every agent fails immediately, add a reviewed plugin-config setup.sh or tell agents to install required dependencies, then start a new run.

+

Setup logs preserve command output verbatim. Keep credentials out of setup output and review logs before sharing them.

4. Inspect every credible candidate

Open Status and use 1–9 to visit each slot. Compare committed and uncommitted counts against the recorded fork SHA. A 0.7.5+ slot can remain labeled working after it finishes until Harvest previews it; state is informative, not a completion gate.

Open Harvest, preview each candidate's diff, run its tests, and compare it against the criterion declared before fan-out. Dirty slots offer WIP commit, skip, or discard; review the backup behavior before discarding.

@@ -150,16 +153,20 @@

5. Treat clean-slot selection as approval

Use q to leave Status or Harvest without selecting a candidate. Invoke Abort to stop an active run: it closes Swarm-owned panes and removes clean plugin-owned worktrees, while keeping branches and anything questionable.

Success definition

A first Explore run is successful when one chosen branch is merged without conflict, its tests pass on the base, the resulting diff meets the stated comparison criterion, and skipped work remains recoverable on branches until deliberate pruning.

+

Publish for PR review

+

In Harvest, press p, then select a slot to publish its branch. The script equivalent is scripts/harvest-step.sh publish <slot> from the installed plugin root. Publication uses an ordinary push to origin, or the explicit HERDR_SWARM_PUBLISH_REMOTE override; it never force-pushes and does not create a GitHub PR itself.

+

After a remote PR is merged, preview again. Harvest recognizes merge ancestry and squash merges whose tree changes are contained in the base. Prune uses ancestry, so squash-merged branches may remain for deliberate review.

Safety and trust boundary

Swarm isolates working trees and provides reviewable branches; it does not sandbox agents. Write agents are trusted same-user principals and can access anything their operating-system user can access. Agents are instructed to commit locally and never push, while the operator remains the merge gate.

-

Harvest uses review-first, --no-ff merges and checks base drift. Dirty discards first create backup refs. Abort keeps branches, and prune is dry-run/env-gated. Ignored files remain outside Git's safety net; inspect the archive inventory before removing a worktree.

+

Harvest uses review-first, --no-ff merges and checks base drift. Dirty discards first create backup refs. Abort keeps branches, and prune is dry-run/env-gated. Active runs resolve by physical repository identity; conflicting generations are refused rather than guessed.

+

Ignored files remain outside Git's safety net. Removal requires the exact one-use cleanup_approval JSON returned by the inventory preview, bound to the resource, path, run, generation, and inventory digest. A generic yes is insufficient, and changed inventory invalidates approval. This also applies to ignored files in detached merge worktrees.

Scripted fan-out

Interactive fan-out uses the action. A zero-TTY run must invoke the pane script directly because action-spawned panes do not inherit caller environment in the pinned runtime:

HERDR_SWARM_SLOTS=3 \
 HERDR_SWARM_PRESETS=claude,claude,codex \
 HERDR_SWARM_TASK_FILE=/path/brief.md \
 HERDR_SWARM_DETRITUS=rename \
-HERDR_WORKSPACE_ID=<repo-workspace-id> \
+HERDR_WORKSPACE_ID='replace-with-repo-workspace-id' \
   bash "$(herdr plugin list --json | jq -r '.plugins[] | select(.id=="structupath.swarm").root')/scripts/fanout-pane.sh"

Per-slot overrides remain interactive-only. If a zero-TTY input is missing, the script exits with a named-variable error instead of waiting on an unreadable prompt.

@@ -169,7 +176,7 @@

Safe exit and cleanup

  • Abort stops the active run and preserves branches; it never deletes branches.
  • Prune is a dry run by default and is separately gated for merged branches and backup refs.
  • Closing the parent workspace stops Swarm agents silently. Committed work remains harvestable; uncommitted editor state may not.
    • -
  • Ignored files are not included in WIP commits or discard snapshots. Inspect the archive-time inventory before acknowledging worktree removal.
    • +
  • Ignored files are not included in WIP commits or discard snapshots. Review the archive inventory and supply its exact one-use cleanup approval before removal.

    • Use the plugin README's Safety model and Uninstall / cleanup sections before destructive cleanup.

    diff --git a/index.html b/index.html index ef3644f..53fdf19 100644 --- a/index.html +++ b/index.html @@ -2,6 +2,7 @@ + Herdr Suite — explore agent-built changes with human review

    Truth boundary: Explore is the ready first workflow. Deliver - is an attended Stage 2 task/report lifecycle operated by a human or - trusted orchestrating agent—not an autonomous approval system. + is an attended Stage 3 lifecycle with reviewed local-ref apply, + requiring exactly Herdr 0.7.5 and explicit operator receipts.

    structupath.swarm.harvestReview and merge selected slot branches back to the recorded baseReview and merge selected slot branches, or explicitly publish a branch for PR review
    structupath.swarm.abort