[hivecommons-hive]

The run-dir guards in src/run-dir.ts (Refusing to use ..., Unsafe session name) stop pluk from capturing a session, yet none of the existing runbooks mention them, so an on-call reader hitting the error has no path from symptom to fix. This adds one runbook and a symptom-table row in runbooks/README.md.

Docs only; no guard is changed or loosened, and the runbook says not to bypass them.

— 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=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Checked the runbook against src/run-dir.ts at the merge base; it matches the code. Looks correct to me.

• Resolution order documented in Triage step 1 matches resolveRunDir (src/run-dir.ts:50) and defaultRunDir (:42-46): --run-dir → PLUK_RUN_DIR → $XDG_RUNTIME_DIR/pluk → <tmpdir>/pluk-<uid>.
• Every message in the "Common causes" table is a verbatim prefix of a thrown error: symlinked directory (:59, :75), non-directory path (:62), directory not owned by current user (:65), symlinked log file (:87), non-file log path (:90), log file not owned by current user (:93), and Unsafe session name (:33).
• The allowed-character set for session names matches SAFE_SESSION_PATTERN = /^[A-Za-z0-9_-]+$/ (:20).
• ../SECURITY.md and the sibling runbook links all resolve to existing files.

Docs-only, no guard touched. Nothing blocking from my side.

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

[hivecommons-hive]

Read the runbook against src/run-dir.ts at cb49413: all seven error strings in the Common-causes table match the source verbatim (run-dir.ts:33,59-67,86-94), the resolution order --run-dir → PLUK_RUN_DIR → $XDG_RUNTIME_DIR/pluk → <tmpdir>/pluk-<uid> matches resolveRunDir/defaultRunDir (run-dir.ts:40-50, called from attach.ts:300), the session-name character set matches SAFE_SESSION_PATTERN (run-dir.ts:19), and SECURITY.md, release-rollback.md and postmortem-template.md all exist. Looks correct to me, with one accuracy fix worth making before merge.

Low — the opening sentence over-attributes the errors. runbooks/run-dir-refused.md:3-4 says to use the runbook when pluk attach, subscribe, watch or sessions fails with Refusing to use ... or Unsafe session name .... In the tree:

• Refusing to use ... is thrown only by ensurePrivateDirectory/ensurePrivateLogFile, whose only callers are in attach (src/attach.ts:317,319,325). No other command emits it.
• Unsafe session name is thrown by attach (src/attach.ts:297) and subscribe (src/subscriber.ts:75). watch calls validateSessionName but swallows the error and merely skips log rotation (src/cli.ts:201-217); sessions never validates at all.

Consequence: an on-call reader whose pluk sessions or pluk watch is misbehaving will be pointed here by the symptom table and look for an error those commands cannot produce. Suggested wording: "Use this when pluk attach fails with Refusing to use ..., or pluk attach/pluk subscribe fails with Unsafe session name ...." The README row (runbooks/README.md:11) is command-agnostic and is fine as is.

Nothing else found; no guard is changed, and the recovery steps are consistent with how attach forwards --run-dir to the spawned watch (src/attach.ts:451).

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

[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]

Checked the runbook's factual claims against the tree at c4cabdc; they all match the code. Looks correct to me.

• Resolution order (--run-dir → PLUK_RUN_DIR → $XDG_RUNTIME_DIR/pluk → <tmpdir>/pluk-<uid>): src/run-dir.ts:41-50.
• All five Refusing to use … messages in the causes table are verbatim from src/run-dir.ts:59-93; Unsafe session name and the [A-Za-z0-9_-] rule: src/run-dir.ts:20,33.
• Which commands surface the errors: attach calls validateSessionName/ensurePrivateDirectory/ensurePrivateLogFile (src/attach.ts:297-319); subscribe raises from the Subscriber constructor (src/subscriber.ts:75); watch wraps its validateSessionName in a try/catch that only skips rotation (src/cli.ts:200-217); sessions only calls resolveRunDir and never a guard (src/sessions.ts:82). So the "watch catches / sessions never raises" note is accurate.
• Relative links (../SECURITY.md, release-rollback.md, postmortem-template.md) resolve; the README symptom row sits between attach and send, matching the table's existing ordering.

Docs only, no behaviour change; verify and test (22/24/26) are green.

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

[hivecommons-hive]

Read src/run-dir.ts and every caller at head c4cabdc; the runbook matches the code. Looks correct to me.

What I verified:

• All five Refusing to use … strings and Unsafe session name match the throws in src/run-dir.ts:31-98 verbatim, and the allowed name set ([A-Za-z0-9_-]) matches SAFE_SESSION_PATTERN at src/run-dir.ts:20.
• Resolution order --run-dir → PLUK_RUN_DIR → $XDG_RUNTIME_DIR/pluk → <tmpdir>/pluk-<uid> matches resolveRunDir/defaultRunDir at src/run-dir.ts:41-50.
• Command scoping is right: attach runs both the name check and the ownership guards (src/attach.ts:297-300); subscribe only validates the name (src/subscriber.ts:75-77), so it can only surface Unsafe session name; watch swallows the name error (src/cli.ts:201-215); sessions only calls resolveRunDir (src/sessions.ts:82).
• SECURITY.md, release-rollback.md, and postmortem-template.md exist at the linked paths.

Docs-only; no guard touched. Nothing blocking from my side.

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

[hivecommons-hive]

Evidence bundle `#396c4cabdc` sha256:ef9355dbd040eee4931de047ca4c3da715b47ef2b32b850f6531d0b84c305dc6 — download from the dashboard or `hivectl review evidence #396`.

[github-actions]

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

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