@christang/keel 5.3.8 → 5.4.0

package/README.md

@@ -114,6 +114,17 @@ keel --init  →  keel context  →  /opsx:apply (pick one task)
    →  task-complete  →  /opsx:sync · /opsx:archive
 ```
 
+On the Claude target, the session-start hook also shows that state to **you**, not only to the
+agent — one line, before you type anything:
+
+```
+Keel: add-user-auth#2.1 — next: task-start. Disposable projection; OpenSpec and Git are the authority.
+```
+
+Set `KEEL_SESSION_PANEL=1` to draw it as a framed panel with the Keel mark instead. It is off by
+default, and turning it on changes nothing but the presentation — the same status and the same
+next command are in both forms.
+
 ### Full vs Lite
 
 Use **Full mode** (the OpenSpec flow above) for new features, interface or protocol changes,

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.3.8 -->
+<!-- keel:start version=5.4.0 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@christang/keel",
   "displayName": "Keel",
   "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
-  "version": "5.3.8",
+  "version": "5.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/plugins/keel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.3.8",
+  "version": "5.4.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.3.8",
+  "version": "5.4.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/scripts/pretooluse-guard.js

@@ -5,8 +5,10 @@
 // file edits while an explicit keel/guard.json manifest is active. Absence of
 // the manifest allows everything silently; a present-but-untrusted manifest
 // fails closed. The hook never writes state, never spawns the keel CLI, and
-// always exits 0 — denial is expressed only through hook output. Paths that
-// resolve outside the repository root are not product writes and pass through.
+// always exits 0 — denial is expressed only through hook output. The
+// repository is the guard's scope: a path resolving outside it is not a product
+// write and passes through, decided before the manifest is read so that no
+// manifest state can reach it.
 
 const crypto = require("crypto");
 const fs = require("fs");
@@ -116,12 +118,27 @@ function main() {
   }
   const repo =
     typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
-  const manifestPath = path.join(repo, "keel", "guard.json");
-  if (!fs.existsSync(manifestPath)) return 0;
 
   const pathField = FILE_EDIT_TOOLS.get(event.tool_name);
   if (!pathField) return 0;
 
+  // The repository is the guard's scope, so this boundary is settled before the
+  // manifest is read at all. It needs only the event's cwd and target, so no
+  // manifest state — absent, invalid, drifted, or completed — has anything to
+  // say about a path outside it. Deciding it here rather than further down is
+  // what stops a branch added to the manifest section from denying a file the
+  // guard never protected; that ordering has already failed twice.
+  const target = event.tool_input ? event.tool_input[pathField] : null;
+  if (typeof target !== "string" || !target) return 0;
+  const relative = path.relative(repo, path.resolve(repo, target));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return 0;
+  }
+  const candidate = relative.replace(/\\/g, "/");
+
+  const manifestPath = path.join(repo, "keel", "guard.json");
+  if (!fs.existsSync(manifestPath)) return 0;
+
   let manifest = null;
   try {
     manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
@@ -144,14 +161,6 @@ function main() {
   // stop the one thing the completion gate is waiting for. Derived from the
   // manifest's existing `change` field, so no manifest shape changes.
   const recordPrefix = `openspec/changes/${manifest.change}/`;
-
-  const target = event.tool_input ? event.tool_input[pathField] : null;
-  if (typeof target !== "string" || !target) return 0;
-  const relative = path.relative(repo, path.resolve(repo, target));
-  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-    return 0;
-  }
-  const candidate = relative.replace(/\\/g, "/");
   if (candidate.startsWith(recordPrefix)) return 0;
 
   for (const entry of manifest.authority) {

package/plugins/keel/scripts/session-start.js

@@ -15,9 +15,11 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
-// This text is injected into the agent and never rendered for the human, so
-// without an explicit instruction the projection reaches nobody who can catch
-// it being wrong. Every branch carries the same phrase, degraded ones included.
+// This text is injected into the agent; the human reads the `systemMessage`
+// line instead. Both channels ship on every branch, degraded ones included,
+// and neither makes the other redundant: the host's line says what the state
+// is, and this instruction is what surfaces the state the agent actually
+// worked from, which is the one a user can catch being wrong.
 const DISCLOSURE = "to the user in your first reply";
 
 const TIMEOUT_MS = Number(process.env.KEEL_HOOK_TIMEOUT_MS || 8000) || 8000;
@@ -32,15 +34,77 @@ function readStdin() {
   }
 }
 
-function emit(context) {
-  process.stdout.write(
-    `${JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext: context,
-      },
-    })}\n`
+// The human line rides the host's `systemMessage` field, which is rendered to
+// the person at session start without waiting for them to type. It is a second
+// channel, not a replacement: `additionalContext` still carries the full
+// projection to the agent, and a host that does not recognize the field simply
+// ignores it and leaves today's behavior intact.
+function emit(context, humanMessage) {
+  const payload = {};
+  if (humanMessage) payload.systemMessage = humanMessage;
+  payload.hookSpecificOutput = {
+    hookEventName: "SessionStart",
+    additionalContext: context,
+  };
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+// Stated on the human line as well as the model payload: the person reading it
+// at session start is the one who must not mistake a projection for authority.
+const DISPOSABLE = "Disposable projection; OpenSpec and Git are the authority.";
+
+// The Keel mark. A keel is the carina, the ridge on a bird's sternum, so the
+// animal that literally has one is a bird. Every cell is drawn from
+// U+2580–U+259F — the same block-element family as the host's own startup
+// banner — because those code points are East-Asian-Ambiguous width: pinning
+// the charset is what keeps the rows aligned under a CJK locale, and matters
+// more than the shape. The rows are padded to equal width so that a future
+// edit which breaks the rectangle is caught rather than silently skewed.
+const MARK = [
+  "▙▖▛▀▜  ▛▀▜▗▟",
+  "  ▌█▐  ▌█▐  ",
+  "  ▙▄▟▚▞▙▄▟  ",
+].join("\n");
+
+// The frame is modelled on the host's own welcome panel and draws from
+// U+2500–U+257F, a different range than the mark. Its width is the longest
+// content row, so a long change name widens the panel instead of being cut:
+// the identifier is the most useful thing in the projection, and truncating
+// the payload to preserve the frame would invert what the frame is for.
+// Leads with a newline because the host prefixes the message with
+// `<hookEvent>:<source> says: `, which would otherwise push the top rule out
+// of line with the rows beneath it.
+// Opt-in. The single line is what answers the reported problem — nobody is
+// told anything at session start — and it ships on. The panel is presentation,
+// and presentation that appears unbidden in every session of every install
+// should be chosen rather than inherited. The allowlist is explicit so a typo
+// leaves the default in place instead of quietly switching it on.
+const PANEL_TITLE = "Keel";
+const PANEL_ENABLED = /^(1|true|on|yes)$/i.test(
+  String(process.env.KEEL_SESSION_PANEL || "").trim()
+);
+
+function panel(lines) {
+  if (!PANEL_ENABLED) return lines.join(" ");
+  const rows = [...MARK.split("\n"), "", ...lines];
+  const width = Math.max(
+    ...rows.map((row) => row.length),
+    PANEL_TITLE.length + 8
   );
+  const centred = rows.map((row) => {
+    if (!row) return "";
+    const isMark = /^[▀-▟ ]+$/.test(row);
+    if (!isMark) return row;
+    const pad = Math.floor((width - row.length) / 2);
+    return " ".repeat(pad) + row;
+  });
+  const head = `─── ${PANEL_TITLE} `;
+  return [
+    "",
+    `╭${head}${"─".repeat(width + 2 - head.length)}╮`,
+    ...centred.map((row) => `│ ${row.padEnd(width)} │`),
+    `╰${"─".repeat(width + 2)}╯`,
+  ].join("\n");
 }
 
 function runKeel(cwd, args) {
@@ -53,11 +117,18 @@ function runKeel(cwd, args) {
   });
 }
 
+// A degraded projection needs the human line most: a hook that fails silently
+// is indistinguishable from a hook that never ran, which is how this whole
+// failure mode was reported in the first place.
 function fallback(reason) {
   emit(
     `Keel hook fallback: ${reason} Run \`keel context\` manually; `
       + "OpenSpec and Git remain the durable authority. Report this failure "
