session-orchestrator 4.1.0 → 5.0.0

package/docs/session-config-template.md

@@ -36,8 +36,8 @@ These seven fields are enforced by `scripts/lib/config-schema.mjs`. Validation i
 test-command: npm test                # non-empty string — quality-gate test runner
 typecheck-command: npm run typecheck   # non-empty string — canonical typecheck runner
 lint-command: npm run lint             # non-empty string — Full Gate lint runner
-agents-per-wave: 6                     # integer ≥ 2 (or { default: 6, deep: 18 })
-waves: 5                               # integer ≥ 3 — execution wave count
+agents-per-wave: 6                     # integer ≥ 2 (or { default: 6, deep: 18 }) — see § Session Structure
+waves: 5                               # integer ≥ 3 — base count; actual wave count is resolved per session type by `scripts/session-shape.mjs`
 persistence: true                      # boolean — STATE.md + memory file resumption
 enforcement: warn                      # strict | warn | off — hook strictness AND validator gate
 ```
@@ -50,13 +50,15 @@ Controls wave count, parallelism, and freeform per-repo notes the orchestrator m
 
 ```yaml
 agents-per-wave: 6                     # integer or "6 (deep: 18)" override syntax
-waves: 5                               # integer ≥ 3
+waves: 5                               # integer ≥ 3 — base count only; resolved shape may ignore it (see below)
 recent-commits: 20                     # how many commits to display at session-start
 special: "any repo-specific instructions"   # freeform — orchestrator reads + obeys
 ```
 
 Read by: `skills/session-start/SKILL.md` (Phase 4.5), `skills/session-plan/SKILL.md`, `skills/wave-executor/wave-loop.md`.
 
+**Wave count, roles and per-wave agent caps are resolved by `scripts/session-shape.mjs`, not derived from `waves` by hand.** Housekeeping is always 1 coordinator-direct maintenance-loop wave; feature is 3 waves (Impl-Core / Impl-Polish+Quality / Finalization); deep is 5 waves (4 when the scope is already known — Discovery is dropped); the `ultradeep` profile is a fixed 7-wave shape that IGNORES `waves` entirely (`wavesConfigHonored: false`). `agents-per-wave` resolves via `resolveAgentCap()` in the same module. Full table: [`session-config-reference.md` § Session Shapes](./session-config-reference.md#session-shapes).
+
 **The override key set is open.** `_coerceInteger` (`scripts/lib/config/coercers.mjs`) parses whatever keys stand inside the parentheses, so `agents-per-wave: 6 (deep: 18, ultradeep: 18)` is valid today with no code change — it yields `{"default": 6, "deep": 18, "ultradeep": 18}`.
 
 **`session-profile` is NOT a Session Config key — do not add one here.** The wave-shape profile (`ultradeep`) lives in STATE.md frontmatter, written per session by the `/session ultradeep` argument alias, and is absent by default. `parseSessionConfig()` emits no such key, so writing one into a repo's `## Session Config` block is inert prose — the same trap as `session-type:`. Full contract: [`session-config-reference.md` § Session Profile](./session-config-reference.md). The PRD's `ultradeep.max-*` budget block is deliberately NOT implemented and no key of that name is read anywhere (deferred until measured, HR-105).
@@ -151,7 +153,7 @@ reasoning-output: false                # opt-in STATE:/PLAN: agent transparency
 grounding-check: true                  # session-end Phase 1.1a planned-vs-touched diff
 grounding-injection-max-files: 3       # 0 disables (#85)
 isolation: auto                        # worktree | none | auto (graduated default #194)
-max-turns: auto                        # housekeeping=8, feature=15, deep=25
+max-turns: auto                        # per session shape (scripts/lib/session-shape.mjs): 8/15/25; ultradeep is per-wave 40/25/15
 auto-commit-per-wave: false            # opt-in: commit after each wave's Quality-Lite PASS (default false; V3.6 plumbing)
 ```
 
@@ -482,7 +484,9 @@ Read by: `scripts/lib/config/dialectic.mjs`, `scripts/lib/auto-dialectic.mjs`, `
 
 ## Eval (#803)
 
