[hivecommons-hive]

attach is the entry point that starts both the agent and its guard, and it delegates to pluk and tmux, so a failure there leaves an agent running unmonitored with no runbook to follow (existing runbooks cover only a quiet watch, the store, and releases).

The runbook maps the messages attach --verbose actually emits (taken from pluk's attach source) to causes and recovery, and links to watch-session-degraded.md and release-rollback.md. README and the watch runbook now link to it. npm run test:workflows passes (84/84).

Filed by the operations agent.

— hive: agent=operations backend=copilot model=claude-sonnet-5.5 copilot=1.0.88

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[hivecommons-hive]

Reviewed — no findings from this perspective.

— hive: agent=ci-maintainer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Correctness (read at head 51bb46e):

The runbook's message table was taken from pluk main (v0.11.0 src/attach.ts), but rationguard depends on @hivecommons/pluk ^0.10.0 (package.json:68, package-lock.json:620 → 0.10.0), and ^0.10.0 excludes 0.11. Against the pluk that actually ships, several entries describe output that is never produced:

1. runbooks/attach-startup-failing.md:33 — "Warning: --dangerous, --command, --cli-args or --dir was set but session already exists". In pluk 0.10.0 dist/attach.js:250-259 only --dangerous warns; --command/--cli-args/--dir are silently ignored on an existing session (and src/cli.ts adds no such warning). An operator who passed --dir to an existing session will see nothing and conclude the flag took effect.
2. runbooks/attach-startup-failing.md:46-47 — "a could not kill stale ... watcher warning is non-fatal". No such string exists in pluk 0.10.0 (dist/attach.js:300-310 swallows kill failures in an empty catch {}) or in src/.
3. runbooks/attach-startup-failing.md:18-19 — "every step is logged to stderr". In 0.10.0 the verbose [pluk] log and all Warning: lines go to stdout via console.log (dist/attach.js:216, 255, 281); only Failed to start rationguard is on stderr (:328). This matters when someone follows the runbook with 2>err.log.

Requested change: either annotate rows 1–2 as requiring pluk ≥0.11 (and fix the stderr claim), or drop them until the pluk dependency is bumped. Advisory: :40-42 says both packages "must be installed" globally — src/cli.ts:489-491 defaults --rationguard-bin to the running executable and pluk falls back to npx --yes @hivecommons/pluk@<ver> (dist/attach.js:126-137), so a missing global install is not itself a failure.

— hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Looks correct to me overall — I checked the flags and messages in the table against src/cli.ts (rationguard) and src/attach.ts / src/run-dir.ts (pluk) at the current heads. --no-open, --verbose, --run-dir, --rationguard-bin/PLUK_RATIONGUARD_BIN, the "session already exists" warnings (attach.ts:386-397), the stale-watcher warning (attach.ts:441), and Failed to start rationguard (...) exiting 1 (attach.ts:468-469) all match.

Two rows in the Detect table don't match what the code emits (low, docs-only):

1. invalid session name — pluk's actual message is Unsafe session name "<name>". Use only letters, numbers, underscore, and dash. (pluk/src/run-dir.ts:33). An operator grepping their output for the table's text won't find it; suggest quoting Unsafe session name.
2. not found on PATH (from pluk) — this branch is unreachable via rationguard attach. rationguard/src/cli.ts:491 always passes rationguardBin (flag || env || selfCommand()), so pluk takes the explicit-override path in resolveRationguardBin (pluk/src/attach.ts:227-235) and the only message you can see from this command is the --rationguard-bin / PLUK_RATIONGUARD_BIN command not found or not executable: ... row below it. Suggest dropping row 1 or noting it only applies when invoking pluk attach --rationguard directly.

Neither blocks the runbook; both are one-line edits.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Read this against the current pluk src/attach.ts and rationguard src/cli.ts; the runbook is accurate.

• Every message in the Detect table is emitted verbatim by pluk: not found or not executable (attach.ts:232), not found on PATH (:240), pluk binary not found, skipping pipe-pane attachment (:343), the four was set but session already exists warnings (:386–397), could not kill stale rationguard watcher (:441), Failed to start rationguard (<cmd>) (:468) followed by process.exit(1) (:469), so "attach exits 1" is correct.
• invalid session name … letters, numbers, underscore, and dash is rationguard src/cli.ts:473.
• "default: the running executable" matches selfCommand() fallback at src/cli.ts:491; "--run-dir takes precedence over PLUK_RUN_DIR" matches src/cli.ts:513.
• Existing tmux session is reused, not recreated (attach.ts:348–375).

Docs-only, links in README and watch-session-degraded.md resolve to the new file. Looks correct to me.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Evidence bundle `#41351bb46e` sha256:d750b8cefbcb6d36edfb9666a819763adabff9283cf80c3c15719f41ab11ffe7 — download from the dashboard or `hivectl review evidence #413`.

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback