cc-session-recover 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.3 — 2026-06-12
+
+- Install only the runtime `.claude` files and `HANDOFF.md` into target projects; package tooling now stays in the npm package.
+- Enable hooks by default, with `--no-hooks` as the opt-out flag.
+- Add `cc-session-recover watch` for running the closed-terminal watcher through `npx`.
+- Remove the old one-time reminder flow and its `loop.md` prompt from the packaged workflow.
+
+## 0.1.2 — 2026-06-12
+
+- Stop installing the package docs into target projects.
+- Keep runtime files out of target git history by appending the session-recovery ignore block.
+- Remove the fake-quota try-it flow from the README.
+
 ## 0.1.0 — 2026-06-12
 
 Initial release of the quota-resume template.

package/README.md

@@ -1,163 +1,47 @@
 # cc-session-recover
 
-Keep a long Claude Code task recoverable when quota or a rate limit stops it.
+Your long Claude Code task survives quota stops — and continues by itself after the reset, with no prompt from you.
 
-This project installs a small workflow into another repo. Claude keeps a handoff file and sets a slow in-session heartbeat. If the terminal closes after a quota stop is recorded, an optional watcher can resume the same Claude session from another shell.
+When quota or a rate limit kills a session mid-task, Claude normally just stops until you come back and tell it to continue. This workflow removes that. Claude keeps a recovery note (`HANDOFF.md`) as it works, retries on a slow schedule while quota is blocked, and the first attempt after the reset picks the task up exactly where it stopped.
 
-## Why This Approach Is Stronger
-
-- It has two recovery paths. With the terminal open, the heartbeat resumes inside the active Claude Code session. With the terminal closed, the watcher can resume the saved session id.
-- Claude Code hooks record the quota stop. The watcher uses `claude -p --resume` only for closed-terminal recovery, so it does not depend on terminal text.
-- `HANDOFF.md` keeps the next step in the repo. A resume has project state, recent progress, and the exact next action.
-- The heartbeat runs inside the active Claude Code session. It keeps the original context alive while quota is blocked.
-- The watcher covers closed terminals. It reads the quota marker, waits for the reset time when available, and resumes the saved session id.
-- The status line cache reduces noisy retries. When Claude Code exposes a reset time, the watcher sleeps until that time plus a buffer.
-- The fake quota test checks the full path: install, hook injection, quota marker, retry loop, exact-session resume, and marker cleanup.
-
-## What You Get
-
-- `HANDOFF.md`: the recovery note for the current task.
-- `.claude/auto-continue.md`: the prompt used by the recurring heartbeat.
-- `.claude/loop.md`: a one-step resume prompt for a scheduled one-time reminder.
-- A `SessionStart` hook that injects the standing instructions at the start of each Claude Code session.
-- A `StopFailure` hook that records quota stops and writes `.claude/quota-blocked.json`.
-- `scripts/quota-watcher.sh`: an optional watcher that uses the marker file to resume the recorded session with `claude -p --resume`.
-- `scripts/test-fake-quota-flow.sh`: an end-to-end test that proves the install, hooks, marker, and watcher without using real quota.
+Every part of this has been verified against a genuine quota stop, end to end.
 
 ## Install
 
-Use `npx` from any project:
-
 ```sh
 npx cc-session-recover init /path/to/project
 ```
 
-Enable the local Claude Code hooks during install:
+(Or from a clone: `bash scripts/install-into-project.sh /path/to/project`. Pass `--no-hooks` with either to install the files without activating anything.)
 
-```sh
-npx cc-session-recover init --enable-local-hook /path/to/project
-```
+Approve the hooks once when Claude Code asks on the next start. That's the whole setup.
 
-You can also install from a clone of this repo:
-
-```sh
-cd /path/to/cc-session-recover
-bash scripts/install-into-project.sh --enable-local-hook /path/to/project
-```
-
-Claude Code may ask you to approve the hooks the next time you start `claude` in that project. Approve them once.
-
-## Use It
-
-Start Claude Code in the target project:
+## Use
 
 ```sh
 cd /path/to/project
 claude
 ```
 
-Then give Claude your real task.
-
-With hooks enabled, the `SessionStart` hook prints `.claude/standing-instructions.md` into Claude's context. That tells Claude to:
-
-1. Keep `HANDOFF.md` current after each small step.
-2. Create a recurring schedule every 45 minutes.
-3. Use this scheduled prompt: `Read .claude/auto-continue.md and follow it.`
-4. Cancel the schedule when the task is complete.
-
-If quota blocks the session, each heartbeat fails while quota remains blocked. The first heartbeat after the reset reads `HANDOFF.md` and continues from the recorded next step.
-
-The terminal must stay open for this heartbeat. The schedule lives inside the running Claude Code session.
-
-## Use Without Hooks
-
-If you install without hooks, include this with your task:
-
-```text
-Keep HANDOFF.md updated after every small safe step.
-
-Also create a recurring schedule every 45 minutes with this prompt:
-
-Read .claude/auto-continue.md and follow it.
-
-Cancel that schedule when the task is complete.
-```
-
-## One-Time Resume
-
-Use this when you know the quota reset time and want one future resume.
-
-Look at the reset time in the Claude Code status line. Add 10 to 15 minutes. Then ask Claude Code to schedule one reminder.
-
-Example:
-
-```text
-Update HANDOFF.md now.
-
-Then set a one-time reminder for 02:25 local time with this prompt:
-
-Read HANDOFF.md first. If the task is incomplete, run git status --short, inspect the current diff only enough to understand the working tree, continue exactly one small safe step from Next Exact Action, run the narrowest relevant check, update HANDOFF.md, and stop.
-```
-
-Pick a time like `02:25`, rather than exactly `02:00` or `02:30`.
-
-Use `/loop` for short polling jobs, such as checking CI. Avoid `/loop 1m` for overnight quota recovery.
-
-## Watcher For Closed Terminals
-
-The heartbeat dies when the terminal closes. If you need unattended recovery after that, enable the local hook and run the watcher from another shell:
-
-```sh
-bash scripts/quota-watcher.sh /path/to/project
-```
-
-The watcher needs `jq` and the `claude` CLI on `PATH`.
-
-When quota stops a turn, the hook writes `.claude/quota-blocked.json`. The watcher reads the saved `session_id` and runs:
-
-```sh
-claude -p --resume <session_id> --permission-mode acceptEdits "<contents of .claude/auto-continue.md>"
-```
+Give Claude your task, normally. Nothing extra to type — the injected standing instructions make Claude keep the recovery note and set its own retry schedule. Leave the terminal open and walk away.
 