-Opt-in configuration for the Standard v1 evaluation harness and the forthcoming `/eval` skill (Session-Prozess-Eval — PRD `docs/prd/2026-07-16-aiat-llm-eval.md` §S6, follow-up wave of Epic #803). This section documents the config surface only; the skill consumer lands in a later wave.
+Opt-in configuration for the Standard v1 evaluation harness and `/eval` (Session-Prozess-Eval); see `skills/eval/SKILL.md` for the current workflow.
+
+The original config proposal is in the archived PRD `docs/prd/2026-07-16-aiat-llm-eval.md` §S6 (Epic #803). <!-- path-check: historical -->
 
 ```yaml
 eval:

package/docs/vault-docs-architecture.md

@@ -123,11 +123,13 @@ Data flow within a single `/session feature → /go → /close` cycle:
 | `vault-staleness` probes | `skills/discovery/probes-vault.md` + `skills/discovery/probes/vault-staleness.mjs` | `/discovery vault` (on-demand) and session-end Phase 2.3 (opt-in close-time gate) | `VAULT_DIR/01-projects/*/` `_overview.md` + narrative files | JSONL findings under `.orchestrator/metrics/vault-staleness.jsonl` and `vault-narrative-staleness.jsonl` | Vault/Ops (telemetry) |
 | `docs-orchestrator` | `skills/docs-orchestrator/SKILL.md` | session-start Phase 2.5, session-plan Step 1.5/1.8, session-end Phase 3.2 (all gated on `enabled: true`) | Session scope + Session Config audience list | `docs-tasks` block in STATE.md (write side); `### Documentation Coverage` block in final report (verify side) | All three (User / Dev / Vault) |
 | `docs-writer` agent | `agents/docs-writer.md` | Dispatched by `wave-executor` for each `Docs`-classified task | `diff`, `git-log`, `session-memory`, `affected-files` | Audience-targeted Markdown writes (Edit/Write); `[docs-orchestrator] Docs task complete` report line | All three (per task) |
-| `narrative-mirror` | `scripts/lib/vault-status/narrative-mirror.mjs` (`mirrorNarrative`) | session-end Phase 3.7, gated on `vault-integration.enabled` | `.claude/STATE.md` narrative sections + the session record | `<vault>/01-projects/<repo-slug>/_session-narrative.md` (generator-marked) | Vault/Ops (durable per-repo narrative) |
+| `narrative-mirror` | `scripts/lib/vault-status/narrative-mirror.mjs` (`mirrorNarrative`) | session-end Phase 3.7, gated on `vault-integration.enabled` | Generated session-state narrative sections (see input note below) + the session record | `<vault>/01-projects/<repo-slug>/_session-narrative.md` (generator-marked) | Vault/Ops (durable per-repo narrative) |
 | `board-writer` | `scripts/lib/vault-status/board-writer.mjs` (`sweepBoard` / `mirrorBoard`) | session-start Phase 1.7 (`in-progress`) and session-end Phase 3.7c (`closed`), gated on `vault-integration.enabled` | live session registry + this repo's root | `<vault>/01-projects/_active-sessions.md` — one row per repo (generator-marked, idempotent, never touches `_overview.md`) | Vault/Ops (cross-repo occupancy board) |
 | `vault-mirror` | `skills/vault-mirror/SKILL.md` + `scripts/vault-mirror.mjs` | session-end Phase 3.7 (sessions); evolve Phase 3.5 (learnings) | `.orchestrator/metrics/sessions.jsonl`, `.orchestrator/metrics/learnings.jsonl` | `<vault>/50-sessions/<id>.md`, `<vault>/40-learnings/<slug>.md` (`_generator` marker `session-orchestrator-vault-mirror@1`) | Vault/Ops (telemetry → Markdown) |
 | `vault-backfill` CLI | `scripts/vault-backfill.mjs` | Manual, also surfaced via `/plan retro vault-backfill` sub-mode | `vault-integration.gitlab-groups` config + GitLab API | `.vault.yaml` per repo + Vault stub directories | Vault/Ops (one-shot migration) |
 
+The narrative mirror reads narrative sections from the generated `.claude/STATE.md` input, together with the session record. <!-- path-check: example -->
+
 ---
 
 ## 4. Audience Model
@@ -138,7 +140,7 @@ table), which is the **single source of truth** for which files belong to
 which audience. Never inline this table elsewhere — always cross-link.
 
 - **User** — external/internal users of the repo. Targets: `README.md`,
-  `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md`. Source:
+  `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md`. Source: <!-- path-check: example -->
   `skills/docs-orchestrator/audience-mapping.md` § Audiences & File Patterns.
 - **Dev** — contributors to the repo, including future Claude sessions.
   Targets: `CLAUDE.md`, `docs/dev/**/*.md`, `docs/adr/**/*.md`. Source: same.

package/hooks/_lib/hook-import-set.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-09-07T18:36:32.142Z",
-  "head": "a244b8707aa5bb650673fce2e6cf548564b43e58",
+  "generated_at": "2026-09-13T09:10:50.839Z",
+  "head": "ff1ed19177795b743186eebfc387319de0e90c31",
   "entries": [
     {
       "file": "hooks/_lib/atomic-json.mjs",
@@ -46,6 +46,7 @@
         "on-session-start.mjs",
         "on-stop.mjs",
         "operator-steer.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -68,6 +69,7 @@
     {
       "file": "hooks/_lib/subagent-paths.mjs",
       "reachable_from": [
+        "enforce-scope.mjs",
         "on-stop.mjs",
         "post-subagent-discovery-validator.mjs",
         "subagent-telemetry.mjs"
@@ -88,6 +90,7 @@
     {
       "file": "hooks/_lib/vcs-create-matcher.mjs",
       "reachable_from": [
+        "post-bash-issue-budget-refund.mjs",
         "pre-bash-issue-budget.mjs",
         "pre-bash-templates-first.mjs"
       ]
@@ -146,6 +149,12 @@
         "operator-steer.mjs"
       ]
     },
+    {
+      "file": "hooks/post-bash-issue-budget-refund.mjs",
+      "reachable_from": [
+        "post-bash-issue-budget-refund.mjs"
+      ]
+    },
     {
       "file": "hooks/post-bash-write-verify.mjs",
       "reachable_from": [
@@ -291,6 +300,7 @@
     {
       "file": "scripts/lib/command-blocker.mjs",
       "reachable_from": [
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-validate.mjs",
         "post-tool-batch-wave-signal.mjs",
@@ -305,6 +315,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-edit-validate.mjs",
         "post-subagent-discovery-validator.mjs",
         "pre-bash-issue-budget.mjs",
@@ -337,6 +348,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -359,6 +371,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -384,7 +397,9 @@
       "reachable_from": [
         "on-session-end.mjs",
         "on-session-start.mjs",
-        "post-edit-validate.mjs"
+        "post-bash-issue-budget-refund.mjs",
+        "post-edit-validate.mjs",
+        "pre-bash-issue-budget.mjs"
       ]
     },
     {
@@ -549,6 +564,7 @@
       "reachable_from": [
         "on-session-end.mjs",
         "on-session-start.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-edit-validate.mjs",
         "pre-bash-issue-budget.mjs"
       ]
@@ -593,6 +609,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -600,6 +617,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "pre-bash-staging-fence.mjs",
         "pre-task-scope-disjoint.mjs",
@@ -632,6 +650,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -670,6 +689,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -677,6 +697,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -763,6 +784,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -808,6 +830,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -828,6 +851,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -848,6 +872,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -855,6 +880,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -877,6 +903,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -884,6 +911,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "pre-task-scope-disjoint.mjs",
         "skill-invocation-telemetry.mjs"
@@ -919,6 +947,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -926,6 +955,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "pre-bash-staging-fence.mjs",
         "pre-task-scope-disjoint.mjs",
@@ -942,6 +972,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -962,6 +993,7 @@
     {
       "file": "scripts/lib/issue-budget.mjs",
       "reachable_from": [
+        "post-bash-issue-budget-refund.mjs",
         "pre-bash-issue-budget.mjs"
       ]
     },
@@ -982,6 +1014,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -989,6 +1022,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1003,6 +1037,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1010,6 +1045,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1024,6 +1060,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1031,6 +1068,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1080,6 +1118,7 @@
         "on-session-start.mjs",
         "on-stop.mjs",
         "operator-steer.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1109,6 +1148,7 @@
         "on-session-start.mjs",
         "on-stop.mjs",
         "operator-steer.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1196,6 +1236,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1216,6 +1257,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1223,6 +1265,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1237,6 +1280,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1244,6 +1288,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1313,6 +1358,12 @@
         "on-session-start.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/session-shape.mjs",
+      "reachable_from": [
+        "on-session-start.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/session-start-probes.mjs",
       "reachable_from": [
@@ -1370,6 +1421,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1377,6 +1429,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1399,6 +1452,7 @@
         "on-session-end.mjs",
         "on-session-start.mjs",
         "on-stop.mjs",
+        "post-bash-issue-budget-refund.mjs",
         "post-bash-write-verify.mjs",
         "post-edit-import-probe.mjs",
         "post-edit-validate.mjs",
@@ -1406,6 +1460,7 @@
         "post-tool-batch-wave-signal.mjs",
         "post-tooluse-frontend-slop.mjs",
         "pre-auq-clarity.mjs",
+        "pre-bash-issue-budget.mjs",
         "pre-bash-memory-propose-audit.mjs",
         "skill-invocation-telemetry.mjs"
       ]
@@ -1478,6 +1533,18 @@
         "pre-bash-staging-fence.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/wave-sizing.mjs",
+      "reachable_from": [
+        "on-session-start.mjs"
+      ]
+    },
+    {
+      "file": "scripts/lib/wave-transcript-tail.mjs",
+      "reachable_from": [
+        "enforce-scope.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/worktree/listing.mjs",
       "reachable_from": [

package/hooks/_lib/lock-bootstrap.mjs

@@ -38,6 +38,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
 
+/**
+ * Native SessionStart `source` values that are a RE-ENTRY into the same logical
+ * session rather than a new one (#1091).
+ *
+ * SSOT for both consumers — the SessionStart hook's high-water-mark
+ * preservation and the force-refresh gate below — so a later widening
+ * ("`fork` is a re-entry too") can never reach one side only. It lives HERE,
+ * in the leaf module, because the hook already imports this file while the
+ * reverse direction would pull the whole hook's closure into a helper.
+ *
+ * `startup` is deliberately absent: a fresh process start must never inherit a
+ * predecessor's markers or take over its lock.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SAME_LOGICAL_SESSION_SOURCES = new Set(['resume', 'clear', 'compact']);
+
 /**
  * Bootstrap the session.lock for this hook invocation.
  *
@@ -55,6 +72,16 @@ import { writeJsonAtomicSync } from '../../scripts/lib/io.mjs';
  *   field is populated by mirroring sessionId for backward-compatible display only.
  * @param {string} opts.mode — session mode (e.g. "deep", "feature").
  * @param {number} [opts.ttlHours=4] — lock TTL in hours.
+ * @param {string|null} [opts.nativeSource=null] — the native SessionStart
+ *   `source` (`startup`|`resume`|`clear`|`compact`), when the harness sent one.
+ *   Only consulted for the same-logical-session force-refresh below; every
+ *   existing caller that omits it keeps its pre-#1091 behaviour exactly.
+ * @param {string|null} [opts.predecessorSessionId=null] — the raw `session_id`
+ *   recorded in `.orchestrator/current-session.json` by our OWN previous run of
+ *   this hook. It is the third, load-bearing conjunct of the re-entry
+ *   force-refresh below: without it a same-host semantic-label collision (#1066)
+ *   lets one session take over a live peer's lock. Omitting it (the default)
+ *   disables the re-entry force-refresh entirely — fail-closed.
  * @param {Function} [opts._acquireImpl] — DI for tests (defaults to importing acquire from session-lock.mjs).
  * @param {Function} [opts._forceAcquireImpl] — DI for tests (defaults to importing forceAcquire from session-lock.mjs).
  * @param {Function} [opts._emitEventImpl] — DI for tests (defaults to importing emitEvent from events.mjs).
@@ -66,6 +93,8 @@ export async function bootstrapLock({
   semanticSessionId,
   mode,
   ttlHours = 4,
+  nativeSource = null,
+  predecessorSessionId = null,
   _acquireImpl,
   _forceAcquireImpl,
   _emitEventImpl,
@@ -106,6 +135,53 @@ export async function bootstrapLock({
 
   if (!acquireResult || typeof acquireResult !== 'object') return null;
 
+  // #1091 F2 — a same-logical-session re-entry whose RAW id the harness did not
+  // preserve. `resume` entered the SessionStart matcher in #1091, so this hook
+  // now runs on re-entry: if Claude Code mints a fresh raw `session_id` there,
+  // `acquire()` returns `reason:'active'` with THIS SESSION'S OWN predecessor
+  // lock as `existingLock` (its heartbeat is fresh, so it is live by
+  // definition), `shouldForce` is false, and the hook bails — leaving the
+  // session running for up to the 4 h TTL without owning its own lock, while
+  // `recordConflictSignal()` below names the session's own former self as a
+  // foreign conflict.
+  //
+  // THREE conjuncts gate the force, and all three are load-bearing:
+  //   (a) `SAME_LOGICAL_SESSION_SOURCES.has(nativeSource)` — the harness itself
+  //       says this is a re-entry rather than a fresh start;
+  //   (b) `existingLock.semantic_session_id === semanticSessionId` — the lock's
+  //       label is written by this same bootstrap, so an equal label means the
+  //       predecessor was minted from the same (branch, date, mode, n) tuple;
+  //   (c) `existingLock.session_id === predecessorSessionId` — the RAW id our
+  //       own previous hook run recorded in current-session.json is the raw id
+  //       the live lock carries.
+  //
+  // (a)+(b) alone are NOT enough (security review, #1066): semantic labels are
+  // measurably collidable on one host — two sessions minted the SAME label when
+  // the host-wide registry contributed nothing to the n-increment — so a
+  // `/clear` in session B would take over session A's LIVE lock. (c) is the only
+  // conjunct tied to a witness WE wrote about OURSELVES; it is deliberately not
+  // `resumeLinkage === 'raw-id'`, which is true exactly when the raw id was
+  // PRESERVED — the complement of the fresh-raw-id case this branch exists for.
+  //
+  // NOT gated on process liveness, deliberately: `pid` on a session.lock is the
+  // ephemeral hook subprocess that WROTE it, so `isPidAliveOnHost(lock.pid)`
+  // reports "dead" for essentially every lock including live heartbeating ones
+  // (7/7 measured, #1137) — a vacuous predicate that would widen this branch to
+  // every source, not narrow it. `isLockLive()` is no help either: under
+  // `reason:'active'` acquire() has already established it is true
+  // (session-lock.mjs `classifyExisting`).
+  //
+  // Ceiling (BV-004), named rather than claimed closed: the residual is a peer
+  // that wrote `current-session.json` LAST with our semantic label — that peer's
+  // raw id is what we read as `predecessorSessionId`, so if it also owns the
+  // live lock, conjunct (c) holds for the wrong session. `current-session.json`
+  // carries no session field of its own (see
+  // `.claude/rules/identity-and-locks.md` § shared repo artefacts), which is
+  // exactly why this is a ceiling and not a proof. Revisit when the lock or
+  // current-session.json carries a durable logical-session id of its own.
+  const isSameLogicalReentry =
+    typeof nativeSource === 'string' && SAME_LOGICAL_SESSION_SOURCES.has(nativeSource);
+
   const shouldForce =
     acquireResult.ok !== true && (
       // #1137: 'stale-heartbeat' replaced the former 'stale-pid-dead' /
@@ -115,7 +191,14 @@ export async function bootstrapLock({
       acquireResult.reason === 'stale-heartbeat' ||
       (acquireResult.reason === 'active' &&
         acquireResult.existingLock &&
-        acquireResult.existingLock.session_id === sessionId)
+        (acquireResult.existingLock.session_id === sessionId ||
+          (isSameLogicalReentry &&
+            typeof semanticSessionId === 'string' &&
+            semanticSessionId.length > 0 &&
+            acquireResult.existingLock.semantic_session_id === semanticSessionId &&
+            typeof predecessorSessionId === 'string' &&
+            predecessorSessionId.length > 0 &&
+            acquireResult.existingLock.session_id === predecessorSessionId)))
     );
 
   if (!acquireResult.ok && shouldForce) {