-      + `and that command ${DISCLOSURE}.`
+      + `and that command ${DISCLOSURE}.`,
+    panel([
+      `Keel: projection unavailable — ${reason} Next: keel context.`,
+      DISPOSABLE,
+    ])
   );
 }
 
@@ -112,8 +183,14 @@ function main() {
       : "Keel session projection (disposable; OpenSpec and Git are the durable authority):";
 
   const lines = [header];
+  let human = [];
   if (context.status === "ready" && context.selection) {
     const task = context.selection.task ? `#${context.selection.task}` : "";
+    human = [
+      `Keel: ${context.selection.change}${task} — next: `
+        + `${context.nextAction ? context.nextAction.kind : "unknown"}.`,
+      DISPOSABLE,
+    ];
     lines.push(
       `- context ready: ${context.selection.change}${task} `
         + `(${context.selection.source}); next action: `
@@ -142,8 +219,18 @@ function main() {
       );
     }
   } else {
-    lines.push(`- context status: ${context.status || "unknown"}.`);
-    for (const reason of (context.reasons || []).slice(0, MAX_REASONS)) {
+    const status = context.status || "unknown";
+    const reasons = (context.reasons || []).slice(0, MAX_REASONS);
+    human = [
+      `Keel: ${status}`
+        + (reasons.length > 0
+          ? ` — ${String(reasons[0]).slice(0, MAX_REASON_LENGTH)}`
+          : "")
+        + " Next: keel context.",
+      DISPOSABLE,
+    ];
+    lines.push(`- context status: ${status}.`);
+    for (const reason of reasons) {
       lines.push(`- reason: ${String(reason).slice(0, MAX_REASON_LENGTH)}`);
     }
     lines.push(
@@ -152,7 +239,7 @@ function main() {
     );
   }
   lines.push(`- report this state ${DISCLOSURE}; it authorizes nothing.`);
-  emit(lines.join("\n"));
+  emit(lines.join("\n"), panel(human));
   return 0;
 }
 

package/scripts/validate_plugin.py

@@ -37,8 +37,8 @@ REQUIRED_SCRIPTS = [
     "scripts/validate_plugin.py",
 ]
 
-PACKAGE_VERSION = "5.3.8"
-PROTOCOL_VERSION = "5.3.8"
+PACKAGE_VERSION = "5.4.0"
+PROTOCOL_VERSION = "5.4.0"
 LEGACY_MANAGED_START = "<!-- keel:start version=2.1 -->"
 OPENSPEC_SCHEMA_NAME = "keel-spec-driven"
 # Mirrors KEEL_PACKAGE_NAME in scripts/install_to_repo.py, one of the two
@@ -5132,6 +5132,164 @@ def fill_template_slots(text: str, comments: str = "strip") -> str:
         text = collapsed
 
 
+def validate_guard_scope_is_the_repository_scenario() -> int:
+    """Issue #31: a decision needing no manifest sat downstream of reading one.
+
+    Whether a target lies outside the repository is computable from the event's
+    cwd and target path alone, but the invalid-manifest denial ran first, so a
+    corrupt `keel/guard.json` denied writes to files the guard never protected.
+    The precedence is what is asserted here, not the passthrough: a scenario
+    checking only that an out-of-repo path passes under a valid manifest would
+    have passed before this change too.
+    """
+    hook = ROOT / "plugins/keel/scripts/pretooluse-guard.js"
+    if not hook.is_file():
+        report(f"guard-scope-is-the-repository: missing hook {hook}.")
+        return 1
+
+    with tempfile.TemporaryDirectory(prefix="keel-guard-scope-") as raw:
+        root = Path(raw)
+        repo = root / "repo"
+        outside = root / "scratch"
+        outside.mkdir(parents=True)
+        write_text(repo / "src/feature.js", "// product\n")
+        # A live spec, so the Covers source lands outside the record layer and
+        # authority drift can actually fire. Drifting the change's own tasks.md
+        # produces no drift at all, because the record layer exempts it.
+        live = repo / "openspec/specs/demo-cap/spec.md"
+        write_text(
+            live,
+            "# demo-cap\n\n## Purpose\n\nFixture.\n\n"
+            "### Requirement: The system emits a feed status\n"
+            "The system SHALL emit the recorded feed status.\n\n"
+            "#### Scenario: A status is emitted\n"
+            "- **WHEN** the feed runs\n- **THEN** the status is recorded\n",
+        )
+        write_text(
+            repo / "openspec/changes/demo/tasks.md",
+            "# Tasks\n\n## Invalidates\n\n- None.\n\n"
+            "- [ ] 1.1 Exercise the guard\n"
+            "  - Covers:\n    - demo-cap / The system emits a feed status\n"
+            "  - Touch:\n    - src/feature.js\n"
+            "  - Verify:\n    - Strategy: evidence-first\n    - M1: node test.js\n"
+            "  - Evidence:\n    - Contract: pending\n    - M1: pending\n"
+            "    - Review:\n      - Status: pending\n"
+            "      - Acceptance check: pending\n      - Scope check: pending\n"
+            "      - Findings: pending\n    - Blocker: none\n",
+        )
+        started = run_keel(
+            repo, "gate", "task-start", "--change", "demo", "--task", "1.1",
+            "--record", "--json",
+        )
+        if started.returncode != 0:
+            report("guard-scope-is-the-repository: the fixture did not start.")
+            report((started.stdout or started.stderr).strip())
+            return 1
+        manifest_path = repo / "keel/guard.json"
+        manifest_text = manifest_path.read_text(encoding="utf-8")
+        hashed = [
+            item["path"] for item in json.loads(manifest_text).get("authority", [])
+        ]
+        if "openspec/specs/demo-cap/spec.md" not in hashed:
+            report(
+                "guard-scope-is-the-repository: the fixture hashed no authority "
+                f"outside the change directory, so drift cannot fire: {hashed}."
+            )
+            return 1
+
+        def decide(target: Path) -> str:
+            event = json.dumps({
+                "cwd": str(repo),
+                "tool_name": "Edit",
+                "tool_input": {"file_path": str(target)},
+            })
+            result = subprocess.run(
+                ["node", str(hook)],
+                input=event,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                check=False,
+            )
+            out = (result.stdout or "").strip()
+            if not out:
+                return "allow"
+            payload = json.loads(out)["hookSpecificOutput"]
+            return payload.get("permissionDecisionReason", "deny")
+
+        def expect(label: str, target: Path, allow: bool, needle: str = "") -> bool:
+            verdict = decide(target)
+            if allow:
+                if verdict != "allow":
+                    report(f"guard-scope-is-the-repository: {label} was denied.")
+                    report(f"  {verdict}")
+                    return False
+                return True
+            if verdict == "allow":
+                report(f"guard-scope-is-the-repository: {label} was allowed.")
+                return False
+            if needle and needle not in verdict:
+                report(
+                    f"guard-scope-is-the-repository: {label} was denied for the "
+                    f"wrong reason; expected {needle!r}."
+                )
+                report(f"  {verdict}")
+                return False
+            return True
+
+        scratch = outside / "notes.md"
+        # M2 — the in-repository denials must survive the reordering.
+        checks = [
+            expect("an in-Touch write", repo / "src/feature.js", True),
+            expect(
+                "an in-repository path outside Touch",
+                repo / "other.js",
+                False,
+                "outside Touch",
+            ),
+            expect(
+                "the guarded change's own records",
+                repo / "openspec/changes/demo/notes.md",
+                True,
+            ),
+            expect("an out-of-repository write", scratch, True),
+        ]
+
+        # M1, first half — genuine authority drift.
+        write_text(live, live.read_text(encoding="utf-8") + "\nDRIFTED\n")
+        checks.append(
+            expect("an in-Touch write under drift", repo / "src/feature.js", False, "drift")
+        )
+        checks.append(
+            expect("an out-of-repository write under drift", scratch, True)
+        )
+
+        # M1, second half — the corrupt manifest, which is the reported defect.
+        manifest_path.write_text("{ not json", encoding="utf-8")
+        checks.append(
+            expect("an out-of-repository write under a corrupt manifest", scratch, True)
+        )
+        checks.append(
+            expect(
+                "an in-repository write under a corrupt manifest",
+                repo / "src/feature.js",
+                False,
+                "invalid",
+            )
+        )
+        if not all(checks):
+            return 1
+    if "guard-scope-is-the-repository" not in {name for name, _ in SCENARIOS}:
+        report(
+            "guard-scope-is-the-repository: the scenario registry does not "
+            "include it."
+        )
+        return 1
+    report("guard-scope-is-the-repository scenario passed.")
+    return 0
+
+
 def validate_completion_requires_a_recorded_anchor_scenario() -> int:
     """Issue #30: an unrecorded anchor made the drift guarantee conditional.
 
@@ -8782,10 +8940,17 @@ def run_session_start_hook(
     *,
     keel_cli: str,
     timeout_ms: int | None = None,
+    panel: str | None = None,
 ) -> subprocess.CompletedProcess[str]:
     env = dict(os.environ)
     env["KEEL_CLI"] = keel_cli
     env["CLAUDE_PLUGIN_ROOT"] = str(ROOT / PLUGIN_ROOT)
+    # The suite must decide the panel's state rather than inherit whatever the
+    # developer running it has exported, or the default-off assertion would
+    # pass or fail by accident of the shell.
+    env.pop("KEEL_SESSION_PANEL", None)
+    if panel is not None:
+        env["KEEL_SESSION_PANEL"] = panel
     if timeout_ms is not None:
         env["KEEL_HOOK_TIMEOUT_MS"] = str(timeout_ms)
     return subprocess.run(
@@ -8811,10 +8976,98 @@ def session_start_context(result: subprocess.CompletedProcess[str]) -> str | Non
     return output.get("additionalContext")
 
 
-# The projection is delivered through additionalContext, which the host injects
-# into the agent and never renders for the human. Every branch must therefore
-# carry the instruction to relay it, including — especially — the degraded ones,
-# because a projection nobody sees is a projection nobody checks.
+def session_start_message(result: subprocess.CompletedProcess[str]) -> str | None:
+    """The human-visible half of the projection, carried on `systemMessage`."""
+    if not result.stdout.strip():
+        return None
+    return json.loads(result.stdout).get("systemMessage")
+
+
+# Each branch pairs its human message with the tokens a person needs in order to
+# act: what the state is, and which command moves it. The degraded branches are
+# the load-bearing rows — a fallback nobody sees is the bug this pair of channels
+# exists to close.
+HUMAN_BRANCH_TOKENS = {
+    "ready": ("demo#1.1",),
+    "idle": ("idle", "keel context"),
+    "ambiguous": ("ambiguous", "keel context"),
+    "missing-CLI": ("missing or incompatible", "keel context"),
+    "malformed": ("malformed", "keel context"),
+    "timeout": ("failed or timed out", "keel context"),
+}
+HUMAN_AUTHORITY_TOKEN = "OpenSpec and Git"
+
+# The mark is drawn only from the block-element range the host's own banner uses.
+# That range is East-Asian-Ambiguous width, so a terminal under a CJK locale
+# renders every one of these cells the same way it already renders the banner —
+# which is the whole reason the charset is pinned rather than the shape.
+MARK_RANGE = (0x2580, 0x259F)
+MARK_ROWS = 3
+BORDER_RANGE = (0x2500, 0x257F)
+
+
+def panel_rows(message: str) -> list[str]:
+    """The rendered panel: everything after the leading newline."""
+    return message[1:].split("\n") if message.startswith("\n") else []
+
+
+def is_mark_row(content: str) -> bool:
+    """A mark row is non-empty and drawn only from blocks and inner spaces.
+
+    The inner spaces are load-bearing shape - they are the owl's eye gaps - so
+    the charset test admits them rather than stripping the row down to its
+    glyphs and demanding every remaining cell be a block.
+    """
+    return bool(content.strip()) and all(
+        c == " " or MARK_RANGE[0] <= ord(c) <= MARK_RANGE[1] for c in content
+    )
+
+
+def panel_problem(message: str) -> str | None:
+    """The panel must close.
+
+    A frame turns a one-cell width error from a cosmetic skew into visibly
+    broken output, so every row is checked for equal width rather than trusted.
+    The mark keeps its own charset check: the border draws from U+2500-U+257F
+    and the mark from U+2580-U+259F, and mixing them is what would misalign
+    under a locale that renders one range wide.
+    """
+    if not message.startswith("\n"):
+        return "human message does not open with a newline before the panel"
+    rows = panel_rows(message)
+    if len(rows) < MARK_ROWS + 3:
+        return f"panel has {len(rows)} rows, too few to frame the mark"
+    if not (rows[0].startswith("╭") and rows[0].endswith("╮")):
+        return f"panel top rule is not a rule: {rows[0]!r}"
+    if "Keel" not in rows[0]:
+        return "panel top rule carries no title"
+    if not (rows[-1].startswith("╰") and rows[-1].endswith("╯")):
+        return f"panel bottom rule is not a rule: {rows[-1]!r}"
+    for row in rows[1:-1]:
+        if not (row.startswith("│") and row.endswith("│")):
+            return f"panel body row is not enclosed: {row!r}"
+    widths = {len(row) for row in rows}
+    if len(widths) != 1:
+        return f"panel rows are ragged: widths {sorted(widths)}"
+    marks = [row[2:-2] for row in rows[1:-1] if is_mark_row(row[2:-2])]
+    if len(marks) != MARK_ROWS:
+        return f"panel carries {len(marks)} mark rows, expected {MARK_ROWS}"
+    return None
+
+
+def panel_content(message: str) -> str:
+    """The panel with its frame and mark taken away."""
+    rows = panel_rows(message)
+    kept = [row[2:-2] for row in rows[1:-1] if not is_mark_row(row[2:-2])]
+    return " ".join(part.strip() for part in kept if part.strip())
+
+
+# additionalContext is the agent's half of the projection; the human reads the
+# systemMessage line asserted above. Every branch must still carry the
+# instruction to relay it, including — especially — the degraded ones. The two
+# checks are not redundant: one proves the state was shown, this one proves the
+# agent was told to say which state it is working from, and only the second can
+# expose the two disagreeing.
 SESSION_START_DISCLOSURE = "to the user in your first reply"
 
 # A host loads its plugins once per session, so the projection can be absent for
@@ -9014,6 +9267,134 @@ def validate_native_plugin_session_start_scenario() -> int:
             report(repr(hang_context))
             return 1
 
+        # Every branch is exercised in both forms. The panel is opt-in, so the
+        # default run is the one that ships; the enabled run only proves the
+        # decoration still assembles when asked for. Both must carry the same
+        # information, which is what keeps the switch from costing anything.
+        branches = (
+            ("ready", ready_repo, real_cli, None),
+            ("idle", idle_repo, real_cli, None),
+            ("ambiguous", ambiguous_repo, real_cli, None),
+            ("missing-CLI", ready_repo, "keel-definitely-missing-cli-xyz", None),
+            ("malformed", ready_repo, f'node "{malformed_cli}"', None),
+            ("timeout", ready_repo, f'node "{hang_cli}"', 700),
+        )
+        for label, repo, cli, timeout_ms in branches:
+            for panel_env in (None, "1"):
+                result = run_session_start_hook(
+                    repo, codex_event, keel_cli=cli,
+                    timeout_ms=timeout_ms, panel=panel_env,
+                )
+                mode = "default" if panel_env is None else "panel"
+                message = session_start_message(result)
+                if not message:
+                    report(
+                        f"native-plugin-session-start {label}/{mode} branch "
+                        "emitted no human-visible message, so that state "
+                        "reaches only the agent and nobody can catch it being "
+                        "wrong."
+                    )
+                    return 1
+                if label == "ambiguous" and "alpha#1.1" in message:
+                    report(
+                        f"native-plugin-session-start {label}/{mode} human "
+                        "message named a guessed owner."
+                    )
+                    return 1
+                if panel_env is None:
+                    decoration = [
+                        c for c in message
+                        if MARK_RANGE[0] <= ord(c) <= MARK_RANGE[1]
+                        or BORDER_RANGE[0] <= ord(c) <= BORDER_RANGE[1]
+                    ]
+                    if decoration:
+                        report(
+                            f"native-plugin-session-start {label} draws the "
+                            f"panel without being asked: {decoration[:6]!r}"
+                        )
+                        return 1
+                    if "\n" in message:
+                        report(
+                            f"native-plugin-session-start {label} default "
+                            f"message is not a single line: {message!r}"
+                        )
+                        return 1
+                    carried = message
+                else:
+                    problem = panel_problem(message)
+                    if problem:
+                        report(
+                            f"native-plugin-session-start {label} {problem}"
+                        )
+                        return 1
+                    # Neither frame nor mark may be load-bearing: take both
+                    # away and the message still has to say what the state is
+                    # and which command moves it.
+                    carried = panel_content(message)
+                absent = [
+                    token
+                    for token in (
+                        *HUMAN_BRANCH_TOKENS[label], HUMAN_AUTHORITY_TOKEN
+                    )
+                    if token not in carried
+                ]
+                if absent:
+                    report(
+                        f"native-plugin-session-start {label}/{mode} message "
+                        f"omits {absent}: {carried!r}"
+                    )
+                    return 1
+
+        # A value outside the allowlist must leave the default in place, so a
+        # typo cannot silently switch the decoration on.
+        typo = session_start_message(
+            run_session_start_hook(
+                idle_repo, codex_event, keel_cli=real_cli, panel="yeah"
+            )
+        ) or ""
+        if "\n" in typo or "╭" in typo:
+            report(
+                "native-plugin-session-start enabled the panel for a value "
+                f"outside the allowlist: {typo!r}"
+            )
+            return 1
+
+        # The panel sizes to its content. A change name longer than every other
+        # row must widen the frame rather than be cut, because the identifier
+        # is the thing the reader came for.
+        long_name = "a-deliberately-long-change-name-that-exceeds-the-panel-default"
+        wide_repo = tmp / "wide"
+        write_text(
+            wide_repo / f"openspec/changes/{long_name}/tasks.md",
+            task_contract_fixture(),
+        )
+        wide_message = session_start_message(
+            run_session_start_hook(wide_repo, codex_event, keel_cli=real_cli, panel="1")
+        ) or ""
+        problem = panel_problem(wide_message)
+        if problem:
+            report(f"native-plugin-session-start wide panel {problem}")
+            return 1
+        if long_name not in panel_content(wide_message):
+            report(
+                "native-plugin-session-start truncated the change name to fit "
+                f"the panel: {panel_content(wide_message)!r}"
+            )
+            return 1
+        narrow_message = session_start_message(
+            run_session_start_hook(
+                idle_repo, codex_event, keel_cli=real_cli, panel="1"
+            )
+        ) or ""
+        wide = len(panel_rows(wide_message)[0])
+        narrow = len(panel_rows(narrow_message)[0])
+        if wide <= narrow:
+            report(
+                "native-plugin-session-start panel width is fixed, not derived "
+                f"from content: wide={wide} narrow={narrow}"
+            )
+            return 1
+
     hooks_config = json.loads(
         (ROOT / PLUGIN_ROOT / "hooks/hooks.json").read_text(encoding="utf-8")
     )
@@ -14145,6 +14526,10 @@ SCENARIOS: tuple = (
         "completion-requires-a-recorded-anchor",
         validate_completion_requires_a_recorded_anchor_scenario,
     ),
+    (
+        "guard-scope-is-the-repository",
+        validate_guard_scope_is_the_repository_scenario,
+    ),
     ("spec-template-validates", validate_spec_template_validates_scenario),
     (
         "tasks-template-red-green-example",