-If the status line cache has a reset time, the watcher sleeps until that time plus a 15-minute buffer before it tries. Without a reset time, it retries on an interval.
+If quota dies mid-task, work resumes automatically after the reset.
 
-Close the interactive Claude Code session before you rely on the watcher. Otherwise the open session and the watcher may work on the same task.
-
-## Status Line Cache
-
-`.claude/statusline-quota-cache.sh` saves Claude Code rate-limit fields into `.claude/rate-limit-state.json`.
-
-The `StopFailure` hook copies that reset time into `.claude/quota-blocked.json`. The watcher uses it to wait for the reset instead of retrying blind.
-
-To keep your existing status line, set `CLAUDE_QUOTA_STATUSLINE_DELEGATE` to your current status line command. The wrapper passes the display through after it caches the quota data.
-
-## Test The Workflow
-
-Run the static project check:
-
-```sh
-bash scripts/verify-claude-loop-workflow.sh
-```
-
-Run the fake quota flow:
-
-```sh
-bash scripts/test-fake-quota-flow.sh
-```
+## Why This Approach Is Stronger
 
-When you run the fake test, the script creates a throwaway repo, installs the workflow, fakes a `SessionStart` event, fakes a `rate_limit` `StopFailure`, replaces `claude` with a stub that fails twice, then checks that the watcher resumes the recorded session.
+- It avoids `tmux`, `screen`, and terminal-injection hacks. Headless `claude -p --resume` is used only by the optional closed-terminal watcher, targeting the exact recorded session.
+- It gives you two recovery paths. With the terminal open, the heartbeat resumes inside the active Claude Code session. With the terminal closed, the watcher resumes the saved session id.
+- `HANDOFF.md` keeps the next step in the repo, with project state, recent progress, and the exact next action.
+- The heartbeat runs inside the active Claude Code session, so the original context stays alive while quota is blocked.
 
 ## Limits
 
-- This does not bypass quota.
-- The heartbeat needs Claude Code to stay open and idle when the scheduled prompt fires.
-- The watcher needs the local hook marker file. It only acts after a quota stop gets recorded.
-- Headless resume cannot ask for permission. Review `--permission-mode acceptEdits` before you use it.
-- Scheduled tasks require Claude Code v2.1.72 or newer.
+- It does not bypass quota. It only waits for the reset.
+- The basic flow needs the terminal to stay open. A closed-terminal recovery mode exists; see the docs.
+- Worst case is never lost work: the recovery note is always on disk, and "Read HANDOFF.md and continue" restores any session by hand.
 
-## More Docs
+## Docs
 
-- [Simple flow](docs/simple-flow.md): the notebook, alarm, and watcher explained without code.
-- [FAQ](docs/faq.md): reliability, hook approval, and what still needs a human.
-- [Auto-resume details](docs/claude-code-auto-resume.md): full behavior and limits.
-- [Verified quota resume example](docs/verified-quota-resume-example.md): a concrete one-time reminder example.
+- [Simple flow](docs/simple-flow.md) — how it works, told as a story (notebook, alarm, watchman).
+- [FAQ](docs/faq.md) — reliability, hook approval, what still needs a human.
+- [Full details](docs/claude-code-auto-resume.md) — closed-terminal watcher, precise reset-time resume, all limits.

package/bin/cli.js

@@ -5,45 +5,66 @@
 // Pure Node so it also works where bash is absent; the installed runtime
 // scripts themselves are bash and need a POSIX shell (macOS, Linux, WSL,
 // Git Bash).
+//
+// Only files Claude Code must execute from inside the project are installed
+// (the .claude prompts, hooks, and status line wrapper). Tooling like the
+// watcher stays in this package and runs via `npx cc-session-recover watch`.
 
 const fs = require('fs');
 const path = require('path');
