@monster-orange/den 0.4.8 → 0.4.10

package/CHANGELOG.md

@@ -4,6 +4,111 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.10] - 2026-11-07
+
+### Changed
+
+- **A confirmed merge stays confirmed.** Once `gh pr view` says an agent's
+  pull request is MERGED, its record keeps that (`prMergeConfirmed`), and
+  `usage` doesn't ask GitHub about it again. A later run that can't check
+  no longer drops it. A merged flag from before 0.4.10, with no
+  confirmation, is checked again.
+- **`usage agents` counts only real asks.** "Asked GitHub for the state of
+  N pull requests" counts the times gh ran. When gh is not installed, it
+  says "Couldn't check N merges: gh is not installed." instead.
+- **The PR column** shows the confirmed pull request, with "(merged)", when
+  the agent merged one it didn't open.
+- **A bare `gh pr merge`** (the branch's own pull request) is confirmed by
+  the number gh gives: the check is now `gh pr view --json number,state`.
+  With no number, it is not marked; an empty ref is never a key.
+- **Dropping a mark drops its rotation.** When gh no longer confirms a
+  merged flag, a "PR merged" rotation it made due is cleared too. A
+  rotation due after compactions is left alone.
+
+### Migrations
+
+None.
+
+## [0.4.9] - 2026-11-07
+
+A session ends when its pull request merges, or after 3 compactions. The
+role then relaunches from a handoff, in a fresh conversation (den#4, the
+session-rotation issue). Sessions that never end re-read huge contexts on
+every call. This keeps each session to one objective.
+
+### Added
+
+- **Den counts compactions.** A `SessionStart` hook (source `compact`),
+  alongside Den's other hooks for default-pack Claude Code agents, counts
+  each compaction of the agent's conversation once it happened. A
+  `/compact` that does nothing is not counted. The count is in
+  `<state dir>/agent-files/<id>/rotation.json`, and starts at 0 for each
+  new conversation.
+- **Two triggers.** A rotation is due after `agents.rotate.after_compactions`
+  compactions (default 3), or once the agent's pull request merged (the
+  `prMerged` outcome from `usage agents`). A merge counts only when the
+  agent ran `gh pr merge` itself, it exited 0, and `gh pr view` then says
+  MERGED. `echo gh pr merge 1` or `gh pr merge --help` never counts.
+- **The agent is told.** The compaction summary keeps the instruction, a
+  `SessionStart` hook adds it after the compaction, and the `Stop` hook
+  blocks once until the handoff is written. The shared instructions say
+  what to do: write `handoff.md` in the agent's files folder, then end the
+  turn.
+- **The handoff check.** A handoff has five parts: Objective, State, Open
+  items, How to QA, Next step. Each must be there and filled in, and every
+  ID explained. `<cli> agents handoff-check <id|file|->` runs the check (on an
+  agent's own handoff.md, by its id) and names what is missing.
+- **Relaunch from handoff.** A fresh conversation (a new conversation id),
+  with the same persona, workspace, folder and grants. Its first prompt is
+  the handoff. The handoff is then kept in `handoffs/`, and the record
+  notes the rotation. `<cli> agents relaunch <id>`, and
+  `POST /api/workspaces/<ws>/agents/<id>/relaunch`.
+- **The Agents page.** A rotated agent reads "Ready to relaunch (3
+  compactions)" or "Ready to relaunch (PR merged)". Its buttons are
+  Relaunch from handoff (the primary one), Start fresh and Remove. With no
+  handoff, or one that fails the check, the row says so and keeps Resume
+  and Start fresh. A running agent shows "Handoff due" or "Ready to
+  relaunch" as a tag.
+- **`agents.rotate` in the org config**: `after_compactions` (1 to 100,
+  default 3) and `standing` (default true). With `standing: false`,
+  standing personas such as the planner never rotate.
+- **Usage shows rotation.** `usage agents` adds each agent's compactions
+  and rotations. `usage report` adds `long_session_context_k`,
+  `never_ending_reread_pct` and `rotations`.
+
+### Changed
+
+- **Resume refuses a rotated conversation.** Once a rotation is due and the
+  handoff passes, `agents resume <id>` exits 1 with
+  `Relaunch from handoff: <cli> agents relaunch <id>`. The resume route
+  answers 409 with code `rotated`. Resume all lists it as not resumed.
+- **A standing persona that rotated relaunches on its own** after a
+  restart, as it resumed on its own before.
+- **The `Stop` hook and the new hooks take the agent's files folder** on
+  their command line (`--files <dir> --after <n>`).
+
+### Metrics (before → after)
+
+- Peak tokens per call in a long session: 365–510k → <150k.
+- Share of context re-reads from never-ending sessions: 59% → <15%.
+- How it is measured: `usage report` on this machine.
+  `long_session_context_k` is the highest average tokens per call of any
+  session. `never_ending_reread_pct` is the share of cache re-reads from
+  sessions that compacted more than `agents.rotate.after_compactions`
+  times. Compare a week's report before and after.
+- On the test fixture (15 sessions with 16 compactions each, and 127 that
+  end within 3): 399k → 139k per call, and 59% → 0% of re-reads. The same
+  calls re-read fewer tokens.
+
+### Migrations
+
+- None needed. Rotation is on for Den's default pack, with 3 compactions.
+  To change the number, set `agents.rotate.after_compactions`. To keep
+  standing personas from rotating, set `agents.rotate.standing: false`.
+  `rotate` is now a reserved key under `agents:`, so no agent can have the
+  id `rotate`. Agents started before 0.4.9 start counting at their next
+  start or resume.
+
 ## [0.4.8] - 2026-11-07
 
 Stopped agents stay in the list, and come back where they were (AG-14, the

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.8/hero-dark.png">
-  <img src="docs/images/0.4.8/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.10/hero-dark.png">
+  <img src="docs/images/0.4.10/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## Set up by your agent
@@ -38,7 +38,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.8/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.10/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -68,10 +68,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.8/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.8/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.8/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.8/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.10/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.10/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.10/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.10/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

package/docs/distributions.md

@@ -2401,6 +2401,11 @@ Den never writes your `~/.claude`; your own hooks still run.
   going (Claude Code's `decision: "block"`). It never blocks twice in a
   row (`stop_hook_active`), so it can't loop. Den adds no `SubagentStop` hook: a subagent reports to its parent
   agent, not to a person.
+- `PreCompact`, and `SessionStart` after a compaction or on resume
+  (`rotation-hook.ts`), count the conversation's compactions (on
+  `SessionStart` after a compaction only) and ask for a handoff once a
+  rotation is due. See Session rotation, below. While one is
+  due, the `Stop` hook also blocks once until `handoff.md` passes.
 
 **The hand-back template**, which the check enforces:
 
@@ -2454,6 +2459,108 @@ A persona of yours that replaces a default one (same id) takes your
 pack's setting, not Den's pack's. Anything but `true` or `false`, or an
 unknown key, is an error naming the key.
 
+### Session rotation: one session per objective
+
+A session that never ends re-reads its whole context on every call. So a
+session ends when its pull request merges, or after a few compactions. Its
+role then relaunches in a fresh conversation, from a handoff the session
+wrote. This is rule R2 (one session per objective) of the agent-loop
+report. It works on den-claude for personas with Den's hooks on.
+
+**How it works.**
+
+1. Den's hooks count compactions. A `SessionStart` hook with source
+   `compact` (`guardrails/rotation-hook.ts`) adds one to
+   `<stateDir>/agent-files/<id>/rotation.json` after every compaction,
+   manual or automatic. It fires only once a compaction happened.
+   `PreCompact` does not count: it also runs for a `/compact` that does
+   nothing ("Not enough messages to compact"). The count belongs to one
+   conversation, and starts at 0 for a new one.
+2. A trigger fires. Either the count reaches
+   `agents.rotate.after_compactions` (default 3), or the agent's pull
+   request merged (the `prMerged` outcome that `<cli> usage agents` saves).
+   A merge is never taken from text. The agent must have run `gh pr merge`
+   as a command (after any `cd` or `VAR=value` prefix; not `--help`, not
+   `echo gh pr merge`), and it must have exited 0. Then `usage` asks
+   `gh pr view <ref> --json number,state` in the agent's folder, and only
+   `MERGED` counts. With no gh, or on any error, it is not marked. That
+   query is the one thing `usage` asks outside this machine; it says so
+   when it does.
+3. Den tells the agent. The `PreCompact` hook's output asks the compaction
+   summary to keep the instruction. A `SessionStart` hook (after a
+   compaction, or on resume) adds it to the context. The `Stop` hook blocks
+   the turn once while the handoff is missing or fails the check. The
+   instruction: write `handoff.md` in the agent's files folder, then end
+   the turn.
+4. Den relaunches the role. **Relaunch from handoff** starts a fresh
+   conversation (a new conversation id) with the same persona, workspace,
+   folder and grants. Its first prompt is the handoff. The handoff moves to
+   `agent-files/<id>/handoffs/`, and the record notes the rotation.
+
+**The handoff** has five parts, each a heading, each filled in. Write it
+plainly, and explain every ID, as in a hand-back. It must stay under 20,000
+characters, since it becomes a first prompt.
+
+```markdown
+## Objective
+
+<what the work is for>
+
+## State
+
+<what is done, and where it is: branch, pull request, files>
+
+## Open items
+
+<what is left; or none>
+
+## How to QA
+
+<the steps to see it working>
+
+## Next step
+
+<the one thing to do first>
+```
+
+`<cli> agents handoff-check <id|file|-> [--json]` runs the check, on an
+agent's `handoff.md` (by its id), a file, or stdin: exit 0 when
+it passes, 1 with each missing or empty part and each unexplained ID. A
+part can also be a line such as `Next step: open the PR`.
+
+**Resume after a rotation.** Once a rotation is due and `handoff.md`
+passes, Den declines a plain Resume of that conversation:
+
+- The Agents page shows the row as "Ready to relaunch (3 compactions)" or
+  "Ready to relaunch (PR merged)". Its buttons are Relaunch from handoff
+  (the primary one), Start fresh and Remove.
+- `<cli> agents resume <id>` refuses (exit 1) and prints
+  `Relaunch from handoff: <cli> agents relaunch <id>`. The resume route
+  answers 409 with code `rotated`.
+- `<cli> agents relaunch <id> [-w <ws>]` and
+  `POST /api/workspaces/<ws>/agents/<id>/relaunch` relaunch it. A running
+  rotated agent is stopped first.
+- With `handoff.md` missing or failing the check, the row says so, and
+  Resume and Start fresh stay. Resume the agent to write or fix it.
+  Relaunch says what is wrong (409 `no_handoff`) and names Start fresh.
+- After a restart, a standing persona that rotated relaunches on its own,
+  as a standing persona resumes on its own.
+
+**Settings**, in the org config:
+
+```yaml
+agents:
+  rotate:
+    after_compactions: 3 # 1 to 100; the default is 3
+    standing: true # standing personas rotate too (the default)
+```
+
+`standing` is for standing personas, such as the planner and the
+orchestrator. With `true` (the default), they rotate like the rest: only
+their context resets, and they keep their id and workspace. With `false`,
+they never rotate. A setting takes effect at the agent's next start or
+relaunch. An unknown key, or a bad value, is an error naming the key.
+
 ### Runtimes
 
 `<cli> doctor` lists the runtime kind. Den knows the runtimes in its
@@ -2654,13 +2761,33 @@ request it opened, whether it merged, whether its last test run passed,
 and its wall-clock time. It matches transcripts to agents by the
 conversation id Den saved at start. It prints the share of agents with
 both. Transcripts never leave the machine, and their text is never kept:
-only counts.
+only counts. "Whether it merged" is checked: when an agent ran
+`gh pr merge`, `usage` asks `gh pr view <ref> --json number,state` to confirm it.
+That query, the pull request's number or URL, is the only thing it asks
+outside, and the output says when it asked (or that it couldn't, because
+gh is not installed). A merge gh confirmed is kept in the record
+(`prMergeConfirmed`, the pull request's ref or, for a bare `gh pr merge`,
+the number gh gave) and not asked about again. A mark gh no longer
+confirms is dropped, with the "PR merged" rotation it made due.
 
 `<cli> usage report [--days 7] [--json]` writes a weekly summary to
 `<state dir>/usage/<date>.json` and `.md`, compared with the last one:
 calls, cache re-reads, polls, sleeps, compactions, corrections and the
 attributed share.
 
+For session rotation, `usage agents` also shows each agent's compactions
+(in its current conversation) and rotations (how many times Den relaunched
+it from a handoff). A merged pull request makes the agent's rotation due.
+`usage report` adds three numbers:
+
+- `long_session_context_k`: the highest average tokens per call of any
+  session in the window, in thousands. A call's tokens are its input,
+  cache reads and cache writes.
+- `never_ending_reread_pct`: the share of cache re-reads that came from
+  never-ending sessions. A never-ending session compacted more often than
+  `agents.rotate.after_compactions`.
+- `rotations`: relaunches from a handoff, over the agents listed.
+
 Den reads Claude Code's transcripts (`$CLAUDE_CONFIG_DIR/projects`, else
 `~/.claude/projects`). A plugin can add a reader for another runtime with
 the `usage` kind (server tier). A runtime with no reader shows "no usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/shared/agents/den-claude.ts

