@sayansr26/agent-os 0.6.1 → 0.6.3

package/plugins/auto-handoff/README.md

@@ -0,0 +1,131 @@
+# claude-auto-handoff
+
+> Vendored into the `sayan-plugins` marketplace from [alexknowshtml/claude-auto-handoff](https://github.com/alexknowshtml/claude-auto-handoff) (MIT, © 2026 Alex Hillman). See [UPSTREAM.md](UPSTREAM.md) for the commit and what differs here.
+
+A Claude Code mod that hands a long session off to a fresh one before the context fills up. It replaces auto-compact.
+
+At the threshold, Haiku writes a structured handoff brief to disk. Then the mod runs `/clear` and seeds the new session with one line that points at the brief. The fresh session reads the brief and keeps working.
+
+![auto-handoff in a live session: the tool gate stops a read at the threshold, the panel walks through the brief and /clear, and the fresh session picks the work back up](https://raw.githubusercontent.com/alexknowshtml/claude-auto-handoff/8d762ce726c962268e2dbe24c1c60f0889a2fcde/docs/demo.gif)
+
+A live run on Haiku with the threshold at 80k. The mod refuses a read at the threshold, writes the brief, clears, and the fresh session is back at work about 7 seconds later at 31k. ([video](https://github.com/alexknowshtml/claude-auto-handoff/blob/8d762ce726c962268e2dbe24c1c60f0889a2fcde/docs/demo.mp4))
+
+## Why not auto-compact?
+
+Auto-compact summarizes in place, and you can't control what it keeps. A handoff brief has a fixed structure that you can edit. It covers work in progress, decisions, assumptions to verify, dead ends, your last request and whether it was answered, and the next step. The files, commits and issues sections come from the transcript in code, so they don't depend on the model's memory.
+
+## What happens
+
+1. **Threshold.** The mod checks the context size after each turn and before each model request, including tool output that hasn't been measured yet. Once it's past the threshold, the mod refuses new tool calls, so one burst of reads can't overflow the window. Unmeasured tool output is an estimate that can run high, so the real size sometimes comes in under the threshold. A refused call still ends in a handoff, at the next request or the end of the turn.
+2. **Brief.** Haiku writes the brief from the transcript. If Haiku fails, a facts-only brief stands in. Briefs go to `~/.claude/state/auto-handoff/<session-id>.md`.
+3. **Clear and seed.** The mod runs `/clear` and sends the fresh session one line: read the brief and follow its Instructions section. In the transcript, that line's brief path and viewer URL are drawn as links. Claude Code makes them clickable only when it detects a terminal that supports links. Over plain SSH it usually doesn't, so set `FORCE_HYPERLINK=1` if your terminal handles links, or use the status line link below.
+4. **A panel above the prompt.** It shows each step with a braille spinner on the one still running: writing the brief, clearing, starting the fresh session. Once the new session is measured it reads `✓ handed off · 162k → 45k` with an `open brief` link, then collapses after 10 seconds. Failures, the loop-guard pause, a facts-only brief and a too-tight threshold stay up until you press Dismiss. Typing `/clear` yourself closes the panel, including one waiting for Dismiss, unless a handoff is running. The panel steps aside while a survey holds that band. The band is drawn on the terminal and desktop only, so on the mobile app or in VS Code the threshold, the result, and anything that stays up also arrive as a toast.
+5. **Viewer.** Each brief also gets a readable page in `~/.claude/state/auto-handoff/pages/`. The page shows the brief and every handoff in the same run, linked in order. The served link is short, like `http://100.x.y.z:3846/1a2b3c4d`, so it fits on one line on a phone. In this copy the server is off by default and the link is the local file; set `viewer` in `/config` (for example `tailscale:3846`) to serve the pages. With `tailscale:3846` the mod serves them on your Tailscale IP at port 3846, so you can open them from any device on your tailnet. Devices off your tailnet can't reach them. The server starts with the first session that loads the mod and runs while that session is open; if it stops, including when the mod reloads, the next session to finish a turn starts it again. A session that finds the port already taken logs one line and leaves the running server alone, since it serves the same pages. Without Tailscale, the mod serves on `127.0.0.1` instead, so the link opens only on this machine. If Tailscale comes up later, a session already serving on localhost keeps using it; the next new session can serve on the Tailscale IP.
+6. **Status line link (optional).** `statusline/handoff-link.sh` wraps your status line command and adds a `↪ <link>` line when the session came from a handoff. Set it as the `statusLine` command in `~/.claude/settings.json`, with your existing command after it:
+
+   ```json
+   "statusLine": { "type": "command", "command": "~/claude-auto-handoff/statusline/handoff-link.sh ~/.claude/my-statusline.sh" }
+   ```
+
+   It needs `jq`. It finds the link in the previous brief's header, which names this session in `to:` and the page in `viewer:`.
+
+Loop guards stop a fresh session that starts large from handing off again right away. They also cap how many handoffs run in a row before you type something.
+
+## Install
+
+Requires a Claude Code build with mods (function-hook plugins). From the `sayan-plugins` marketplace (`agent-os init` installs it too; `--no-auto-handoff` skips it):
+
+```
+/plugin marketplace add sayansr26/agent-os
+/plugin install auto-handoff@sayan-plugins
+```
+
+Or from upstream, as a plugin folder:
+
+```sh
+git clone https://github.com/alexknowshtml/claude-auto-handoff.git ~/claude-auto-handoff
+claude --plugin-dir ~/claude-auto-handoff
+```
+
+To load it in every session, set `CLAUDE_CODE_PLUGIN_DIRS` to the folder in your shell environment, or in the `env` block of `~/.claude/settings.json`:
+
+```json
+{ "env": { "CLAUDE_CODE_PLUGIN_DIRS": "~/claude-auto-handoff" } }
+```
+
+## Configure
+
+Every setting is a row in `/config` under auto-handoff. They're stored in `~/.claude/settings.json` under `pluginConfigs`.
+
+| Setting | Default | What it does |
+|---|---|---|
+| `threshold` | `160000` | Context tokens that trigger a handoff. Sized for a 200k window: it leaves room for the brief and the turn in flight. A seeded session hands off no sooner than 40k past its own starting size, whatever this says; set it lower than that and the panel tells you where the line actually is |
+| `maxConsecutiveHandoffs` | `2` | Handoffs allowed before you type a prompt; past this, the mod pauses until you do |
+| `briefTemplate` | `~/.claude/auto-handoff/brief.md` | Your copy of the sections Haiku writes |
+| `instructionsTemplate` | `~/.claude/auto-handoff/instructions.md` | Your copy of what the fresh session is told to do |
+| `ignoreFiles` | blank | Regex for edited files to leave out of the brief, such as caches or synced state |
+| `viewer` | blank | Where to serve the brief pages, as `host:port`. `tailscale` as the host means this machine's Tailscale IP, or `127.0.0.1` when Tailscale isn't set up. Leave blank for no server; the link is then the local file |
+
+Environment variables:
+
+- `AUTO_HANDOFF_TOKENS=60000` overrides the threshold for one run, so you can watch a handoff without filling 160k first. It stays set in that shell after the test. Seeded sessions start near 45k, so a value under about 85k leaves them less than 40k of room: the mod then hands off at start + 40k instead and the panel shows `threshold 60k (AUTO_HANDOFF_TOKENS) leaves 15k ...` so you know the override is still live.
+- `AUTO_HANDOFF_DISABLE=1` turns the mod off for one session, viewer server included.
+- `DISABLE_AUTO_COMPACT` also turns it off. When something else manages the context limit, such as a wrapper that pipes the session, `/clear` would break that pipe. The viewer server still runs there.
+
+## Change the brief's structure and rules
+
+The brief is shaped by two markdown files. The defaults live in this repo's [`templates/`](templates/) folder:
+
+- **[`templates/brief.md`](templates/brief.md)** is the prompt Haiku gets after the transcript. Each `## ` heading is a section of the brief.
+- **[`templates/instructions.md`](templates/instructions.md)** goes at the top of the brief and tells the fresh session what to do with it.
+
+On a session's first start, the mod copies both files to `~/.claude/auto-handoff/` if they aren't there yet. Edit those copies, not the ones in the repo, so a `git pull` never overwrites your changes. The next handoff uses your version.
+
+To get the current default back, delete your copy. The next start copies it fresh. To keep your files somewhere else, point `briefTemplate` or `instructionsTemplate` in `/config` at them.
+
+### Editing `brief.md`
+
+Add, remove, rename or reorder `## ` sections. The text under each heading tells Haiku what to put there. A Haiku reply counts as valid if it contains at least one of your headings. Otherwise the mod falls back to a facts-only brief.
+
+Leave out files and commits sections. The mod adds them from the transcript in code.
+
+### Editing `instructions.md`
+
+It has one switch:
+
+```md
+{{#priority}}Shown when the last request is not fully answered.{{/priority}}
+{{^priority}}Shown when it is.{{/priority}}
+```
+
+The switch reads the brief's `## Last Request from the User` section and its `Status:` line. Keep both in `brief.md` if you want it to work.
+
+## Logs
+
+Everything the mod does is logged to `~/.claude/state/auto-handoff/auto-handoff.log`.
+
+## Develop
+
+```sh
+claude plugin validate .
+claude plugin test .
+```
+
+The mod hot-reloads when you save while it's loaded with `--plugin-dir`.
+
+## Changelog
+
+- **0.8.6** On a machine without `sh` (Windows), the brief page is still written, and the link opens it as a local file instead of a server that never started. The viewer no longer shells out to `mkdir`.
+- **0.8.5** Windows support, from [@davidboomcycle](https://github.com/davidboomcycle) (#3). The mod falls back to `USERPROFILE` when `HOME` is unset, so briefs no longer land in `<project>/undefined/`. Where there is no `sh`, the log is written through `$.fs`. The tests pass on Windows. The viewer server still needs a POSIX shell.
+- **0.8.4** Any token figure in Haiku's brief that isn't in Handoff Numbers is marked `[unverified: not in Handoff Numbers]` and logged. The figure is marked, not removed.
+- **0.8.3** The brief gets the real numbers: tokens at handoff, the threshold and where it came from, the session's starting size, and how many handoffs ran with no message from you. Haiku must copy them or write "unknown", so a brief can no longer invent a figure like "burned its 200k budget".
+- **0.8.2** A refused tool call always ends in a handoff, even when the real size measures under the threshold. Your own `/clear` closes the panel. A second session that finds the viewer port taken exits quietly instead of logging a stack trace.
+- **0.8.1** On the mobile app and in VS Code, which don't draw the panel, the threshold, the result and anything that stays up also arrive as toasts.
+- **0.8.0** A panel above the prompt replaces the toasts, with a spinner on each step and an `open brief` link.
+- **0.7.0** A seeded session hands off no sooner than 40k past its starting size. When the threshold is set tighter than that, the panel says so and names the setting. The viewer serves on `127.0.0.1` when Tailscale isn't available.
+- **0.6.0** A viewer page for each brief, served on your Tailscale IP with short links. The pages in a chain link to each other. The seed row's links are clickable, and the status line script adds a handoff link.
+- **0.5.0** First release: a Haiku brief, `/clear` and a seed prompt. It includes the tool gate, the check before each request, auto-compact replaced by a handoff, and the loop guards.
+
+## License
+
+MIT

package/plugins/auto-handoff/UPSTREAM.md

@@ -0,0 +1,22 @@
+# Upstream
+
+This plugin is a vendored copy of [alexknowshtml/claude-auto-handoff](https://github.com/alexknowshtml/claude-auto-handoff)
+by Alex Hillman, MIT licensed (see [LICENSE](LICENSE)); the copyright and author stay his.
+
+- Source commit: `8d762ce726c962268e2dbe24c1c60f0889a2fcde` (upstream version 0.8.6), taken 2026-10-22.
+- Left out: `docs/demo.gif` and `docs/demo.mp4` (1.5 MB); the README links to them upstream.
+
+## Local changes
+
+- `viewer` defaults to blank (no server) in `.claude-plugin/plugin.json` and `hooks/config.ts`.
+  Upstream defaults to `tailscale:3846`, which starts a detached HTTP server that outlives the
+  session. `agent-os init` installs this plugin into projects by default, so it must not start a
+  network listener nobody asked for. Set `viewer` in `/config` to turn it on.
+- Tests that exercise the server name `viewer: 'tailscale:3846'` explicitly.
+- README: provenance note, install from `sayan-plugins`, viewer default.
+
+## Syncing from upstream
+
+Fetch the new commit into a scratch folder, diff it against this folder, re-apply the local
+changes above, update the commit here, and bump `version` in `.claude-plugin/plugin.json` so
+installs update. Run `claude plugin validate` and `claude plugin test` on this folder after.

package/plugins/auto-handoff/hooks/brief.ts

@@ -0,0 +1,190 @@
+import type { SessionMessage } from 'claude-code'
+import { renderTemplate, sectionHeadings } from './templates.ts'
+
+// Brief building.
+// Files, commits, issues and the last real request come from the transcript in code;
+// Haiku only writes the judgment sections. Its reply is checked, and the facts alone
+// stand in when it fails.
+
+const MAX_MESSAGES = 120
+const MAX_MSG_CHARS = 2_000
+const MAX_TRANSCRIPT_CHARS = 150_000
+
+// Harness signals that arrive as user messages but are never the user's words.
+const META_PREFIXES = ['Stop hook feedback', '[Automatic handoff]', '[auto-handoff]', '[Image', '<system-reminder>', '<command-name>', '<local-command']
+
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit'])
+const GIT_COMMIT_OUTPUT = /^\[[\w./-]+(?: \(root-commit\))? ([0-9a-f]{7,})\] (.+)$/m
+
+export type Facts = {
+  filesModified: string[]
+  commits: string[]
+  issues: string[]
+  lastUserMessage?: string
+  handoffTokens?: number
+  threshold?: number
+  /** Where the base threshold came from: the env override or the /config setting. */
+  thresholdSource?: string
+  seededSessionStartSize?: number
+  /** Handoffs since the user last typed, this one included. */
+  unattendedCount?: number
+  /** Which handoff this is in its chain (1 for the first, 2 for the second, etc.). */
+  depth?: number
+}
+
+/** The user's own words, or undefined for a harness signal or a tool-result-only message. */
+export function userText(m: SessionMessage): string | undefined {
+  if (m.role !== 'user') return undefined
+  const raw = m.text.trim()
+  if (!raw) return undefined
+  return isMeta(raw) ? undefined : raw
+}
+
+function isMeta(text: string): boolean {
+  return META_PREFIXES.some(p => text.startsWith(p))
+}
+
+function commitSubject(command: string): string | undefined {
+  if (!/\bgit\b[^\n|;&]*\bcommit\b/.test(command)) return undefined
+  const heredoc = command.match(/<<\s*'?(\w+)'?\n([\s\S]*?)\n\1/)
+  if (heredoc) return heredoc[2]?.trim().split('\n')[0]
+  return command.match(/-m\s+(["'])(.+?)\1/)?.[2]
+}
+
+/** ignoreFiles: paths that never count as edits (auto-synced state, caches); the ignoreFiles setting. */
+export function extractFacts(messages: readonly SessionMessage[], ignoreFiles?: RegExp): Facts {
+  const files = new Set<string>()
+  const commits: string[] = []
+  const issues = new Set<string>()
+  let lastUserMessage: string | undefined
+  for (const m of messages) {
+    const said = userText(m)
+    if (said) lastUserMessage = said
+    for (const n of `${said ?? (m.role === 'assistant' ? m.text : '')}`.matchAll(/(?<![\w&/])#(\d{2,5})\b/g)) issues.add(`#${n[1]}`)
+    for (const t of m.toolUses) {
+      const path = t.input.file_path ?? t.input.notebook_path
+      if (EDIT_TOOLS.has(t.tool) && typeof path === 'string' && !t.isError && !ignoreFiles?.test(path)) files.add(path)
+      if (t.tool !== 'Bash' || typeof t.input.command !== 'string' || t.isError) continue
+      // git's own "[main abc1234] subject" line is the proof a commit landed; the command is the fallback
+      const out = t.text?.match(GIT_COMMIT_OUTPUT)
+      const subject = out ? `${out[2]} (${out[1]})` : t.text === undefined ? commitSubject(t.input.command) : undefined
+      if (subject && !commits.includes(subject)) commits.push(subject)
+    }
+  }
+  return { filesModified: [...files].slice(-20), commits: commits.slice(-10), issues: [...issues].slice(-15), lastUserMessage }
+}
+
+/** The transcript as Haiku reads it. Harness signals are labelled so they are not taken for the user. */
+export function renderTranscript(messages: readonly SessionMessage[]): string {
+  const lines = messages.slice(-MAX_MESSAGES).map(m => {
+    const role = m.role === 'user' && m.text.trim() && !userText(m) ? 'system signal (not the user)' : m.role
+    const text = m.text.length > MAX_MSG_CHARS ? m.text.slice(0, MAX_MSG_CHARS) + ' [truncated]' : m.text
+    const tools = m.toolUses.map(t => `  [tool ${t.tool}${t.isError ? ' ERROR' : ''}] ${JSON.stringify(t.input).slice(0, 300)}`)
+    return [`### ${role}`, text, ...tools].filter(Boolean).join('\n')
+  })
+  const joined = lines.join('\n\n')
+  return joined.length > MAX_TRANSCRIPT_CHARS ? joined.slice(-MAX_TRANSCRIPT_CHARS) : joined
+}
+
+function list(items: string[], empty: string): string {
+  return items.length ? items.map(i => `- ${i}`).join('\n') : empty
+}
+
+// The only token figures the brief may use. Haiku once wrote "burned its 200k budget" for a
+// session at 93k because the prompt held no numbers at all.
+function handoffNumbersBlock(f: Facts): string {
+  const lines = []
+  if (f.depth !== undefined) lines.push(`- **Handoff depth:** ${f.depth}`)
+  if (f.handoffTokens !== undefined) lines.push(`- **Tokens at handoff:** ${f.handoffTokens} (${k(f.handoffTokens)})`)
+  if (f.threshold !== undefined) lines.push(`- **Threshold:** ${f.threshold} (${k(f.threshold)})${f.thresholdSource ? `, from ${f.thresholdSource}` : ''}`)
+  if (f.seededSessionStartSize !== undefined) lines.push(`- **This session's starting size (seeded from a handoff):** ${f.seededSessionStartSize} (${k(f.seededSessionStartSize)})`)
+  if (f.unattendedCount !== undefined) lines.push(`- **Handoffs in a row with no user message:** ${f.unattendedCount}`)
+  return lines.length ? `## Handoff Numbers\n${lines.join('\n')}\n` : ''
+}
+
+const k = (n: number) => `${Math.round(n / 1000)}k`
+
+export function factsBlock(f: Facts, withLastMessage = true): string {
+  const numbers = handoffNumbersBlock(f)
+  const files = `## Files Modified (from Edit/Write calls)
+${list(f.filesModified, 'None.')}
+
+## Commits This Session
+${list(f.commits, 'None.')}
+
+## GitHub Issues Mentioned
+${f.issues.length ? f.issues.join(', ') : 'None.'}`
+  const all = [numbers, files].filter(Boolean).join('\n')
+  return withLastMessage ? `${all}\n\n## Last Real User Message (verbatim)\n${f.lastUserMessage ?? 'None found.'}` : all
+}
+
+export function briefPrompt(messages: readonly SessionMessage[], facts: Facts, template: string): string {
+  // Data first, instructions last.
+  return `## Extracted Facts\n${factsBlock(facts)}\n\n## Conversation\n${renderTranscript(messages)}\n\n---\n\n${template.trim()}`
+}
+
+/** A reply that holds none of the template's sections is a dialogue fragment, not a brief. */
+export function isValidBrief(text: string, template: string): boolean {
+  return sectionHeadings(template).some(h => text.includes(h))
+}
+
+// Whether the brief's last-request section
+// says the request is not (fully) answered. A chain with no user message is not a real request.
+export function hasUnansweredLastRequest(text: string): boolean {
+  const heading = /##\s*Last Request from the User/i.exec(text)
+  if (!heading) return false
+  const rest = text.slice(heading.index + heading[0].length)
+  const next = /^#{1,6}\s/m.exec(rest)
+  const section = next ? rest.slice(0, next.index) : rest
+  if (/No user message found|^\s*\[auto-handoff\]/i.test(section)) return false
+  return /\bStatus[\s*_`]*:[\s*_`"]*(Not (?:yet |fully )?answered|Partially answered|Unanswered)/i.test(section)
+}
+
+export type BriefContext = {
+  sessionId: string
+  /** The session's transcript file. */
+  transcript: string
+  /** The instructions template, rendered at the top of the brief. */
+  instructions: string
+}
+
+export function assembleBrief(ctx: BriefContext, facts: Facts, haiku: string | undefined): string {
+  const header = `${renderTemplate(ctx.instructions, { priority: haiku ? hasUnansweredLastRequest(haiku) : false })}
+
+## Session Handoff Brief
+
+- **Previous Session:** ${ctx.sessionId}
+- **Transcript:** \`${ctx.transcript}\`
+
+## How to Use This Brief
+${haiku ? 'Haiku wrote the judgment sections from conversation text with tool output abbreviated. The facts sections came from tool calls in code.' : 'Haiku did not return a usable brief, so this holds only facts extracted in code. Read the transcript for the rest.'} Treat every line as a starting point, not a fact. Before acting on anything here, spawn a subagent to verify: run git status, gh pr view, or Read the file directly. If a fact is missing, grep the transcript before asking the user.`
+  // A valid Haiku brief already quotes the last request in its own section.
+  return [header, haiku?.trim(), factsBlock(facts, !haiku)].filter(Boolean).join('\n\n')
+}
+
+// A token figure: "93k", "93.1k", "93,105 tokens", "93105 tokens".
+const TOKEN_FIGURE = /\b(\d{1,4}(?:\.\d+)?)k\b|\b(\d{1,3}(?:,\d{3})+|\d{4,7})(?= tokens\b)/gi
+
+const figureValue = (k?: string, whole?: string) => k !== undefined ? Number(k) * 1000 : Number(whole!.replace(/,/g, ''))
+
+/**
+ * Marks every token figure in Haiku's text that the Handoff Numbers block does not hold, within
+ * rounding to the nearest thousand. The template asks Haiku to copy those numbers; this makes it a
+ * rule. Figures are marked, not removed, so the next session sees what was claimed and that it is
+ * unchecked. With no numbers block, every figure is marked.
+ */
+export function markUnverifiedFigures(text: string, f: Facts): { text: string; flagged: string[] } {
+  const block = handoffNumbersBlock(f)
+  const allowed = [
+    ...[...block.matchAll(/\b(\d{1,4}(?:\.\d+)?)k\b/g)].map(m => figureValue(m[1])),
+    ...[...block.matchAll(/\b\d{4,7}\b/g)].map(m => Number(m[0])),
+  ]
+  const flagged: string[] = []
+  const marked = text.replace(TOKEN_FIGURE, (match: string, k?: string, whole?: string) => {
+    const value = figureValue(k, whole)
+    if (allowed.some(a => Math.abs(a - value) < 1000)) return match
+    flagged.push(match)
+    return `${match} [unverified: not in Handoff Numbers]`
+  })
+  return { text: marked, flagged }
+}

package/plugins/auto-handoff/hooks/config.ts

@@ -0,0 +1,64 @@
+// Settings from /config and the constants built on them. Engine-free: the host follows $ only
+// into functions declared in register.tsx, so anything taking $ stays there.
+
+export const BRIEF_DIR = '.claude/state/auto-handoff'
+// The two numbers are userConfig fields (plugin.json), set in /config. Defaults match the manifest.
+// threshold: matches HANDOFF_ARM_TOKENS in context-warning.ts.
+// MIN_HEADROOM and maxUnattended are loop guards. A seeded session must grow MIN_HEADROOM past its
+// first-turn size (its floor) before it can hand off again, and at most maxUnattended handoffs may
+// run before the user types a prompt. MIN_HEADROOM is fixed: seeded sessions start near 45k, so at
+// the default threshold it never moves the line; it only matters when the threshold is set low.
+// 40k is the empirical line where a seeded session can read its brief and still do real work. The
+// 2026-10-03 live run (threshold 20k, seeded sessions start at ~31k) chained six times with no
+// guard; the 2026-10-04 run (AUTO_HANDOFF_TOKENS=80000 left in a shell, floor ~45k) chained eight
+// times with a guard of a quarter of the threshold, because max(80k, 45k + 20k) is still 80k, and
+// 35k of room goes in reading the brief. Progress, not time: a 15-minute chain cap could block a
+// real session that fills fast.
+// The rest shape the brief: two template files and a pattern for files
+// that never count as edits.
+// viewer: where the mod serves the brief pages, "host:port"; "tailscale" as the host means this
+// machine's Tailscale IP, or 127.0.0.1 without Tailscale. Blank: no server, and the link is the local file.
+// sayan-plugins ships it blank (upstream: 'tailscale:3846'), so installing the mod starts no server.
+export type Config = { threshold: number; maxUnattended: number; briefTemplate: string; instructionsTemplate: string; ignoreFiles?: RegExp; viewer: string }
+export const DEFAULTS: Config = { threshold: 160_000, maxUnattended: 2, briefTemplate: '~/.claude/auto-handoff/brief.md', instructionsTemplate: '~/.claude/auto-handoff/instructions.md', viewer: '' }
+export const MIN_HEADROOM = 40_000
+// Each template's default, a file in the mod's templates/ folder.
+export const TEMPLATES = [['briefTemplate', 'brief.md'], ['instructionsTemplate', 'instructions.md']] as const
+export type TemplateKey = typeof TEMPLATES[number][0]
+// Used only when the shipped default is unreadable too, so the fresh session still knows what to do.
+export const LAST_RESORT_INSTRUCTIONS = '## Instructions\n\nThis turn was triggered by the system, not by a user. Read this brief and continue the work it describes.'
+
+export const k = (n: number) => `${Math.round(n / 1000)}k`
+export const short = (sessionId: string) => sessionId.slice(0, 8)
+export const expand = (path: string, home: string) => path.replace(/^~(?=\/|$)/, home)
+
+// A non-positive or non-numeric value falls back to the default rather than handing off at 0.
+const num = (v: unknown, fallback: number) => typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : fallback
+const str = (v: unknown, fallback: string) => typeof v === 'string' && v.trim() ? v.trim() : fallback
+// A bad pattern is dropped, not fatal: a typo in /config should not stop handoffs.
+function pattern(v: unknown): RegExp | undefined {
+  if (typeof v !== 'string' || !v.trim()) return undefined
+  try { return new RegExp(v) } catch { return undefined }
+}
+
+/** The /config values, each checked, with the manifest's defaults for anything missing or bad. */
+export function parseConfig(options: Record<string, unknown>): Config {
+  return {
+  threshold: num(options.threshold, DEFAULTS.threshold),
+  maxUnattended: num(options.maxConsecutiveHandoffs, DEFAULTS.maxUnattended),
+  briefTemplate: str(options.briefTemplate, DEFAULTS.briefTemplate),
+  instructionsTemplate: str(options.instructionsTemplate, DEFAULTS.instructionsTemplate),
+  ignoreFiles: pattern(options.ignoreFiles),
+  viewer: typeof options.viewer === 'string' ? options.viewer.trim() : DEFAULTS.viewer,
+  }
+}
+
+// The seed prompt's first characters; the render hook knows the seed row by them.
+export const SEED_PREFIX = '[auto-handoff] ↪ Handoff from session'
+// The seed text with its brief path and viewer URL as markdown links. The path becomes a
+// file: link labelled by its file name; the URL links to itself. Exported for the test.
+export function linkify(text: string): string {
+  return text
+    .replace(/(?<=\bat )(\/\S+\.md)(?=[\s)]|$)/, (p) => `[${p.slice(p.lastIndexOf('/') + 1)}](file://${p})`)
+    .replace(/(https?:\/\/[^\s)]+)/, (u) => `[${u}](${u})`)
+}

package/plugins/auto-handoff/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/plugins/auto-handoff/hooks/panel.tsx

@@ -0,0 +1,45 @@
+// The band above the prompt is the mod's whole UI: a header line and the steps under it, with
+// a braille spinner on whatever is still running. A toast cannot animate or carry a link, so the
+// panel replaced them. This file draws; register.tsx holds the panel and its timers, since the
+// host never follows $ across an import.
+
+export type Mark = 'spin' | 'done' | 'warn' | 'fail'
+export type Line = { mark: Mark; text: string }
+// sticky: stays until dismissed (a failure, the pause, a warning); otherwise a panel with nothing
+// spinning collapses on its own.
+export type Panel = { header: Line; steps: Line[]; link?: string; sticky?: boolean }
+
+export const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+const GLYPH: Record<Exclude<Mark, 'spin'>, string> = { done: '✓', warn: '⚠', fail: '✗' }
+const COLOR: Record<Mark, string> = { spin: 'yellow', done: 'green', warn: 'yellow', fail: 'red' }
+
+export const isSpinning = (p: Panel) => p.header.mark === 'spin' || p.steps.some((l) => l.mark === 'spin')
+
+// The plain text of the panel, one line per row, for logs and tests.
+export const panelText = (p: Panel, frame = 0) =>
+  [p.header, ...p.steps].map((l, i) => `${i ? '  ' : ''}${glyph(l.mark, frame)} ${l.text}`).join('\n')
+
+const glyph = (m: Mark, frame: number) => m === 'spin' ? SPINNER[frame % SPINNER.length] : GLYPH[m]
+
+// The elements come from $.ui.resolve in the render hook.
+type Elements = { Box: any; Text: any; Markdown: any; Button: any }
+
+export function panelTree({ Box, Text, Markdown, Button }: Elements, p: Panel, frame: number, onDismiss: () => void) {
+  return (
+    <Box flexDirection="column">
+      <Box>
+        <Text color={COLOR[p.header.mark]}>{glyph(p.header.mark, frame)} </Text>
+        <Text bold>{p.header.text}</Text>
+      </Box>
+      {p.steps.map((l, i) => (
+        <Box key={`step-${i}`}>
+          <Text>  </Text>
+          <Text color={COLOR[l.mark]}>{glyph(l.mark, frame)} </Text>
+          <Text dimColor={l.mark === 'done'}>{l.text}</Text>
+        </Box>
+      ))}
+      {p.link ? <Markdown text={`  [open brief](${p.link})`} /> : null}
+      {p.sticky ? <Button key="dismiss" label="Dismiss" onPress={onDismiss} /> : null}
+    </Box>
+  )
+}