+const { spawn } = require('child_process');
 
 const TEMPLATE_ROOT = path.join(__dirname, '..');
 
 const FILES = [
-  '.claude/loop.md',
   '.claude/auto-continue.md',
   '.claude/standing-instructions.md',
   '.claude/settings.example.json',
   '.claude/statusline-quota-cache.sh',
   '.claude/hooks/log-stop-failure.sh',
   '.claude/hooks/inject-standing-instructions.sh',
-  'docs/claude-code-auto-resume.md',
-  'docs/verified-quota-resume-example.md',
-  'docs/simple-flow.md',
-  'docs/faq.md',
-  'scripts/install-into-project.sh',
-  'scripts/verify-claude-loop-workflow.sh',
-  'scripts/quota-watcher.sh',
-  'scripts/test-fake-quota-flow.sh',
 ];
 
-const COPY_IF_MISSING = ['HANDOFF.md', 'README.md'];
+const COPY_IF_MISSING = ['HANDOFF.md'];
+
+// HANDOFF.md must stay editable by unattended Claude runs, so it cannot live
+// in .claude/ (Claude Code blocks edits there). Ignoring it in git gives the
+// same "never committed" result without breaking recovery.
+const IGNORE_ENTRIES = [
+  'HANDOFF.md',
+  '.claude/settings.local.json',
+  '.claude/rate-limit-state.json',
+  '.claude/stop-failure-events.jsonl',
+  '.claude/quota-blocked.json',
+];
+const IGNORE_HEADER = '# Claude Code session-recovery runtime state';
 
 function usage() {
-  console.error('Usage: cc-session-recover init [--enable-local-hook] [target-dir]');
+  console.error('Usage: cc-session-recover init [--no-hooks] [target-dir]');
+  console.error('       cc-session-recover watch [target-dir]');
+  console.error('Hooks are enabled by default; Claude Code still asks you to approve them once.');
   process.exit(2);
 }
 