@@ -21,6 +21,11 @@
  *   alongside any hooks the user has; Den never writes ~/.claude.
  * - Each launch picks a fresh conversation id (--session-id); resume
  *   continues it with --resume <id>, in the same cwd, with the same MCP.
+ *   A relaunch from handoff (den#4) is a launch whose first prompt, the
+ *   last argument, is the handoff.
+ * - Session rotation (den#4): the hooks include PreCompact and
+ *   SessionStart (rotation-hook.ts) with the agent's files dir and its
+ *   limit (LaunchInput rotateAfter), so its compactions are counted there.
  * - Permission prompts stay in the terminal (approvals: "terminal"):
  *   --permission-mode default, unless the persona's `permission_mode` sets
  *   one of Claude Code's modes; bypassPermissions warns at every start. The
@@ -45,7 +50,8 @@ import * as fs from "fs";
 import * as path from "path";
 import { configuredRuntimeBin } from "../den-config.js";
 import { rolePrompt } from "./personas.js";
-import { guardrailHooks } from "./guardrails.js";
+import { GUARDRAILS_DIR, guardrailHooks, hookCommands } from "./guardrails.js";
+import { DEFAULT_ROTATE } from "./rotation.js";
 import {
   LaunchError,
   mcpConfigJson,
@@ -227,7 +233,16 @@ function common(input: LaunchInput): {
 } {
   const file = mcpConfigPath(input);
   const mode = permissionMode(input);
-  const hooks = input.persona.guardrails?.hooks ? guardrailHooks() : null;
+  // den#4: the rotation hooks count this agent's compactions in its files dir.
+  const hooks = input.persona.guardrails?.hooks
+    ? guardrailHooks(
+        GUARDRAILS_DIR,
+        hookCommands(GUARDRAILS_DIR, process.execPath, {
+          files: input.filesDir,
+          after: input.rotateAfter ?? DEFAULT_ROTATE.afterCompactions,
+        }),
+      )
+    : null;
   const settings = input.stateDir || hooks ? settingsPath(input) : null;
   return {
     argv: [
@@ -287,20 +302,40 @@ function binFor(input: LaunchInput): string {
   return d.path;
 }
 
+/**
+ * The first prompt as claude's last argument, or nothing. An agent wrote
+ * the text (its handoff), so it is never allowed to start with "-": that
+ * would be read as a flag. One that does gets a word in front.
+ */
+export function firstPromptArg(text: string | undefined): string[] {
+  const t = text?.trim();
+  if (!t) return [];
+  return [t.startsWith("-") ? `Prompt: ${t}` : t];
+}
+
 export const denClaude: Runtime = {
   id: DEN_CLAUDE_ID,
   label: DEN_CLAUDE_CATALOG.name,
   vendor: DEN_CLAUDE_CATALOG.vendor,
   catalog: DEN_CLAUDE_CATALOG,
   denTools: true,
+  firstPrompt: true,
   find: DEN_CLAUDE_FIND,
   detect,
   launch(input): LaunchOutput {
     const bin = binFor(input);
     const id = input.resumeToken ?? randomUUID();
     const c = common(input);
+    // A relaunch from handoff (den#4): the handoff is the first prompt,
+    // the last argument (firstPromptArg: never read as a flag).
     return {
-      argv: [bin, "--session-id", id, ...c.argv],
+      argv: [
+        bin,
+        "--session-id",
+        id,
+        ...c.argv,
+        ...firstPromptArg(input.firstPrompt),
+      ],
       env: {},
       files: c.files,
       resumeToken: id,

package/src/shared/agents/guardrails/hooks.json

@@ -22,6 +22,29 @@
           }
         ]
       }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{rotation}",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{rotation}",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/src/shared/agents/guardrails/instructions.md

@@ -37,3 +37,26 @@ a numbered yes/no question is sent back to you to fix.
 Write "Decisions: none" when there are none, and "URL: none" (with a short
 reason) when the work has no page to open. Every message you end a turn
 with is read by a person, hand-back or not: explain each ID in it.
+
+### When your session rotates
+
+A session ends when its pull request merges, or after a few compactions
+(three unless your team set another number). Den tells you when that
+happens. Then write a handoff to the file Den names (`handoff.md` in your
+agent files folder) and end your turn. Den checks it, and relaunches your
+role from it in a fresh conversation. Use these headings, each filled in:
+
+```
+## Objective
+<what the work is for, in a sentence or two>
+## State
+<what is done, and where it is: branch, pull request, files>
+## Open items
+<what is left, one per line; or none>
+## How to QA
+<the steps to see it working>
+## Next step
+<the one thing to do first>
+```
+
+Write it plainly. Explain every ID in it, as in a hand-back.

package/src/shared/agents/guardrails/rotation-hook.ts

@@ -0,0 +1,127 @@
+/**
+ * Den's session-rotation hook for Claude Code sessions it launches
+ * (den#4). One script for two events, run with the agent's own files dir
+ * and its limit:
+ *
+ *   rotation-hook.ts --files <agent files dir> --after <n>   (0: never rotates)
+ *
+ * Hook contract (https://code.claude.com/docs/en/hooks):
+ *   - PreCompact: JSON on stdin with the common fields (`session_id`,
+ *     `transcript_path`, `cwd`, `hook_event_name`) and `trigger` (manual or
+ *     auto) and `custom_instructions`. Exit 0's stdout becomes instructions
+ *     for the compaction summary. It runs before Claude Code decides to
+ *     compact ("Not enough messages to compact" still runs it), so it never
+ *     counts. When this compaction would make a rotation due, its stdout
+ *     asks the summary to keep the instruction to write the handoff.
+ *   - SessionStart, with `source` "compact" (after a compaction that
+ *     happened) or "resume". "compact" counts the compaction in
+ *     rotation.json (rotation.ts). While a rotation is due, it prints
+ *     `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":…}}`,
+ *     which Claude Code adds to the context: write handoff.md, then end
+ *     the turn.
+ *
+ * The parser is tolerant: a field it doesn't find is left out, never an
+ * error. Any error lets Claude Code carry on (exit 0, nothing printed):
+ * the hook never blocks a compaction.
+ */
+import {
+  dueFor,
+  noteCompaction,
+  notePendingCompaction,
+  readHandoff,
+  readRotation,
+  rotationInstruction,
+} from "../rotation.js";
+
+export interface RotationHookArgs {
+  files: string;
+  after: number;
+}
+
+/** `--files <dir> --after <n>`; null when either is missing. */
+export function parseHookArgs(
+  argv: readonly string[],
+): RotationHookArgs | null {
+  const at = (flag: string) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const files = at("--files");
+  const after = Number(at("--after") ?? "");
+  if (!files || !Number.isInteger(after) || after < 0) return null;
+  return { files, after };
+}
+
+/** The hook's stdout for one input ("" prints nothing). */
+export function rotationHookOutput(
+  input: unknown,
+  args: RotationHookArgs,
+  now: Date = new Date(),
+): string {
+  if (!input || typeof input !== "object") return "";
+  const i = input as Record<string, unknown>;
+  const event = i.hook_event_name;
+  const conversation =
+    typeof i.session_id === "string" && i.session_id ? i.session_id : undefined;
+  if (event === "PreCompact" || (event === undefined && "trigger" in i)) {
+    // Not counted here: the compaction may not happen.
+    const prev = readRotation(args.files);
+    notePendingCompaction(args.files, conversation, i.trigger, args.after);
+    const counted =
+      prev &&
+      (!conversation ||
+        !prev.conversation ||
+        prev.conversation === conversation)
+        ? prev
+        : null;
+    const next = (counted?.compactions ?? 0) + 1;
+    const due =
+      dueFor(counted, conversation) ??
+      (args.after > 0 && next >= args.after ? "compactions" : undefined);
+    if (!due) return "";
+    return [
+      "Keep this instruction, word for word, at the top of the summary:",
+      rotationInstruction(
+        args.files,
+        due,
+        Math.max(next, counted?.compactions ?? 0),
+      ),
+    ].join("\n");
+  }
+  if (event === "SessionStart" || (event === undefined && "source" in i)) {
+    if (i.source !== "compact" && i.source !== "resume") return "";
+    const s =
+      i.source === "compact"
+        ? noteCompaction(args.files, i, args.after, now)
+        : readRotation(args.files);
+    const due = dueFor(s, conversation);
+    if (!due || readHandoff(args.files).status === "ok") return "";
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: rotationInstruction(args.files, due, s!.compactions),
+      },
+    });
+  }
+  return "";
+}
+
+async function main(): Promise<void> {
+  const args = parseHookArgs(process.argv.slice(2));
+  let text = "";
+  for await (const chunk of process.stdin) text += String(chunk);
+  if (!args) return;
+  let out = "";
+  try {
+    out = rotationHookOutput(JSON.parse(text), args);
+  } catch {
+    out = "";
+  }
+  if (out) process.stdout.write(`${out}\n`);
+}
+
+if (process.argv[1] && /rotation-hook\.[jt]s$/.test(process.argv[1]))
+  main().then(
+    () => process.exit(0),
+    () => process.exit(0),
+  );

package/src/shared/agents/guardrails/stop-hook.ts

@@ -13,17 +13,63 @@
  * When Claude is already continuing because of a stop hook
  * (stop_hook_active), it lets the turn end, so it never loops. Any error
  * lets the turn end too.
+ *
+ * Session rotation (den#4): run with `--files <agent files dir> --after
+ * <n>`, while a rotation is due (rotation.ts) and handoff.md is missing or
+ * fails the handoff check, it blocks once with what to write. Once the
+ * handoff passes, the turn ends as usual.
  */
 import { bareIds, checkHandback, looksLikeHandback } from "../handback.js";
+import {
+  dueFor,
+  readHandoff,
+  readRotation,
+  rotationInstruction,
+} from "../rotation.js";
+import { parseHookArgs, type RotationHookArgs } from "./rotation-hook.js";
+
+/** A due rotation's block, or "" (no rotation due, or the handoff passes). */
+function rotationBlock(
+  input: { session_id?: unknown },
+  args: RotationHookArgs,
+): string {
+  const s = readRotation(args.files);
+  const conversation =
+    typeof input.session_id === "string" ? input.session_id : undefined;
+  const due = dueFor(s, conversation);
+  if (!due) return "";
+  const h = readHandoff(args.files);
+  if (h.status === "ok") return "";
+  return JSON.stringify({
+    decision: "block",
+    reason: [
+      rotationInstruction(args.files, due, s!.compactions),
+      ...(h.status === "invalid"
+        ? [
+            "Den checked the handoff there and it is not ready. Fix these:",
+            ...h.problems.map((p) => `- ${p}`),
+          ]
+        : []),
+    ].join("\n"),
+  });
+}
 
 /** The hook's stdout for one Stop input ("" lets the turn end). */
-export function stopDecision(input: unknown): string {
+export function stopDecision(
+  input: unknown,
+  rotation?: RotationHookArgs | null,
+): string {
   if (!input || typeof input !== "object") return "";
   const i = input as {
     stop_hook_active?: unknown;
     last_assistant_message?: unknown;
+    session_id?: unknown;
   };
   if (i.stop_hook_active === true) return "";
+  if (rotation) {
+    const block = rotationBlock(i, rotation);
+    if (block) return block;
+  }
   const msg = i.last_assistant_message;
   if (typeof msg !== "string") return "";
   // A hand-back is checked whole. Any other final message is what the
@@ -52,7 +98,7 @@ async function main(): Promise<void> {
   for await (const chunk of process.stdin) text += String(chunk);
   let out = "";
   try {
-    out = stopDecision(JSON.parse(text));
+    out = stopDecision(JSON.parse(text), parseHookArgs(process.argv.slice(2)));
   } catch {
     out = "";
   }