+function watch(target) {
+  const script = path.join(TEMPLATE_ROOT, 'scripts', 'quota-watcher.sh');
+  const child = spawn('bash', [script, target], { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code === null ? 1 : code));
+  child.on('error', (err) => {
+    console.error(`Could not start watcher: ${err.message}`);
+    process.exit(1);
+  });
+}
+
 function main() {
   const args = process.argv.slice(2);
-  if (args[0] !== 'init') usage();
+  if (args[0] !== 'init' && args[0] !== 'watch') usage();
 
-  let enableHook = false;
+  let enableHook = true;
   let target = '.';
   for (const arg of args.slice(1)) {
-    if (arg === '--enable-local-hook') enableHook = true;
+    if (arg === '--no-hooks') enableHook = false;
+    else if (arg === '--enable-local-hook') enableHook = true; // legacy no-op, was the old default-off flag
     else if (arg.startsWith('-')) usage();
     else target = arg;
   }
@@ -54,6 +75,11 @@ function main() {
     process.exit(1);
   }
 
+  if (args[0] === 'watch') {
+    watch(target);
+    return;
+  }
+
   for (const rel of FILES) {
     const src = path.join(TEMPLATE_ROOT, rel);
     const dest = path.join(target, rel);
@@ -71,6 +97,16 @@ function main() {
     }
   }
 
+  const giPath = path.join(target, '.gitignore');
+  const existing = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
+  const lines = existing.split(/\r?\n/);
+  const missing = IGNORE_ENTRIES.filter((e) => !lines.includes(e));
+  if (missing.length) {
+    const lead = existing && !existing.endsWith('\n') ? '\n' : '';
+    const header = lines.includes(IGNORE_HEADER) ? '' : `${IGNORE_HEADER}\n`;
+    fs.appendFileSync(giPath, `${lead}${header}${missing.join('\n')}\n`);
+  }
+
   if (enableHook) {
     const local = path.join(target, '.claude', 'settings.local.json');
     if (fs.existsSync(local)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-session-recover",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Quota-resume workflow for Claude Code: handoff notebook, heartbeat auto-continue, StopFailure hooks, and an unattended watcher that resumes after quota resets.",
   "scripts": {
     "check": "node --check bin/cli.js && bash -n scripts/*.sh .claude/hooks/*.sh .claude/statusline-quota-cache.sh && bash scripts/verify-claude-loop-workflow.sh",
@@ -12,13 +12,11 @@
   },
   "files": [
     "bin",
-    ".claude/loop.md",
     ".claude/auto-continue.md",
     ".claude/standing-instructions.md",
     ".claude/settings.example.json",
     ".claude/statusline-quota-cache.sh",
     ".claude/hooks",
-    "docs",
     "scripts",
     "HANDOFF.md",
     "CHANGELOG.md",

package/scripts/install-into-project.sh

@@ -3,15 +3,16 @@
 set -eu
 
 usage() {
-  printf 'Usage: %s [--enable-local-hook] /path/to/project\n' "$0" >&2
+  printf 'Usage: %s [--no-hooks] /path/to/project\n' "$0" >&2
+  printf 'Hooks are enabled by default; Claude Code still asks you to approve them once.\n' >&2
 }
 
-ENABLE_LOCAL_HOOK=0
+ENABLE_LOCAL_HOOK=1
 
-if [ "${1:-}" = "--enable-local-hook" ]; then
-  ENABLE_LOCAL_HOOK=1
-  shift
-fi
+case "${1:-}" in
+  --no-hooks) ENABLE_LOCAL_HOOK=0; shift ;;
+  --enable-local-hook) shift ;; # legacy no-op, was the old default-off flag
+esac
 
 if [ "$#" -ne 1 ]; then
   usage
@@ -26,25 +27,14 @@ TEMPLATE_ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
   exit 1
 }
 
-mkdir -p "$TARGET/.claude/hooks" "$TARGET/docs" "$TARGET/scripts"
+mkdir -p "$TARGET/.claude/hooks"
 
-if [ ! -f "$TARGET/README.md" ]; then
-  cp "$TEMPLATE_ROOT/README.md" "$TARGET/README.md"
-fi
-cp "$TEMPLATE_ROOT/.claude/loop.md" "$TARGET/.claude/loop.md"
 cp "$TEMPLATE_ROOT/.claude/auto-continue.md" "$TARGET/.claude/auto-continue.md"
 cp "$TEMPLATE_ROOT/.claude/standing-instructions.md" "$TARGET/.claude/standing-instructions.md"
 cp "$TEMPLATE_ROOT/.claude/statusline-quota-cache.sh" "$TARGET/.claude/statusline-quota-cache.sh"
 cp "$TEMPLATE_ROOT/.claude/hooks/inject-standing-instructions.sh" "$TARGET/.claude/hooks/inject-standing-instructions.sh"
 cp "$TEMPLATE_ROOT/.claude/settings.example.json" "$TARGET/.claude/settings.example.json"
 cp "$TEMPLATE_ROOT/.claude/hooks/log-stop-failure.sh" "$TARGET/.claude/hooks/log-stop-failure.sh"
-cp "$TEMPLATE_ROOT/docs/claude-code-auto-resume.md" "$TARGET/docs/claude-code-auto-resume.md"
-cp "$TEMPLATE_ROOT/docs/verified-quota-resume-example.md" "$TARGET/docs/verified-quota-resume-example.md"
-cp "$TEMPLATE_ROOT/scripts/install-into-project.sh" "$TARGET/scripts/install-into-project.sh"
-cp "$TEMPLATE_ROOT/scripts/verify-claude-loop-workflow.sh" "$TARGET/scripts/verify-claude-loop-workflow.sh"
-cp "$TEMPLATE_ROOT/scripts/quota-watcher.sh" "$TARGET/scripts/quota-watcher.sh"
-cp "$TEMPLATE_ROOT/scripts/test-fake-quota-flow.sh" "$TARGET/scripts/test-fake-quota-flow.sh"
-
 if [ ! -f "$TARGET/HANDOFF.md" ]; then
   cp "$TEMPLATE_ROOT/HANDOFF.md" "$TARGET/HANDOFF.md"
 fi
@@ -52,10 +42,34 @@ fi
 chmod +x "$TARGET/.claude/hooks/log-stop-failure.sh"
 chmod +x "$TARGET/.claude/hooks/inject-standing-instructions.sh"
 chmod +x "$TARGET/.claude/statusline-quota-cache.sh"
-chmod +x "$TARGET/scripts/test-fake-quota-flow.sh"
-chmod +x "$TARGET/scripts/install-into-project.sh"
-chmod +x "$TARGET/scripts/verify-claude-loop-workflow.sh"
-chmod +x "$TARGET/scripts/quota-watcher.sh"
+
+# Keep runtime state out of the target's git history. HANDOFF.md must stay in
+# the project root (Claude Code blocks unattended edits inside .claude/), so
+# ignoring it is how it stays uncommitted.
+GITIGNORE="$TARGET/.gitignore"
+GITIGNORE_HEADER='# Claude Code session-recovery runtime state'
+NEEDS_HEADER=1
+APPENDED_GITIGNORE=0
+touch "$GITIGNORE"
+if grep -qxF "$GITIGNORE_HEADER" "$GITIGNORE"; then
+  NEEDS_HEADER=0
+fi
+append_gitignore_line() {
+  if [ "$APPENDED_GITIGNORE" -eq 0 ] && [ -s "$GITIGNORE" ] && [ "$(tail -c 1 "$GITIGNORE")" != "" ]; then
+    printf '\n' >> "$GITIGNORE"
+  fi
+  APPENDED_GITIGNORE=1
+  printf '%s\n' "$1" >> "$GITIGNORE"
+}
+for entry in HANDOFF.md .claude/settings.local.json .claude/rate-limit-state.json .claude/stop-failure-events.jsonl .claude/quota-blocked.json; do
+  if ! grep -qxF "$entry" "$GITIGNORE"; then
+    if [ "$NEEDS_HEADER" -eq 1 ]; then
+      append_gitignore_line "$GITIGNORE_HEADER"
+      NEEDS_HEADER=0
+    fi
+    append_gitignore_line "$entry"
+  fi
+done
 
 if [ "$ENABLE_LOCAL_HOOK" -eq 1 ]; then
   if [ -f "$TARGET/.claude/settings.local.json" ]; then

package/scripts/test-fake-quota-flow.sh

@@ -42,6 +42,8 @@ mkdir -p "$DUMMY"
 git -C "$DUMMY" init -q
 bash "$TEMPLATE_ROOT/scripts/install-into-project.sh" --enable-local-hook "$DUMMY" >/dev/null
 [ -f "$DUMMY/.claude/settings.local.json" ] || fail "hook settings not installed"
+[ ! -d "$DUMMY/scripts" ] || fail "install must not create a scripts folder in the target"
+[ ! -d "$DUMMY/docs" ] || fail "install must not create a docs folder in the target"
 
 step "Fake SessionStart: standing instructions should be injected"
 INJECTED=$(printf '{"session_id":"fake-session-123","hook_event_name":"SessionStart","source":"startup"}' \
@@ -89,7 +91,7 @@ chmod +x "$BIN/claude"
 
 step "Run the watcher against the fake CLI"
 QUOTA_WATCH_INTERVAL=1 QUOTA_RESUME_BUFFER=1 PATH="$BIN:$PATH" \
-  bash "$DUMMY/scripts/quota-watcher.sh" "$DUMMY" >"$WORK/watcher.log" 2>&1 &
+  bash "$TEMPLATE_ROOT/scripts/quota-watcher.sh" "$DUMMY" >"$WORK/watcher.log" 2>&1 &
 WATCHER_PID=$!
 disown "$WATCHER_PID" 2>/dev/null || true
 

package/scripts/verify-claude-loop-workflow.sh

@@ -20,7 +20,6 @@ require_text() {
   grep -Fqi -- "$text" "$ROOT/$file" || fail "$file must mention: $text"
 }
 
-require_file ".claude/loop.md"
 require_file ".claude/auto-continue.md"
 require_file "HANDOFF.md"
 require_file ".claude/settings.example.json"
@@ -30,26 +29,20 @@ require_file ".claude/standing-instructions.md"
 require_file "scripts/test-fake-quota-flow.sh"
 require_file "README.md"
 require_file "docs/claude-code-auto-resume.md"
-require_file "docs/verified-quota-resume-example.md"
+require_file "docs/simple-flow.md"
+require_file "docs/faq.md"
 require_file "scripts/install-into-project.sh"
 require_file "scripts/quota-watcher.sh"
 require_file "package.json"
 require_file "bin/cli.js"
 require_file "LICENSE"
 
-require_text ".claude/loop.md" "HANDOFF.md"
-require_text ".claude/loop.md" "git status --short"
-require_text ".claude/loop.md" "one small safe step"
-require_text ".claude/loop.md" "update HANDOFF.md"
-require_text ".claude/loop.md" "stop"
-
 require_text ".claude/auto-continue.md" "HANDOFF.md"
 require_text ".claude/auto-continue.md" "git status --short"
 require_text ".claude/auto-continue.md" "remaining checklist"
 require_text ".claude/auto-continue.md" "safe to fire at any time"
 require_text ".claude/auto-continue.md" "Cancel this recurring schedule"
 
-require_text "docs/claude-code-auto-resume.md" "one-time reminder"
 require_text "docs/claude-code-auto-resume.md" "auto-continue.md"
 require_text "docs/claude-code-auto-resume.md" "heartbeat"
 require_text "docs/claude-code-auto-resume.md" "claude"
@@ -61,14 +54,8 @@ require_text "docs/claude-code-auto-resume.md" "StopFailure"
 require_text "docs/claude-code-auto-resume.md" "Do not use"
 require_text "docs/claude-code-auto-resume.md" "/loop 1m"
 
-require_text "docs/verified-quota-resume-example.md" "02:25"
-require_text "docs/verified-quota-resume-example.md" "one-time reminder"
-require_text "docs/verified-quota-resume-example.md" "git status --short"
-require_text "docs/verified-quota-resume-example.md" "Do not use"
-require_text "docs/verified-quota-resume-example.md" "/loop 1m"
-
 require_text "README.md" "install-into-project.sh"
-require_text "README.md" "one-time reminder"
+require_text "README.md" "npx cc-session-recover init"
 require_text "README.md" "not bypass quota"
 
 require_text ".claude/settings.example.json" "SessionStart"
@@ -94,7 +81,7 @@ require_text "scripts/quota-watcher.sh" "session_id"
 [ -x "$ROOT/scripts/test-fake-quota-flow.sh" ] || fail "scripts/test-fake-quota-flow.sh must be executable"
 
 for forbidden in "claude -p" "tmux" "screen" "expect" "TIOCSTI"; do
-  if grep -Fqi -- "$forbidden" "$ROOT/.claude/loop.md" "$ROOT/.claude/auto-continue.md" "$ROOT/HANDOFF.md"; then
+  if grep -Fqi -- "$forbidden" "$ROOT/.claude/auto-continue.md" "$ROOT/HANDOFF.md"; then
     fail "runtime workflow must not require $forbidden"
   fi
 done

package/.claude/loop.md

@@ -1,25 +0,0 @@
-# Claude Code Resume Prompt
-
-Use this prompt for a one-time scheduled resume or for a slow `/loop`.
-
-Resume only if the task is incomplete.
-
-First read `HANDOFF.md`.
-
-Then:
-
-1. Run `git status --short`.
-2. Inspect the current diff only enough to understand the working tree.
-3. Continue exactly one small safe step from `Next Exact Action`.
-4. Run the narrowest relevant check for that step.
-5. Update HANDOFF.md with the new state.
-6. Stop after that small step.
-
-Rules:
-
-- Do not repeat completed work.
-- Do not start unrelated work.
-- Do not do broad refactors.
-- Do not run destructive commands.
-- Do not run expensive full test suites unless `HANDOFF.md` says they are needed.
-- If the handoff is missing or unclear, update it with what you know and stop.

package/docs/claude-code-auto-resume.md

@@ -1,242 +0,0 @@
-# Claude Code Quota Resume Workflow
-
-This workflow helps Claude Code continue after a quota or rate limit pause without a new prompt from you.
-
-The main mechanism is a fresh handoff file plus a recurring in-session heartbeat armed at task start.
-A one-time scheduled resume after the reset time still works when you know the reset time.
-Neither bypasses quota.
-They only wait until quota should be available again.
-
-## Automatic Injection Through Hooks
-
-Hook events differ in what they are allowed to do:
-
-- `SessionStart` can inject context: anything its script prints to stdout is added to Claude's context for the session.
-- `UserPromptSubmit` can also inject context, alongside each prompt you send.
-- `StopFailure` can only observe: its output is ignored, so it can log and write files but never inject a prompt or schedule anything.
-
-This template uses `SessionStart` to inject `.claude/standing-instructions.md` at the start of every session.
-That file tells Claude to keep the handoff fresh, arm the 45-minute heartbeat for any multi-step task, and cancel it when done.
-With the local hook settings enabled, you never paste the setup message again.
-
-One honest limit: injected instructions are still instructions.
-The harness guarantees Claude receives them, and the heartbeat schedule itself is enforced by the harness once created, but creating it is something Claude does in response to the injected text.
-
-## Recommended Flow: Heartbeat Armed At Task Start
-
-With the hook enabled, just give Claude the task; the arming instructions are injected for you.
-Without it, arm the heartbeat when you give the task, not when quota is about to run out.
-You do not need to know the reset time.
-
-```text
-Keep HANDOFF.md updated after every small safe step.
-
-Also create a recurring schedule every 45 minutes with this prompt:
-
-Read .claude/auto-continue.md and follow it.
-
-Cancel that schedule when the task is fully complete.
-```
-
-How it behaves:
-
-- While Claude is working, the session is busy, so heartbeat fires wait or pass quickly.
-- If quota blocks a turn, the session goes idle and each heartbeat fire fails cheaply, about once per interval.
-- The first fire after the quota reset reads `HANDOFF.md` and continues the task to completion.
-- The prompt in `.claude/auto-continue.md` is safe to fire at any time, so a fire after completion is a no-op.
-
-The terminal must stay open for the heartbeat.
-Use an interval of 30 to 60 minutes.
-Do not use a one-minute interval.
-
-## Install In Any Project
-
-From the template folder:
-
-```sh
-cd /path/to/cc-session-recover
-bash scripts/install-into-project.sh /path/to/project
-```
-
-To also install the optional local quota logger hook:
-
-```sh
-bash scripts/install-into-project.sh --enable-local-hook /path/to/project
-```
-
-The hook is a logger plus a marker writer.
-It cannot schedule the same-session resume by itself.
-The marker feeds the optional unattended watcher described below.
-
-## What It Does
-
-The one-time resume prompt in `.claude/loop.md` tells Claude Code to:
-
-- Read `HANDOFF.md`.
-- Check the current git state.
-- Do one small safe step.
-- Run the narrowest useful check.
-- Update the handoff.
-- Stop.
-
-The handoff is the recovery file for the current task.
-It should stay fresh while Claude works.
-Do not wait until the quota is almost gone.
-Claude may not always know that a quota stop is about to happen.
-
-The heartbeat prompt in `.claude/auto-continue.md` is different.
-It keeps working through the remaining checklist until the task is complete or blocked, because a one-step-per-fire prompt would never finish a real task.
-
-## One-Time Resume Flow
-
-1. Run `claude` in the repo.
-2. Give Claude the main coding task.
-3. Make sure Claude keeps `HANDOFF.md` updated.
-4. Look at the reset time in your Claude Code status line.
-5. Add a 10 to 15 minute buffer.
-6. Ask Claude Code to schedule one resume at that time.
-
-The terminal must stay open.
-The Claude Code session must be idle when the scheduled resume fires.
-
-Example:
-
-```text
-Update HANDOFF.md now.
-
-Then set a one-time reminder for 02:25 local time with this prompt:
-
-Read HANDOFF.md first. If the task is incomplete, run git status --short, inspect the current diff only enough to understand the working tree, continue exactly one small safe step from Next Exact Action, run the narrowest relevant check, update HANDOFF.md, and stop.
-```
-
-Use a time like `02:25`, not exactly `02:00` or `02:30`.
-Claude Code may add a small timing offset to one-shot tasks at the top or bottom of the hour.
-
-## What Happens During Quota Or Rate Limit
-
-If quota or rate limit blocks a turn, Claude Code cannot keep working at that moment.
-The scheduled resume does not bypass quota.
-
-After quota resets, the scheduled resume prompt runs.
-Claude reads `HANDOFF.md`, checks the repo state, does one small safe step, updates the handoff, and stops.
-
-This avoids sending a prompt every minute while quota is still blocked.
-
-## When To Use `/loop`
-
-Use `/loop` for short polling tasks.
-For example, use it to check whether CI passed or whether a deployment finished.
-
-Do not use `/loop 1m` for overnight quota recovery.
-That can add repeated failed attempts to the session.
-
-If you do not know the reset time, use a slow loop such as `/loop 1h`, not a one-minute loop.
-
-## How To Stop The Loop
-
-Press Esc while the loop is waiting.
-
-If that does not stop it, use the normal Claude Code stop control in the same terminal.
-
-One-time scheduled reminders are different.
-Ask Claude Code to list or cancel scheduled tasks if you need to remove one.
-
-## Hooks And Status Line
-
-Claude Code status lines can receive rate-limit fields such as `rate_limits.five_hour.resets_at`.
-That is how the reset time can be shown.
-
-Claude Code hooks can detect a `rate_limit` stop through `StopFailure`.
-But `StopFailure` hooks have no decision control.
-So a hook can log or notify, but it should not be treated as a documented way to schedule a same-session resume.
-
-This template includes an optional hook logger:
-
-- `.claude/settings.example.json`
-- `.claude/hooks/log-stop-failure.sh`
-
-To enable it in one project, copy `.claude/settings.example.json` to `.claude/settings.local.json`.
-If that file already exists, merge the hook settings manually.
-
-When quota stops a turn, the hook appends a short note to `HANDOFF.md`.
-It also writes raw hook input to `.claude/stop-failure-events.jsonl` and a marker to `.claude/quota-blocked.json`.
-
-## Optional Unattended Watcher
-
-The heartbeat needs the terminal open.
-If the terminal might close, run the watcher from another shell:
-
-```sh
-bash scripts/quota-watcher.sh /path/to/project
-```
-
-It requires `jq`, the `claude` CLI on `PATH`, and the local hook enabled.
-
-When the hook writes `.claude/quota-blocked.json`, the watcher reads the `session_id` from it and retries:
-
-```sh
-claude -p --resume <session_id> --permission-mode acceptEdits "<contents of .claude/auto-continue.md>"
-```
-
-While quota is blocked, each attempt fails and the watcher sleeps.
-After the reset, the resume succeeds, the task continues headlessly, and the watcher clears the marker.
-
-## Precise Resume Using The Status Line Cache
-
-The status line wrapper `.claude/statusline-quota-cache.sh` saves the rate-limit fields, including `five_hour.resets_at`, to `.claude/rate-limit-state.json` while you work.
-The StopFailure hook stamps that cached reset time into the quota marker.
-When the marker has a reset time, the watcher does not knock on an interval.
-It sleeps until the reset time plus `QUOTA_RESUME_BUFFER` seconds, default 900 (15 minutes), and knocks once.
-The reset time is Unix epoch seconds, so the arithmetic is timezone-safe; local time appears only in printed messages.
-The interval knocking remains only as the fallback when no reset time is known or the precise knock fails.
-
-To keep an existing status line, set `CLAUDE_QUOTA_STATUSLINE_DELEGATE` to its command in the `statusLine` settings entry; the wrapper caches the fields and passes the display through unchanged.
-
-Cautions:
-
-- Exit the interactive Claude Code session before relying on the watcher, or both will work the same task in parallel.
-- Headless mode cannot ask for permissions, so configure the project allowlist or accept the default `--permission-mode acceptEdits`, and understand what that allows.
-- Set `QUOTA_WATCH_INTERVAL` and `QUOTA_WATCH_CLAUDE_ARGS` to tune the retry interval and claude flags.
-
-## Testing The Flow Without Real Quota
-
-Run:
-
-```sh
-bash scripts/test-fake-quota-flow.sh
-```
-
-It tests the full chain in a throwaway dummy repo:
-
-1. Installs the template into the dummy repo with the hook enabled.
-2. Pipes a fake `SessionStart` event into the injection hook and asserts the standing instructions come out.
-3. Pipes a fake `rate_limit` `StopFailure` event into the logger hook and asserts the log line, the handoff note, and the `quota-blocked.json` marker with the right `session_id`.
-4. Replaces the `claude` CLI with a stub that fails twice, simulating blocked quota, then succeeds, simulating the reset.
-5. Runs the real watcher against the stub and asserts it retried, resumed the exact recorded session with the auto-continue prompt, and cleared the marker.
-
-The one piece this cannot fake is the in-session heartbeat schedule, because that timer lives inside a real Claude Code session.
-To check that piece live, start `claude` in a scratch repo, give it a tiny multi-step task, and confirm it creates the 45-minute schedule on its own from the injected instructions.
-
-## Why The Interactive Flow Avoids Terminal Hacks
-
-The in-session flow uses the original Claude Code terminal.
-It avoids `tmux`, `screen`, `expect`, terminal-injection hacks, and `TIOCSTI`.
-
-Those tools try to control a terminal from the outside.
-That is fragile.
-It can also continue the wrong session.
-
-The built-in scheduler is simpler.
-It runs inside the same Claude Code session that already has the task context.
-
-The watcher's headless `claude -p --resume` is different from terminal injection.
-It is a documented CLI mode, and it targets the exact session recorded by the hook.
-
-## Verified Limits
-
-- Scheduled tasks require Claude Code v2.1.72 or newer.
-- Session scheduled tasks only fire while Claude Code is running and idle.
-- Closing the terminal or ending the session stops them.
-- A missed scheduled time does not catch up later unless Claude was only busy in the same open session.
-- Starting a fresh conversation clears session scheduled tasks.
-- Resuming with `claude --resume` or `claude --continue` can restore unexpired tasks.

package/docs/faq.md

@@ -1,37 +0,0 @@
-# FAQ
-
-Honest answers, including the parts that are not proven.
-
-## Where does the 45-minute alarm live?
-
-Inside the running Claude Code session, in memory.
-It is not a system cron job, not a launchd job, and not a file on disk.
-The standing-instructions hook asks Claude to create it at task start, and Claude creates it with Claude Code's built-in scheduler.
-Because it lives in the process, closing the terminal kills it.
-
-## Is this 100% reliable?
-
-No. Three layers, three confidence levels:
-
-- The scripts and the watchman: tested end to end with real sessions. Strong.
-- The harness behavior (hooks firing, schedules firing): documented by Claude Code, and the injection and resume paths were verified live.
-- Claude obeying the standing orders (keeping the notebook fresh, arming the alarm): this is a model following instructions. It is very reliable, not guaranteed. This is the weakest link.
-
-The first genuine quota stop is the final exam: afterwards, check `.claude/stop-failure-events.jsonl` to confirm the hook fired for real.
-
-## What still needs a human?
-
-- Opening the session and giving the task.
-- Keeping the terminal open for the alarm, or starting the watchman if it cannot stay open.
-- Approving the hooks once per project, the first time Claude Code sees them.
-- Judging the finished work. The workflow recovers progress; it does not review quality.
-
-## What happens if the terminal closes?
-
-The alarm dies with the session, but nothing is lost:
-
-- The notebook (`HANDOFF.md`) is still on disk with the exact next step.
-- If the watchman is running and a quota stop was recorded, it resumes the session headlessly on its own.
-- Otherwise, reopen the project, run `claude`, and say: "Read HANDOFF.md and continue."
-
-Worst case equals one typed line, never lost work.

package/docs/simple-flow.md

@@ -1,43 +0,0 @@
-# The Simple Flow: Notebook, Alarm, Watchman
-
-This is the plain-English story of how this workflow survives quota stops.
-
-## The notebook
-
-Claude keeps a notebook called `HANDOFF.md` in the project root.
-After every small piece of work it writes down: the goal, what is done, and the exact next step.
-If Claude is cut off at any moment, whoever reads the notebook can continue exactly where it stopped.
-That "whoever" is usually Claude itself, later.
-
-## The alarm
-
-When you give Claude a big task, it sets a repeating alarm inside the session:
-every 45 minutes, "read `.claude/auto-continue.md` and follow it."
-
-- While Claude is working, the alarm is harmless.
-- If the task is already done, the alarm fire reads the notebook, sees "done", and goes back to sleep.
-- If quota cut Claude off, each alarm fire fails cheaply while quota is still blocked.
-- The first fire after the quota reset reads the notebook and continues the work.
-
-You never type anything. The one rule: the terminal must stay open, because the alarm lives inside the running session.
-
-## The watchman
-
-If the terminal cannot stay open, run the watchman in a second terminal:
-
-```sh
-bash scripts/quota-watcher.sh /path/to/project
-```
-
-When quota cuts Claude off, a hook drops a marker file with the session id.
-The watchman sees the marker and knocks every 20 minutes: "can I resume that session yet?"
-While quota is blocked: no, it waits. After the reset: yes, it resumes that exact session headlessly, hands it the notebook, and the work finishes without any window at all.
-
-Use the alarm or the watchman, not both at once, or two Claudes will do the same work twice.
-
-## A normal day with this installed
-
-1. `cd` into the project and run `claude`.
-2. Give your task normally. A hook already injected the standing orders, so Claude sets up the notebook and the alarm by itself.
-3. Walk away. Quota stops are recovered automatically.
-4. Worst case, everything fails: the notebook still means you lose nothing. Type "read HANDOFF.md and continue" and you are back.

package/docs/verified-quota-resume-example.md

@@ -1,57 +0,0 @@
-# Verified Quota Resume Example
-
-This example uses only documented Claude Code behavior.
-
-## Situation
-
-You are working in `/path/to/my-app`.
-Claude Code shows that the 5-hour quota resets at `02:10`.
-You want work to continue overnight without sending a prompt every minute.
-
-## What You Type
-
-Inside the same Claude Code terminal, type:
-
-```text
-Update HANDOFF.md now.
-
-Then set a one-time reminder for 02:25 local time with this prompt:
-
-Read HANDOFF.md first. If the task is incomplete, run git status --short, inspect the current diff only enough to understand the working tree, continue exactly one small safe step from Next Exact Action, run the narrowest relevant check, update HANDOFF.md, and stop.
-```
-
-## Why `02:25`
-
-The quota reset is `02:10`.
-The extra 15 minutes gives a buffer.
-The time is not exactly `02:00` or `02:30`, so it avoids the special timing offset Claude Code may add at those exact marks.
-
-## What Should Happen
-
-1. Claude updates `HANDOFF.md`.
-2. Claude schedules one future prompt for `02:25` local time.
-3. If quota blocks the current turn before then, nothing keeps retrying every minute.
-4. At about `02:25`, if Claude Code is still open and idle, the scheduled prompt fires.
-5. Claude reads the handoff.
-6. Claude does one small safe step.
-7. Claude updates the handoff again.
-8. Claude stops.
-
-## What This Does Not Do
-
-- It does not bypass quota.
-- It does not work if the terminal is closed.
-- It does not work if Claude Code exits.
-- It does not guarantee the whole task finishes.
-- It does not use `tmux`, `screen`, `expect`, `claude -p`, or terminal injection.
-
-## If The Reset Time Is Unknown
-
-Use a slow loop only as a fallback:
-
-```text
-/loop 1h
-```
-
-Do not use `/loop 1m` for quota recovery.
-That can add many failed attempts to the session.